SHA256
原来 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 就报错、线上不受影响"
This commit is contained in:
@@ -24,6 +24,17 @@ jobs:
|
|||||||
!contains(github.event.head_commit.message, '[skip deploy]'))
|
!contains(github.event.head_commit.message, '[skip deploy]'))
|
||||||
runs-on: self-hosted
|
runs-on: self-hosted
|
||||||
timeout-minutes: 30
|
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:
|
steps:
|
||||||
- name: 同步到目标提交
|
- name: 同步到目标提交
|
||||||
run: |
|
run: |
|
||||||
|
|||||||
+31
-6
@@ -197,15 +197,40 @@
|
|||||||
> sudo rm -rf customization/custom/options # 空的 root 目录, 删掉即可
|
> sudo rm -rf customization/custom/options # 空的 root 目录, 删掉即可
|
||||||
> ```
|
> ```
|
||||||
>
|
>
|
||||||
> **⚠️ 8. act_runner 的 job 容器不要自己挂 `docker.sock`。**
|
> **⚠️ 8. `docker.sock` 怎么挂:`docker_host: "-"` 与"job 自己申报"是配套的一对。**
|
||||||
> act_runner 会把 docker daemon socket **自动**挂进 job 容器(`container.docker_host` 的默认
|
> 默认行为是 act_runner 把 docker daemon socket **自动**挂进 job 容器 —— 等于这个 runner 上的
|
||||||
> 行为); 再在 `deploy/runner/config.yaml` 的 `container.options` 里挂一次, 第一次真实部署
|
> **每个** job 都白拿 docker(= root 等价)。现在把这份能力收窄成"要用 docker 的 job 自己申报":
|
||||||
> 就会以这个错误告终:
|
> ```yaml
|
||||||
|
> # deploy/runner/config.yaml —— runner 侧: 不自动挂, 并给申报加白名单
|
||||||
|
> container:
|
||||||
|
> docker_host: "-" # 自动找 daemon, 但不挂进 job 容器
|
||||||
|
> valid_volumes: [...] # job 申报的挂载必须在这个表里
|
||||||
|
> ```
|
||||||
|
> ```yaml
|
||||||
|
> # .gitea/workflows/deploy.yml —— job 侧: 只给需要它的那个 job
|
||||||
|
> container:
|
||||||
|
> volumes:
|
||||||
|
> - /var/run/docker.sock:/var/run/docker.sock
|
||||||
|
> ```
|
||||||
|
> ⚠️ **两者必须成对**: 只写 `volumes` 而没有 `docker_host: "-"`, 就会和自动挂载撞成
|
||||||
> ```
|
> ```
|
||||||
> failed to create container: 'Duplicate mount point: /var/run/docker.sock'
|
> failed to create container: 'Duplicate mount point: /var/run/docker.sock'
|
||||||
> ```
|
> ```
|
||||||
> 2026-09-13 用 `act_runner exec` 预演 job 时提前发现。`container.options` 里只保留
|
> (2026-09-13 用 `act_runner exec` 预演时第一次踩到。注意 `exec` 有自己的
|
||||||
> 部署克隆(同路径)、宿主 docker CLI、compose 插件这三项。
|
> `--container-daemon-socket` 默认值、**不读**配置里的 `docker_host`, 所以用 exec 预演时
|
||||||
|
> 这个错会一直出现 —— 它验证不了这一项。)
|
||||||
|
>
|
||||||
|
> **⚠️ 10. `valid_volumes` 会静默丢掉挂载。**
|
||||||
|
> job 申报的 `container.volumes`(以及全局 `options` 里的 `--volume`)都必须出现在
|
||||||
|
> `container.valid_volumes` 里, 否则 act_runner 只打一行
|
||||||
|
> `... is not a valid volume, will be ignored` 就把它丢掉, **job 照常往下跑** —— 现象是容器里
|
||||||
|
> 少了个目录, 而不是报错。2026-09-21 就因此让部署 job 的
|
||||||
|
> `cd /home/ymy/deploy/tjhlp-gitea` 失败。排查两行命令:
|
||||||
|
> ```bash
|
||||||
|
> docker exec gitea-runner sed -n '/valid_volumes/,+6p' /config/config.yaml
|
||||||
|
> docker inspect $(docker ps -q --filter name=GITEA-ACTIONS) \
|
||||||
|
> --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'
|
||||||
|
> ```
|
||||||
>
|
>
|
||||||
> **⚠️ 9. 宿主 `/usr/bin/python3` 是 3.6, 别让它排到 PATH 前面。**
|
> **⚠️ 9. 宿主 `/usr/bin/python3` 是 3.6, 别让它排到 PATH 前面。**
|
||||||
> `customization/build.py` 用了 `from __future__ import annotations`, 需要 ≥3.7。
|
> `customization/build.py` 用了 `from __future__ import annotations`, 需要 ≥3.7。
|
||||||
|
|||||||
+143
-68
@@ -19,33 +19,45 @@
|
|||||||
不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 人工流程)、
|
不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 人工流程)、
|
||||||
`issue-templates` 重新推送(运营操作)、官网仓库(`Website`)的部署(那是 GitHub Actions 的事)。
|
`issue-templates` 重新推送(运营操作)、官网仓库(`Website`)的部署(那是 GitHub Actions 的事)。
|
||||||
|
|
||||||
### 0.1 落地现状与剩余动作(2026-09-13)
|
### 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;工作树干净 |
|
| 部署克隆 `/home/ymy/deploy/tjhlp-gitea`(`origin` = 本机裸仓库,免凭据) | `git remote -v`;`deploy/.env` 600 |
|
||||||
| runner 已注册 | `action_runner` 表:`tjhlp-gitea-1 / v0.6.1 / ["self-hosted"]`;日志 `declare successfully` |
|
| runner 已注册 | `action_runner`:`tjhlp-gitea-1 / v0.6.1 / ["self-hosted"]` |
|
||||||
| 生产已切到部署克隆 | `docker inspect gitea` 的三个挂载源都指向 `/home/ymy/deploy/tjhlp-gitea/...` |
|
| 生产由 CI 部署 | `last-deployed` = HEAD 的 SHA;`action_run` 最新一次 `status=1` |
|
||||||
| 部署脚本本机跑通(回滚被真实触发过两次) | `auto-deploy.sh` → `build.py` → `up -d` → `verify.sh` + `check.sh` → `✅ 部署成功`;`deploy/.state/last-deployed` 记 SHA |
|
| job 容器里工具齐全 | `act_runner exec` 预演:`Python 3.10.12 / git 2.55 / docker server 29.8.0 / compose v5.5.1` |
|
||||||
| job 容器路径 | `act_runner exec` 预演:`uid=0 / Python 3.10.12 / git 2.55 / docker server 29.8.0 / compose v5.5.1`,部署克隆可见,`loopback-api=200 apache=200`,`🏁 Job succeeded` |
|
|
||||||
|
|
||||||
这次落地中发现并修掉的问题(细节见 [README](README.md) 陷阱 7–9):
|
2026-09-21 打通时踩的三个坑(对应当天几次红色的运行):
|
||||||
|
|
||||||
1. 全新克隆里 `customization/custom/options/` 不存在 → docker 以 root 创建这个挂载源目录 →
|
1. **`container.valid_volumes` 为空表时,挂载会被静默丢弃**(只打一行
|
||||||
`build.py` 写不进去 → **语言文件生成失败、「工单」回归**(首页/登录页却看着正常)。
|
`... is not a valid volume, will be ignored`)→ job 容器里没有部署克隆,第一步
|
||||||
修法:`.gitkeep` 让目录随 checkout 存在 + 部署前可写性检查。
|
`cd /home/ymy/deploy/tjhlp-gitea` 就失败。修法:把要挂的路径列进白名单。
|
||||||
2. `container.options` 里自己挂 `docker.sock` 与 act_runner 的自动挂载冲突
|
2. **部署克隆的 `origin` 是宿主上的本地裸库**(`/srv/gitea/...`),job 容器里没有它 →
|
||||||
(`Duplicate mount point`),第一次真实部署必然失败。修法:去掉显式挂载。
|
`git fetch` 报 "does not appear to be a git repository"。修法:把 `/srv/gitea` 只读挂进去。
|
||||||
3. 宿主 `/usr/bin/python3` 是 **3.6**,PATH 顺序一变 `build.py` 就 `SyntaxError`,而且语言
|
3. **workflow 的 step 之间不共享工作目录**,第二步要自己 `cd` 过去(`actions/checkout` 那种
|
||||||
文件会**静默地**不再更新。修法:脚本自己挑 ≥3.7 的解释器并用它跑 build.py。
|
"代码在当前目录"的心智模型在这里不成立)。
|
||||||
|
|
||||||
|
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. **你来 `git push`**(本地有 4 个未推送提交)——推送即触发第一次 CI 运行;由于要部署的
|
1. 本轮改动**要等一次 push 才能端到端验证**(判据与回退方式见 §9 第 2 条)。
|
||||||
版本已经在本机部署过,这次应当是"无变化"的快速通过。
|
2. 用一个测试 fork 发 PR,确认 fork PR 的 workflow 审批行为(§9);确认前不要把仓库
|
||||||
2. 用一个测试 fork 发 PR,确认 fork PR 的 workflow 审批行为(§9.1);确认前不要把仓库
|
|
||||||
开放给不可信贡献者。
|
开放给不可信贡献者。
|
||||||
3. 给 `main` 加分支保护(§4.4)。
|
3. 给 `main` 加分支保护(§4.4)。
|
||||||
|
|
||||||
@@ -56,7 +68,7 @@
|
|||||||
| 项 | 实测值 | 对方案的影响 |
|
| 项 | 实测值 | 对方案的影响 |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| Gitea | 1.27.3;Actions 默认开启(`modules/setting/actions.go` 里 `Enabled: true`),仓库页有 `/actions` | 不用改配置就能用 |
|
| Gitea | 1.27.3;Actions 默认开启(`modules/setting/actions.go` 里 `Enabled: true`),仓库页有 `/actions` | 不用改配置就能用 |
|
||||||
| 已注册 runner | **无**(`action_runner` 表空) | 要自己起一个 |
|
| 已注册 runner | 方案制定时**无**(现已注册,见 §0.1) | 要自己起一个 |
|
||||||
| `act_runner` 镜像 | `docker pull gitea/act_runner:latest` 成功:**arm64, v0.6.1, 69.3MB** | runner 用容器跑,**不需要 root** |
|
| `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 |
|
| 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`) | 正常联网,不是离线环境 |
|
| 宿主出网 | 国内直连 `200`;境外经代理 `200`(`https://dl.gitea.com/...`、`https://github.com` 经 `127.0.0.1:7890` 均 `200`) | 正常联网,不是离线环境 |
|
||||||
@@ -79,11 +91,11 @@
|
|||||||
Gitea (10.80.42.185/QA) ── 调度 workflow ──► act_runner(docker compose 服务, 容器)
|
Gitea (10.80.42.185/QA) ── 调度 workflow ──► act_runner(docker compose 服务, 容器)
|
||||||
▲ │ 拉起 job 容器
|
▲ │ 拉起 job 容器
|
||||||
│ 日志/状态显示在仓库 Actions 标签 ▼
|
│ 日志/状态显示在仓库 Actions 标签 ▼
|
||||||
└──────────────────── job 容器(network: host)
|
└──────────────────── job 容器(network: host;宿主能力由 job 自己申报)
|
||||||
├─ 挂 docker.sock → 可执行 docker compose
|
├─ 挂 docker.sock → 可执行 docker compose
|
||||||
├─ 挂 /home/ymy/deploy(同路径)→ 部署克隆
|
├─ 挂 /home/ymy/deploy(同路径, 部署克隆)+ /srv/gitea(ro, 它的 origin)
|
||||||
└─ 跑 auto-deploy.sh: build.py → up -d → verify → 失败回滚
|
└─ 跑 auto-deploy.sh: build.py → up -d → verify → 失败回滚
|
||||||
```
|
未申报的 job(将来的 PR 检查)拿不到上面任何一项
|
||||||
|
|
||||||
### 2.2 runner 形态:容器(推荐)vs 宿主二进制
|
### 2.2 runner 形态:容器(推荐)vs 宿主二进制
|
||||||
|
|
||||||
@@ -92,7 +104,7 @@
|
|||||||
| 安装 | `docker compose up -d`(镜像实测可拉) | 下载二进制 + **需要 sudo** 装 systemd 单元 |
|
| 安装 | `docker compose up -d`(镜像实测可拉) | 下载二进制 + **需要 sudo** 装 systemd 单元 |
|
||||||
| job 执行 | job 容器(镜像由 label 决定) | 直接在宿主以 `ymy` 执行 |
|
| job 执行 | job 容器(镜像由 label 决定) | 直接在宿主以 `ymy` 执行 |
|
||||||
| 工具依赖 | 靠 job 镜像(要确认镜像里有 git/python3/docker CLI) | 宿主现成,最省事 |
|
| 工具依赖 | 靠 job 镜像(要确认镜像里有 git/python3/docker CLI) | 宿主现成,最省事 |
|
||||||
| 挂载 | 靠 `container.options` 把 docker.sock 与部署克隆按**同路径**挂进 job 容器 | 无 |
|
| 挂载 | 由 deploy job 在 `container.volumes` 里申报(受 runner 的 `valid_volumes` 白名单约束) | 无 |
|
||||||
| 开机自启 | compose 的 `restart: unless-stopped` | systemd |
|
| 开机自启 | compose 的 `restart: unless-stopped` | systemd |
|
||||||
| 结论 | **默认选它**:不需要 root、标准、日志清晰 | 想少一层容器、且你愿意跑一次 sudo 时选它 |
|
| 结论 | **默认选它**:不需要 root、标准、日志清晰 | 想少一层容器、且你愿意跑一次 sudo 时选它 |
|
||||||
|
|
||||||
@@ -220,25 +232,31 @@ runner:
|
|||||||
- "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-22.04"
|
- "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-22.04"
|
||||||
container:
|
container:
|
||||||
network: host # job 容器与宿主共用网络: 127.0.0.1:2080 与 10.80.42.185 都能直连
|
network: host # job 容器与宿主共用网络: 127.0.0.1:2080 与 10.80.42.185 都能直连
|
||||||
options: >-
|
docker_host: "-" # 自动找 daemon, 但【不】把 socket 挂进 job 容器(要用 docker 的 job 自己申报)
|
||||||
--volume /home/ymy/deploy:/home/ymy/deploy
|
valid_volumes: # 允许 job 申报的挂载白名单(glob 匹配挂载源路径; [] = 一个都不许)
|
||||||
--volume /usr/bin/docker:/usr/bin/docker:ro
|
- /home/ymy/deploy
|
||||||
--volume /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro
|
- /srv/gitea
|
||||||
|
- /var/run/docker.sock
|
||||||
|
- /usr/bin/docker
|
||||||
|
- /usr/libexec/docker/cli-plugins
|
||||||
|
# 这里【故意不写】全局 options: 挂载由 deploy job 自己申报, 见 §5.1
|
||||||
force_pull: false # 镜像已有就别每次拉
|
force_pull: false # 镜像已有就别每次拉
|
||||||
# ★ 不要挂 /var/run/docker.sock: act_runner 会自动挂, 重复挂会
|
|
||||||
# "Duplicate mount point: /var/run/docker.sock" 直接失败(实测)
|
|
||||||
cache:
|
cache:
|
||||||
enabled: true
|
enabled: true
|
||||||
```
|
```
|
||||||
|
|
||||||
三处关键点:
|
四处关键点:
|
||||||
|
|
||||||
- `--volume /home/ymy/deploy:/home/ymy/deploy` **必须同路径**:`docker compose` 在 job 容器里
|
- **白名单管两头**:job 申报的 `container.volumes` 和全局 `options` 里的 `--volume` 都要在
|
||||||
把相对挂载解析成绝对路径后交给宿主 daemon 执行,路径不一致会挂到空目录;
|
`valid_volumes` 里,否则被**静默丢弃**(`... is not a valid volume, will be ignored`),
|
||||||
- 挂 `/usr/bin/docker` 与 `cli-plugins` 是为了不依赖 job 镜像里有没有 docker CLI / compose 插件
|
2026-09-21 实际因此失败;
|
||||||
(宿主是 glibc,Ubuntu 镜像能用;落地时若镜像自带,也可以去掉这两行);
|
- **同路径挂载 `/home/ymy/deploy`**:`docker compose` 在 job 容器里把相对挂载解析成绝对路径后
|
||||||
- `docker.sock` 会被 act_runner 自动挂进 job 容器(`container.docker_host` 默认行为),
|
交给宿主 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 试运行(手动触发)
|
### 4.3 试运行(手动触发)
|
||||||
|
|
||||||
@@ -264,12 +282,15 @@ cache:
|
|||||||
`auto-deploy.sh`(可版本化、可手工跑、可本地调试)。
|
`auto-deploy.sh`(可版本化、可手工跑、可本地调试)。
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
# main 推送后自动部署到 10.80.42.185/QA。
|
||||||
|
# 逻辑都在 deploy/scripts/auto-deploy.sh 里, 这里只负责"同步到目标提交 + 调脚本"。
|
||||||
|
# 详见 deploy/ci-cd.md。
|
||||||
name: deploy
|
name: deploy
|
||||||
|
|
||||||
on:
|
on:
|
||||||
push:
|
push:
|
||||||
branches: [main]
|
branches: [main]
|
||||||
workflow_dispatch: # 阶段 4.3 只留这个
|
workflow_dispatch:
|
||||||
|
|
||||||
concurrency:
|
concurrency:
|
||||||
group: deploy-main
|
group: deploy-main
|
||||||
@@ -287,19 +308,40 @@ jobs:
|
|||||||
!contains(github.event.head_commit.message, '[skip deploy]'))
|
!contains(github.event.head_commit.message, '[skip deploy]'))
|
||||||
runs-on: self-hosted
|
runs-on: self-hosted
|
||||||
timeout-minutes: 30
|
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:
|
steps:
|
||||||
- name: 同步到目标提交
|
- name: 同步到目标提交
|
||||||
run: |
|
run: |
|
||||||
set -euo pipefail
|
set -euo pipefail
|
||||||
cd /home/ymy/deploy/tjhlp-gitea
|
cd /home/ymy/deploy/tjhlp-gitea
|
||||||
git fetch --prune origin
|
git fetch --prune origin
|
||||||
git checkout --detach "${{ github.sha }}"
|
# -f: 部署克隆是 CI 独占的; 上一个已部署版本的 deploy/runner/* 等文件在本版本
|
||||||
|
# 若已被跟踪, 会作为"未跟踪文件"挡住普通 checkout(实测)
|
||||||
|
git checkout -f --detach "${{ github.sha }}"
|
||||||
|
git --no-pager log --oneline -1
|
||||||
- name: 构建并部署(失败自动回滚)
|
- name: 构建并部署(失败自动回滚)
|
||||||
run: |
|
run: |
|
||||||
set -euo pipefail
|
set -euo pipefail
|
||||||
|
# 工作流没有 actions/checkout, 默认工作目录里没有代码; 上一步已把
|
||||||
|
# 部署克隆同步到目标提交, 这里必须显式 cd 过去 (2026-09-21 实际踩到)。
|
||||||
|
cd /home/ymy/deploy/tjhlp-gitea
|
||||||
./deploy/scripts/auto-deploy.sh
|
./deploy/scripts/auto-deploy.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
|
`container.volumes` 那一块是 2026-09-22 收窄授权的结果:需要宿主能力的只有这一个 job,
|
||||||
|
所以挂载在它这里申报;runner 侧的 `valid_volumes` 决定哪些申报能被接受。**加新的 workflow
|
||||||
|
(例如 PR 检查)时不需要、也不要给它申报这些卷** —— 它默认就是裸容器。
|
||||||
|
|
||||||
**不写 `uses:`** 的理由:本项目不需要——代码从本机裸仓库取、部署逻辑是仓库里的脚本,
|
**不写 `uses:`** 的理由:本项目不需要——代码从本机裸仓库取、部署逻辑是仓库里的脚本,
|
||||||
省掉每次运行下载 action 的开销,也避开 `github.com` 主站直连超时带来的不确定性。
|
省掉每次运行下载 action 的开销,也避开 `github.com` 主站直连超时带来的不确定性。
|
||||||
将来若要做 PR 检查(lint/pytest)想用现成 action,两条路:给 runner 容器配容器可达的代理,
|
将来若要做 PR 检查(lint/pytest)想用现成 action,两条路:给 runner 容器配容器可达的代理,
|
||||||
@@ -323,8 +365,8 @@ PUBLIC_URL="${GITEA_PUBLIC_URL:-https://cpp.tongji.sh/QA}"
|
|||||||
# 本机回环验证不能走代理, 否则会拿 502 冒充故障(见 README 陷阱 5)
|
# 本机回环验证不能走代理, 否则会拿 502 冒充故障(见 README 陷阱 5)
|
||||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
|
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
|
||||||
export no_proxy='*' NO_PROXY='*'
|
export no_proxy='*' NO_PROXY='*'
|
||||||
# 既能在 job 容器里跑, 也能在宿主上跑; 不要写死某台机器的 pyenv 路径
|
# 既能在 job 容器里跑, 也能在宿主上跑: 脚本用 pick_python() 自己挑一个 ≥3.7 的解释器
|
||||||
export PATH="/usr/local/bin:/usr/bin:/bin:${PATH}"
|
# (宿主 /usr/bin/python3 是 3.6, 见 README 陷阱 9), 不要写死某台机器的 pyenv 路径
|
||||||
|
|
||||||
mkdir -p "$STATE_DIR"
|
mkdir -p "$STATE_DIR"
|
||||||
TARGET=${1:-$(git -C "$REPO_DIR" rev-parse HEAD)}
|
TARGET=${1:-$(git -C "$REPO_DIR" rev-parse HEAD)}
|
||||||
@@ -414,24 +456,41 @@ curl -sS --noproxy '*' -H 'Accept-Language: zh-CN' "${BASE}/user/login" | grep -
|
|||||||
|
|
||||||
## 7. 安全
|
## 7. 安全
|
||||||
|
|
||||||
- job 容器里挂了 `docker.sock`,而 `docker` 组等价 root;host 模式(备选 B)更是直接以 `ymy` 在
|
### 7.1 收窄后的边界(2026-09-22 起)
|
||||||
宿主执行。所以:
|
|
||||||
|
|
||||||
1. runner 只注册成**仓库级**(`/repos/{owner}/{repo}/actions/runners/registration-token`),
|
runner 不再把宿主能力全局发给每个 job:
|
||||||
不要注册成 instance/org 级——否则组织里任何仓库都能用这个 runner 拿到宿主 root;
|
|
||||||
2. `main` 必须开分支保护(PR + review)。贡献者是课程团队,属于可信范围,但
|
- `container.docker_host: "-"`:**不**把 docker socket 自动挂进 job 容器;
|
||||||
"谁有写权限 = 谁能 root 宿主"这条要写明白;
|
- 需要宿主能力的是 **deploy job 自己**,它在 `container.volumes` 里申报五项挂载;
|
||||||
3. **落地前确认 fork PR 的工作流策略**(§9.1):若 fork PR 能不经批准直接跑 workflow,
|
- `container.valid_volumes` 是允许清单:申报了但不在表里的卷会被**丢弃**(不是报错),
|
||||||
等于把宿主 root 交给外部 PR;确认之前不要把仓库开放给不可信贡献者。若策略不可控,
|
所以这个 runner 上的任何 job 都挂不上 `/`、`/etc`、`~/.ssh` 之类。
|
||||||
退化为 §10 的 cron 轮询(只跑宿主上的固定脚本,不执行仓库里的代码);
|
|
||||||
|
也就是说,"能 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:` 是防误操作,不是安全边界。
|
4. `[skip deploy]`、`if:` 是防误操作,不是安全边界。
|
||||||
|
|
||||||
- 凭据最小化:部署流程**不需要任何 git token**(从本机裸仓库 fetch);注册令牌一次性用完即弃;
|
### 7.3 其余
|
||||||
只有将来要回写状态/发 Issue 时才需要 Actions secrets(1.27 支持仓库级
|
|
||||||
`/repos/{owner}/{repo}/actions/secrets`)。
|
|
||||||
|
|
||||||
- `gitea/act_runner` 镜像来自 Docker Hub 的官方组织仓库(本机 daemon 经代理拉取);
|
- runner 只注册成**仓库级**(`/repos/{owner}/{repo}/actions/runners/registration-token`),
|
||||||
落地时记录 tag/digest,升级方式与 Gitea 同(写进 README 升级章节)。
|
不要注册成 instance/org 级——否则组织里任何仓库都能用这个 runner 拿到宿主 root。
|
||||||
|
- 凭据最小化:部署流程**不需要任何 git token**(从本机裸仓库 fetch);注册令牌一次性用完即弃。
|
||||||
|
- `gitea/act_runner` 镜像来自 Docker Hub 官方组织仓库;落地时记录 tag/digest(升级方式同 README)。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -448,6 +507,12 @@ cd /home/ymy/deploy/tjhlp-gitea && git checkout --detach <sha> && ./deploy/scrip
|
|||||||
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose logs -f runner
|
cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose logs -f runner
|
||||||
docker compose stop runner && docker compose start 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
|
docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea
|
||||||
# 每次运行的完整日志在 仓库 → Actions 里
|
# 每次运行的完整日志在 仓库 → Actions 里
|
||||||
@@ -457,22 +522,32 @@ docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea
|
|||||||
|
|
||||||
## 9. 尚未验证的点(诚实清单)
|
## 9. 尚未验证的点(诚实清单)
|
||||||
|
|
||||||
已由本机预演确认、不再是待确认项的:job 镜像里有 `git 2.55`/`Python 3.10`/docker CLI ✓;
|
**已经被真实运行确认的**(2026-09-21,共 5 次运行、最新一次成功):
|
||||||
act_runner v0.6.1 支持 `:host` 标签与 `container.network: host` ✓;compose 插件在 job 容器里
|
|
||||||
可用 ✓;部署克隆、回环 `127.0.0.1:2080`、经 Apache 的 `10.80.42.185/QA` 在 job 容器内都通 ✓。
|
|
||||||
|
|
||||||
仍然未知:
|
- 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.3 处理。
|
**仍然未知:**
|
||||||
2. **workflow 语法支持面**:`concurrency`、`timeout-minutes`、`permissions`、job 级 `if` 里的
|
|
||||||
`contains(...)` 在 1.27 的实现里是否都生效 —— 第一次真实运行即知。
|
1. **fork PR 的 workflow 审批行为**(安全前提):用一个测试 fork 发 PR 验证;在此之前按 §7.2
|
||||||
3. **Gitea 侧的调度与日志回传**:本机只预演了 job *执行*,没预演调度/日志上报。第一次真实
|
第 3 条处理。
|
||||||
运行会验证。此外部署过程本身会重启 gitea 容器,job 与 Gitea 的连接可能短暂断开
|
2. **本轮收窄授权(2026-09-22)的端到端效果**:`docker_host: "-"` + job 自己申报
|
||||||
(act_runner 会重试),表现为日志里若干 `failed to fetch task` / `unexpected EOF` —— 属正常现象。
|
`container.volumes` 这条路径,`act_runner exec` 验证不了——exec 有自己的
|
||||||
4. **`github.sha` / `github.event.head_commit.message`** 的取值(试运行时 echo 一次确认)。
|
`--container-daemon-socket` 默认值、也不读配置里的 `valid_volumes`(实测:exec 里未授权
|
||||||
5. **Actions 日志保留与体积**:`[actions] LOG_RETENTION_DAYS`(默认 365)与存储位置。
|
路径照样挂上、裸 job 照样有 socket),只能靠一次真实 push。判据:
|
||||||
6. **Gitea 是否支持"环境审批"**:若有 deployments/environments 的审批,可作为
|
- **成功**:运行变绿 + `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 的审批,可作为"自动部署但
|
||||||
|
上线要点一下"的中间档。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
+24
-21
@@ -14,34 +14,37 @@ runner:
|
|||||||
container:
|
container:
|
||||||
# host: job 容器与宿主共用网络 —— verify.sh 里对 127.0.0.1:2080 的检查才有效,
|
# host: job 容器与宿主共用网络 —— verify.sh 里对 127.0.0.1:2080 的检查才有效,
|
||||||
# 10.80.42.185 也不需要额外放行。
|
# 10.80.42.185 也不需要额外放行。
|
||||||
|
# ⚠️ 这是 runner 级设置, 所以这个 runner 上的【每个】job 都共享宿主网络 —— 还没能
|
||||||
|
# 收窄的一轴(见 ci-cd.md §7 残留项)。
|
||||||
network: host
|
network: host
|
||||||
# ★ 不要在这里挂 /var/run/docker.sock: act_runner 会自动把 docker daemon socket
|
# ★ 不把宿主 docker socket 自动挂进 job 容器(默认行为是自动挂 = 每个 job 都能拿到
|
||||||
# 挂进 job 容器(container.docker_host 的默认行为), 再挂一次会直接失败:
|
# root 等价能力)。改成"要用 docker 的 job 自己申报", 并受下面的白名单约束。
|
||||||
# failed to create container: 'Duplicate mount point: /var/run/docker.sock'
|
docker_host: "-"
|
||||||
# (2026-09-13 用 `act_runner exec` 预演 job 时实测踩到 —— 若没预演, 第一次真实
|
# ★ job 允许申报的挂载白名单(gobwas/glob 匹配【挂载源路径】; [] = 一个都不许, ['**'] = 全放)。
|
||||||
# 部署就会以这个错误告终。)
|
# 注意: 全局 options 里的 --volume 也过这道白名单 —— 不在表里的会被
|
||||||
|
# "[xxx] is not a valid volume, will be ignored" 直接丢弃。2026-09-21 就因为这个
|
||||||
|
# (当时 options 有挂载但白名单是默认空表)让 job 容器里看不到 /home/ymy/deploy,
|
||||||
|
# 第一步 `cd /home/ymy/deploy/tjhlp-gitea` 就失败。
|
||||||
#
|
#
|
||||||
# 下面这些挂载是 act_runner 不管的:
|
# 表里的四项分别对应:
|
||||||
# * 部署克隆同路径挂载: job 容器里 `docker compose` 会把相对挂载解析成绝对路径后
|
# /home/ymy/deploy job 里的工作目录(deploy job 申报, 可写)
|
||||||
# 交给宿主 daemon, 两边路径必须一致, 否则会挂到空目录;
|
# /srv/gitea 部署克隆的 origin 是这里面的本地裸库; 不挂进去
|
||||||
# * 宿主 docker CLI + compose 插件: 不依赖 job 镜像里带没带(宿主是 glibc, Ubuntu 镜像能用)。
|
# `git fetch` 会报 "does not appear to be a git repository"
|
||||||
options: >-
|
# (2026-09-21 实际踩到), 只读
|
||||||
--volume /home/ymy/deploy:/home/ymy/deploy
|
# /var/run/docker.sock 部署要 `docker compose up -d`, 只给申报它的 job
|
||||||
--volume /srv/gitea:/srv/gitea:ro
|
# /usr/bin/docker 等 docker CLI + compose 插件, 不依赖 job 镜像里带没带
|
||||||
--volume /usr/bin/docker:/usr/bin/docker:ro
|
|
||||||
--volume /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro
|
|
||||||
# ★ options 里的 --volume 也会过这道白名单: 不在 valid_volumes 里的卷会被
|
|
||||||
# "[xxx] is not a valid volume, will be ignored" 丢弃。漏配时 job 容器里
|
|
||||||
# 看不到 /home/ymy/deploy, 第一步 `cd /home/ymy/deploy/tjhlp-gitea` 就失败
|
|
||||||
# (2026-09-21 实际踩到)。
|
|
||||||
# ★ 部署克隆的 origin 是宿主本地裸库 /srv/gitea/...; job 容器里没有它,
|
|
||||||
# `git fetch` 会报 "does not appear to be a git repository"(同一天又踩到),
|
|
||||||
# 故把 /srv/gitea 只读挂进去。
|
|
||||||
valid_volumes:
|
valid_volumes:
|
||||||
- /home/ymy/deploy
|
- /home/ymy/deploy
|
||||||
- /srv/gitea
|
- /srv/gitea
|
||||||
|
- /var/run/docker.sock
|
||||||
- /usr/bin/docker
|
- /usr/bin/docker
|
||||||
- /usr/libexec/docker/cli-plugins
|
- /usr/libexec/docker/cli-plugins
|
||||||
|
# ★ 这里【故意不写】全局 options 挂载: 需要宿主路径/socket 的只有 deploy 这一个 job,
|
||||||
|
# 由它在 .gitea/workflows/deploy.yml 的 container.volumes 里自己申报(见 ci-cd.md §5.1)。
|
||||||
|
# 挂在这里等于这个 runner 上的每个 job(比如将来加的 PR 检查/测试)都白拿 socket = root。
|
||||||
|
# 另外 act_runner 会自动挂 docker.sock, 再在 options 里挂一次会以
|
||||||
|
# "Duplicate mount point: /var/run/docker.sock" 直接失败(2026-09-13 预演时实测),
|
||||||
|
# 所以 docker_host: "-" 与 job 自己申报是配套的一对改动。
|
||||||
force_pull: false # 镜像本地已有就不再拉
|
force_pull: false # 镜像本地已有就不再拉
|
||||||
|
|
||||||
cache:
|
cache:
|
||||||
|
|||||||
Reference in New Issue
Block a user