SHA256
forked from course-team/tjhlp-gitea
只写方案, 不落地(workflow 以代码块形式放在文档里, 避免没有 runner 时 push 触发一直挂在"等待 runner")。 要点(都基于本机实测 + 1.27.3 源码): - runner 必须是"宿主上的 act_runner 二进制 + host 模式": 离线环境下容器模式 既拉不到 job 镜像, 镜像里也没有 python3/git/docker CLI; host 模式下 job 直接 以 ymy 在宿主执行, 路径/工具全现成 - 工作流不写 uses:: DEFAULT_ACTIONS_URL 默认指向 github.com, 离线拿不到 actions/checkout; 同步代码用 run: 里的 git - 免凭据: 从 /srv/gitea/git/repositories/course-team/tjhlp-gitea.git 直接 fetch (实测 git -c safe.directory 对本机 git 无效, 必须写进配置文件) - 部署逻辑放 deploy/scripts/auto-deploy.sh(可版本化/可手工跑), workflow 只做 "同步到 github.sha + 调脚本"; build.py 失败不碰容器, 验证失败自动回滚 - 落地步骤分 4 阶段: 下载 runner(需一次外网) -> 部署克隆 -> sudo 装 systemd 单元并注册(仓库级 runner, API 已确认存在) -> 先 workflow_dispatch 手动跑通 再打开 push 触发 + main 分支保护 - 明确写出 host 模式的安全含义(等价 root)、待落地确认项(host 标签语法/fork PR 审批等)与备选方案(cron 轮询) deploy/README.md 快速索引加一行指向该文档。
480 lines
22 KiB
Markdown
480 lines
22 KiB
Markdown
# CI/CD:main 自动部署(Gitea Actions 方案)
|
||
|
||
> **状态:方案,尚未落地。** 落地需要两步你现在才能做的事:① 一次可用的外网(下载
|
||
> `act_runner` 二进制);② 用 `sudo` 装一个 systemd 单元。除此之外全部可以在本机完成。
|
||
>
|
||
> 相关文档:[deploy/README.md](README.md)(部署与陷阱)、
|
||
> [customization/README.md](../customization/README.md)(定制机制与预览)。
|
||
|
||
---
|
||
|
||
## 0. 目标
|
||
|
||
`course-team/tjhlp-gitea` 的 `main` 一有推送,就自动把平台更新到那个提交:
|
||
构建定制产物 → 重建容器 → 跑验证 → 失败自动回滚。人工只负责 review 和 push。
|
||
|
||
不在本方案范围内:
|
||
|
||
- Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 的人工流程);
|
||
- `issue-templates` 重新推送(`uv run tjhlp repos init-templates ...`,semantics 上属于运营操作);
|
||
- 官网仓库(`Website`)的部署,那是 GitHub Actions 的事。
|
||
|
||
---
|
||
|
||
## 1. 现状与约束(2026-09-13 实测)
|
||
|
||
| 项 | 实测值 | 对方案的影响 |
|
||
|---|---|---|
|
||
| Gitea 版本 | 1.27.3(`docker.gitea.com/gitea:1.27.3`) | — |
|
||
| Actions | 默认开启(`modules/setting/actions.go` 里 `Enabled: true`),仓库页有 `/actions` 标签 | 不需要改配置就能用 |
|
||
| 已注册 runner | **无**(`action_runner` 表空) | 要自己装 |
|
||
| `DEFAULT_ACTIONS_URL` | 默认 `https://github.com` | **离线环境下 `uses: actions/checkout` 会失败** → 工作流不写 `uses:` |
|
||
| 外网 | 宿主与容器都不通;宿主 `7890` 是 ssh 转发的开发代理,只监听 `127.0.0.1`,容器不可达 | runner 二进制要一次性下载;job 不能拉镜像 |
|
||
| `sudo` | 需要密码(无免密) | 系统级 systemd 单元由你执行;我自己装不了 |
|
||
| cron | `crond` active+enabled,`ymy` 无 crontab | 备选方案可用(见 §10) |
|
||
| docker | `/usr/bin/docker` + `/usr/libexec/docker/cli-plugins/docker-compose`;`ymy` 在 `docker`(980) 组 | runner 以 `ymy` 跑即可操作 compose |
|
||
| 部署数据 | `/srv/gitea`(`git:git`)、PostgreSQL 在 `gitea-db` | 部署克隆要能读裸仓库 |
|
||
| 裸仓库 | `/srv/gitea/git/repositories/course-team/tjhlp-gitea.git`,`drwxr-xr-x git:git` | **可免凭据 fetch**(需 `safe.directory`,见 §4.1) |
|
||
| 现成脚本 | `deploy/scripts/{verify,backup,restore}.sh`、`customization/build.py`、`preview.sh check` | 直接复用 |
|
||
|
||
关键结论:**在离线 + 无 root 的前提下,唯一能跑通的 runner 形态是"宿主上的 act_runner 二进制 +
|
||
host 模式"**(§2.2)。容器模式 runner 需要拉 job 镜像、镜像里还要有 python3/git/docker-cli,
|
||
本项目现在做不到。
|
||
|
||
---
|
||
|
||
## 2. 方案总览
|
||
|
||
### 2.1 架构
|
||
|
||
```text
|
||
开发者 push main
|
||
│
|
||
▼
|
||
Gitea (10.80.42.185/QA) ── 调度 workflow ──► act_runner(宿主 systemd 服务, User=ymy)
|
||
▲ │ host 模式: 命令直接在宿主执行
|
||
│ 日志/状态显示在仓库 Actions 标签 ▼
|
||
└────────────────────────────── /home/ymy/deploy/tjhlp-gitea(部署克隆)
|
||
│
|
||
fetch 自 /srv/gitea/git/repositories/...(免凭据)
|
||
▼
|
||
build.py → docker compose up -d → verify.sh + check.sh
|
||
│
|
||
失败 ──► 回滚到上一个成功部署的 SHA
|
||
```
|
||
|
||
### 2.2 为什么是「宿主 act_runner + host 模式」
|
||
|
||
| 备选 | 结论 |
|
||
|---|---|
|
||
| act_runner 跑在容器里 + job 用容器模式 | 要拉 `gitea/runner-images` / `node:20` 之类镜像(无外网),且 job 里要有 python3、git、docker CLI —— 现成镜像都没有。**排除** |
|
||
| act_runner 跑在容器里 + job 用 host 模式 | host 模式是"在 runner 进程所在的那台机器上执行",runner 在容器里就等于在那个容器里,照样缺 python3/docker CLI。**排除** |
|
||
| **act_runner 二进制装在宿主 + host 模式** | job 直接以 `ymy` 在宿主执行:docker、python3、git、部署克隆路径全部现成,**不需要任何挂载/镜像**。**选它** |
|
||
| 完全不用 Actions,宿主 cron 轮询 | 无需外网、无需 root、今天就能落地,但没有 UI/日志/状态。作为 §10 备选保留 |
|
||
|
||
host 模式的代价写在 §7:**workflow 里的命令等价于你本人在宿主执行**(`ymy` 在 docker 组 = 等价 root)。
|
||
|
||
### 2.3 触发与门禁
|
||
|
||
- 触发:`push` 到 `main`,外加 `workflow_dispatch`(落地初期先只手动触发);
|
||
- 跳过:提交信息含 `[skip deploy]` 不部署(与 Gitea 自带的 `[skip ci]` 同风格);
|
||
- 串行:workflow 里 `concurrency` + 脚本里 `flock` 双保险,避免两次推送同时重建容器;
|
||
- 只部署 `main`:job 级 `if` 卡死分支,PR/其它分支即使跑工作流也不会碰生产。
|
||
|
||
---
|
||
|
||
## 3. 组件清单
|
||
|
||
| 组件 | 位置 | 谁维护 |
|
||
|---|---|---|
|
||
| 部署克隆 | `/home/ymy/deploy/tjhlp-gitea` | 本方案新建(§4.1) |
|
||
| 部署凭据 | `deploy/.env`(`chmod 600`,已 gitignore) | 从现有部署复制 |
|
||
| 部署状态 | `deploy/.state/last-deployed`(记录上次成功的 SHA) | 脚本写,需加进 `.gitignore` |
|
||
| act_runner | `/usr/local/bin/act_runner` + `/home/ymy/.act_runner/{config.yaml,.runner}` | 你安装/注册(§4.2) |
|
||
| systemd 单元 | `/etc/systemd/system/act_runner.service` | 你用 sudo 安装(§4.2) |
|
||
| 工作流 | `.gitea/workflows/deploy.yml` | 仓库内,落地时才提交(§5.1) |
|
||
| 部署脚本 | `deploy/scripts/auto-deploy.sh` | 仓库内(§5.2) |
|
||
| 定制断言 | `customization/check.sh <base-url>` | 仓库内,新增(§5.3) |
|
||
|
||
---
|
||
|
||
## 4. 落地步骤
|
||
|
||
### 阶段 0 — 下载 runner(一次性,需要外网)
|
||
|
||
你的开发代理能通时执行(版本号落地时换成最新稳定版):
|
||
|
||
```bash
|
||
VER=0.2.13 # ← 以 https://dl.gitea.com/act_runner/ 或 gitea.com/gitea/act_runner/releases 为准
|
||
curl -fsSL -o /tmp/act_runner \
|
||
"https://dl.gitea.com/act_runner/${VER}/act_runner-${VER}-linux-arm64"
|
||
file /tmp/act_runner && sha256sum /tmp/act_runner # 期望: ELF 64-bit ARM aarch64
|
||
sudo install -m 0755 /tmp/act_runner /usr/local/bin/act_runner
|
||
act_runner --version
|
||
```
|
||
|
||
> 本机是 aarch64,务必取 `linux-arm64`。若代理拿不到,也可在有网的机器上下载后 `scp` 过来。
|
||
|
||
### 阶段 1 — 部署克隆
|
||
|
||
```bash
|
||
# 1) 让 ymy 能读 Gitea 的裸仓库(实测: -c safe.directory 对本机 git 无效, 必须写进配置文件)
|
||
git config --global --add safe.directory \
|
||
/srv/gitea/git/repositories/course-team/tjhlp-gitea.git
|
||
|
||
# 2) 从裸仓库克隆(免凭据): origin 就指向本机裸仓库, 后续 fetch 不再需要任何 token
|
||
git clone /srv/gitea/git/repositories/course-team/tjhlp-gitea.git \
|
||
/home/ymy/deploy/tjhlp-gitea
|
||
|
||
# 3) 复制部署密钥(不要把 .env 提交进仓库)
|
||
cd /home/ymy/deploy/tjhlp-gitea
|
||
cp /home/ymy/tjhlp-gitea/deploy/.env deploy/.env
|
||
chmod 600 deploy/.env
|
||
mkdir -p deploy/.state
|
||
|
||
# 4) 冒烟: 用手动脚本跑一次(此时还没接 CI)
|
||
./deploy/scripts/auto-deploy.sh # 落地脚本后才有; 先跑 verify.sh 确认现状 OK
|
||
```
|
||
|
||
注意:`deploy/.env` 从此有**两份**(dev 克隆一份、部署克隆一份)。约定:**部署克隆那份是权威**,
|
||
dev 克隆那份只服务本地预览;改密钥时两边同步(或把 dev 克隆的 `.env` 改成指向部署克隆的软链)。
|
||
|
||
### 阶段 2 — 安装并注册 runner
|
||
|
||
```bash
|
||
# 2.1 生成【仓库级】注册令牌(API 实测存在:
|
||
# POST /api/v1/repos/{owner}/{repo}/actions/runners/registration-token)
|
||
# 也可以在 仓库 → Settings → Actions → Runners 页面点按钮拿
|
||
TOKEN=$(curl -sS -X POST \
|
||
-H "Authorization: token <你的 PAT, 需要 repo 权限>" \
|
||
"https://cpp.tongji.sh/QA/api/v1/repos/course-team/tjhlp-gitea/actions/runners/registration-token" \
|
||
| python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')
|
||
|
||
# 2.2 注册
|
||
mkdir -p /home/ymy/.act_runner && cd /home/ymy/.act_runner
|
||
act_runner register --no-interactive \
|
||
--instance "https://cpp.tongji.sh/QA" \
|
||
--token "$TOKEN" \
|
||
--name "tjhlp-gitea-host" \
|
||
--labels "self-hosted:host"
|
||
ls -l .runner # 注册凭据, 别提交/别外传
|
||
```
|
||
|
||
`/home/ymy/.act_runner/config.yaml`:
|
||
|
||
```yaml
|
||
log:
|
||
level: info
|
||
runner:
|
||
file: .runner
|
||
capacity: 1 # 同一时刻只跑一个 job, 与部署必须串行的事实一致
|
||
timeout: 30m
|
||
labels:
|
||
- "self-hosted:host" # host 模式: 直接在运行 act_runner 的这台机器上执行
|
||
cache:
|
||
enabled: true
|
||
dir: /home/ymy/.act_runner/cache
|
||
```
|
||
|
||
`/etc/systemd/system/act_runner.service`(你用 sudo 安装):
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=Gitea Actions runner (tjhlp-gitea, host mode)
|
||
After=network-online.target docker.service
|
||
Wants=network-online.target
|
||
|
||
[Service]
|
||
User=ymy
|
||
Group=ymy
|
||
SupplementaryGroups=docker
|
||
WorkingDirectory=/home/ymy/.act_runner
|
||
Environment=PATH=/home/ymy/.local/bin:/usr/local/bin:/usr/bin:/bin
|
||
ExecStart=/usr/local/bin/act_runner daemon --config /home/ymy/.act_runner/config.yaml
|
||
Restart=always
|
||
RestartSec=5
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now act_runner
|
||
systemctl status act_runner --no-pager
|
||
journalctl -u act_runner -f # 之后调试看这里
|
||
```
|
||
|
||
注册成功后,仓库 → **Settings → Actions → Runners** 里应能看到 `tjhlp-gitea-host`(Idle)。
|
||
注册令牌用完即弃;runner 之后用 `.runner` 里的凭据通信,不会过期。
|
||
|
||
### 阶段 3 — 试运行(手动触发)
|
||
|
||
1. 提交 §5 的三个文件(workflow / auto-deploy.sh / check.sh),但 `on:` 里**先只留
|
||
`workflow_dispatch`**(没有 runner 时 push 触发会一直挂在"等待 runner");
|
||
2. 仓库 → Actions → deploy → **Run workflow**(选择 `main`);
|
||
3. 盯日志,确认:构建成功 → 容器重建 → 验证全过 → Actions 页面绿色;
|
||
4. 故意推一个坏提交(例如把一个 `overrides` 键写错)验证**回滚路径**确实生效。
|
||
|
||
### 阶段 4 — 打开自动触发 + 加保护
|
||
|
||
1. 把 `push: branches: [main]` 加回 workflow;
|
||
2. 仓库 → Settings → Branches → 给 `main` 加保护:**要求 PR + 至少 1 个 review**,
|
||
禁止直接 push(否则任何有写权限的人 push 一次就重启平台);
|
||
3. 在 `deploy/README.md` 的快速索引里把这条指过来(本方案已加)。
|
||
|
||
---
|
||
|
||
## 5. 流水线内容
|
||
|
||
### 5.1 `.gitea/workflows/deploy.yml`
|
||
|
||
刻意做得很薄:workflow 只负责"同步到目标提交 + 调仓库里的部署脚本",
|
||
真正的逻辑放在 `auto-deploy.sh`(可版本化、可手动跑、可在本地调试)。
|
||
|
||
```yaml
|
||
name: deploy
|
||
|
||
on:
|
||
push:
|
||
branches: [main]
|
||
workflow_dispatch: # 阶段 3 只留这个
|
||
|
||
concurrency:
|
||
group: deploy-main
|
||
cancel-in-progress: false
|
||
|
||
permissions:
|
||
contents: read
|
||
|
||
jobs:
|
||
deploy:
|
||
# 只认 main 的 push 或手动触发; 提交信息含 [skip deploy] 则跳过
|
||
if: >-
|
||
github.event_name == 'workflow_dispatch' ||
|
||
(github.ref == 'refs/heads/main' &&
|
||
!contains(github.event.head_commit.message, '[skip deploy]'))
|
||
runs-on: self-hosted
|
||
timeout-minutes: 30
|
||
steps:
|
||
- name: 同步到目标提交
|
||
run: |
|
||
set -euo pipefail
|
||
cd /home/ymy/deploy/tjhlp-gitea
|
||
git fetch --prune origin
|
||
git checkout --detach "${{ github.sha }}"
|
||
- name: 构建并部署(失败自动回滚)
|
||
run: |
|
||
set -euo pipefail
|
||
export PATH=/home/ymy/.local/bin:/usr/local/bin:/usr/bin:/bin
|
||
/home/ymy/deploy/tjhlp-gitea/deploy/scripts/auto-deploy.sh
|
||
```
|
||
|
||
要点:
|
||
|
||
- **不写 `uses:`**:离线环境拿不到 `actions/checkout` 等 action(`DEFAULT_ACTIONS_URL`
|
||
默认指向 github.com)。同步代码用 `run:` 里的 `git` 就够了;
|
||
- `checkout --detach ${{ github.sha }}` 保证部署的就是这次推送的提交(而不是"恰好 fetch 到的 main");
|
||
- 脚本是在**同步之后**才被调用的,所以每次跑的都是目标提交里的新脚本;
|
||
- `timeout-minutes` / `concurrency` / `permissions` 在 1.27 的支持情况见 §9(落地时验证)。
|
||
|
||
### 5.2 `deploy/scripts/auto-deploy.sh`
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
# main 自动部署。由 .gitea/workflows/deploy.yml 调用, 也可手工执行:
|
||
# ./auto-deploy.sh # 部署当前 checkout
|
||
# ./auto-deploy.sh <sha> # 部署指定提交
|
||
set -euo pipefail
|
||
|
||
REPO_DIR=$(cd "$(dirname "$0")/../.." && pwd)
|
||
STATE_DIR="${REPO_DIR}/deploy/.state"
|
||
STATE_FILE="${STATE_DIR}/last-deployed"
|
||
PUBLIC_URL="${GITEA_PUBLIC_URL:-http://10.80.42.185/QA}"
|
||
|
||
# 本机回环验证不能走代理, 否则 mihomo 会拿 502 冒充故障(见 README 陷阱 5)
|
||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
|
||
export no_proxy='*' NO_PROXY='*'
|
||
export PATH=/home/ymy/.local/bin:/usr/local/bin:/usr/bin:/bin
|
||
|
||
mkdir -p "$STATE_DIR"
|
||
TARGET=${1:-$(git -C "$REPO_DIR" rev-parse HEAD)}
|
||
PREV=$(cat "$STATE_FILE" 2>/dev/null || true)
|
||
|
||
# 双保险: workflow 的 concurrency + 这里的 flock
|
||
exec 9>"${STATE_DIR}/lock"
|
||
flock -n 9 || { echo "[auto-deploy] 已有部署在跑, 退出"; exit 0; }
|
||
|
||
echo "[auto-deploy] 目标 ${TARGET} (上次成功: ${PREV:-无})"
|
||
cd "$REPO_DIR"
|
||
|
||
deploy() {
|
||
python3 customization/build.py # 生成语言文件 + 规范 custom/ 权限(容器用户要能读)
|
||
python3 customization/build.py --check # 生成物/权限校验, 不过就中止, 不碰容器
|
||
( cd deploy && docker compose up -d ) # 幂等: 只有配置/镜像变化时才重建
|
||
}
|
||
|
||
verify() {
|
||
( cd deploy && ./scripts/verify.sh ) # 容器健康 + 本机 API + 经 Apache 反代
|
||
customization/check.sh "$PUBLIC_URL" # 定制断言: 首页/登录页/OIDC/术语(见 5.3)
|
||
}
|
||
|
||
rollback() {
|
||
[[ -z "${PREV}" ]] && { echo "[auto-deploy] 无历史版本可回退, 保持现状"; return 0; }
|
||
echo "[auto-deploy] 回滚到 ${PREV}"
|
||
git checkout --detach "$PREV"
|
||
deploy || true
|
||
verify || true
|
||
}
|
||
|
||
if deploy && verify; then
|
||
echo "$TARGET" > "$STATE_FILE"
|
||
echo "[auto-deploy] ✅ 部署成功 ${TARGET}"
|
||
else
|
||
echo "[auto-deploy] ❌ 部署或验证失败, 开始回滚"
|
||
rollback
|
||
exit 1 # 让 Actions 里的这次运行标红, 日志留在 UI 里
|
||
fi
|
||
```
|
||
|
||
落库前要做的两件小事:
|
||
|
||
- `.gitignore` 加 `deploy/.state/`;
|
||
- `deploy/scripts/auto-deploy.sh` 加可执行位(`git` 只记可执行位,写文件时别丢)。
|
||
|
||
也**不做**的事,以及理由:
|
||
|
||
- 每次部署不做数据库备份:部署只改代码/配置,DB 不动;`deploy/backups/` 是 `root:root`
|
||
(CI 以 `ymy` 跑,写不进去)。版本升级依旧人工走 README §7;
|
||
- 不自动重推 `issue-templates`:那是运营动作,不该跟代码推送耦合。
|
||
|
||
### 5.3 新增 `customization/check.sh <base-url>`
|
||
|
||
现在 `preview.sh check` 里的断言(首页文案、页脚、meta、静态页、官网链接、`工单` 不出现、
|
||
登录页两张卡片、无通行密钥方框)正是"定制有没有生效"的证据,但它们写死在预览脚本里。
|
||
落地时把它抽出来,让预览与生产共用:
|
||
|
||
```bash
|
||
customization/check.sh http://127.0.0.1:2081 # 预览
|
||
customization/check.sh https://cpp.tongji.sh/QA # 生产(CI 里调)
|
||
```
|
||
|
||
生产侧额外加两条(今天踩过的坑,必须自动化守住):
|
||
|
||
```bash
|
||
# 1) OIDC 认证源注册成功: 必须是 307 跳转到统一身份认证, 404 = 认证源没注册上
|
||
curl -sS --noproxy '*' -o /dev/null -w '%{http_code} %{redirect_url}\n' \
|
||
"${BASE}/user/oauth2/%E9%AB%98%E7%A8%8B%E7%BB%9F%E4%B8%80%E8%BA%AB%E4%BB%BD%E8%AE%A4%E8%AF%81"
|
||
# 2) 登录页两张卡片 + 没有 passkey 空方框
|
||
curl -sS --noproxy '*' -H 'Accept-Language: zh-CN' "${BASE}/user/login" | grep -c '管理员登录'
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 失败与回滚
|
||
|
||
| 失败点 | 行为 |
|
||
|---|---|
|
||
| `build.py` 报错(overrides 键不存在/占位符改坏/文件不可读) | 立即中止,**不碰容器**,Actions 标红 |
|
||
| `docker compose up -d` 失败(配置语法/镜像缺失) | 同一提交重试无意义 → 直接回滚 |
|
||
| 容器起不来(模板报错、权限 600 之类的 `[F]`) | `verify.sh` 会等到 start_period 结束仍非 healthy → 判失败 → 回滚 |
|
||
| 验证断言失败(首页文案丢了、OIDC 404、出现「工单」) | 判失败 → 回滚 |
|
||
| 回滚也失败 | 脚本打印现场并 `exit 1`;平台上仍是坏版本,需要人工介入(`journalctl -u act_runner` + `docker compose logs`) |
|
||
| runner 掉线/未注册 | 推送后 Actions 里显示"等待 runner",**不会**部署,也不会影响线上;`systemctl status act_runner` 恢复 |
|
||
|
||
回滚是 `git checkout --detach <上一个成功 SHA>` + 重新 `up -d`,只动代码/挂载文件;
|
||
数据库、`/srv/gitea` 数据、`.env` 全程不参与,所以回滚很快(约几十秒)。
|
||
|
||
---
|
||
|
||
## 7. 安全
|
||
|
||
- **host 模式 = 这些命令以 `ymy` 身份在宿主执行,而 `ymy` 在 `docker` 组里(等价 root)。**
|
||
所以:
|
||
|
||
1. runner 只注册成**仓库级**(`/repos/{owner}/{repo}/actions/runners/registration-token`),
|
||
不要注册成 instance/org 级 —— 否则组织里任何仓库都能用这个 runner 执行宿主命令;
|
||
2. `main` 必须开分支保护(PR + review)。本仓库的贡献者是课程团队,属于可信范围,
|
||
但"谁都能 push 就谁能 root 宿主"这条要写明白;
|
||
3. **落地前必须确认 fork PR 的工作流策略**(§9):如果 Gitea 允许 fork PR 直接跑
|
||
workflow 且无需批准,那么外部 PR 就等于任意代码执行。确认之前不要把仓库开放给
|
||
不可信的外部贡献者;若策略不可控,退化为 §10 的 cron 轮询方案(不执行仓库里的代码,
|
||
只跑宿主上的固定脚本);
|
||
4. `[skip deploy]`、`if:` 这些是**防误操作**,不是安全边界;真正的边界是"谁能写这个仓库"。
|
||
|
||
- 凭据最小化:部署流程**不需要任何 git token**(从本机裸仓库 fetch);生成注册令牌用的 PAT
|
||
只在阶段 2 用一次,用完即可吊销。Actions secrets/variables 的 API 在 1.27 里也有
|
||
(`/repos/{owner}/{repo}/actions/secrets`),将来要通知(例如发 Issue)再用。
|
||
|
||
- `act_runner` 本体是外部二进制:落地时核对 `sha256sum`,并记录版本号(升级方式同 Gitea,
|
||
写进 README 的升级章节)。
|
||
|
||
---
|
||
|
||
## 8. 日常操作
|
||
|
||
```bash
|
||
# 手动部署当前 main(不依赖 Actions / 不依赖 runner)
|
||
/home/ymy/deploy/tjhlp-gitea/deploy/scripts/auto-deploy.sh
|
||
|
||
# 回滚到指定提交
|
||
cd /home/ymy/deploy/tjhlp-gitea && git checkout --detach <sha> && ./deploy/scripts/auto-deploy.sh
|
||
|
||
# 临时停掉自动部署
|
||
sudo systemctl stop act_runner # 或仓库 Settings → Actions → Runners 里停用
|
||
|
||
# 看 runner 日志 / 部署日志
|
||
journalctl -u act_runner -f
|
||
docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea
|
||
# 也可以直接在仓库 Actions 标签里看每次运行的完整日志
|
||
```
|
||
|
||
⚠️ **切换后不要再从 dev 克隆 `/home/ymy/tjhlp-gitea` 执行 `docker compose up -d`**:
|
||
compose 项目名虽然同为 `gitea`(同一组容器),但 bind mount 的源路径按 compose 文件所在目录解析,
|
||
从 dev 克隆 up 会把挂载指回 dev 克隆,和 CI 部署的版本打架。dev 克隆只用于开发与预览。
|
||
|
||
---
|
||
|
||
## 9. 待落地确认项(我无法在离线环境验证的)
|
||
|
||
1. **`act_runner` 的 host 标签语法**:本方案用 `labels: ["self-hosted:host"]`。落地时以该版本
|
||
`act_runner` 的官方 README 为准;**若不支持 host 模式**,退化为容器模式,需要额外准备:
|
||
给 runner 容器挂 `/var/run/docker.sock`、以同路径挂载部署克隆(`-v /home/ymy/deploy:/home/ymy/deploy`)、
|
||
并准备一个含 `bash`/`git`/`python3`/`docker` CLI 的 job 镜像(离线要 `docker save` 导入)。
|
||
2. **fork PR 的 workflow 审批行为**:用一个测试 fork 发 PR 验证;在此之前按 §7 第 3 条处理。
|
||
3. **workflow 语法支持面**:`concurrency`、`timeout-minutes`、`permissions`、job 级 `if` 里
|
||
的 `contains(...)` 在 1.27 的 Actions 实现里是否都生效(用 `workflow_dispatch` 试)。
|
||
4. **Actions 日志/产物保留**:`[actions] LOG_RETENTION_DAYS`(默认 365)与本地存储路径,
|
||
以及是否需要限制大小。
|
||
5. **`github.sha` / `github.event.head_commit.message`** 在本版本 runner 上的取值(试运行时打印一次确认)。
|
||
6. **Gitea 侧是否有"环境审批"**(deployments/environments 需要人工批准)—— 若有,可作为
|
||
"自动部署但上线需点一下"的中间档。
|
||
|
||
---
|
||
|
||
## 10. 备选方案
|
||
|
||
| 方案 | 何时选 | 代价 |
|
||
|---|---|---|
|
||
| **cron 轮询 + `auto-deploy.sh`** | runner 装不上(无外网),或 §9.2 的 fork PR 策略不可控 | 延迟 ≤60s;无 UI/日志,只有落盘日志;`ymy` 的 crontab 一行搞定,不需要 root |
|
||
| **容器模式 runner** | 将来有了稳定外网与可用的 job 镜像 | 要维护镜像 + docker socket 暴露给 runner 容器 |
|
||
| **纯手工** | 推送频率低、想每次都人工确认 | 就是现在这样 |
|
||
|
||
cron 版的差别只有触发那一步(其余复用 §5.2 的脚本):
|
||
|
||
```cron
|
||
# crontab -e (ymy)
|
||
* * * * * cd /home/ymy/deploy/tjhlp-gitea && git fetch -q origin main && \
|
||
[ "$(git rev-parse origin/main)" != "$(cat deploy/.state/last-deployed 2>/dev/null)" ] && \
|
||
./deploy/scripts/auto-deploy.sh "$(git rev-parse origin/main)" >> deploy/.state/cron.log 2>&1
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 落地顺序(一句话版)
|
||
|
||
```text
|
||
阶段 0 下载 act_runner(要外网) → 阶段 1 建部署克隆 → 阶段 2 sudo 装 systemd 单元并注册
|
||
→ 阶段 3 只留 workflow_dispatch 手动跑通 + 演练一次回滚 → 阶段 4 打开 push 触发 + main 分支保护
|
||
```
|