docs(docs): 新增 CICD 参考实现规范

- project_rules §15.7: 参考项目位置 + 关键配置点（container/runner 标签/部署方式/网络） - cicd-runbook §10: 参考项目对照表（配置项、关键差异、修改流程、冲突处理） - 修正 cicd-runbook runner 标签：self-hosted,deploy → ubuntu-latest
2026-07-08 16:12:45 +08:00
parent c31b3ddeba
commit a1d7fcfd71
2 changed files with 88 additions and 10 deletions
--- a/.trae/rules/project_rules.md
+++ b/.trae/rules/project_rules.md
@@ -510,6 +510,23 @@ services/[service]/src/
 | `.github/workflows/docker.yml` | Docker 镜像构建与推送（main + tag 触发）    |
 | `.github/workflows/deploy.yml` | 部署到服务器（main 触发，需环境审批）       |

+### 15.7 参考实现（强制参照）
+
+**所有 CI/CD 配置必须参照 `E:\Desktop\CICD\` 项目（同机 Gitea 仓库），不另行自创。**
+
+- **参考项目位置**：`E:\Desktop\CICD\.gitea\workflows\ci.yml`（同机单仓库 CI 实现）
+- **关键配置点（必须沿用）**：
+  - **Runner 标签**：`ubuntu-latest`（actrunner 已配置；参考项目用 `CDCD`，Edu 改为 `ubuntu-latest`）
+  - **容器化运行**：TS 类 job 必须使用 `container: dockerreg.eazygame.cn/node-with-docker:22`（带 docker 的 node 22 镜像，用于在 job 内执行 `docker build`/`docker run`）
+  - **Go 类 job**：使用 `container: golang:1.22-alpine`（仅 quality 阶段），`docker-build` 阶段切换到 `node-with-docker:22` 镜像 + `setup-go`
+  - **部署方式**：保留 `docker compose`（不照搬参考项目的 `docker run` 单容器方式，因 Edu 是微服务多容器）
+  - **代理配置**：runner 已配置全局代理，CI 内不再设置 npm/docker 代理（参考项目中的 `172.17.0.1:7890` 代理段不要照搬）
+  - **Next.js standalone 构建**：teacher-portal 沿用参考项目的 standalone 模式（`output: 'standalone'` + 复制 public/.next/static）
+  - **网络**：部署用 `edu-shared` 外部网络连接服务器已有 MySQL/Redis（参考项目用 `1panel-network`，Edu 不同）
+- **改动需同步**：修改任何 workflow 文件前，先比对参考项目同类配置，确保不偏离上述约定
+
+> 当参考项目与本规范冲突时，以本规范为准（Edu 是微服务架构，参考项目是单体 Next.js）。
+
 ---

 **本规则文件是项目的强制约束，所有 contributor（含 AI）必须遵守。规则变更需同步更新 004 与 arch.db。**
--- a/docs/standards/cicd-runbook.md
+++ b/docs/standards/cicd-runbook.md
@@ -31,14 +31,14 @@

 ### 1.1 组件清单

-| 组件                         | 说明                                                            |
-| ---------------------------- | --------------------------------------------------------------- |
-| **Gitea**                    | `git.eazygame.cn`，代码托管 + Actions + Container Registry      |
-| **Gitea Actions**            | CI 运行器，兼容 GitHub Actions 语法                             |
-| **Gitea Container Registry** | 镜像仓库，地址 `git.eazygame.cn/xiner/edu/<service>:<tag>`      |
-| **Deploy Runner**            | 跑在服务器上的 self-hosted runner，标签 `[self-hosted, deploy]` |
-| **服务器 MySQL**             | 已有容器，端口 3306，容器名 `edu-mysql`（假设）                 |
-| **服务器 Redis**             | 已有容器，端口 6379，容器名 `edu-redis`（假设）                 |
+| 组件                         | 说明                                                       |
+| ---------------------------- | ---------------------------------------------------------- |
+| **Gitea**                    | `git.eazygame.cn`，代码托管 + Actions + Container Registry |
+| **Gitea Actions**            | CI 运行器，兼容 GitHub Actions 语法                        |
+| **Gitea Container Registry** | 镜像仓库，地址 `git.eazygame.cn/xiner/edu/<service>:<tag>` |
+| **Deploy Runner**            | 跑在服务器上的 actrunner，标签 `ubuntu-latest`             |
+| **服务器 MySQL**             | 已有容器，端口 3306，容器名 `edu-mysql`（假设）            |
+| **服务器 Redis**             | 已有容器，端口 6379，容器名 `edu-redis`（假设）            |

 ### 1.2 流水线文件

@@ -67,7 +67,7 @@
   chmod +x act_runner
   ./act_runner register --instance https://git.eazygame.cn --token <TOKEN>
   ```
-3. 配置 runner 标签为 `self-hosted,deploy`（部署用）和 `self-hosted,linux`（CI 用）
+3. 配置 runner 标签为 `ubuntu-latest`（CI 与部署共用）

 ### 2.2 启用 Gitea Container Registry

@@ -435,7 +435,68 @@ docker images git.eazygame.cn/xiner/edu

 ---

-## 10. 相关文档
+## 10. 参考实现（强制参照）
+
+**所有 CI/CD 配置变更必须参照同机的 `E:\Desktop\CICD\` 项目（Gitea 单仓库 CI 实现），不另行自创。**
+
+### 10.1 参考项目位置
+
+| 路径                                              | 内容                                  |
+| ------------------------------------------------- | ------------------------------------- |
+| `E:\Desktop\CICD\.gitea\workflows\ci.yml`         | 主 CI 配置（build-deploy + 安全扫描） |
+| `E:\Desktop\CICD\.gitea\workflows\dr-drill.yml`   | 灾备演练                              |
+| `E:\Desktop\CICD\.gitea\workflows\lighthouse.yml` | 性能审计                              |
+| `E:\Desktop\CICD\.gitea\workflows\security.yml`   | 安全扫描                              |
+| `E:\Desktop\CICD\.trae\rules\project_rules.md`    | 参考项目规则（对照学习）              |
+
+### 10.2 关键配置点（必须沿用）
+
+参考项目 `ci.yml` 的核心配置：
+
+| 配置项              | 参考项目值                                             | Edu 项目取值                                |
+| ------------------- | ------------------------------------------------------ | ------------------------------------------- |
+| **Runner 标签**     | `CDCD`                                                 | `ubuntu-latest`                             |
+| **TS job 容器**     | `dockerreg.eazygame.cn/node-with-docker:22`            | 同（带 docker 的 node 22 镜像）             |
+| **Go quality 容器** | （无 Go）                                              | `golang:1.22-alpine`                        |
+| **Go docker-build** | （无 Go）                                              | `node-with-docker:22` + `setup-go`          |
+| **部署方式**        | `docker build` + `docker run --network 1panel-network` | `docker compose pull && up`（多服务编排）   |
+| **网络**            | `1panel-network`                                       | `edu-shared`（连接已有 MySQL/Redis）        |
+| **npm 代理**        | docker gateway IP `172.17.0.1:7890`                    | 不配置（runner 已全局代理）                 |
+| **Next.js 构建**    | standalone + 复制 `public`/`.next/static`              | teacher-portal 沿用                         |
+| **环境变量**        | secrets 注入 `DATABASE_URL`/`NEXTAUTH_SECRET`          | secrets 注入 `DATABASE_URL`/`JWT_SECRET` 等 |
+| **定时备份**        | `schedule: cron "0 2 * * *"`                           | 待 P6 阶段实现                              |
+
+### 10.3 关键差异（Edu vs 参考项目）
+
+| 维度     | 参考项目                 | Edu 项目                                               |
+| -------- | ------------------------ | ------------------------------------------------------ |
+| 架构     | 单体 Next.js             | 微服务（TS + Go + Python + Proto）                     |
+| 包管理器 | npm                      | pnpm（TS）/ go mod（Go）/ uv（Python）                 |
+| 服务数量 | 1 个（nextjs-app）       | 3+（api-gateway / classes / teacher-portal）           |
+| 部署方式 | docker run 单容器        | docker compose 多服务编排                              |
+| CI 拆分  | 单 ci.yml 大而全         | 按语言拆 ci-ts/ci-go/ci-py/ci-proto                    |
+| 镜像仓库 | 本地 `nextjs-app:latest` | Gitea Registry `git.eazygame.cn/xiner/edu/<svc>:<tag>` |
+
+### 10.4 修改 workflow 的流程
+
+1. **先读参考项目同类配置**：`Read E:\Desktop\CICD\.gitea\workflows\ci.yml`
+2. **比对差异**：参照 §10.3 表格，确认 Edu 项目的特殊取值
+3. **修改 Edu workflow**：保持关键配置点（container、runner 标签）一致
+4. **YAML 语法校验**：`python -c "import yaml; yaml.safe_load(open('<file>'))"`
+5. **提交并推送**：触发 CI 验证
+
+### 10.5 当参考项目与本规范冲突时
+
+- **架构差异**（单体 vs 微服务）：以 Edu 项目规范为准
+- **部署方式**（docker run vs compose）：以 Edu 项目规范为准
+- **镜像/网络/标签**：以 Edu 项目规范为准
+- **CI 容器化、构建流程、缓存策略**：参照参考项目
+
+> 详见 [project_rules §15.7 参考实现](../../.trae/rules/project_rules.md)
+
+---
+
+## 11. 相关文档

 - [project_rules §15 CI/CD 规范](../../.trae/rules/project_rules.md)
 - [project_rules §14 多 AI 协作规范](../../.trae/rules/project_rules.md)