From 73ce8162aa6d2de855f5ae0b80f6a00df4e0f48327eec1596901fbe9fb21245b Mon Sep 17 00:00:00 2001 From: Maoayo233 Date: Sun, 13 Sep 2026 21:53:34 +0800 Subject: [PATCH] =?UTF-8?q?feat(ci):=20=E8=90=BD=E5=9C=B0=20main=20?= =?UTF-8?q?=E8=87=AA=E5=8A=A8=E9=83=A8=E7=BD=B2=E7=9A=84=E5=8F=AF=E5=A4=8D?= =?UTF-8?q?=E7=94=A8=E4=BB=B6(runner=20=E9=85=8D=E7=BD=AE/=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E8=84=9A=E6=9C=AC/=E5=AE=9A=E5=88=B6=E6=96=AD?= =?UTF-8?q?=E8=A8=80/=E5=B7=A5=E4=BD=9C=E6=B5=81)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按 deploy/ci-cd.md 方案把除推送触发之外的东西都准备好: - customization/check.sh : 把 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(含全部实测证据与待确认项)。 --- .gitea/workflows/deploy.yml | 40 ++++++++ .gitignore | 4 + customization/build.py | 10 +- customization/check.sh | 119 ++++++++++++++++++++++ customization/custom/options/.gitkeep | 15 +++ deploy/README.md | 35 +++++++ deploy/ci-cd.md | 61 +++++++++-- deploy/runner/.env.example | 10 ++ deploy/runner/compose.yaml | 33 ++++++ deploy/runner/config.yaml | 36 +++++++ deploy/scripts/auto-deploy.sh | 141 ++++++++++++++++++++++++++ 11 files changed, 494 insertions(+), 10 deletions(-) create mode 100644 .gitea/workflows/deploy.yml create mode 100755 customization/check.sh create mode 100644 customization/custom/options/.gitkeep create mode 100644 deploy/runner/.env.example create mode 100644 deploy/runner/compose.yaml create mode 100644 deploy/runner/config.yaml create mode 100755 deploy/scripts/auto-deploy.sh diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml new file mode 100644 index 0000000..a6c322f --- /dev/null +++ b/.gitea/workflows/deploy.yml @@ -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 diff --git a/.gitignore b/.gitignore index 930a335..be46b02 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/customization/build.py b/customization/build.py index 3c4d66d..8163015 100755 --- a/customization/build.py +++ b/customization/build.py @@ -188,7 +188,15 @@ def main() -> int: return 0 OUT_PATH.parent.mkdir(parents=True, exist_ok=True) - OUT_PATH.write_text(rendered, encoding="utf-8") + 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: diff --git a/customization/check.sh b/customization/check.sh new file mode 100755 index 0000000..28611e9 --- /dev/null +++ b/customization/check.sh @@ -0,0 +1,119 @@ +#!/usr/bin/env bash +# 定制生效断言 —— 对任意实例跑一遍, 预览与生产共用。 +# 用法: +# customization/check.sh http://127.0.0.1:2081 # 预览 +# customization/check.sh http://10.80.42.185/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 "http://10.80.42.185/Website/" "${tmp}/home.html" && + ok "首页/导航栏已链接课程官网" || bad "首页没有课程官网链接" +grep -q "http://10.80.42.185/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}" diff --git a/customization/custom/options/.gitkeep b/customization/custom/options/.gitkeep new file mode 100644 index 0000000..8b8de5f --- /dev/null +++ b/customization/custom/options/.gitkeep @@ -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, 它们不需要占位。 diff --git a/deploy/README.md b/deploy/README.md index 27c01f1..b63410c 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -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: http://10.80.42.185/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 顺序。 --- diff --git a/deploy/ci-cd.md b/deploy/ci-cd.md index cd16d7d..34b103f 100644 --- a/deploy/ci-cd.md +++ b/deploy/ci-cd.md @@ -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: http://10.80.42.185/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 的审批,可作为 diff --git a/deploy/runner/.env.example b/deploy/runner/.env.example new file mode 100644 index 0000000..583ce2e --- /dev/null +++ b/deploy/runner/.env.example @@ -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=http://10.80.42.185/QA +#RUNNER_NAME=tjhlp-gitea-1 +# runner 的 label 不在这里配: 以 config.yaml 的 runner.labels 为准(实测 env 会被忽略) diff --git a/deploy/runner/compose.yaml b/deploy/runner/compose.yaml new file mode 100644 index 0000000..a0bab9e --- /dev/null +++ b/deploy/runner/compose.yaml @@ -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:-http://10.80.42.185/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" diff --git a/deploy/runner/config.yaml b/deploy/runner/config.yaml new file mode 100644 index 0000000..e904bba --- /dev/null +++ b/deploy/runner/config.yaml @@ -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 diff --git a/deploy/scripts/auto-deploy.sh b/deploy/scripts/auto-deploy.sh new file mode 100755 index 0000000..f7acffb --- /dev/null +++ b/deploy/scripts/auto-deploy.sh @@ -0,0 +1,141 @@ +#!/usr/bin/env bash +# main 自动部署 —— 由 .gitea/workflows/deploy.yml 调用, 也可以手工执行。 +# +# ./auto-deploy.sh # 部署当前 checkout +# ./auto-deploy.sh # 部署指定提交 +# +# 流程: 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