Files
tjhlp-gitea/deploy/ci-cd.md
T
admin 53116f7a23
deploy / deploy (push) Successful in 11s
fix(ci): 部署时必须重启 gitea —— 指纹要与上次成功部署比, 而不是 build.py 前后
事故经过(2026-09-22): 「提问指南」换地址那个提交推送后 CI 挂了, auto-deploy 回滚。
check.sh 报「没找到官网提问指南链接 / 仍有旧地址」—— 但脚本确实把部署克隆同步到了新
提交、语言文件也重新生成了。原来 deploy() 比较的是 build.py 运行【前后】的指纹: 那只能
发现语言文件被重新生成, 纯模板改动前后完全一样 → 从不重启 → 容器继续用启动时加载的旧
模板 → 断言失败 → 整个部署被判失败并回滚。也就是说: 任何只改模板的提交都必然挂 CI。

修法: 把指纹记在 deploy/.state/custom-hash 里, 与【上次成功部署】的指纹比较, 不同就
restart gitea(restart 而不是 up -d: compose 配置没变时 up -d 不重建容器)。rollback 路径
改成 deploy force 无条件重启 —— 失败的那次可能已经用新模板重启过容器, 回滚必须再重启
回去, 顺便也修好下面这个副作用。

顺带修一个 bind mount 的坑: 挂载【源目录】被「删掉再建」后容器里挂的还是旧 inode(空
目录)。这次事故里 public/ 下的文件被删光、git 顺手删掉空目录, 于是线上
/QA/assets/tjhlp/ask-guide.html 变成 404。已在预览上复现([B] 404 → restart 后 [C] 200),
restart 会重新解析挂载, 所以上面的修法同时把它修好。

验证(不碰生产的沙箱, 假 docker + 桩 verify/check):
  1 全新状态首次部署        → up -d + restart ✓
  2 什么都没改再部署        → 不重启 ✓
  3 只改一个模板文件        → 重启 ✓(这次的回归点)
  4 之后再来一次            → 不重启 ✓
  5 check 失败 → 回滚       → checkout PREV + 强制 restart ✓, 状态文件不被污染 ✓
另外 check.sh / preview.sh 的失败信息里加了「模板改动要重启才生效」的提示, 并把
ci-cd.md §5.2(脚本清单+为什么必须 restart)与 README §12 速查表同步更新。
2026-09-23 01:52:58 +08:00

31 KiB
Raw Blame History

CI/CD:main 自动部署(Gitea Actions 方案)

状态:已落地并本地验证通过(2026-09-13),只差一次 git push。 runner 已注册、部署克隆已建、生产已切到部署克隆、整条部署路径(含真实 job 容器) 已在本机预演通过;推送 main 后第一次 CI 运行即接管。全程不需要 root。

本文标注 [实测] 的结论都是 2026-09-13 在本机跑出来的,命令写在对应位置,可复现。 当前进度与剩余动作见 §0.1。 相关文档:deploy/README.md(部署与陷阱,含本次踩到的 3 个坑)、 customization/README.md(定制机制与预览)。


0. 目标

course-team/tjhlp-gitea 的 main 一有推送,就自动把平台更新到那个提交: 构建定制产物 → 重建容器 → 跑验证 → 失败自动回滚。人工只负责 review 和 push。

不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 README §7 人工流程)、 issue-templates 重新推送(运营操作)、官网仓库(Website)的部署(那是 GitHub Actions 的事)。

0.1 落地现状与剩余动作(更新到 2026-09-22)

CI/CD 已上线跑通。 action_run 表里共 5 次运行:前几次是打通路上的跳过/失败,最新一次 (HEAD 9954700)status=1(=Success),deploy/.state/last-deployed = 9954700 —— 生产 就是 CI 部署的版本。

项 证据
部署克隆 /home/ymy/deploy/tjhlp-gitea(origin = 本机裸仓库,免凭据) git remote -v;deploy/.env 600
runner 已注册 action_runner:tjhlp-gitea-1 / v0.6.1 / ["self-hosted"]
生产由 CI 部署 last-deployed = HEAD 的 SHA;action_run 最新一次 status=1
job 容器里工具齐全 act_runner exec 预演:Python 3.10.12 / git 2.55 / docker server 29.8.0 / compose v5.5.1

2026-09-21 打通时踩的三个坑(对应当天几次红色的运行):

  1. container.valid_volumes 为空表时,挂载会被静默丢弃(只打一行 ... is not a valid volume, will be ignored)→ job 容器里没有部署克隆,第一步 cd /home/ymy/deploy/tjhlp-gitea 就失败。修法:把要挂的路径列进白名单。
  2. 部署克隆的 origin 是宿主上的本地裸库(/srv/gitea/...),job 容器里没有它 → git fetch 报 "does not appear to be a git repository"。修法:把 /srv/gitea 只读挂进去。
  3. workflow 的 step 之间不共享工作目录,第二步要自己 cd 过去(actions/checkout 那种 "代码在当前目录"的心智模型在这里不成立)。

2026-09-22 本轮改动:把宿主能力从"runner 全局发给每个 job"收窄成"deploy job 自己申报":

  • container.docker_host: "-" → 不再自动把 docker socket 挂进 job 容器;
  • 删掉 container.options 里的全局挂载;
  • 五项挂载(部署克隆、/srv/gitea、socket、docker CLI、compose 插件)改为在 .gitea/workflows/deploy.yml 的 container.volumes 里申报,并全部列进 container.valid_volumes 白名单。

效果:将来加的 PR 检查/测试 job 默认是裸容器——没有宿主路径,也申报不了白名单之外的卷 (本机实测:不申报任何挂载的 job 看不到 /home/ymy/deploy 与 /srv/gitea)。socket 那一项 在真实调度路径上的确认方式与失败模式见 §9,其余残留见 §7.2。

剩余动作:

  1. 本轮改动要等一次 push 才能端到端验证(判据与回退方式见 §9 第 2 条)。
  2. 用一个测试 fork 发 PR,确认 fork PR 的 workflow 审批行为(§9);确认前不要把仓库 开放给不可信贡献者。
  3. 给 main 加分支保护(§4.4)。

1. 现状与约束 [实测]

项 实测值 对方案的影响
Gitea 1.27.3;Actions 默认开启(modules/setting/actions.go 里 Enabled: true),仓库页有 /actions 不用改配置就能用
已注册 runner 方案制定时无(现已注册,见 §0.1) 要自己起一个
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 架构

 开发者 push main
        │
        ▼
 Gitea (10.80.42.185/QA) ── 调度 workflow ──► act_runner(docker compose 服务, 容器)
        ▲                                          │  拉起 job 容器
        │ 日志/状态显示在仓库 Actions 标签            ▼
        └────────────────────  job 容器(network: host;宿主能力由 job 自己申报)
                                  ├─ 挂 docker.sock → 可执行 docker compose
                                  ├─ 挂 /home/ymy/deploy(同路径, 部署克隆)+ /srv/gitea(ro, 它的 origin)
                                  └─ 跑 auto-deploy.sh: build.py → up -d → verify → 失败回滚
                                     未申报的 job(将来的 PR 检查)拿不到上面任何一项

### 2.2 runner 形态:容器(推荐)vs 宿主二进制

| | **A. 容器(推荐)** | B. 宿主二进制 + host 模式 |
|---|---|---|
| 安装 | `docker compose up -d`(镜像实测可拉) | 下载二进制 + **需要 sudo** 装 systemd 单元 |
| job 执行 | job 容器(镜像由 label 决定) | 直接在宿主以 `ymy` 执行 |
| 工具依赖 | 靠 job 镜像(要确认镜像里有 git/python3/docker CLI) | 宿主现成,最省事 |
| 挂载 | 由 deploy job 在 `container.volumes` 里申报(受 runner 的 `valid_volumes` 白名单约束) | 无 |
| 开机自启 | 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)

# 让 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 页面点按钮):

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),然后:

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:

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
      # 不要在 env 里设 GITEA_RUNNER_LABELS: act_runner 会警告
      # "Labels from command will be ignored, use labels defined in config file.",
      # label 以 config.yaml 为准(实测)
      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:

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 都能直连
  docker_host: "-"       # 自动找 daemon, 但【不】把 socket 挂进 job 容器(要用 docker 的 job 自己申报)
  valid_volumes:         # 允许 job 申报的挂载白名单(glob 匹配挂载源路径; [] = 一个都不许)
    - /home/ymy/deploy
    - /srv/gitea
    - /var/run/docker.sock
    - /usr/bin/docker
    - /usr/libexec/docker/cli-plugins
  # 这里【故意不写】全局 options: 挂载由 deploy job 自己申报, 见 §5.1
  force_pull: false      # 镜像已有就别每次拉
cache:
  enabled: true

四处关键点:

  • 白名单管两头:job 申报的 container.volumes 和全局 options 里的 --volume 都要在 valid_volumes 里,否则被静默丢弃(... is not a valid volume, will be ignored), 2026-09-21 实际因此失败;
  • 同路径挂载 /home/ymy/deploy:docker compose 在 job 容器里把相对挂载解析成绝对路径后 交给宿主 daemon 执行,路径不一致会挂到空目录;
  • /srv/gitea 只读:部署克隆的 origin 是这个宿主路径下的裸库,job 容器里没有它就 git fetch 不了(2026-09-21 实际踩到);
  • 不把 docker.sock 写进全局 options:那等于每个 job 都拿到 root。改由 deploy job 自己申报,而 docker_host: "-" 保证它不会和"自动挂载"撞成 Duplicate mount point: /var/run/docker.sock。

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(可版本化、可手工跑、可本地调试)。

# main 推送后自动部署到 10.80.42.185/QA。
# 逻辑都在 deploy/scripts/auto-deploy.sh 里, 这里只负责"同步到目标提交 + 调脚本"。
# 详见 deploy/ci-cd.md。
name: deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

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
    # ★ 宿主能力(docker socket、部署克隆、裸库、docker CLI)由【本 job】申报,而不是由
    #   runner 全局发给每个 job。runner 侧的 container.valid_volumes 是允许清单:
    #   没列进去的挂载会被丢弃,所以这里的每一项都要在 deploy/runner/config.yaml 里有对应项。
    #   将来加 PR 检查/测试 workflow 时,那个 job 不申报就什么都拿不到(无 socket = 无 root)。
    container:
      volumes:
        - /home/ymy/deploy:/home/ymy/deploy              # 工作目录(auto-deploy.sh 要写 .state)
        - /srv/gitea:/srv/gitea:ro                       # deploy 克隆的 origin(本地裸库)
        - /var/run/docker.sock:/var/run/docker.sock      # docker compose up -d
        - /usr/bin/docker:/usr/bin/docker:ro             # 宿主 docker CLI
        - /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro  # compose 插件
    steps:
      - name: 同步到目标提交
        run: |
          set -euo pipefail
          cd /home/ymy/deploy/tjhlp-gitea
          git fetch --prune origin
          # -f: 部署克隆是 CI 独占的; 上一个已部署版本的 deploy/runner/* 等文件在本版本
          #     若已被跟踪, 会作为"未跟踪文件"挡住普通 checkout(实测)
          git checkout -f --detach "${{ github.sha }}"
          git --no-pager log --oneline -1
      - name: 构建并部署(失败自动回滚)
        run: |
          set -euo pipefail
          # 工作流没有 actions/checkout, 默认工作目录里没有代码; 上一步已把
          # 部署克隆同步到目标提交, 这里必须显式 cd 过去 (2026-09-21 实际踩到)。
          cd /home/ymy/deploy/tjhlp-gitea
          ./deploy/scripts/auto-deploy.sh

container.volumes 那一块是 2026-09-22 收窄授权的结果:需要宿主能力的只有这一个 job, 所以挂载在它这里申报;runner 侧的 valid_volumes 决定哪些申报能被接受。加新的 workflow (例如 PR 检查)时不需要、也不要给它申报这些卷 —— 它默认就是裸容器。

不写 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

#!/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 容器里跑, 也能在宿主上跑: 脚本用 pick_python() 自己挑一个 ≥3.7 的解释器
# (宿主 /usr/bin/python3 是 3.6, 见 README 陷阱 9), 不要写死某台机器的 pyenv 路径

mkdir -p "$STATE_DIR"
TARGET=${1:-$(git -C "$REPO_DIR" rev-parse HEAD)}
PREV=$(cat "$STATE_FILE" 2>/dev/null || true)
HASH_FILE="${STATE_DIR}/custom-hash"   # 上次成功部署时 custom/ 的指纹

exec 9>"${STATE_DIR}/lock"                      # workflow 的 concurrency 之外再加一道
flock -n 9 || { echo "[auto-deploy] 已有部署在跑, 退出"; exit 0; }

echo "[auto-deploy] 目标 ${TARGET} (上次成功: ${PREV:-无})"
cd "$REPO_DIR"

# customization/custom/ 的指纹: 模板、静态页、生成的语言文件都在里面, 都是启动时加载的
custom_hash() {
	(cd customization/custom && find . -type f -exec sha256sum {} + | sort | sha256sum | cut -d' ' -f1)
}

deploy() {                                  # deploy force = 无条件重启(回滚路径用)
	python3 customization/build.py          # 生成语言文件 + 规范 custom/ 权限(容器用户要能读)
	python3 customization/build.py --check  # 生成物/权限校验, 不过就中止, 不碰容器
	( cd deploy && docker compose up -d )   # 幂等: 只有配置/镜像变化时才重建
	# ★ 必须和【上次成功部署的指纹】比, 不能只比 build.py 前后 —— 后者只能发现语言
	#   文件变化, 纯模板改动前后一模一样, 于是永远不重启、容器继续用旧模板(详见下方说明)
	if [[ -n "${1:-}" || $(custom_hash) != "$(cat "$HASH_FILE" 2>/dev/null)" ]]; then
		( cd deploy && docker compose restart gitea )
	fi
}

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 force || true                    # 强制重启: 失败那次可能已用新模板重启过容器
	verify || true
}

if deploy && verify; then
	echo "$TARGET" > "$STATE_FILE"
	custom_hash > "$HASH_FILE"             # 记下这次成功部署的指纹, 供下次比较
	echo "[auto-deploy] ✅ 部署成功 ${TARGET}"
else
	echo "[auto-deploy] ❌ 部署或验证失败, 开始回滚"
	rollback
	exit 1        # 让这次 Actions 运行标红, 完整日志留在 UI 里
fi

为什么非要 restart(2026-09-22 踩到的坑):模板与语言文件是 Gitea 启动时加载的, 而 docker compose up -d 在 compose 配置没变时不会重建容器。最早的实现比较的是 build.py 运行前后的指纹——那只会在语言文件被重新生成时才变;纯模板改动(改文案、 换链接)前后完全一样,于是从不重启,容器继续用旧模板,check.sh 断言失败 → 整个部署 被判失败并回滚(「提问指南」换地址那个提交就是这样被回滚的)。改成把指纹记在 .state/custom-hash 里、与上次成功部署比较后,模板改动会触发重启。

restart 还顺带修一个 bind mount 的坑:挂载源目录被「删掉再建」(例如某个提交把 custom/public/ 下的文件删光了,git 顺手删掉空目录)后,容器里挂的仍是旧 inode, 看到的是一个空目录——只有重新 start 才会解析到新目录。同一次事故里线上的 /QA/assets/tjhlp/ask-guide.html 就是这么变成 404 的(已在预览上复现并验证 restart 能修)。 CI 若只更新了文档/脚本(custom/ 没动),指纹相同则不重启,省掉一次无谓的停机。

落库前的两个小动作:.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、静态页、官网链接、 不出现「工单」、登录页两张卡、无通行密钥方框)正是部署后要守的东西。落地时把它抽出来共用:

customization/check.sh http://127.0.0.1:2081   # 预览
customization/check.sh https://cpp.tongji.sh/QA  # 生产(CI 里调)

生产侧再加两条(今天踩过的坑,必须自动化守住):

# 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. 安全

7.1 收窄后的边界(2026-09-22 起)

runner 不再把宿主能力全局发给每个 job:

  • container.docker_host: "-":不把 docker socket 自动挂进 job 容器;
  • 需要宿主能力的是 deploy job 自己,它在 container.volumes 里申报五项挂载;
  • container.valid_volumes 是允许清单:申报了但不在表里的卷会被丢弃(不是报错), 所以这个 runner 上的任何 job 都挂不上 /、/etc、~/.ssh 之类。

也就是说,"能 root 宿主"从"这个 runner 上的所有 job"收窄成了"deploy job 加上白名单 里那五项"。将来加 PR 检查/测试 workflow 时,那些 job 默认是裸容器(实测:不申报任何挂载的 job 看不到 /home/ymy/deploy、/srv/gitea)。

7.2 仍然存在的残留(别当成"已经隔离了")

  1. 能 push workflow 的人 = 能 root 宿主。 job 容器里跑的是仓库里的脚本,而 deploy job 必须有 socket;main 的分支保护才是这条的实际控制点。 ⚠️ 另外 v0.6.1 不会剥离 job 自己申报的逃逸类 container.options(如 --privileged): 这是 runner 3.x 才有的行为(3.x 文档写明"会剥离并告警",v0.6.1 的 generate-config 里 没有这类说明)。所以升级 runner 到 3.x 值得排期——镜像 gitea/runner:3 已经存在, 配置键(valid_volumes/docker_host/container.network)也是同一套。
  2. container.network: host 是 runner 级设置,收窄不到单个 job:这个 runner 上的每个 job 都共享宿主网络,因此能访问宿主回环上的服务(例如 127.0.0.1:2080 的 Gitea)。 要收窄它,得把 --network host 挪到 deploy job 的 container.options,并把 verify.sh 的回环检查改成"连不上就跳过、只认公网 URL"——留作后续。
  3. fork PR 的策略仍未确认(§9):若 fork PR 能不经批准直接跑 workflow,等于把宿主 root 交给外部 PR;确认之前不要把仓库开放给不可信贡献者。
  4. [skip deploy]、if: 是防误操作,不是安全边界。

7.3 其余

  • runner 只注册成仓库级(/repos/{owner}/{repo}/actions/runners/registration-token), 不要注册成 instance/org 级——否则组织里任何仓库都能用这个 runner 拿到宿主 root。
  • 凭据最小化:部署流程不需要任何 git token(从本机裸仓库 fetch);注册令牌一次性用完即弃。
  • gitea/act_runner 镜像来自 Docker Hub 官方组织仓库;落地时记录 tag/digest(升级方式同 README)。

8. 日常操作

# 手动部署当前 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

# ★ 改了 deploy/runner/config.yaml 之后【必须重启 runner】才生效
#   (runner 只在启动时读一次配置; 只 `up -d` 不会重建容器)
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose restart runner
# ⚠️ 别让 deploy job 自己去重启 runner: 那等于掐断正在跑的这个 job
#   (重启日志里会出现 "cancelled in progress jobs during shutdown")。

# 平台日志(部署后排查)
docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea
# 每次运行的完整日志在 仓库 → Actions 里

9. 尚未验证的点(诚实清单)

已经被真实运行确认的(2026-09-21,共 5 次运行、最新一次成功):

  • Gitea 1.27 的调度、日志回传、concurrency、timeout-minutes、permissions、job 级 if + contains(github.event.head_commit.message, ...)、github.sha 都按预期工作;
  • job 镜像里有 git 2.55 / Python 3.10 / docker CLI;container.network: host 下回环与 10.80.42.185/QA 都通;docker compose 可用;
  • runner 配置里的 container.valid_volumes 会被真实调度路径采纳(09-21 那次失败正是 空白名单把挂载丢掉导致的)。

仍然未知:

  1. fork PR 的 workflow 审批行为(安全前提):用一个测试 fork 发 PR 验证;在此之前按 §7.2 第 3 条处理。
  2. 本轮收窄授权(2026-09-22)的端到端效果:docker_host: "-" + job 自己申报 container.volumes 这条路径,act_runner exec 验证不了——exec 有自己的 --container-daemon-socket 默认值、也不读配置里的 valid_volumes(实测:exec 里未授权 路径照样挂上、裸 job 照样有 socket),只能靠一次真实 push。判据:
    • 成功:运行变绿 + deploy/.state/last-deployed = 本次 SHA;
    • 失败:部署 job 在第一步 cd /home/ymy/deploy/tjhlp-gitea 就报错、线上不受影响 (挂载没挂上 = 什么都还没做)→ 说明 container.volumes 没被采纳,git revert 回退到 "全局 options + 白名单"的旧形态即可。
    • 想在生产路径上验证"裸 job 真的连 socket 也没有",需要临时加一个 on: workflow_dispatch 的探针 workflow(本机只验证了"没有宿主路径"这一半 ✓)。
  3. Actions 日志保留与体积:[actions] LOG_RETENTION_DAYS(默认 365)与存储位置。
  4. 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 的脚本):

# 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. 落地顺序(一句话版)

4.1 部署克隆 → 4.2 拿仓库级令牌 + docker compose 起 runner → 4.3 只留 workflow_dispatch
手动跑通并演练一次回滚 → 4.4 打开 push 触发 + main 分支保护