Files
persionalBrand/docs/ci.md
que01 18bcdbeb00
CI / Static checks (push) Successful in 5m49s
CI / Production build (push) Successful in 5m44s
CI / Browser smoke (push) Has been skipped
CI / API integration (push) Successful in 3m36s
ci: 增加 PR 浏览器 smoke (#1)
2026-10-21 07:49:43 +00:00

110 lines
5.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CI(Gitea Actions)
远端仓库是 Gitea,CI 由 `.gitea/workflows/ci.yml` 定义,运行在 `oracle_arm` 主机上的 self-hosted runner。
## Runner
安装与运维步骤见 `docs/runner-setup.md`(`deploy/runner/install-runner.sh` 可复现整套配置)。
- 程序:`gitea-runner` v5.2.0(linux/arm64),位于 `/home/ubuntu/gitea-runner`
- 服务:systemd user unit `gitea-runner.service`
- 标签:`ubuntu-latest`、`oracle-arm`
- 执行模式:Docker,单并发,任务容器限制 `--cpus=1.5 --memory=4g`
- 作用域:仅 `que01/persionalBrand` 仓库
查看状态:
```bash
ssh oracle_arm 'systemctl --user status gitea-runner.service'
ssh oracle_arm 'journalctl --user -u gitea-runner -n 100 --no-pager'
```
## 当前门禁
- `static`:格式、lint、typecheck、模板检查、路由与模板 preview 覆盖
- `build`:生产构建、Admin preview 构建、模板 release 校验
- `api`:PostgreSQL service container 上的 API integration
- `browser-smoke`:PR 和手动触发时执行会话恢复、创建品牌与页面方案 smoke;只在 PR 和 `workflow_dispatch` 运行,main 合并后不重复执行
完整浏览器回归仍作为发布前本地门禁执行,避免在 2 核生产主机上运行完整 Playwright 套件抢占资源。PR smoke 只跑两条关键流程,并使用已构建的 Admin 静态产物与 mocked API。
## 注意
Runner 与生产 API 共用 `oracle_arm` 主机。任务容器已限制 CPU 与内存;如果 CI 期间生产延迟明显,应暂停 runner 或迁移到独立主机。
## 缓存
Runner 内置 cache server(`cache.host=172.17.0.1`、`cache.port=8193`、`cache.dir=/home/ubuntu/gitea-runner/cache-data`),供 `actions/setup-node` 的 pnpm 缓存使用。
任务容器与主机之间被 `ufw` 的 `INPUT DROP` 默认策略拦截,需要显式放行 Docker 使用的三个私网网段:
```bash
sudo ufw allow from 172.16.0.0/12 to any port 8193 proto tcp comment "gitea actions cache"
sudo ufw allow from 192.168.0.0/16 to any port 8193 proto tcp comment "gitea actions cache"
sudo ufw allow from 10.0.0.0/8 to any port 8193 proto tcp comment "gitea actions cache"
```
注意 Gitea Actions 会为每个 job 建立自己的 bridge 网络(实测网关为 `192.168.80.1`),不只是默认的 `172.17.0.1`;只放行 `172.16.0.0/12` 仍然会超时。
未放行时表现为 `Failed to GetCacheEntryDownloadURL ... ETIMEDOUT`,每个 job 会额外空等数分钟,且缓存永远不会命中。验证方式是在 job 容器内直接请求缓存端口:
```bash
docker exec <job-container> node -e 'fetch("http://172.17.0.1:8193/").then(r=>console.log(r.status))'
```
返回 `404` 表示连通(该端口不提供根路径),超时表示仍被拦截。
Runner 日志级别保持 `debug`:`info` 级别不会记录各 step 的 `Success - Main ...` 与告警,排障时只能依赖 Gitea 页面。
## 首次完整通过
| 项 | 值 |
| ---------------- | ----------------------------- |
| run | `21`(`run_number=21`) |
| commit | `c33c9cb` |
| Static checks | 05:03:54 → 05:15:42 UTC,通过 |
| Production build | 05:15:47 → 05:27:27 UTC,通过 |
| API integration | 05:27:32 → 05:37:16 UTC,通过 |
单并发下整轮约 33 分钟;三个 job 串行执行,主要耗时在 `pnpm install` 与构建。
该轮次全部告警均来自缓存后端不可达(`ETIMEDOUT`),已按上一节修复。
修复后的对照数据(run `22`,commit `261a33a`;run `23` 的 static 为 5.7 分钟):
| job | 修复前耗时 | 修复后耗时 |
| ---------------- | ---------- | --------------------------------------------------------- |
| Static checks | 11.8 min | 11.7 min(该 job 在放行规则生效前启动,仍走缓存超时路径) |
| Production build | 11.7 min | 7.6 min |
| API integration | 9.7 min | 3.8 min |
缓存内容为 pnpm store,首次落盘约 268 MB,位于 `/home/ubuntu/gitea-runner/cache-data`。
## 触发范围
- `push` 到 `main` 时忽略纯文档改动(`**.md`),避免 2 核主机为文档提交跑完整 CI。
- `pull_request` 不设置 `paths-ignore`。branch protection 要求的 status check 必须每次都上报,否则纯文档 PR 会一直停在「等待检查」而无法合并。
- 需要给纯文档提交补一次状态时,用 `workflow_dispatch` 手动触发。
模板完成证据的源码哈希已同步收敛,文档、CI 配置和部署脚本改动不再使证据失效;模板、renderer、Admin 模板编辑器、品牌内容 API 等会影响交付的源码改动仍会更新哈希。`pre-commit` 会按 Git index 重算并暂存证据,不再需要单独的 `chore: 更新模板完成证据源码哈希` 提交。注意:`pre-commit` 只在该仓库执行过 `pnpm install`(触发 `prepare` 设置 `core.hooksPath`)后生效。
## 分支保护
`main` 由 Gitea branch protection 保护,规则为:
- 禁止直接 push 和 force push,所有改动走分支 + Pull Request。
- 必须通过 `CI / *` 状态检查(覆盖 `Static checks`、`Production build`、`API integration` 及其后续新增 job)。
- `required_approvals = 0`:当前是单人维护,不强制他人审批,但 CI 必须全绿。
仓库管理员如需紧急放行,应临时调整保护规则并在事后恢复,不要长期用管理员权限绕过检查。规则可通过 `PATCH /api/v1/repos/que01/persionalBrand/branch_protections/main` 复现:
```json
{
"enable_push": false,
"enable_force_push": false,
"enable_status_check": true,
"status_check_contexts": ["CI / *"],
"required_approvals": 0
}
```