Files
tjhlp-gitea/deploy/ci-cd.md
T
admin a65970303f docs: 新增 CI/CD 方案(deploy/ci-cd.md): main 推送经 Gitea Actions 自动部署
只写方案, 不落地(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 快速索引加一行指向该文档。
2026-09-13 16:59:39 +08:00

480 lines
22 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 方案)
> **状态:方案,尚未落地。** 落地需要两步你现在才能做的事:① 一次可用的外网(下载
> `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 分支保护
```