diff --git a/.trae/rules/project_rules.md b/.trae/rules/project_rules.md index 1fb14f0..527f050 100644 --- 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。** diff --git a/docs/standards/cicd-runbook.md b/docs/standards/cicd-runbook.md index 6844f51..c446637 100644 --- 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/:` | -| **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/:` | +| **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 ``` -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/:` | + +### 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(''))"` +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)