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 自动注入的结论不变。
This commit is contained in:
2026-09-13 17:27:47 +08:00
parent a65970303f
commit ea3ad2bb31
5 changed files with 217 additions and 236 deletions
+1 -1
View File
@@ -68,7 +68,7 @@ services:
# --- 出站代理: 显式给值挡掉自动注入, 默认不用代理 ---------------------
# compose 会把宿主 shell 的 http_proxy(本机是 127.0.0.1:7890, 在容器里指向
# 容器自己)自动注入; 生产上这会直接让 OIDC discovery 失败(登录 404)。
# 预览与生产都不需要出站代理, 理由见 deploy/compose.yaml 同位置注释。
# 容器直连外网本身是通的(实测), 不需要代理; 理由见 deploy/compose.yaml 同位置注释。
HTTP_PROXY: ${GITEA_HTTP_PROXY:-}
HTTPS_PROXY: ${GITEA_HTTPS_PROXY:-}
http_proxy: ${GITEA_HTTP_PROXY:-}
+3 -3
View File
@@ -34,9 +34,9 @@ GITEA_CUSTOM_DIR=../customization/custom
# * compose 会把「运行 compose 的 shell」里的 http_proxy 自动注入容器, 而本机登录
# shell 里是 127.0.0.1:7890 —— 那个地址在容器里是容器自己, 一旦被注入, Gitea
# 启动时 OIDC discovery 就失败, 统一身份认证登录 404; 显式给空值能挡住注入。
# * 平台本身不需要出站代理: 唯一与功能相关的出站(OIDC)目标是 10.80.42.185,
# 容器内直连即可; 会访问外网的只有「检查更新」(纯提示)和个别学生仓库的 webhook。
# 将来若配了稳定且【容器可达】的代理, 在这里给出即可(别写 127.0.0.1):
# * 容器【直连外网是通的】(实测 dl.gitea.com / api.github.com / codeload 都能直连),
# 平台功能相关的出站(OIDC)也在内网直连, 所以不需要代理。
# 将来若确实要给容器配代理, 必须是【容器可达】的地址(别写 127.0.0.1, 那是容器自己):
# -----------------------------------------------------------------------------
#GITEA_HTTP_PROXY=https://cpp.tongji.sh:7890
#GITEA_HTTPS_PROXY=https://cpp.tongji.sh:7890
+9 -8
View File
@@ -161,16 +161,17 @@
> 这个坑很隐蔽: 容器是健康的、健康检查 `200`、登录页 `200`, 只有真正点登录才炸。
>
> `compose.yaml` 现在**显式**给出这几个变量、且默认**空值**(= 容器内不用代理),
> 显式赋值可以挡住自动注入。**默认不用代理是实测结论**:
> * 唯一与功能相关的出站是 OIDC, 目标是 `10.80.42.185`, 容器内直连即 `200`;
> * 容器里会访问外网的只有「检查更新」(纯提示)与个别学生仓库的 webhook
> (`Heai/Test-Webhooks` → `heai.ink`、`jkljkluiouio/hw02` → `debianapi.jkljkluiouio.top`),
> 课程平台自身与课程仓库都不依赖;
> 显式赋值可以挡住自动注入。**默认不用代理的依据**(2026-09-13 实测):
> * 容器**直连外网是通的**: `dl.gitea.com`、`api.github.com`、`codeload.github.com`
> 在容器里直接 curl 分别是 `200/200/301`(`github.com` 主站直连会超时, 但平台不依赖它);
> * 与功能相关的出站只有 OIDC, 目标是 `10.80.42.185`, 容器内直连即 `200`;
> * 宿主 `7890` 那个代理是 **ssh 转发的开发用代理**, `ss -ltn` 显示只监听
> `127.0.0.1:7890`/`[::1]:7890`, 容器两条路都连不上(实测 `curl -x` 直接
> `Could not connect to server`), 配上去只会让每次出站先绕一圈再失败。
> `127.0.0.1:7890`/`[::1]:7890` —— 在容器里 `127.0.0.1` 是容器自己,
> `10.80.42.185:7890` 也不可达(实测 `curl -x` 直接 `Could not connect`),
> 所以这个代理配进容器只会让出站先绕一圈再失败。
>
> 将来有稳定且**容器可达**的代理时, 在 `.env` 里给 `GITEA_HTTP_PROXY`(见 `.env.example`)。
> 将来真要给容器配代理, 必须是**容器可达**的地址(把隧道绑到 LAN 口, 或让容器用
> host 网络), 再在 `.env` 里给 `GITEA_HTTP_PROXY`(见 `.env.example`)。
> **每次 `up -d` 后建议验一次** OIDC 入口是否还通:
> ```bash
> curl -sS --noproxy '*' -o /dev/null -w '%{http_code} %{redirect_url}\n' \
+197 -216
View File
@@ -1,8 +1,9 @@
# CI/CD:main 自动部署(Gitea Actions 方案)
> **状态:方案,尚未落地。** 落地需要两步你现在才能做的事:① 一次可用的外网(下载
> `act_runner` 二进制);② 用 `sudo` 装一个 systemd 单元。除此之外全部可以在本机完成。
> **状态:方案,尚未落地。** 全流程**不需要 root**(`ymy` 在 `docker` 组即可),
> 只需要一次「在 Gitea 页面/API 上拿注册令牌」的动作。
>
> 本文标注 **[实测]** 的结论都是 2026-09-13 在本机跑出来的,命令写在对应位置,可复现。
> 相关文档:[deploy/README.md](README.md)(部署与陷阱)、
> [customization/README.md](../customization/README.md)(定制机制与预览)。
@@ -13,33 +14,25 @@
`course-team/tjhlp-gitea` 的 `main` 一有推送,就自动把平台更新到那个提交:
构建定制产物 → 重建容器 → 跑验证 → 失败自动回滚。人工只负责 review 和 push。
不在本方案范围内:
- Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 的人工流程);
- `issue-templates` 重新推送(`uv run tjhlp repos init-templates ...`,semantics 上属于运营操作);
- 官网仓库(`Website`)的部署,那是 GitHub Actions 的事。
不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 人工流程)、
`issue-templates` 重新推送(运营操作)、官网仓库(`Website`)的部署(那是 GitHub Actions 的事)。
---
## 1. 现状与约束(2026-09-13 实测)
## 1. 现状与约束 **[实测]**
| 项 | 实测值 | 对方案的影响 |
|---|---|---|
| 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,
本项目现在做不到。
| 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` | 直接复用 |
---
@@ -51,35 +44,46 @@ host 模式"**(§2.2)。容器模式 runner 需要拉 job 镜像、镜像里
开发者 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
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 为什么是「宿主 act_runner + host 模式」
### 2.2 runner 形态:容器(推荐)vs 宿主二进制
| 备选 | 结论 |
|---|---|
| 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 备选保留 |
| | **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 时选它 |
host 模式的代价写在 §7:**workflow 里的命令等价于你本人在宿主执行**(`ymy` 在 docker 组 = 等价 root)。
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/其它分支即使跑工作流也不会碰生产。
- 串行:workflow 的 `concurrency` + 脚本里的 `flock` 双保险;
- 只认 `main`:job 级 `if` 卡死分支,PR/其它分支即使跑工作流也不碰生产。
---
@@ -89,139 +93,130 @@ host 模式的代价写在 §7:**workflow 里的命令等价于你本人在宿
|---|---|---|
| 部署克隆 | `/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) |
| 部署状态 | `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. 落地步骤
### 阶段 0 — 下载 runner(一次性,需要外网)
你的开发代理能通时执行(版本号落地时换成最新稳定版):
### 4.1 部署克隆(不需要 root)
```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 无效, 必须写进配置文件)
# 让 ymy 能读 Gitea 的裸仓库。
# ★ 实测: git -c safe.directory=... 对本机 git 无效, 必须写进配置文件才生效。
git config --global --add safe.directory \
/srv/gitea/git/repositories/course-team/tjhlp-gitea.git
# 2) 从裸仓库克隆(免凭据): origin 就指向本机裸仓库, 后续 fetch 不再需要任何 token
# 从裸仓库克隆: origin 就指向本机裸仓库, CI 全程不需要任何 git 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
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` 改成指向部署克隆的软链)。
> ⚠️ 从此 `deploy/.env` 有**两份**(dev 克隆一份、部署克隆一份)。约定:**部署克隆那份是权威**,
> dev 克隆那份只服务本地预览;改密钥时两边同步。
>
> ⚠️ 切换后**不要再从 dev 克隆 `up -d`**:compose 项目名同为 `gitea`(同一组容器),但 bind mount
> 的源路径按 compose 文件所在目录解析,两边会互相覆盖。dev 克隆只留开发与预览。
### 阶段 2 — 安装并注册 runner
### 4.2 起 runner 并注册(不需要 root)
先在 Gitea 上拿一个**仓库级**注册令牌(API 实测存在:
`POST /api/v1/repos/{owner}/{repo}/actions/runners/registration-token`;
也可以在 仓库 → Settings → Actions → Runners 页面点按钮):
```bash
# 2.1 生成【仓库级】注册令牌(API 实测存在:
# POST /api/v1/repos/{owner}/{repo}/actions/runners/registration-token)
# 也可以在 仓库 → Settings → Actions → Runners 页面点按钮拿
TOKEN=$(curl -sS -X POST \
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 # 注册凭据, 别提交/别外传
| python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])'
```
`/home/ymy/.act_runner/config.yaml`:
把令牌写进 `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: .runner
capacity: 1 # 同一时刻只跑一个 job, 与部署必须串行的事实一致
file: /data/.runner
capacity: 1 # 部署必须串行, 一个 job 一个 job 地跑
timeout: 30m
labels:
- "self-hosted:host" # host 模式: 直接在运行 act_runner 的这台机器上执行
# 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
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
- `--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` 默认行为),
上面仍显式挂一次更直观。
[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
### 4.3 试运行(手动触发)
[Install]
WantedBy=multi-user.target
```
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` 的键写错)验证**回滚路径**真的生效。
```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 — 打开自动触发 + 加保护
### 4.4 打开自动触发 + 加保护
1. 把 `push: branches: [main]` 加回 workflow;
2. 仓库 → Settings → Branches → 给 `main` 加保护:**要求 PR + 至少 1 个 review**,
禁止直接 push(否则任何有写权限的人 push 一次就重启平台);
3. 在 `deploy/README.md` 的快速索引里把这条指过来(本方案已加)。
2. 仓库 → Settings → Branches → 给 `main` 加保护:**要求 PR + 至少 1 个 review**;
3. `deploy/README.md` 的快速索引里已有一行指向本文档。
---
@@ -229,8 +224,8 @@ journalctl -u act_runner -f # 之后调试看这里
### 5.1 `.gitea/workflows/deploy.yml`
刻意做得很薄:workflow 只负责"同步到目标提交 + 调仓库里的部署脚本",
真正的逻辑放在 `auto-deploy.sh`(可版本化、可手动跑、可在本地调试)。
刻意做得很薄:workflow 只做"同步到目标提交 + 调仓库里的部署脚本",逻辑都在
`auto-deploy.sh`(可版本化、可手工跑、可本地调试)。
```yaml
name: deploy
@@ -238,7 +233,7 @@ name: deploy
on:
push:
branches: [main]
workflow_dispatch: # 阶段 3 只留这个
workflow_dispatch: # 阶段 4.3 只留这个
concurrency:
group: deploy-main
@@ -266,17 +261,14 @@ jobs:
- 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
./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(落地时验证)。
**不写 `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`
@@ -292,17 +284,17 @@ 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)
# 本机回环验证不能走代理, 否则会拿 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
# 既能在 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)
# 双保险: workflow 的 concurrency + 这里的 flock
exec 9>"${STATE_DIR}/lock"
exec 9>"${STATE_DIR}/lock" # workflow 的 concurrency 之外再加一道
flock -n 9 || { echo "[auto-deploy] 已有部署在跑, 退出"; exit 0; }
echo "[auto-deploy] 目标 ${TARGET} (上次成功: ${PREV:-无})"
@@ -333,39 +325,36 @@ if deploy && verify; then
else
echo "[auto-deploy] ❌ 部署或验证失败, 开始回滚"
rollback
exit 1 # 让 Actions 里的这次运行标红, 日志留在 UI 里
exit 1 # 让这次 Actions 运行标红, 完整日志留在 UI 里
fi
```
落库前要做的两件小事:
落库前的两个小动作:`.gitignore` 加 `deploy/.state/`、`deploy/runner/data/`、
`deploy/runner/.env`;给 `auto-deploy.sh` 加可执行位(`git` 只记可执行位)。
- `.gitignore` 加 `deploy/.state/`;
- `deploy/scripts/auto-deploy.sh` 加可执行位(`git` 只记可执行位,写文件时别丢)。
**不做**的事及理由:
也**不做**的事,以及理由:
- 每次部署不做数据库备份:部署只改代码/配置,DB 不动;`deploy/backups/` 是 `root:root`
(CI 以 `ymy` 跑,写不进去)。版本升级依旧人工走 README §7;
- 不自动重推 `issue-templates`:那是运营动作,不该跟代码推送耦合。
- 每次部署不做数据库备份:部署只改代码/配置,DB 不动;且 `deploy/backups/` 是 `root:root`,
CI 以 `ymy` 跑写不进去。版本升级仍走 README §7(带备份);
- 不自动重推 `issue-templates`:运营动作,不该跟代码推送耦合。
### 5.3 新增 `customization/check.sh <base-url>`
现在 `preview.sh check` 里的断言(首页文案、页脚、meta、静态页、官网链接、`工单` 不出现、
登录页两张卡片、无通行密钥方框)正是"定制有没有生效"的证据,但它们写死在预览脚本里。
落地时把它抽出来,让预览与生产共用:
`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 = 认证源没注册上
# 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 空方框
# 2) 登录页有「管理员登录」卡片且没有 passkey 空方框
curl -sS --noproxy '*' -H 'Accept-Language: zh-CN' "${BASE}/user/login" | grep -c '管理员登录'
```
@@ -376,79 +365,71 @@ curl -sS --noproxy '*' -H 'Accept-Language: zh-CN' "${BASE}/user/login" | grep -
| 失败点 | 行为 |
|---|---|
| `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` 恢复 |
| `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` 全程不参与,所以回滚很快(约几十秒)。
回滚 = `git checkout --detach <上一个成功 SHA>` + 重新 `up -d`,只动代码与挂载文件;
数据库、`/srv/gitea` 数据、`.env` 全程不参与,所以几十秒内完成。
---
## 7. 安全
- **host 模式 = 这些命令以 `ymy` 身份在宿主执行,而 `ymy` 在 `docker` 组里(等价 root)。**
所以:
- job 容器里挂了 `docker.sock`,而 `docker` 组等价 root;host 模式(备选 B)更是直接以 `ymy` 在
宿主执行。所以:
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:` 这些是**防误操作**,不是安全边界;真正的边界是"谁能写这个仓库"。
不要注册成 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);生成注册令牌用的 PAT
只在阶段 2 用一次,用完即可吊销。Actions secrets/variables 的 API 在 1.27 里也有
(`/repos/{owner}/{repo}/actions/secrets`),将来要通知(例如发 Issue)再用。
- 凭据最小化:部署流程**不需要任何 git token**(从本机裸仓库 fetch);注册令牌一次性用完即弃;
只有将来要回写状态/发 Issue 时才需要 Actions secrets(1.27 支持仓库级
`/repos/{owner}/{repo}/actions/secrets`)。
- `act_runner` 本体是外部二进制:落地时核对 `sha256sum`,并记录版本号(升级方式同 Gitea,
写进 README 的升级章节)。
- `gitea/act_runner` 镜像来自 Docker Hub 的官方组织仓库(本机 daemon 经代理拉取);
落地时记录 tag/digest,升级方式与 Gitea 同(写进 README 升级章节)。
---
## 8. 日常操作
```bash
# 手动部署当前 main(不依赖 Actions / 不依赖 runner)
# 手动部署当前 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 启停 / 看日志
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose logs -f runner
docker compose stop runner && docker compose start runner
# 看 runner 日志 / 部署日志
journalctl -u act_runner -f
# 平台日志(部署后排查)
docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea
# 也可以直接在仓库 Actions 标签里看每次运行的完整日志
# 每次运行的完整日志在 仓库 → Actions 里
```
⚠️ **切换后不要再从 dev 克隆 `/home/ymy/tjhlp-gitea` 执行 `docker compose up -d`**:
compose 项目名虽然同为 `gitea`(同一组容器),但 bind mount 的源路径按 compose 文件所在目录解析,
从 dev 克隆 up 会把挂载指回 dev 克隆,和 CI 部署的版本打架。dev 克隆只用于开发与预览。
---
## 9. 待落地确认项(我无法在离线环境验证的)
## 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 需要人工批准)—— 若有,可作为
"自动部署但上线需点一下"的中间档。
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 的审批,可作为
"自动部署但上线要点一下"的中间档。
---
@@ -456,11 +437,11 @@ compose 项目名虽然同为 `gitea`(同一组容器),但 bind mount 的
| 方案 | 何时选 | 代价 |
|---|---|---|
| **cron 轮询 + `auto-deploy.sh`** | runner 装不上(无外网),或 §9.2 的 fork PR 策略不可控 | 延迟 ≤60s;无 UI/日志,只有落盘日志;`ymy` 的 crontab 一行搞定,不需要 root |
| **容器模式 runner** | 将来有了稳定外网与可用的 job 镜像 | 要维护镜像 + docker socket 暴露给 runner 容器 |
| **纯手工** | 推送频率低、想每次都人工确认 | 就是现在这样 |
| **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 版的触发部分(其余复用 §5.2 的脚本):
```cron
# crontab -e (ymy)
@@ -474,6 +455,6 @@ cron 版的差别只有触发那一步(其余复用 §5.2 的脚本):
## 11. 落地顺序(一句话版)
```text
阶段 0 下载 act_runner(要外网) → 阶段 1 建部署克隆 → 阶段 2 sudo 装 systemd 单元并注册
→ 阶段 3 只留 workflow_dispatch 手动跑通 + 演练一次回滚 → 阶段 4 打开 push 触发 + main 分支保护
4.1 部署克隆 → 4.2 拿仓库级令牌 + docker compose 起 runner → 4.3 只留 workflow_dispatch
手动跑通并演练一次回滚 → 4.4 打开 push 触发 + main 分支保护
```
+7 -8
View File
@@ -170,15 +170,14 @@ services:
# 后果: /user/oauth2/<认证源> 返回 404, 统一身份认证登录不可用(2026-09-11 实际踩到)。
# 显式赋值可以挡住注入 —— 哪怕给的是空值。
#
# 为什么默认不用代理(2026-09-11 实测结论):
# * 与功能相关的出站只有 OIDC, 目标是 10.80.42.185, 容器内直连就是 200;
# * 容器里唯一会访问外网的是「检查更新」(纯提示)和个别学生仓库里的 webhook
# (Heai/Test-Webhooks -> heai.ink、jkljkluiouio/hw02 -> debianapi.*),
# 课程平台自身与课程仓库都不依赖它们;
# 不用代理的理由(2026-09-13 实测):
# * 容器直连外网是通的 —— dl.gitea.com / api.github.com / codeload.github.com
# 在容器里直接 curl 都是 200/301(github.com 主站直连会超时, 但平台不依赖它);
# * 功能相关的出站只有 OIDC, 目标是 10.80.42.185, 容器内直连就是 200;
# * 宿主 7890 那个代理是 ssh 转发的开发用代理, 只监听宿主 127.0.0.1,
# 容器既连不上 127.0.0.1:7890(那是容器自己的回环)也连不上
# 10.80.42.185:7890(实测 connect refused) —— 配上只会让出站多绕一圈再失败。
# 将来若真有稳定且容器可达的代理, 在 deploy/.env 里给 GITEA_HTTP_PROXY 即可。
# 容器里连不上(127.0.0.1:7890 是容器自己; 10.80.42.185:7890 实测 connect refused)。
# 将来真要给容器配代理, 必须是【容器可达】的地址(隧道绑 LAN 口, 或用 host 网络兜底),
# 再在 deploy/.env 里给 GITEA_HTTP_PROXY。
HTTP_PROXY: ${GITEA_HTTP_PROXY:-}
HTTPS_PROXY: ${GITEA_HTTPS_PROXY:-}
http_proxy: ${GITEA_HTTP_PROXY:-}