# CI/CD:main 自动部署(Gitea Actions 方案) > **状态:已落地并本地验证通过(2026-09-13),只差一次 `git push`。** > runner 已注册、部署克隆已建、生产已切到部署克隆、整条部署路径(含真实 job 容器) > 已在本机预演通过;推送 `main` 后第一次 CI 运行即接管。**全程不需要 root。** > > 本文标注 **[实测]** 的结论都是 2026-09-13 在本机跑出来的,命令写在对应位置,可复现。 > 当前进度与剩余动作见 §0.1。 > 相关文档:[deploy/README.md](README.md)(部署与陷阱,含本次踩到的 3 个坑)、 > [customization/README.md](../customization/README.md)(定制机制与预览)。 --- ## 0. 目标 `course-team/tjhlp-gitea` 的 `main` 一有推送,就自动把平台更新到那个提交: 构建定制产物 → 重建容器 → 跑验证 → 失败自动回滚。人工只负责 review 和 push。 不在本方案范围内:Gitea 版本升级(要备份 + 数据库迁移,仍走 [README §7](README.md) 人工流程)、 `issue-templates` 重新推送(运营操作)、官网仓库(`Website`)的部署(那是 GitHub Actions 的事)。 ### 0.1 落地现状与剩余动作(2026-09-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. 现状与约束 **[实测]** | 项 | 实测值 | 对方案的影响 | |---|---|---| | 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` | 直接复用 | --- ## 2. 方案总览 ### 2.1 架构 ```text 开发者 push main │ ▼ 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 runner 形态:容器(推荐)vs 宿主二进制 | | **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 时选它 | act_runner v0.6.1 自己的 `generate-config` 输出里明确写了两种 label 写法,两个事实由此确认: ```text # Like: "macos-arm64:host" or "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest" labels: - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest" container: # Could be host, bridge or the name of a custom network. network: "" ``` 即 **`:host` 支持**(备选 B 可用)、**`container.network: host` 支持**(方案 A 里让 job 容器 能和宿主共用回环,`verify.sh` 里 `127.0.0.1:2080` 的检查才继续有效)。 ### 2.3 触发与门禁 - 触发:`push` 到 `main`,外加 `workflow_dispatch`(落地初期先只手动触发); - 跳过:提交信息含 `[skip deploy]` 不部署(与 Gitea 自带的 `[skip ci]` 同风格); - 串行:workflow 的 `concurrency` + 脚本里的 `flock` 双保险; - 只认 `main`:job 级 `if` 卡死分支,PR/其它分支即使跑工作流也不碰生产。 --- ## 3. 组件清单 | 组件 | 位置 | 谁维护 | |---|---|---| | 部署克隆 | `/home/ymy/deploy/tjhlp-gitea` | 本方案新建(§4.1) | | 部署凭据 | `deploy/.env`(`chmod 600`,已 gitignore) | 从现有部署复制 | | 部署状态 | `deploy/.state/last-deployed`(上次成功的 SHA) | 脚本写,加进 `.gitignore` | | runner | `deploy/runner/compose.yaml` + `deploy/runner/config.yaml` + `deploy/runner/data/`(gitignore) | 新增到仓库 | | 工作流 | `.gitea/workflows/deploy.yml` | 新增到仓库(§5.1) | | 部署脚本 | `deploy/scripts/auto-deploy.sh` | 新增到仓库(§5.2) | | 定制断言 | `customization/check.sh ` | 新增到仓库(§5.3) | --- ## 4. 落地步骤 ### 4.1 部署克隆(不需要 root) ```bash # 让 ymy 能读 Gitea 的裸仓库。 # ★ 实测: git -c safe.directory=... 对本机 git 无效, 必须写进配置文件才生效。 git config --global --add safe.directory \ /srv/gitea/git/repositories/course-team/tjhlp-gitea.git # 从裸仓库克隆: origin 就指向本机裸仓库, CI 全程不需要任何 git token git clone /srv/gitea/git/repositories/course-team/tjhlp-gitea.git \ /home/ymy/deploy/tjhlp-gitea cd /home/ymy/deploy/tjhlp-gitea cp /home/ymy/tjhlp-gitea/deploy/.env deploy/.env # 部署密钥, 别提交 chmod 600 deploy/.env mkdir -p deploy/.state ``` > ⚠️ 从此 `deploy/.env` 有**两份**(dev 克隆一份、部署克隆一份)。约定:**部署克隆那份是权威**, > dev 克隆那份只服务本地预览;改密钥时两边同步。 > > ⚠️ 切换后**不要再从 dev 克隆 `up -d`**:compose 项目名同为 `gitea`(同一组容器),但 bind mount > 的源路径按 compose 文件所在目录解析,两边会互相覆盖。dev 克隆只留开发与预览。 ### 4.2 起 runner 并注册(不需要 root) 先在 Gitea 上拿一个**仓库级**注册令牌(API 实测存在: `POST /api/v1/repos/{owner}/{repo}/actions/runners/registration-token`; 也可以在 仓库 → Settings → Actions → Runners 页面点按钮): ```bash curl -sS -X POST \ -H "Authorization: token <你的 PAT, 需要 repo 权限>" \ "http://10.80.42.185/QA/api/v1/repos/course-team/tjhlp-gitea/actions/runners/registration-token" \ | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])' ``` 把令牌写进 `deploy/runner/.env`(gitignore),然后: ```bash cd /home/ymy/deploy/tjhlp-gitea/deploy/runner docker compose up -d docker compose logs -f runner # 看到 "runner registered successfully" 即可 ``` 仓库 → Settings → Actions → Runners 里应出现 `tjhlp-gitea-1`(Idle)。注册令牌用完即弃: 注册结果存在 `deploy/runner/data/.runner`,之后 runner 用它通信,不会过期。 `deploy/runner/compose.yaml`: ```yaml name: gitea-runner services: runner: image: gitea/act_runner:latest # 实测 arm64 / v0.6.1 / 可拉取 restart: unless-stopped environment: # 这组变量名来自镜像里的 /usr/local/bin/run.sh(实测) GITEA_INSTANCE_URL: http://10.80.42.185/QA GITEA_RUNNER_REGISTRATION_TOKEN: ${RUNNER_REGISTRATION_TOKEN:?先按 §4.2 拿令牌} GITEA_RUNNER_NAME: tjhlp-gitea-1 # 不要在 env 里设 GITEA_RUNNER_LABELS: act_runner 会警告 # "Labels from command will be ignored, use labels defined in config file.", # label 以 config.yaml 为准(实测) CONFIG_FILE: /config/config.yaml volumes: - /var/run/docker.sock:/var/run/docker.sock # runner 用它拉起 job 容器 - ./data:/data # 注册凭据 (.runner) - ./config.yaml:/config/config.yaml:ro ``` `deploy/runner/config.yaml`: ```yaml log: level: info runner: file: /data/.runner capacity: 1 # 部署必须串行, 一个 job 一个 job 地跑 timeout: 30m labels: # job 跑在容器里; 镜像换成本地已有/更小的亦可(如 catthehacker/ubuntu:act-22.04) - "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-22.04" container: network: host # job 容器与宿主共用网络: 127.0.0.1:2080 与 10.80.42.185 都能直连 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 # 镜像已有就别每次拉 # ★ 不要挂 /var/run/docker.sock: act_runner 会自动挂, 重复挂会 # "Duplicate mount point: /var/run/docker.sock" 直接失败(实测) cache: enabled: true ``` 三处关键点: - `--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` 默认行为), 上面仍显式挂一次更直观。 ### 4.3 试运行(手动触发) 1. 提交 §5 的文件,workflow 的 `on:` **先只留 `workflow_dispatch`**(没有 runner 时 push 触发 会一直挂在"等待 runner"); 2. 仓库 → Actions → deploy → **Run workflow**(选 `main`); 3. 盯日志确认:构建 → `up -d` → 验证全过 → Actions 绿色; 4. 故意推一个坏提交(例如把 `overrides/locale_zh-CN.json` 的键写错)验证**回滚路径**真的生效。 ### 4.4 打开自动触发 + 加保护 1. 把 `push: branches: [main]` 加回 workflow; 2. 仓库 → Settings → Branches → 给 `main` 加保护:**要求 PR + 至少 1 个 review**; 3. `deploy/README.md` 的快速索引里已有一行指向本文档。 --- ## 5. 流水线内容 ### 5.1 `.gitea/workflows/deploy.yml` 刻意做得很薄:workflow 只做"同步到目标提交 + 调仓库里的部署脚本",逻辑都在 `auto-deploy.sh`(可版本化、可手工跑、可本地调试)。 ```yaml name: deploy on: push: branches: [main] workflow_dispatch: # 阶段 4.3 只留这个 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 git checkout --detach "${{ github.sha }}" - name: 构建并部署(失败自动回滚) run: | set -euo pipefail ./deploy/scripts/auto-deploy.sh ``` **不写 `uses:`** 的理由:本项目不需要——代码从本机裸仓库取、部署逻辑是仓库里的脚本, 省掉每次运行下载 action 的开销,也避开 `github.com` 主站直连超时带来的不确定性。 将来若要做 PR 检查(lint/pytest)想用现成 action,两条路:给 runner 容器配容器可达的代理, 或在 runner 的 `config.yaml` 里设置 `github_mirror`(v0.6.1 的配置注释里就是为"特殊网络环境" 准备的),把 `uses:` 的 github 地址替换成镜像。 ### 5.2 `deploy/scripts/auto-deploy.sh` ```bash #!/usr/bin/env bash # main 自动部署。由 .gitea/workflows/deploy.yml 调用, 也可手工执行: # ./auto-deploy.sh # 部署当前 checkout # ./auto-deploy.sh # 部署指定提交 set -euo pipefail REPO_DIR=$(cd "$(dirname "$0")/../.." && pwd) STATE_DIR="${REPO_DIR}/deploy/.state" STATE_FILE="${STATE_DIR}/last-deployed" PUBLIC_URL="${GITEA_PUBLIC_URL:-http://10.80.42.185/QA}" # 本机回环验证不能走代理, 否则会拿 502 冒充故障(见 README 陷阱 5) unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY export no_proxy='*' NO_PROXY='*' # 既能在 job 容器里跑, 也能在宿主上跑; 不要写死某台机器的 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) exec 9>"${STATE_DIR}/lock" # workflow 的 concurrency 之外再加一道 flock -n 9 || { echo "[auto-deploy] 已有部署在跑, 退出"; exit 0; } echo "[auto-deploy] 目标 ${TARGET} (上次成功: ${PREV:-无})" cd "$REPO_DIR" deploy() { python3 customization/build.py # 生成语言文件 + 规范 custom/ 权限(容器用户要能读) python3 customization/build.py --check # 生成物/权限校验, 不过就中止, 不碰容器 ( cd deploy && docker compose up -d ) # 幂等: 只有配置/镜像变化时才重建 } verify() { ( cd deploy && ./scripts/verify.sh ) # 容器健康 + 本机 API + 经 Apache 反代 customization/check.sh "$PUBLIC_URL" # 定制断言: 首页/登录页/OIDC/术语(见 5.3) } rollback() { [[ -z "${PREV}" ]] && { echo "[auto-deploy] 无历史版本可回退, 保持现状"; return 0; } echo "[auto-deploy] 回滚到 ${PREV}" git checkout --detach "$PREV" deploy || true verify || true } if deploy && verify; then echo "$TARGET" > "$STATE_FILE" echo "[auto-deploy] ✅ 部署成功 ${TARGET}" else echo "[auto-deploy] ❌ 部署或验证失败, 开始回滚" rollback exit 1 # 让这次 Actions 运行标红, 完整日志留在 UI 里 fi ``` 落库前的两个小动作:`.gitignore` 加 `deploy/.state/`、`deploy/runner/data/`、 `deploy/runner/.env`;给 `auto-deploy.sh` 加可执行位(`git` 只记可执行位)。 **不做**的事及理由: - 每次部署不做数据库备份:部署只改代码/配置,DB 不动;且 `deploy/backups/` 是 `root:root`, CI 以 `ymy` 跑写不进去。版本升级仍走 README §7(带备份); - 不自动重推 `issue-templates`:运营动作,不该跟代码推送耦合。 ### 5.3 新增 `customization/check.sh ` `preview.sh check` 里那一串"定制有没有生效"的断言(首页文案、页脚、meta、静态页、官网链接、 不出现「工单」、登录页两张卡、无通行密钥方框)正是部署后要守的东西。落地时把它抽出来共用: ```bash customization/check.sh http://127.0.0.1:2081 # 预览 customization/check.sh http://10.80.42.185/QA # 生产(CI 里调) ``` 生产侧再加两条(今天踩过的坑,必须自动化守住): ```bash # 1) OIDC 认证源注册成功: 必须是 307 跳到统一身份认证; 404 = 认证源没注册上 curl -sS --noproxy '*' -o /dev/null -w '%{http_code} %{redirect_url}\n' \ "${BASE}/user/oauth2/%E9%AB%98%E7%A8%8B%E7%BB%9F%E4%B8%80%E8%BA%AB%E4%BB%BD%E8%AE%A4%E8%AF%81" # 2) 登录页有「管理员登录」卡片且没有 passkey 空方框 curl -sS --noproxy '*' -H 'Accept-Language: zh-CN' "${BASE}/user/login" | grep -c '管理员登录' ``` --- ## 6. 失败与回滚 | 失败点 | 行为 | |---|---| | `build.py` 报错(overrides 键不存在/占位符改坏/文件不可读) | 立即中止,**不碰容器**,Actions 标红 | | `docker compose up -d` 失败(配置语法/镜像缺失) | 重试无意义 → 直接回滚 | | 容器起不来(模板报错、权限 600 之类的 `[F]`) | `verify.sh` 等到 start_period 结束仍非 healthy → 回滚 | | 验证断言失败(首页文案丢了、OIDC 404、出现「工单」) | 回滚 | | 回滚也失败 | 脚本打印现场并 `exit 1`;线上仍是坏版本,需要人工介入(`docker compose logs`) | | runner 掉线 | 推送后 Actions 显示"等待 runner",**不会**部署、也不影响线上;`docker compose up -d` 恢复 | 回滚 = `git checkout --detach <上一个成功 SHA>` + 重新 `up -d`,只动代码与挂载文件; 数据库、`/srv/gitea` 数据、`.env` 全程不参与,所以几十秒内完成。 --- ## 7. 安全 - job 容器里挂了 `docker.sock`,而 `docker` 组等价 root;host 模式(备选 B)更是直接以 `ymy` 在 宿主执行。所以: 1. runner 只注册成**仓库级**(`/repos/{owner}/{repo}/actions/runners/registration-token`), 不要注册成 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);注册令牌一次性用完即弃; 只有将来要回写状态/发 Issue 时才需要 Actions secrets(1.27 支持仓库级 `/repos/{owner}/{repo}/actions/secrets`)。 - `gitea/act_runner` 镜像来自 Docker Hub 的官方组织仓库(本机 daemon 经代理拉取); 落地时记录 tag/digest,升级方式与 Gitea 同(写进 README 升级章节)。 --- ## 8. 日常操作 ```bash # 手动部署当前 main(不依赖 Actions/runner) /home/ymy/deploy/tjhlp-gitea/deploy/scripts/auto-deploy.sh # 回滚到指定提交 cd /home/ymy/deploy/tjhlp-gitea && git checkout --detach && ./deploy/scripts/auto-deploy.sh # runner 启停 / 看日志 cd /home/ymy/deploy/tjhlp-gitea/deploy/runner && docker compose logs -f runner docker compose stop runner && docker compose start runner # 平台日志(部署后排查) docker compose -f /home/ymy/deploy/tjhlp-gitea/deploy/compose.yaml logs -f gitea # 每次运行的完整日志在 仓库 → Actions 里 ``` --- ## 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. **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. 备选方案 | 方案 | 何时选 | 代价 | |---|---|---| | **B. 宿主二进制 + host 模式** | 不想给 job 容器挂 docker.sock / 不想维护 job 镜像 | 需要一次 sudo 装 systemd 单元;label 用 `self-hosted:host`(v0.6.1 配置里确认支持) | | **cron 轮询 + `auto-deploy.sh`** | fork PR 策略不可控,或不想让仓库里的代码在宿主上执行 | 延迟 ≤60s;无 UI/日志,只有落盘日志 | | **纯手工** | 推送频率低、每次都想人工确认 | 就是现在这样 | cron 版的触发部分(其余复用 §5.2 的脚本): ```cron # crontab -e (ymy) * * * * * cd /home/ymy/deploy/tjhlp-gitea && git fetch -q origin main && \ [ "$(git rev-parse origin/main)" != "$(cat deploy/.state/last-deployed 2>/dev/null)" ] && \ ./deploy/scripts/auto-deploy.sh "$(git rev-parse origin/main)" >> deploy/.state/cron.log 2>&1 ``` --- ## 11. 落地顺序(一句话版) ```text 4.1 部署克隆 → 4.2 拿仓库级令牌 + docker compose 起 runner → 4.3 只留 workflow_dispatch 手动跑通并演练一次回滚 → 4.4 打开 push 触发 + main 分支保护 ```