Files
tjhlp-gitea/deploy/ci-cd.md
T
admin ea3ad2bb31 docs: 修正 CI/CD 方案的前提 —— 本机可完整访问互联网
之前测的是错的: 我把 --noproxy '*' 和 -x 一起传给 curl, 等于把要测的代理关掉了,
再叠加当时的一过性网络抖动, 得出了"宿主与容器都上不了外网"的错误结论。重测(2026-09-13):

- 宿主: 国内直连 200, 境外经 127.0.0.1:7890 代理 200;
- 容器: 直连 dl.gitea.com 200 / api.github.com 200 / codeload 301
  (仅 github.com 主站直连会超时), 即容器本来就有网, 不需要代理;
- docker daemon 已配代理(/etc/systemd/system/docker.service.d/http-proxy.conf),
  镜像拉取正常: gitea/act_runner:latest 拉到 arm64 v0.6.1(69.3MB),
  docker.gitea.com/runner-images:ubuntu-22.04 等 job 镜像 manifest 均可取;
- 用 act_runner 镜像自带的 generate-config 确认了两个关键能力:
  label 支持 ":host"(宿主模式), container.network 支持 "host"。

据此重写 deploy/ci-cd.md:
- 主方案改为标准做法: runner 用 gitea/act_runner 容器 + compose 管理,
  job 跑在容器里(network: host, 同路径挂载部署克隆与 docker.sock),
  全程不需要 root(ymy 在 docker 组); 宿主二进制 + host 模式降为备选 B
- 去掉了"离线"带来的一堆绕路(一次性下载二进制、不能写 uses: 等);
  不写 uses: 仍保留, 但理由改成"本项目不需要 + 避开 github.com 主站直连超时",
  并给出需要时的 github_mirror / 代理两条路
- 待确认项从 6 条缩到 3 条实质问题(fork PR 审批、job 镜像工具、workflow 语法支持面)

同时修正 compose/README/.env.example 里"容器上不了外网"的措辞:
默认不用代理的真正理由是"容器直连就通、且宿主 7890 只监听回环容器不可达",
而不是"外网不通"。显式空值挡 compose 自动注入的结论不变。
2026-09-13 17:27:47 +08:00

461 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CI/CD:main 自动部署(Gitea Actions 方案)
> **状态:方案,尚未落地。** 全流程**不需要 root**(`ymy` 在 `docker` 组即可),
> 只需要一次「在 Gitea 页面/API 上拿注册令牌」的动作。
>
> 本文标注 **[实测]** 的结论都是 2026-09-13 在本机跑出来的,命令写在对应位置,可复现。
> 相关文档:[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` 重新推送(运营操作)、官网仓库(`Website`)的部署(那是 GitHub Actions 的事)。
---
## 1. 现状与约束 **[实测]**
| 项 | 实测值 | 对方案的影响 |
|---|---|---|
| Gitea | 1.27.3;Actions 默认开启(`modules/setting/actions.go` 里 `Enabled: true`),仓库页有 `/actions` | 不用改配置就能用 |
| 已注册 runner | **无**(`action_runner` 表空) | 要自己起一个 |
| `act_runner` 镜像 | `docker pull gitea/act_runner:latest` 成功:**arm64, v0.6.1, 69.3MB** | runner 用容器跑,**不需要 root** |
| job 镜像 | `docker.gitea.com/runner-images:ubuntu-22.04`(Gitea 官方, arm64 可用)、`catthehacker/ubuntu:act-22.04`(arm64, 压缩约 512MB)、`node:20-bookworm-slim`、`rockylinux:8` 的 manifest 都能取到 | 有现成镜像可跑容器模式 job |
| 宿主出网 | 国内直连 `200`;境外经代理 `200`(`https://dl.gitea.com/...`、`https://github.com` 经 `127.0.0.1:7890` 均 `200`) | 正常联网,不是离线环境 |
| 容器出网 | 容器内直连:`dl.gitea.com` `200`、`api.github.com` `200`、`codeload.github.com` `301`;**`github.com` 主站直连 12s 超时** | `uses: actions/checkout` 这类动作走 codeload/api 通常可以;主站要通就得给镜像或 `github_mirror` |
| docker daemon 代理 | `/etc/systemd/system/docker.service.d/http-proxy.conf` 里 `HTTP(S)_PROXY=http://127.0.0.1:7890` | 镜像拉取走代理,正常 |
| `ymy` 的组 | `ymy, wheel, git(982), docker(980)` | 容器方案不需要 sudo;host 模式才需要 |
| 裸仓库 | `/srv/gitea/git/repositories/course-team/tjhlp-gitea.git`,`drwxr-xr-x git:git`,`git ls-remote` 通(需 `safe.directory`,见 §4.1) | CI 可以**免凭据**取代码 |
| 现成积木 | `deploy/scripts/{verify,backup,restore}.sh`、`customization/build.py`、`preview.sh check` | 直接复用 |
---
## 2. 方案总览
### 2.1 架构
```text
开发者 push main
│
▼
Gitea (10.80.42.185/QA) ── 调度 workflow ──► act_runner(docker compose 服务, 容器)
▲ │ 拉起 job 容器
│ 日志/状态显示在仓库 Actions 标签 ▼
└──────────────────── job 容器(network: host)
├─ 挂 docker.sock → 可执行 docker compose
├─ 挂 /home/ymy/deploy(同路径)→ 部署克隆
└─ 跑 auto-deploy.sh: build.py → up -d → verify → 失败回滚
```
### 2.2 runner 形态:容器(推荐)vs 宿主二进制
| | **A. 容器(推荐)** | B. 宿主二进制 + host 模式 |
|---|---|---|
| 安装 | `docker compose up -d`(镜像实测可拉) | 下载二进制 + **需要 sudo** 装 systemd 单元 |
| job 执行 | job 容器(镜像由 label 决定) | 直接在宿主以 `ymy` 执行 |
| 工具依赖 | 靠 job 镜像(要确认镜像里有 git/python3/docker CLI) | 宿主现成,最省事 |
| 挂载 | 靠 `container.options` 把 docker.sock 与部署克隆按**同路径**挂进 job 容器 | 无 |
| 开机自启 | compose 的 `restart: unless-stopped` | systemd |
| 结论 | **默认选它**:不需要 root、标准、日志清晰 | 想少一层容器、且你愿意跑一次 sudo 时选它 |
act_runner v0.6.1 自己的 `generate-config` 输出里明确写了两种 label 写法,两个事实由此确认:
```text
# Like: "macos-arm64:host" or "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
labels:
- "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
container:
# Could be host, bridge or the name of a custom network.
network: ""
```
即 **`:host` 支持**(备选 B 可用)、**`container.network: host` 支持**(方案 A 里让 job 容器
能和宿主共用回环,`verify.sh` 里 `127.0.0.1:2080` 的检查才继续有效)。
### 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` |
| runner | `deploy/runner/compose.yaml` + `deploy/runner/config.yaml` + `deploy/runner/data/`(gitignore) | 新增到仓库 |
| 工作流 | `.gitea/workflows/deploy.yml` | 新增到仓库(§5.1) |
| 部署脚本 | `deploy/scripts/auto-deploy.sh` | 新增到仓库(§5.2) |
| 定制断言 | `customization/check.sh <base-url>` | 新增到仓库(§5.3) |
---
## 4. 落地步骤
### 4.1 部署克隆(不需要 root)
```bash
# 让 ymy 能读 Gitea 的裸仓库。
# ★ 实测: git -c safe.directory=... 对本机 git 无效, 必须写进配置文件才生效。
git config --global --add safe.directory \
/srv/gitea/git/repositories/course-team/tjhlp-gitea.git
# 从裸仓库克隆: origin 就指向本机裸仓库, CI 全程不需要任何 git token
git clone /srv/gitea/git/repositories/course-team/tjhlp-gitea.git \
/home/ymy/deploy/tjhlp-gitea
cd /home/ymy/deploy/tjhlp-gitea
cp /home/ymy/tjhlp-gitea/deploy/.env deploy/.env # 部署密钥, 别提交
chmod 600 deploy/.env
mkdir -p deploy/.state
```
> ⚠️ 从此 `deploy/.env` 有**两份**(dev 克隆一份、部署克隆一份)。约定:**部署克隆那份是权威**,
> dev 克隆那份只服务本地预览;改密钥时两边同步。
>
> ⚠️ 切换后**不要再从 dev 克隆 `up -d`**:compose 项目名同为 `gitea`(同一组容器),但 bind mount
> 的源路径按 compose 文件所在目录解析,两边会互相覆盖。dev 克隆只留开发与预览。
### 4.2 起 runner 并注册(不需要 root)
先在 Gitea 上拿一个**仓库级**注册令牌(API 实测存在:
`POST /api/v1/repos/{owner}/{repo}/actions/runners/registration-token`;
也可以在 仓库 → Settings → Actions → Runners 页面点按钮):
```bash
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"])'
```
把令牌写进 `deploy/runner/.env`(gitignore),然后:
```bash
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner
docker compose up -d
docker compose logs -f runner # 看到 "runner registered successfully" 即可
```
仓库 → Settings → Actions → Runners 里应出现 `tjhlp-gitea-1`(Idle)。注册令牌用完即弃:
注册结果存在 `deploy/runner/data/.runner`,之后 runner 用它通信,不会过期。
`deploy/runner/compose.yaml`:
```yaml
name: gitea-runner
services:
runner:
image: gitea/act_runner:latest # 实测 arm64 / v0.6.1 / 可拉取
restart: unless-stopped
environment:
# 这组变量名来自镜像里的 /usr/local/bin/run.sh(实测)
GITEA_INSTANCE_URL: https://cpp.tongji.sh/QA
GITEA_RUNNER_REGISTRATION_TOKEN: ${RUNNER_REGISTRATION_TOKEN:?先按 §4.2 拿令牌}
GITEA_RUNNER_NAME: tjhlp-gitea-1
GITEA_RUNNER_LABELS: self-hosted
CONFIG_FILE: /config/config.yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock # runner 用它拉起 job 容器
- ./data:/data # 注册凭据 (.runner)
- ./config.yaml:/config/config.yaml:ro
```
`deploy/runner/config.yaml`:
```yaml
log:
level: info
runner:
file: /data/.runner
capacity: 1 # 部署必须串行, 一个 job 一个 job 地跑
timeout: 30m
labels:
# job 跑在容器里; 镜像换成本地已有/更小的亦可(如 catthehacker/ubuntu:act-22.04)
- "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-22.04"
container:
network: host # job 容器与宿主共用网络: 127.0.0.1:2080 与 10.80.42.185 都能直连
options: >-
--volume /home/ymy/deploy:/home/ymy/deploy
--volume /usr/bin/docker:/usr/bin/docker:ro
--volume /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro
force_pull: false # 镜像已有就别每次拉
cache:
enabled: true
```
三处关键点:
- `--volume /home/ymy/deploy:/home/ymy/deploy` **必须同路径**:`docker compose` 在 job 容器里
把相对挂载解析成绝对路径后交给宿主 daemon 执行,路径不一致会挂到空目录;
- 挂 `/usr/bin/docker` 与 `cli-plugins` 是为了不依赖 job 镜像里有没有 docker CLI / compose 插件
(宿主是 glibc,Ubuntu 镜像能用;落地时若镜像自带,也可以去掉这两行);
- `docker.sock` 会被 act_runner 自动挂进 job 容器(`container.docker_host` 默认行为),
上面仍显式挂一次更直观。
### 4.3 试运行(手动触发)
1. 提交 §5 的文件,workflow 的 `on:` **先只留 `workflow_dispatch`**(没有 runner 时 push 触发
会一直挂在"等待 runner");
2. 仓库 → Actions → deploy → **Run workflow**(选 `main`);
3. 盯日志确认:构建 → `up -d` → 验证全过 → Actions 绿色;
4. 故意推一个坏提交(例如把 `overrides/locale_zh-CN.json` 的键写错)验证**回滚路径**真的生效。
### 4.4 打开自动触发 + 加保护
1. 把 `push: branches: [main]` 加回 workflow;
2. 仓库 → Settings → Branches → 给 `main` 加保护:**要求 PR + 至少 1 个 review**;
3. `deploy/README.md` 的快速索引里已有一行指向本文档。
---
## 5. 流水线内容
### 5.1 `.gitea/workflows/deploy.yml`
刻意做得很薄:workflow 只做"同步到目标提交 + 调仓库里的部署脚本",逻辑都在
`auto-deploy.sh`(可版本化、可手工跑、可本地调试)。
```yaml
name: deploy
on:
push:
branches: [main]
workflow_dispatch: # 阶段 4.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
./deploy/scripts/auto-deploy.sh
```
**不写 `uses:`** 的理由:本项目不需要——代码从本机裸仓库取、部署逻辑是仓库里的脚本,
省掉每次运行下载 action 的开销,也避开 `github.com` 主站直连超时带来的不确定性。
将来若要做 PR 检查(lint/pytest)想用现成 action,两条路:给 runner 容器配容器可达的代理,
或在 runner 的 `config.yaml` 里设置 `github_mirror`(v0.6.1 的配置注释里就是为"特殊网络环境"
准备的),把 `uses:` 的 github 地址替换成镜像。
### 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}"
# 本机回环验证不能走代理, 否则会拿 502 冒充故障(见 README 陷阱 5)
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
export no_proxy='*' NO_PROXY='*'
# 既能在 job 容器里跑, 也能在宿主上跑; 不要写死某台机器的 pyenv 路径
export PATH="/usr/local/bin:/usr/bin:/bin:${PATH}"
mkdir -p "$STATE_DIR"
TARGET=${1:-$(git -C "$REPO_DIR" rev-parse HEAD)}
PREV=$(cat "$STATE_FILE" 2>/dev/null || true)
exec 9>"${STATE_DIR}/lock" # workflow 的 concurrency 之外再加一道
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/runner/data/`、
`deploy/runner/.env`;给 `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`;线上仍是坏版本,需要人工介入(`docker compose logs`) |
| runner 掉线 | 推送后 Actions 显示"等待 runner",**不会**部署、也不影响线上;`docker compose up -d` 恢复 |
回滚 = `git checkout --detach <上一个成功 SHA>` + 重新 `up -d`,只动代码与挂载文件;
数据库、`/srv/gitea` 数据、`.env` 全程不参与,所以几十秒内完成。
---
## 7. 安全
- job 容器里挂了 `docker.sock`,而 `docker` 组等价 root;host 模式(备选 B)更是直接以 `ymy` 在
宿主执行。所以:
1. runner 只注册成**仓库级**(`/repos/{owner}/{repo}/actions/runners/registration-token`),
不要注册成 instance/org 级——否则组织里任何仓库都能用这个 runner 拿到宿主 root;
2. `main` 必须开分支保护(PR + review)。贡献者是课程团队,属于可信范围,但
"谁有写权限 = 谁能 root 宿主"这条要写明白;
3. **落地前确认 fork PR 的工作流策略**(§9.1):若 fork PR 能不经批准直接跑 workflow,
等于把宿主 root 交给外部 PR;确认之前不要把仓库开放给不可信贡献者。若策略不可控,
退化为 §10 的 cron 轮询(只跑宿主上的固定脚本,不执行仓库里的代码);
4. `[skip deploy]`、`if:` 是防误操作,不是安全边界。
- 凭据最小化:部署流程**不需要任何 git token**(从本机裸仓库 fetch);注册令牌一次性用完即弃;
只有将来要回写状态/发 Issue 时才需要 Actions secrets(1.27 支持仓库级
`/repos/{owner}/{repo}/actions/secrets`)。
- `gitea/act_runner` 镜像来自 Docker Hub 的官方组织仓库(本机 daemon 经代理拉取);
落地时记录 tag/digest,升级方式与 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
# runner 启停 / 看日志
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose logs -f runner
docker compose stop runner && docker compose start runner
# 平台日志(部署后排查)
docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea
# 每次运行的完整日志在 仓库 → Actions 里
```
---
## 9. 待落地确认项
1. **fork PR 的 workflow 审批行为**(安全前提):用一个测试 fork 发 PR 验证;在此之前按 §7.3 处理。
2. **job 镜像里有没有 `git`/`python3`**:首次运行时确认;缺就换镜像(`catthehacker/ubuntu:act-22.04`
实测 arm64 可用)或自建小镜像(`rockylinux:8` + 国内源装 `git python3 docker-ce-cli`)。
3. **workflow 语法支持面**:`concurrency`、`timeout-minutes`、`permissions`、job 级 `if` 里的
`contains(...)` 在 1.27 的实现里是否都生效(用 `workflow_dispatch` 试一次即知)。
4. **`github.sha` / `github.event.head_commit.message`** 的取值(试运行时 echo 一次确认)。
5. **Actions 日志保留与体积**:`[actions] LOG_RETENTION_DAYS`(默认 365)与存储位置。
6. **Gitea 是否支持"环境审批"**:若有 deployments/environments 的审批,可作为
"自动部署但上线要点一下"的中间档。
---
## 10. 备选方案
| 方案 | 何时选 | 代价 |
|---|---|---|
| **B. 宿主二进制 + host 模式** | 不想给 job 容器挂 docker.sock / 不想维护 job 镜像 | 需要一次 sudo 装 systemd 单元;label 用 `self-hosted:host`(v0.6.1 配置里确认支持) |
| **cron 轮询 + `auto-deploy.sh`** | fork PR 策略不可控,或不想让仓库里的代码在宿主上执行 | 延迟 ≤60s;无 UI/日志,只有落盘日志 |
| **纯手工** | 推送频率低、每次都想人工确认 | 就是现在这样 |
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
4.1 部署克隆 → 4.2 拿仓库级令牌 + docker compose 起 runner → 4.3 只留 workflow_dispatch
手动跑通并演练一次回滚 → 4.4 打开 push 触发 + main 分支保护
```