之前测的是错的: 我把 --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 自动注入的结论不变。
21 KiB
CI/CD:main 自动部署(Gitea Actions 方案)
状态:方案,尚未落地。 全流程不需要 root(
ymy在docker组即可), 只需要一次「在 Gitea 页面/API 上拿注册令牌」的动作。本文标注 [实测] 的结论都是 2026-09-13 在本机跑出来的,命令写在对应位置,可复现。 相关文档:deploy/README.md(部署与陷阱)、 customization/README.md(定制机制与预览)。
0. 目标
course-team/tjhlp-gitea 的 main 一有推送,就自动把平台更新到那个提交:
构建定制产物 → 重建容器 → 跑验证 → 失败自动回滚。人工只负责 review 和 push。
不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 README §7 人工流程)、
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 架构
开发者 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 写法,两个事实由此确认:
# 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
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:
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 试运行(手动触发)
- 提交 §5 的文件,workflow 的
on:先只留workflow_dispatch(没有 runner 时 push 触发 会一直挂在"等待 runner"); - 仓库 → Actions → deploy → Run workflow(选
main); - 盯日志确认:构建 →
up -d→ 验证全过 → Actions 绿色; - 故意推一个坏提交(例如把
overrides/locale_zh-CN.json的键写错)验证回滚路径真的生效。
4.4 打开自动触发 + 加保护
- 把
push: branches: [main]加回 workflow; - 仓库 → Settings → Branches → 给
main加保护:要求 PR + 至少 1 个 review; deploy/README.md的快速索引里已有一行指向本文档。
5. 流水线内容
5.1 .gitea/workflows/deploy.yml
刻意做得很薄:workflow 只做"同步到目标提交 + 调仓库里的部署脚本",逻辑都在
auto-deploy.sh(可版本化、可手工跑、可本地调试)。
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
#!/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、静态页、官网链接、
不出现「工单」、登录页两张卡、无通行密钥方框)正是部署后要守的东西。落地时把它抽出来共用:
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. 安全
-
job 容器里挂了
docker.sock,而docker组等价 root;host 模式(备选 B)更是直接以ymy在 宿主执行。所以:- runner 只注册成仓库级(
/repos/{owner}/{repo}/actions/runners/registration-token), 不要注册成 instance/org 级——否则组织里任何仓库都能用这个 runner 拿到宿主 root; main必须开分支保护(PR + review)。贡献者是课程团队,属于可信范围,但 "谁有写权限 = 谁能 root 宿主"这条要写明白;- 落地前确认 fork PR 的工作流策略(§9.1):若 fork PR 能不经批准直接跑 workflow, 等于把宿主 root 交给外部 PR;确认之前不要把仓库开放给不可信贡献者。若策略不可控, 退化为 §10 的 cron 轮询(只跑宿主上的固定脚本,不执行仓库里的代码);
[skip deploy]、if:是防误操作,不是安全边界。
- runner 只注册成仓库级(
-
凭据最小化:部署流程不需要任何 git token(从本机裸仓库 fetch);注册令牌一次性用完即弃; 只有将来要回写状态/发 Issue 时才需要 Actions secrets(1.27 支持仓库级
/repos/{owner}/{repo}/actions/secrets)。 -
gitea/act_runner镜像来自 Docker Hub 的官方组织仓库(本机 daemon 经代理拉取); 落地时记录 tag/digest,升级方式与 Gitea 同(写进 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
# 平台日志(部署后排查)
docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea
# 每次运行的完整日志在 仓库 → Actions 里
9. 待落地确认项
- fork PR 的 workflow 审批行为(安全前提):用一个测试 fork 发 PR 验证;在此之前按 §7.3 处理。
- job 镜像里有没有
git/python3:首次运行时确认;缺就换镜像(catthehacker/ubuntu:act-22.04实测 arm64 可用)或自建小镜像(rockylinux:8+ 国内源装git python3 docker-ce-cli)。 - workflow 语法支持面:
concurrency、timeout-minutes、permissions、job 级if里的contains(...)在 1.27 的实现里是否都生效(用workflow_dispatch试一次即知)。 github.sha/github.event.head_commit.message的取值(试运行时 echo 一次确认)。- Actions 日志保留与体积:
[actions] LOG_RETENTION_DAYS(默认 365)与存储位置。 - 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 分支保护