feat(ci): 落地 main 自动部署的可复用件(runner 配置/部署脚本/定制断言/工作流)
deploy / deploy (push) Skipped

按 deploy/ci-cd.md 方案把除推送触发之外的东西都准备好:

- customization/check.sh <base-url>: 把 preview.sh check 里的"定制生效"断言抽成
  任意实例可跑的脚本(首页/页脚/meta/官网链接/登录页两张卡/无通行密钥方框/
  无「工单」/无 example.com), 另加生产才有的 OIDC 入口 307 断言(404 = 认证源没注册上)。
  实测对生产 17/17 通过。
- deploy/scripts/auto-deploy.sh: build.py -> compose up -d -> verify.sh + check.sh,
  失败自动回滚到 deploy/.state/last-deployed; flock 串行; 结束时把 clone 所有权还给
  ymy(job 容器里是 root); 内网验证强制不走代理。
- deploy/runner/{compose.yaml,config.yaml,.env.example}: act_runner v0.6.1 跑在容器里
  (不需要 root), network: host + 同路径挂载部署克隆 + 宿主 docker CLI/compose 插件,
  capacity 1 保证部署串行。
- .gitea/workflows/deploy.yml: push main + workflow_dispatch, [skip deploy] 跳过,
  concurrency 串行, 只做"同步到 github.sha + 调 auto-deploy.sh"。
- .gitignore: deploy/.state/、deploy/runner/{.env,data/}。

依据见 deploy/ci-cd.md(含全部实测证据与待确认项)。
This commit is contained in:
2026-09-13 22:09:32 +08:00
parent ea3ad2bb31
commit 73ce8162aa
11 changed files with 494 additions and 10 deletions
+40
View File
@@ -0,0 +1,40 @@
# 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
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
./deploy/scripts/auto-deploy.sh
+4
View File
@@ -17,6 +17,10 @@ credentials_*.csv
# Deployment (docker compose)
deploy/.env
deploy/backups/
# CI/CD: 部署状态(上次成功的 SHA)与 runner 的注册凭据/缓存
deploy/.state/
deploy/runner/.env
deploy/runner/data/
# Customization
customization/custom/options/locale/locale_zh-CN.json
+8
View File
@@ -188,7 +188,15 @@ def main() -> int:
return 0
OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
try:
OUT_PATH.write_text(rendered, encoding="utf-8")
except PermissionError as exc:
raise SystemExit(
f"写入失败: {exc}\n"
f" 多半是 docker 以 root 创建过这个挂载源目录(bind mount 的源目录不存在时它会这么做),\n"
f" 普通用户就写不进去了。删掉再重试: sudo rm -rf {OUT_PATH.parent}\n"
f" (仓库里 customization/custom/options/.gitkeep 就是为防止这种情况而存在的)"
) from exc
print(f"✓ 已生成 {OUT_PATH}")
fixed = ensure_readable(CUSTOM_DIR)
if fixed:
+119
View File
@@ -0,0 +1,119 @@
#!/usr/bin/env bash
# 定制生效断言 —— 对任意实例跑一遍, 预览与生产共用。
# 用法:
# customization/check.sh http://127.0.0.1:2081 # 预览
# customization/check.sh https://cpp.tongji.sh/QA # 生产(CI 里也调这个)
#
# 退出码: 0 全通过 / 1 有断言失败 / 2 用法错误。
# 只读: 只发 GET, 不改任何东西。
set -uo pipefail
BASE_URL="${1:-}"
if [[ -z ${BASE_URL} ]]; then
sed -n '2,9p' "$0"
exit 2
fi
BASE_URL="${BASE_URL%/}"
ORIGIN="$(printf '%s' "${BASE_URL}" | sed -E 's#(^https?://[^/]+).*#\1#')"
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
fail=0
ok() { printf ' ✓ %s\n' "$1"; }
bad() {
printf ' ✗ %s\n' "$1"
fail=1
}
skip() { printf ' – %s\n' "$1"; }
tmp="$(mktemp -d)"
trap 'rm -rf "${tmp}"' EXIT
# --noproxy: 验证目标都在内网, 走代理只会把 200 变成 502(见 deploy/README.md 陷阱 5)
curl_() { curl -sS --noproxy '*' --max-time 20 "$@"; }
echo "== 定制检查 ${BASE_URL} =="
# --- 首页 -------------------------------------------------------------------
if ! curl_ -fsS -H 'Accept-Language: zh-CN' "${BASE_URL}/" -o "${tmp}/home.html"; then
echo " ✗ 首页打不开(HTTP 非 2xx), 后面不再检查"
exit 1
fi
ok "首页可访问"
grep -q "先搜索,再提问" "${tmp}/home.html" &&
ok "首页用的是定制模板 home.tmpl" || bad "首页没有定制模板的内容"
grep -q "assets/tjhlp/ask-guide.html" "${tmp}/home.html" &&
ok "导航栏/首页已指向课程提问指南" || bad "没找到提问指南链接"
! grep -q "painless\|极易搭建\|Easy to install\|Cross-platform" "${tmp}/home.html" &&
ok "首页已无 Gitea 功能介绍" || bad "首页仍有 Gitea 功能介绍文案"
! grep -qi "powered by" "${tmp}/home.html" &&
ok "页脚已无 Powered by Gitea" || bad "页脚仍有 Powered by"
! grep -q "docs.gitea.com" "${tmp}/home.html" &&
ok "页面已无 docs.gitea.com 外链" || bad "仍有 docs.gitea.com 外链"
grep -q 'name="description" content="同济大学高级语言程序设计课程答疑平台"' "${tmp}/home.html" &&
ok "meta description 已替换" || bad "meta description 未替换"
# --- 与课程官网的联动 -------------------------------------------------------
grep -q "https://cpp.tongji.sh/Website/" "${tmp}/home.html" &&
ok "首页/导航栏已链接课程官网" || bad "首页没有课程官网链接"
grep -q "https://cpp.tongji.sh/Website/ask-question/" "${tmp}/home.html" &&
ok "首页已链接官网《学会提问》" || bad "首页没有《学会提问》链接"
if curl_ -fsS -o "${tmp}/guide.html" "${BASE_URL}/assets/tjhlp/ask-guide.html"; then
ok "custom/public 静态页可访问"
grep -q "Website/ask-question/" "${tmp}/guide.html" &&
ok "站内提问指南已回链官网" || bad "站内提问指南没有官网链接"
else
bad "提问指南静态页 404"
fi
# --- 中文术语与登录页 -------------------------------------------------------
if curl_ -fsS -H 'Accept-Language: zh-CN' "${BASE_URL}/user/login" -o "${tmp}/login.html"; then
ok "登录页可访问"
grep -q "管理员登录" "${tmp}/login.html" &&
ok "登录页有独立的「管理员登录」卡片" || bad "登录页缺少管理员登录卡片"
! grep -q "webauthn-error\|signin-passkey" "${tmp}/login.html" &&
ok "登录页已无空的通行密钥(WebAuthn)方框" || bad "登录页仍有通行密钥区块"
# OIDC 入口: 配了认证源的实例才会渲染 external-login-navigator
if grep -q 'id="external-login-navigator"' "${tmp}/login.html"; then
href="$(grep -o 'href="[^"]*/user/oauth2/[^"]*"' "${tmp}/login.html" | head -1 |
sed -E 's/^href="//; s/"$//')"
if [[ -z ${href} ]]; then
bad "登录页有认证源区块但没解析出 OAuth2 链接"
else
code="$(curl_ -o /dev/null -w '%{http_code}' "${ORIGIN}${href}")"
# 307 = 认证源注册成功并跳转统一身份认证; 404 = 认证源没注册上(见 README 陷阱 6)
[[ ${code} == 307 ]] &&
ok "OIDC 入口 ${href} 返回 307(跳转统一身份认证)" ||
bad "OIDC 入口返回 ${code}, 期望 307(404 = 认证源没注册上)"
fi
else
skip "该实例未配置认证源, 跳过 OIDC 入口检查(预览实例属此情况)"
fi
else
bad "登录页打不开"
fi
# 术语: 中文界面里不该再出现「工单」
if curl_ -fsS -H 'Accept-Language: zh-CN' -o "${tmp}/issues.html" \
"${BASE_URL}/course-team/tjhlp-gitea/issues"; then
! grep -q "工单" "${tmp}/issues.html" &&
ok "Issue 列表页中文界面已无「工单」" || bad "Issue 列表页仍有「工单」"
else
skip "读不到 issue 列表页(需要登录?), 跳过「工单」检查"
fi
# --- 仓库内文件(在 checkout 里跑时才有意义) --------------------------------
if [[ -d ${ROOT}/issue-templates ]]; then
! grep -rq "example.com" "${ROOT}/issue-templates/" &&
ok "Issue 模板已无 example.com 占位链接" || bad "Issue 模板里仍有 example.com"
fi
if [[ -f ${ROOT}/custom/options/locale/locale_zh-CN.json ]]; then
! grep -q "工单" "${ROOT}/custom/options/locale/locale_zh-CN.json" &&
ok "生成的 zh-CN 语言文件已无「工单」" || bad "语言文件里仍有「工单」"
fi
if [[ ${fail} == 0 ]]; then
echo "全部检查通过"
else
echo "存在检查未通过项"
fi
exit "${fail}"
+15
View File
@@ -0,0 +1,15 @@
# 这个文件唯一的用途: 让 git 跟踪住这个空目录。
#
# customization/custom/ 下的三个子目录会被逐个 bind mount 进容器:
# custom/options -> /data/gitea/options
# custom/public -> /data/gitea/public
# custom/templates-> /data/gitea/templates
# 如果 options/ 在全新克隆里不存在(它下面只放生成出来的 locale_zh-CN.json, 而那个文件
# 是 gitignore 的), 那么 docker compose 会【以 root 创建】这个挂载源目录 —— 之后
# 普通用户跑 customization/build.py 就写不进去:
# PermissionError: [Errno 13] Permission denied: .../custom/options/locale
# 于是语言文件永远生成不出来, 中文界面退回上游文案(「工单」又回来了)。
# 2026-09-13 第一次把生产切到部署克隆时真实踩到。
#
# 有了这个占位文件, 目录随 checkout 就存在且属于当前用户, 问题从结构上消失。
# 真正有内容的是 custom/templates 与 custom/public, 它们不需要占位。
+35
View File
@@ -178,6 +178,41 @@
> 'http://127.0.0.1:2080/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'
> # 期望: 307 + Location: https://cpp.tongji.sh/oidc/auth?... (404 = 认证源没注册上)
> ```
>
> **⚠️ 7. 全新克隆 + compose: docker 会以 root 创建不存在的挂载源目录。**
> `compose.yaml` 把 `customization/custom/{options,public,templates}` 逐个挂进容器。
> 其中 `options/` 里只有生成出来的 `locale_zh-CN.json`, 而它是 gitignore 的 —— 于是
> 全新克隆里这个目录不存在, **docker 会以 root 创建它**, 之后普通用户跑
> `customization/build.py` 就写不进去:
> ```
> PermissionError: [Errno 13] Permission denied: .../custom/options/locale
> ```
> 后果不是报错那么明显: 语言文件生成失败 → 中文界面退回上游文案(「工单」又回来了),
> 而首页/登录页看起来一切正常。2026-09-13 第一次把生产切到部署克隆(CI 用的那份)时踩到。
>
> 现在有两道防线: ①仓库里 `customization/custom/options/.gitkeep` 让目录随 checkout 就存在
> 且属于当前用户; ②`deploy/scripts/auto-deploy.sh` 在部署前检查三个目录存在且**可写**,
> 不满足就明确报错。若已经中招:
> ```bash
> sudo rm -rf customization/custom/options # 空的 root 目录, 删掉即可
> ```
>
> **⚠️ 8. act_runner 的 job 容器不要自己挂 `docker.sock`。**
> act_runner 会把 docker daemon socket **自动**挂进 job 容器(`container.docker_host` 的默认
> 行为); 再在 `deploy/runner/config.yaml` 的 `container.options` 里挂一次, 第一次真实部署
> 就会以这个错误告终:
> ```
> failed to create container: 'Duplicate mount point: /var/run/docker.sock'
> ```
> 2026-09-13 用 `act_runner exec` 预演 job 时提前发现。`container.options` 里只保留
> 部署克隆(同路径)、宿主 docker CLI、compose 插件这三项。
>
> **⚠️ 9. 宿主 `/usr/bin/python3` 是 3.6, 别让它排到 PATH 前面。**
> `customization/build.py` 用了 `from __future__ import annotations`, 需要 ≥3.7。
> 宿主上正确的解释器是 `~/.local/bin/python3`(3.14), 但 `/usr/bin/python3` 是 Rocky 8 的
> 3.6 —— 只要 PATH 被改成 `/usr/bin` 优先, 就会看到
> `SyntaxError: future feature annotations is not defined`, 而且**语言文件静默地不再更新**。
> `auto-deploy.sh` 现在自己挑一个 ≥3.7 的解释器(并用它跑 build.py), 不依赖 PATH 顺序。
---
+52 -9
View File
@@ -1,10 +1,12 @@
# CI/CD:main 自动部署(Gitea Actions 方案)
> **状态:方案,尚未落地。** 全流程**不需要 root**(`ymy` 在 `docker` 组即可),
> 只需要一次「在 Gitea 页面/API 上拿注册令牌」的动作。
> **状态:已落地并本地验证通过(2026-09-13),只差一次 `git push`。**
> runner 已注册、部署克隆已建、生产已切到部署克隆、整条部署路径(含真实 job 容器)
> 已在本机预演通过;推送 `main` 后第一次 CI 运行即接管。**全程不需要 root。**
>
> 本文标注 **[实测]** 的结论都是 2026-09-13 在本机跑出来的,命令写在对应位置,可复现。
> 相关文档:[deploy/README.md](README.md)(部署与陷阱)、
> 当前进度与剩余动作见 §0.1。
> 相关文档:[deploy/README.md](README.md)(部署与陷阱,含本次踩到的 3 个坑)、
> [customization/README.md](../customization/README.md)(定制机制与预览)。
---
@@ -17,6 +19,36 @@
不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 人工流程)、
`issue-templates` 重新推送(运营操作)、官网仓库(`Website`)的部署(那是 GitHub Actions 的事)。
### 0.1 落地现状与剩余动作(2026-09-13)
已完成并验证:
| 项 | 证据 |
|---|---|
| 部署克隆 `/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` |
| 生产已切到部署克隆 | `docker inspect gitea` 的三个挂载源都指向 `/home/ymy/deploy/tjhlp-gitea/...` |
| 部署脚本本机跑通(回滚被真实触发过两次) | `auto-deploy.sh` → `build.py` → `up -d` → `verify.sh` + `check.sh` → `✅ 部署成功`;`deploy/.state/last-deployed` 记 SHA |
| 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):
1. 全新克隆里 `customization/custom/options/` 不存在 → docker 以 root 创建这个挂载源目录 →
`build.py` 写不进去 → **语言文件生成失败、「工单」回归**(首页/登录页却看着正常)。
修法:`.gitkeep` 让目录随 checkout 存在 + 部署前可写性检查。
2. `container.options` 里自己挂 `docker.sock` 与 act_runner 的自动挂载冲突
(`Duplicate mount point`),第一次真实部署必然失败。修法:去掉显式挂载。
3. 宿主 `/usr/bin/python3` 是 **3.6**,PATH 顺序一变 `build.py` 就 `SyntaxError`,而且语言
文件会**静默地**不再更新。修法:脚本自己挑 ≥3.7 的解释器并用它跑 build.py。
剩余动作:
1. **你来 `git push`**(本地有 4 个未推送提交)——推送即触发第一次 CI 运行;由于要部署的
版本已经在本机部署过,这次应当是"无变化"的快速通过。
2. 用一个测试 fork 发 PR,确认 fork PR 的 workflow 审批行为(§9.1);确认前不要把仓库
开放给不可信贡献者。
3. 给 `main` 加分支保护(§4.4)。
---
## 1. 现状与约束 **[实测]**
@@ -164,7 +196,9 @@ services:
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
# 不要在 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 容器
@@ -191,6 +225,8 @@ container:
--volume /usr/bin/docker:/usr/bin/docker:ro
--volume /usr/libexec/docker/cli-plugins:/usr/libexec/docker/cli-plugins:ro
force_pull: false # 镜像已有就别每次拉
# ★ 不要挂 /var/run/docker.sock: act_runner 会自动挂, 重复挂会
# "Duplicate mount point: /var/run/docker.sock" 直接失败(实测)
cache:
enabled: true
```
@@ -419,13 +455,20 @@ 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 ✓;
act_runner v0.6.1 支持 `:host` 标签与 `container.network: host` ✓;compose 插件在 job 容器里
可用 ✓;部署克隆、回环 `127.0.0.1:2080`、经 Apache 的 `10.80.42.185/QA` 在 job 容器内都通 ✓。
仍然未知:
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` 试一次即知)。
2. **workflow 语法支持面**:`concurrency`、`timeout-minutes`、`permissions`、job 级 `if` 里的
`contains(...)` 在 1.27 的实现里是否都生效 —— 第一次真实运行即知。
3. **Gitea 侧的调度与日志回传**:本机只预演了 job *执行*,没预演调度/日志上报。第一次真实
运行会验证。此外部署过程本身会重启 gitea 容器,job 与 Gitea 的连接可能短暂断开
(act_runner 会重试),表现为日志里若干 `failed to fetch task` / `unexpected EOF` —— 属正常现象。
4. **`github.sha` / `github.event.head_commit.message`** 的取值(试运行时 echo 一次确认)。
5. **Actions 日志保留与体积**:`[actions] LOG_RETENTION_DAYS`(默认 365)与存储位置。
6. **Gitea 是否支持"环境审批"**:若有 deployments/environments 的审批,可作为
+10
View File
@@ -0,0 +1,10 @@
# 复制成 .env 后填写(deploy/runner/.env 已 gitignore)
#
# RUNNER_REGISTRATION_TOKEN: 仓库 → Settings → Actions → Runners → 创建 Runner 时给的令牌。
# 一次性, 用完即弃; 注册成功后身份存在 ./data/.runner, 重启不会再注册。
RUNNER_REGISTRATION_TOKEN=
# 默认值在 compose.yaml 里, 需要时再覆盖
#GITEA_INSTANCE_URL=https://cpp.tongji.sh/QA
#RUNNER_NAME=tjhlp-gitea-1
# runner 的 label 不在这里配: 以 config.yaml 的 runner.labels 为准(实测 env 会被忽略)
+33
View File
@@ -0,0 +1,33 @@
# Gitea Actions runner —— 跑在容器里, 由 docker 自己拉起(不需要 root, ymy 在 docker 组即可)。
#
# cd deploy/runner
# cp .env.example .env # 填 RUNNER_REGISTRATION_TOKEN(仓库 → Settings → Actions → Runners)
# docker compose up -d
# docker compose logs -f runner
#
# 详见 ../ci-cd.md §4.2。注册结果存在 ./data/.runner, 重启不会重复注册。
name: gitea-runner
services:
runner:
image: gitea/act_runner:latest # 实测 arm64 / v0.6.1
container_name: gitea-runner
restart: unless-stopped
environment:
# 变量名与镜像里 /usr/local/bin/run.sh 一致
GITEA_INSTANCE_URL: ${GITEA_INSTANCE_URL:-https://cpp.tongji.sh/QA}
GITEA_RUNNER_REGISTRATION_TOKEN: ${RUNNER_REGISTRATION_TOKEN:?deploy/runner/.env 里给 RUNNER_REGISTRATION_TOKEN}
GITEA_RUNNER_NAME: ${RUNNER_NAME:-tjhlp-gitea-1}
# 注意: 不要在这里设 GITEA_RUNNER_LABELS —— act_runner 会警告
# "Labels from command will be ignored, use labels defined in config file.",
# label 以 config.yaml 的 runner.labels 为准(实测)。
CONFIG_FILE: /config/config.yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock # runner 用它拉起 job 容器
- ./data:/data # 注册凭据 / 缓存(gitignore)
- ./config.yaml:/config/config.yaml:ro
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
+36
View File
@@ -0,0 +1,36 @@
# act_runner 配置 —— 关键项都有注释, 依据是 act_runner v0.6.1 自带的 generate-config 输出。
log:
level: info
runner:
file: /data/.runner # 与 compose.yaml 的 ./data 挂载对应; 注册后保存在这里
capacity: 1 # 部署必须串行: 一次只跑一个 job
timeout: 30m
labels:
# job 跑在容器里(network: host), 镜像用 Gitea 官方 runner 镜像(实测 arm64 可用)。
# 换成 catthehacker/ubuntu:act-22.04 也可以; 记得同步 compose.yaml 的 GITEA_RUNNER_LABELS。
- "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-22.04"
container:
# host: job 容器与宿主共用网络 —— verify.sh 里对 127.0.0.1:2080 的检查才有效,
# 10.80.42.185 也不需要额外放行。
network: host
# ★ 不要在这里挂 /var/run/docker.sock: act_runner 会自动把 docker daemon socket
# 挂进 job 容器(container.docker_host 的默认行为), 再挂一次会直接失败:
# failed to create container: 'Duplicate mount point: /var/run/docker.sock'
# (2026-09-13 用 `act_runner exec` 预演 job 时实测踩到 —— 若没预演, 第一次真实
# 部署就会以这个错误告终。)
#
# 下面这些挂载是 act_runner 不管的:
# * 部署克隆同路径挂载: job 容器里 `docker compose` 会把相对挂载解析成绝对路径后
# 交给宿主 daemon, 两边路径必须一致, 否则会挂到空目录;
# * 宿主 docker CLI + compose 插件: 不依赖 job 镜像里带没带(宿主是 glibc, Ubuntu 镜像能用)。
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: /data/cache
+141
View File
@@ -0,0 +1,141 @@
#!/usr/bin/env bash
# main 自动部署 —— 由 .gitea/workflows/deploy.yml 调用, 也可以手工执行。
#
# ./auto-deploy.sh # 部署当前 checkout
# ./auto-deploy.sh <sha> # 部署指定提交
#
# 流程: build.py(生成+校验) → docker compose up -d → 验证(verify.sh + check.sh)
# 任一步失败 → 回滚到 deploy/.state/last-deployed 记录的上一个成功提交。
# 只动代码与挂载文件; 数据库/`.env`/备份目录全程不参与(见 deploy/ci-cd.md §6)。
set -euo pipefail
REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[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}"
# 本机/内网回环验证不能走代理, 否则会把 200 变成 502(见 deploy/README.md 陷阱 5)
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
export no_proxy='*' NO_PROXY='*'
# 只补齐标准路径(append): 不要把 /usr/bin 提到最前面 —— 宿主上 /usr/bin/python3 是 3.6
export PATH="${PATH}:/usr/local/bin:/usr/bin:/bin"
# build.py 用了 `from __future__ import annotations`, 需要 python3 >= 3.7。
# 宿主: python3 在 ~/.local/bin(3.14), /usr/bin/python3 是 3.6(Rocky 8);
# job 容器(Ubuntu 22.04): /usr/bin/python3 是 3.10。所以不能盲信 PATH 里的第一个。
# (第一次实测就踩到: 把 /usr/bin 提前 → 用 3.6 跑 build.py → SyntaxError → 语言文件没生成。)
pick_python() {
local c
for c in "$(command -v python3 2>/dev/null)" /usr/local/bin/python3 /usr/bin/python3 "${HOME}/.local/bin/python3"; do
[[ -n ${c} && -x ${c} ]] || continue
if "${c}" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 7) else 1)' 2>/dev/null; then
printf '%s' "${c}"
return 0
fi
done
return 1
}
PY="$(pick_python)" || {
echo "[auto-deploy] 找不到 >= 3.7 的 python3, 中止"
exit 1
}
echo "[auto-deploy] python3: ${PY} ($("${PY}" -V 2>&1))"
mkdir -p "${STATE_DIR}"
TARGET="${1:-$(git -C "${REPO_DIR}" rev-parse HEAD)}"
PREV="$(cat "${STATE_FILE}" 2>/dev/null || true)"
# job 容器里是 root, 会把 clone 里新生成的文件留成 root 所有, 影响宿主上的手工 git 操作。
# 结束时(无论成功失败)把所有权还回去。
restore_owner() {
[[ "$(id -u)" == 0 ]] || return 0
chown -R "${DEPLOY_OWNER_UID:-1001}:${DEPLOY_OWNER_GID:-1001}" "${REPO_DIR}" 2>/dev/null || true
}
trap restore_owner EXIT
# workflow 的 concurrency 之外再加一道, 防止手工执行与 CI 撞车
exec 9>"${STATE_DIR}/lock"
flock -n 9 || {
echo "[auto-deploy] 已有部署在跑, 本次退出"
exit 0
}
echo "[auto-deploy] 目标 ${TARGET} (上次成功部署: ${PREV:-无})"
cd "${REPO_DIR}"
# customization/custom/ 的指纹: 模板、静态页、生成的语言文件都在里面。
# 这些是 Gitea 启动时加载的, 变了必须重启容器才生效(README §3), 而 `compose up -d`
# 只在 compose 配置变化时才重建 —— 所以这里自己比指纹, 变了就 restart。
custom_hash() {
(cd customization/custom && find . -type f -exec sha256sum {} + | sort | sha256sum | cut -d' ' -f1)
}
# compose 的 bind mount 源目录必须先存在【且属于当前用户】: 源目录不存在时 docker 会
# 以 root 创建它, 之后 build.py 就写不进去(全新克隆第一次部署时真实踩到, 于是语言文件
# 生成失败、「工单」回来了)。仓库里 custom/options/.gitkeep 从结构上避免这一点,
# 这里再兜底检查一次, 失败就说清楚怎么办。
prepare_custom_dirs() {
local d
for d in options public templates; do
if [[ ! -d customization/custom/${d} ]]; then
mkdir -p "customization/custom/${d}" 2>/dev/null || {
echo "[auto-deploy] 无法创建 customization/custom/${d}" >&2
return 1
}
fi
if [[ ! -w customization/custom/${d} ]]; then
echo "[auto-deploy] customization/custom/${d} 不可写 —— 很可能是 docker 以 root 创建过它。" >&2
echo " 删除后重试(宿主上需 sudo; job 容器里是 root): rm -rf customization/custom/${d}" >&2
return 1
fi
done
}
deploy() {
local before after
prepare_custom_dirs || return 1
before="$(custom_hash)"
"${PY}" customization/build.py || return 1 # 生成语言文件 + 规范 custom/ 权限
"${PY}" customization/build.py --check || return 1 # 生成物/权限校验, 不过就中止, 不碰容器
after="$(custom_hash)"
(cd deploy && docker compose up -d) || return 1 # 幂等: 只有配置/挂载/镜像变化时才重建
if [[ ${before} != "${after}" ]]; then
echo "[auto-deploy] custom/ 有变化(模板/静态页/语言文件), 重启 gitea 使其生效"
(cd deploy && docker compose restart gitea) || return 1
fi
}
verify() {
(cd deploy && ./scripts/verify.sh) || return 1 # 容器健康 + 本机 API + 经 Apache 反代
if [[ -x ${REPO_DIR}/customization/check.sh ]]; then
"${REPO_DIR}/customization/check.sh" "${PUBLIC_URL}" || return 1 # 定制断言
else
# 回滚到旧版本时那个版本可能还没有这个脚本 —— 那不是失败
echo "[auto-deploy] (${TARGET} 这个版本没有 customization/check.sh, 跳过定制断言)"
fi
}
rollback() {
if [[ -z ${PREV} ]]; then
echo "[auto-deploy] 没有历史成功版本可回退, 保持现状"
return 0
fi
echo "[auto-deploy] 回滚到 ${PREV}"
# -f: 旧版本里可能没有 deploy/runner/* 这类文件, 它们在新版本是"未跟踪文件",
# 会挡住普通 checkout(实测), 这里直接覆盖
git checkout -f --detach "${PREV}"
deploy || true
verify || true
}
# 包成一个函数再放进 if: 避免依赖 "&& 列表最后一个命令在 if 条件里是否触发 errexit" 这类细节
pipeline() { deploy && verify; }
if pipeline; then
echo "${TARGET}" >"${STATE_FILE}"
echo "[auto-deploy] ✅ 部署成功 ${TARGET}"
else
echo "[auto-deploy] ❌ 部署或验证失败, 开始回滚"
rollback
exit 1
fi