SHA256
deploy / deploy (push) Successful in 4s
原来 runner 用 container.options 把 docker.sock / 部署克隆 / 裸库 / docker CLI
全局挂给【每个】job。这个 runner 上的任何 workflow(以后加的 PR 检查、测试)都因此
白拿 docker = root 等价能力。
改成:
* container.docker_host: "-" → 不再自动把 socket 挂进 job 容器
* 删掉全局 container.options 挂载
* 五项挂载(socket/部署克隆/裸库/docker CLI/compose 插件)由 deploy job 在 workflow
的 container.volumes 里自己申报
* 五项仍列在 container.valid_volumes 白名单里(不在表里的申报会被静默丢弃)
效果: 不申报的 job 默认是裸容器(实测看不到 /home/ymy/deploy 与 /srv/gitea)。
验证边界(诚实记录):
* Gitea 侧确认会把整个 job 的 YAML(含 container:)作为任务载荷发给 runner
—— services/actions/run.go 里 payload, _ := v.Marshal()
* act 侧确认会采纳 job 申报的 volumes —— act_runner exec 实测
* 但 `act_runner exec` 有自己的 --container-daemon-socket 默认值、也不读配置里的
valid_volumes/docker_host, 所以这两项只能靠一次真实运行确认; 失败模式是
"第一步 cd 就报错、线上不受影响"
579 lines
29 KiB
Markdown
579 lines
29 KiB
Markdown
# CI/CD:main 自动部署(Gitea Actions 方案)
|
||
|
||
> **状态:已落地并本地验证通过(2026-09-13),只差一次 `git push`。**
|
||
> runner 已注册、部署克隆已建、生产已切到部署克隆、整条部署路径(含真实 job 容器)
|
||
> 已在本机预演通过;推送 `main` 后第一次 CI 运行即接管。**全程不需要 root。**
|
||
>
|
||
> 本文标注 **[实测]** 的结论都是 2026-09-13 在本机跑出来的,命令写在对应位置,可复现。
|
||
> 当前进度与剩余动作见 §0.1。
|
||
> 相关文档:[deploy/README.md](README.md)(部署与陷阱,含本次踩到的 3 个坑)、
|
||
> [customization/README.md](../customization/README.md)(定制机制与预览)。
|
||
|
||
---
|
||
|
||
## 0. 目标
|
||
|
||
`course-team/tjhlp-gitea` 的 `main` 一有推送,就自动把平台更新到那个提交:
|
||
构建定制产物 → 重建容器 → 跑验证 → 失败自动回滚。人工只负责 review 和 push。
|
||
|
||
不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 人工流程)、
|
||
`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 架构
|
||
|
||
```text
|
||
开发者 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)
|
||
|
||
```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
|
||
# 不要在 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`:
|
||
|
||
```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`(可版本化、可手工跑、可本地调试)。
|
||
|
||
```yaml
|
||
# 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`
|
||
|
||
```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 容器里跑, 也能在宿主上跑: 脚本用 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)
|
||
|
||
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. 安全
|
||
|
||
### 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. 日常操作
|
||
|
||
```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
|
||
|
||
# ★ 改了 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 的脚本):
|
||
|
||
```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 分支保护
|
||
```
|