From a2f31ec5a093f14ebae2a1e2ea122f0b5e447dc2 Mon Sep 17 00:00:00 2001 From: hurole <1192163814@qq.com> Date: Sun, 11 Jan 2026 11:16:11 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E7=A7=BB=E9=99=A4=20doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.meta/OWNERS.md | 7 - docs/.meta/templates/design-template.md | 116 ------------ docs/.meta/templates/runbook-template.md | 22 --- docs/api/README.md | 14 -- docs/api/endpoints.md | 78 -------- docs/api/openapi.yaml | 28 --- docs/architecture/adr-0001-service-design.md | 26 --- .../design-0001-product-prototype.md | 175 ------------------ .../design-0004-execution-queue.md | 166 ----------------- .../design-0005-refactor-deply.md | 130 ------------- docs/changelogs/CHANGELOG.md | 9 - docs/development/setup.md | 88 --------- docs/getting-started.md | 79 -------- docs/index.md | 22 --- docs/onboarding/new-hire.md | 13 -- docs/runbooks/incident-response.md | 28 --- 16 files changed, 1001 deletions(-) delete mode 100644 docs/.meta/OWNERS.md delete mode 100644 docs/.meta/templates/design-template.md delete mode 100644 docs/.meta/templates/runbook-template.md delete mode 100644 docs/api/README.md delete mode 100644 docs/api/endpoints.md delete mode 100644 docs/api/openapi.yaml delete mode 100644 docs/architecture/adr-0001-service-design.md delete mode 100644 docs/architecture/design-0001-product-prototype.md delete mode 100644 docs/architecture/design-0004-execution-queue.md delete mode 100644 docs/architecture/design-0005-refactor-deply.md delete mode 100644 docs/changelogs/CHANGELOG.md delete mode 100644 docs/development/setup.md delete mode 100644 docs/getting-started.md delete mode 100644 docs/index.md delete mode 100644 docs/onboarding/new-hire.md delete mode 100644 docs/runbooks/incident-response.md diff --git a/docs/.meta/OWNERS.md b/docs/.meta/OWNERS.md deleted file mode 100644 index c601752..0000000 --- a/docs/.meta/OWNERS.md +++ /dev/null @@ -1,7 +0,0 @@ -# 文档拥有者 - -- backend: backend-team@example.com -- ops: ops-team@example.com -- product: product-team@example.com - -每个文档请在 front-matter 中声明 `owners` 字段。 diff --git a/docs/.meta/templates/design-template.md b/docs/.meta/templates/design-template.md deleted file mode 100644 index df8bb05..0000000 --- a/docs/.meta/templates/design-template.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: 设计文档模板 -summary: 记录一个功能/模块的设计方案、权衡与落地计划（建议配套 ADR）。 -owners: - - team: -reviewers: - - -status: draft -date: 2026-01-03 -version: 0.1.0 -related: - - adr: docs/architecture/adr-xxxx-.md - - pr: - - issue: ---- - -# 设计文档：<标题> - -## 1. 背景（Context） - -- 当前问题是什么？为什么现在要做？ -- 相关现状：已有模块/接口/数据模型（附链接） -- 约束：技术栈、部署方式、团队边界、时间/人力 - -## 2. 目标（Goals） - -- [ ] 目标 1（可验证） -- [ ] 目标 2（可验证） - -## 3. 非目标（Non-goals） - -- 不做什么（防止范围膨胀） - -## 4. 需求与范围（Requirements & Scope） - -- 用户/角色：谁会用？（例如：管理员、开发者、CI runner） -- 功能需求： - - R1: - - R2: -- 非功能需求：性能、可用性、可维护性、可观测性 - -## 5. 方案概览（High-level Design） - -- 用 5-10 行描述整体方案（模块、数据流、调用链） -- 关键选择：为什么选这个方案？ - -## 6. 详细设计（Detailed Design） - -### 6.1 接口/API 设计 - -- 新增/变更端点（路径、方法、权限、请求/响应示例） -- 错误码与错误语义（与 `BusinessError` 对齐） - -### 6.2 数据模型/数据库 - -- Prisma model 变更（字段、索引、迁移策略） -- 数据一致性与幂等策略（例如：重试/重复提交） - -### 6.3 任务/队列/异步处理（如有） - -- 队列模型：入队、出队、并发、重试、死信/失败处理 -- 状态机：状态枚举与迁移 - -### 6.4 配置与环境变量 - -- 新增 env（默认值、是否敏感、是否需要重启） - -### 6.5 可观测性 - -- 日志：关键日志点、traceId/requestId（如有） -- 指标：成功率、延迟、队列长度、失败原因分布 -- 告警：P0/P1 触发条件 - -### 6.6 安全与权限 - -- 认证：是否要求登录（session） -- 授权：角色/资源权限（项目级、流水线级） -- 数据安全：敏感信息、token、日志脱敏 - -## 7. 影响与权衡（Trade-offs） - -- 性能影响 -- 运维影响 -- 对现有接口/调用方的影响 -- 技术债与后续演进 - -## 8. 兼容性与迁移（Compatibility & Migration） - -- 是否 breaking change？ -- 迁移步骤（DB、配置、数据回填） -- 回滚策略 - -## 9. 测试计划（Test Plan） - -- 单测：覆盖哪些模块 -- 集成测试：关键链路（如：创建部署 -> 入队 -> 执行 -> 状态更新） -- 手工验证：步骤清单 - -## 10. 发布计划（Rollout Plan） - -- 分阶段：灰度/开关/逐步放量（如有） -- 监控指标与验收标准 - -## 11. 备选方案（Alternatives Considered） - -- 方案 A：为什么不用 -- 方案 B：为什么不用 - -## 12. 风险与开放问题（Risks & Open Questions） - -- 风险 1 -- 问题 1（需要谁来决定/何时决定） - -## 13. 附录（Appendix） - -- 相关链接：控制器、DTO、Prisma schema、PR 等 diff --git a/docs/.meta/templates/runbook-template.md b/docs/.meta/templates/runbook-template.md deleted file mode 100644 index 9c2e385..0000000 --- a/docs/.meta/templates/runbook-template.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Runbook 模板 -owners: - - ops: ops-team -status: draft ---- - -# Runbook 标题 - -## 触发条件 - -## 负责人 - -## 联系方式 - -## 暂时性缓解 - -## 恢复步骤 - -## 验证 - -## 回滚（如果适用） diff --git a/docs/api/README.md b/docs/api/README.md deleted file mode 100644 index 8386288..0000000 --- a/docs/api/README.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: API 文档 -summary: 本目录存放 OpenAPI 定义与 API 使用说明。 -tags: [api] -owners: - - team: backend -status: stable ---- - -# API 文档 - -本目录包含 OpenAPI 规范与示例。可使用 Swagger UI 或 Redoc 渲染 `openapi.yaml`。 - -- OpenAPI: `openapi.yaml` diff --git a/docs/api/endpoints.md b/docs/api/endpoints.md deleted file mode 100644 index e713876..0000000 --- a/docs/api/endpoints.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: API 端点总览 -summary: 基于 `apps/server` 控制器实现的主要 REST API 端点汇总。 -owners: - - team: backend -status: stable ---- - -# API 端点总览 - -基础前缀：`/api` - -下面列出当前实现的主要控制器与常用端点。 - -## Projects (`/api/projects`) - -- GET `/api/projects` : 列表（支持分页与按 name 搜索） -- GET `/api/projects/:id` : 获取单个项目（包含 workspace 状态） -- POST `/api/projects` : 创建项目（body: `name`, `repository`, `projectDir` 等） -- PUT `/api/projects/:id` : 更新项目 -- DELETE `/api/projects/:id` : 软删除（将 `valid` 置为 0） - -示例： - -```http -GET /api/projects?page=1&limit=10 -``` - -## User (`/api/user`) - -- GET `/api/user/list` : 模拟用户列表 -- GET `/api/user/detail/:id` : 用户详情 -- POST `/api/user` : 创建用户 -- PUT `/api/user/:id` : 更新用户 -- DELETE `/api/user/:id` : 删除用户 -- GET `/api/user/search` : 搜索用户 - -## Auth (`/api/auth`) - -- GET `/api/auth/url` : 获取 Gitea OAuth 授权 URL -- POST `/api/auth/login` : 使用 OAuth code 登录（返回 session） -- GET `/api/auth/logout` : 登出 -- GET `/api/auth/info` : 当前会话用户信息 - -注意：需要配置 `GITEA_URL`、`GITEA_CLIENT_ID`、`GITEA_REDIRECT_URI`。 - -## Deployments (`/api/deployments`) - -- GET `/api/deployments` : 列表（支持 projectId 过滤） -- POST `/api/deployments` : 创建部署（会将任务加入执行队列） -- POST `/api/deployments/:id/retry` : 重新执行某次部署（复制记录并 requeue） - -## Pipelines (`/api/pipelines`) - -- GET `/api/pipelines` : 列表（含 steps） -- GET `/api/pipelines/templates` : 获取可用流水线模板 -- GET `/api/pipelines/:id` : 单个流水线（含步骤） -- POST `/api/pipelines` : 创建流水线 -- POST `/api/pipelines/from-template` : 基于模板创建流水线 -- PUT `/api/pipelines/:id` : 更新流水线 -- DELETE `/api/pipelines/:id` : 软删除 - -## Steps (`/api/steps`) - -- GET `/api/steps` : 列表（支持 pipelineId 过滤） -- GET `/api/steps/:id` : 单个步骤 -- POST `/api/steps` : 创建步骤（包含 `script` 字段） -- PUT `/api/steps/:id` : 更新步骤 -- DELETE `/api/steps/:id` : 软删除 - -## Git (`/api/git`) - -- GET `/api/git/commits?projectId=&branch=` : 获取指定项目的提交列表（调用 Gitea） -- GET `/api/git/branches?projectId=` : 获取分支列表 - ---- - -想要更详细的示例（请求 body、响应 schema），我可以为每个端点基于 `dto.ts` 自动生成示例请求/响应片段。是否需要我继续生成？ diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml deleted file mode 100644 index 1e6d8c4..0000000 --- a/docs/api/openapi.yaml +++ /dev/null @@ -1,28 +0,0 @@ -openapi: 3.0.1 -info: - title: Foka-CI 示例 API - version: '1.0.0' -paths: - /health: - get: - summary: 健康检查 - responses: - '200': - description: OK - /projects: - get: - summary: 列出项目 - responses: - '200': - description: 项目列表 - content: - application/json: - schema: - type: array - items: - type: object - properties: - id: - type: string - name: - type: string diff --git a/docs/architecture/adr-0001-service-design.md b/docs/architecture/adr-0001-service-design.md deleted file mode 100644 index 2d7fb3e..0000000 --- a/docs/architecture/adr-0001-service-design.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: ADR 0001 - 服务设计决策 -date: 2026-01-03 -authors: - - backend-team -status: accepted ---- - -# ADR 0001: 服务设计与部署模型 - -## 背景 - -需要选择微服务还是单体部署以便平衡开发速度与运维复杂度。 - -## 决策 - -采用模块化单体（modular monolith）作为初始阶段部署方式，关键模块解耦、接口明确，后续按需拆分服务。 - -## 影响 - -- 优点：降低初期运维成本，便于本地调试与 CI 集成。 -- 缺点：需要在代码边界设计中预留拆分点。 - -## 备注 - -在拆分时优先考虑数据库边界和独立部署能力。 diff --git a/docs/architecture/design-0001-product-prototype.md b/docs/architecture/design-0001-product-prototype.md deleted file mode 100644 index 2b177da..0000000 --- a/docs/architecture/design-0001-product-prototype.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: 设计文档 0001 - 产品原型 -summary: 产品的设计原型 -owners: - - team: backend -reviewers: - - ops-team -status: draft -date: 2026-01-03 -version: 0.1.0 ---- - -# 设计文档 0001：产品整体原型 - -## 1. 背景（Context） - -企业内部代码发布是非常频繁的事情，无论是测试环境还是生产环境，发布代码常常面临着一些痛点：频繁发布浪费开发时；手动发布代码可能漏掉某些步骤、造成环境报错。所以需要引入 CI/CD 工具让发布流程自动化，市场上已经存在很多解决类似问题的产品，例如 Drone CI、jenkins 等，但是这些工具不够灵活、不能满足全部场景，所以便有了 Foka-CI 这款产品。 - -## 2. 拆解需求 - -### 登录认证页面 - -仅提供 Gitea 的 OAuth 认证登录，方便获取仓库信息，简化密码登录过程 - -### 项目列表页面 - -查看所有项目，项目的基本信息有： - -- 项目名 -- 项目描述（可选） -- 代码仓库地址 -- 项目的工作目录，用于将代码克隆到该目录下，发布流水线脚本在该目录下执行 - -创建项目，需要填写基本信息 - -### 项目详情页 - - -## 2. 目标（Goals） - -- [ ] 明确“部署任务”从创建到执行的状态流转与约束 -- [ ] 明确重试语义（retry 会创建新 deployment，而不是复用原记录） -- [ ] 降低重复入队/重复执行的风险（幂等与并发边界清晰） -- [ ] 让运维/排障更容易：关键日志点与可观测性清单 - -## 3. 非目标（Non-goals） - -- 不引入外部消息队列（如 Redis/Kafka），仍以当前内存队列 + DB 恢复为基础 -- 不在本文直接实现大规模调度/分布式 runner（后续 ADR/设计再做） - -## 4. 需求与范围（Requirements & Scope） - -### 功能需求 - -- 创建部署：写入一条 Deployment 记录，初始状态为 `pending`，并加入执行队列 -- 重试部署：通过 `/deployments/:id/retry` 创建一条新的 Deployment 记录（复制必要字段），并加入执行队列 -- 服务重启恢复：服务启动后能从 DB 找回仍为 `pending` 的任务并继续执行 - -### 非功能需求 - -- 可靠性：服务重启不会“丢任务”（pending 的任务能恢复） -- 幂等性：避免同一个 deployment 被重复执行 -- 可观测性：能定位某次部署为何失败、何时开始/结束、队列长度 - -## 5. 方案概览（High-level Design） - -当前方案核心链路如下： - -1. API 创建 Deployment（status=pending） -2. `ExecutionQueue.addTask(deploymentId, pipelineId)` 入队 -3. `ExecutionQueue.processQueue()` 串行消费 `pendingQueue` -4. `executePipeline()` 会读取 Deployment 与关联 Project，获取 `projectDir`，然后创建 `PipelineRunner` 执行 -5. 定时轮询：每 30 秒扫描 DB 中的 pending 任务，若不在 `runningDeployments` 集合则补入队列 - -## 6. 详细设计（Detailed Design） - -### 6.1 接口/API 设计 - -#### 创建部署 - -- POST `/api/deployments` -- 行为：创建 Deployment 后立即入队 - -#### 重试部署 - -- POST `/api/deployments/:id/retry` -- 行为：读取原 deployment -> 创建新 deployment（status=pending）-> 入队 -- 语义：重试是“创建一个新的任务实例”，便于保留历史执行记录 - -### 6.2 数据模型/数据库 - -Deployment 当前关键字段（见 schema 注释）： - -- `status`: pending/running/success/failed/cancelled（目前入队依赖 pending） -- `buildLog`: 执行日志（当前创建时写空字符串） -- `startedAt`/`finishedAt`: 时间标记（目前 created 时 startedAt 默认 now） - -建议补齐/明确（文档层面约束，代码后续落地）： - -- 状态迁移： - - `pending` -> `running`（开始执行前） - - `running` -> `success|failed|cancelled`（结束后） -- 幂等控制： - - 以 deploymentId 为“单次执行唯一标识”，同一个 deploymentId 不允许重复开始执行 - -### 6.3 队列/轮询/并发 - -现状： - -- `runningDeployments` 同时承担“已入队/执行中”的去重集合 -- `pendingQueue` 为内存 FIFO -- 单实例串行消费（`processQueue` while 循环） -- 轮询间隔常量 30 秒 - -风险点（需要在文档中明确约束/后续逐步修正）： - -- 多实例部署：如果将来启动多个 server 实例，每个实例都可能轮询到同一条 pending 记录并执行（需要 DB 锁/租约/状态原子更新） -- 状态更新缺口：当前 `ExecutionQueue` 代码中没有看到明确把 status 从 pending 改成 running/failed/success 的逻辑（可能在 `PipelineRunner` 内处理；若没有，需要补齐） - -建议（不改变整体架构前提）： - -- 将轮询间隔改为可配置 env：`EXECUTION_POLL_INTERVAL_MS`（默认 30000） -- 在真正执行前做一次 DB 原子“抢占”：仅当 status=pending 时更新为 running（并记录开始时间）；更新失败则放弃执行 - -### 6.4 可观测性 - -最低要求（建议后续落地到代码/日志规范）： - -- 日志字段：deploymentId、pipelineId、projectId、projectDir、status -- 队列指标：pendingQueue length、runningDeployments size -- 失败记录：捕获异常 message/stack（避免泄露敏感信息） - -### 6.5 安全与权限 - -当前接口层面需要确认： - -- `/api/deployments` 与 `/api/deployments/:id/retry` 是否需要登录/鉴权（取决于 middleware 配置） -- 若需要鉴权：建议限制为有项目权限的用户才能创建/重试部署 - -## 7. 影响与权衡（Trade-offs） - -- 继续采用内存队列：实现简单，但天然不支持多实例并发安全 -- DB 轮询恢复：可靠性提升，但会带来额外 DB 查询压力 - -## 8. 兼容性与迁移（Compatibility & Migration） - -- 文档层面不破坏现有 API -- 若引入 status 原子抢占，需要确保旧数据/旧状态兼容（例如对历史 pending 记录仍可恢复） - -## 9. 测试计划（Test Plan） - -- 集成链路：创建 deployment -> 入队 -> 触发执行（可用假 runner） -- 重启恢复：插入 pending 记录 -> initialize() -> 任务被 addTask -- 重试接口：原记录存在/不存在的分支 - -## 10. 发布计划（Rollout Plan） - -- 先补齐文档 + 最小日志规范 -- 再逐步落地：status 原子抢占 + 轮询间隔 env - -## 11. 备选方案（Alternatives Considered） - -- 引入 Redis 队列（BullMQ 等）：更可靠、支持多实例，但复杂度上升 -- 使用 DB 作为队列（表 + 锁/租约）：更可靠，但需要严格的并发控制 - -## 12. 风险与开放问题（Risks & Open Questions） - -- Q1：`PipelineRunner` 是否负责更新 Deployment.status？如果没有，状态机应由谁维护？ -- Q2：服务是否计划多实例部署？如果是，必须补齐“抢占执行”机制 - -## 13. 附录（Appendix） - -- 代码：`apps/server/libs/execution-queue.ts` -- 控制器：`apps/server/controllers/deployment/index.ts` -- Schema：`apps/server/prisma/schema.prisma` diff --git a/docs/architecture/design-0004-execution-queue.md b/docs/architecture/design-0004-execution-queue.md deleted file mode 100644 index 8d68bee..0000000 --- a/docs/architecture/design-0004-execution-queue.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: 设计文档 0001 - 部署执行队列与重试（基于当前实现） -summary: 记录当前 ExecutionQueue 的行为与下一步改进方向，便于团队对齐。 -owners: - - team: backend -reviewers: - - ops-team -status: draft -date: 2026-01-03 -version: 0.1.0 -related: - - code: apps/server/libs/execution-queue.ts - - code: apps/server/controllers/deployment/index.ts - - schema: apps/server/prisma/schema.prisma ---- - -# 设计文档 0001：部署执行队列与重试 - -## 1. 背景（Context） - -当前服务端在启动时会初始化执行队列（`ExecutionQueue.initialize()`），用于从数据库恢复 `status=pending` 的部署任务并按顺序执行流水线。 - -现有相关事实（来自当前代码）： - -- 服务启动入口：`apps/server/app.ts` -- 路由：`/api/deployments`（创建部署后入队）与 `/api/deployments/:id/retry`（复制记录后入队） -- 数据库：SQLite + Prisma，Deployment 存在 `status` 字段（注释标明：pending/running/success/failed/cancelled） -- 队列实现：内存队列 `pendingQueue` + `runningDeployments` Set，并有轮询机制（默认 30 秒）把 DB 中的 pending 任务补进队列 - -## 2. 目标（Goals） - -- [ ] 明确“部署任务”从创建到执行的状态流转与约束 -- [ ] 明确重试语义（retry 会创建新 deployment，而不是复用原记录） -- [ ] 降低重复入队/重复执行的风险（幂等与并发边界清晰） -- [ ] 让运维/排障更容易：关键日志点与可观测性清单 - -## 3. 非目标（Non-goals） - -- 不引入外部消息队列（如 Redis/Kafka），仍以当前内存队列 + DB 恢复为基础 -- 不在本文直接实现大规模调度/分布式 runner（后续 ADR/设计再做） - -## 4. 需求与范围（Requirements & Scope） - -### 功能需求 - -- 创建部署：写入一条 Deployment 记录，初始状态为 `pending`，并加入执行队列 -- 重试部署：通过 `/deployments/:id/retry` 创建一条新的 Deployment 记录（复制必要字段），并加入执行队列 -- 服务重启恢复：服务启动后能从 DB 找回仍为 `pending` 的任务并继续执行 - -### 非功能需求 - -- 可靠性：服务重启不会“丢任务”（pending 的任务能恢复） -- 幂等性：避免同一个 deployment 被重复执行 -- 可观测性：能定位某次部署为何失败、何时开始/结束、队列长度 - -## 5. 方案概览（High-level Design） - -当前方案核心链路如下： - -1) API 创建 Deployment（status=pending） -2) `ExecutionQueue.addTask(deploymentId, pipelineId)` 入队 -3) `ExecutionQueue.processQueue()` 串行消费 `pendingQueue` -4) `executePipeline()` 会读取 Deployment 与关联 Project，获取 `projectDir`，然后创建 `PipelineRunner` 执行 -5) 定时轮询：每 30 秒扫描 DB 中的 pending 任务，若不在 `runningDeployments` 集合则补入队列 - -## 6. 详细设计（Detailed Design） - -### 6.1 接口/API 设计 - -#### 创建部署 - -- POST `/api/deployments` -- 行为：创建 Deployment 后立即入队 - -#### 重试部署 - -- POST `/api/deployments/:id/retry` -- 行为：读取原 deployment -> 创建新 deployment（status=pending）-> 入队 -- 语义：重试是“创建一个新的任务实例”，便于保留历史执行记录 - -### 6.2 数据模型/数据库 - -Deployment 当前关键字段（见 schema 注释）： - -- `status`: pending/running/success/failed/cancelled（目前入队依赖 pending） -- `buildLog`: 执行日志（当前创建时写空字符串） -- `startedAt`/`finishedAt`: 时间标记（目前 created 时 startedAt 默认 now） - -建议补齐/明确（文档层面约束，代码后续落地）： - -- 状态迁移： - - `pending` -> `running`（开始执行前） - - `running` -> `success|failed|cancelled`（结束后） -- 幂等控制： - - 以 deploymentId 为“单次执行唯一标识”，同一个 deploymentId 不允许重复开始执行 - -### 6.3 队列/轮询/并发 - -现状： - -- `runningDeployments` 同时承担“已入队/执行中”的去重集合 -- `pendingQueue` 为内存 FIFO -- 单实例串行消费（`processQueue` while 循环） -- 轮询间隔常量 30 秒 - -风险点（需要在文档中明确约束/后续逐步修正）： - -- 多实例部署：如果将来启动多个 server 实例，每个实例都可能轮询到同一条 pending 记录并执行（需要 DB 锁/租约/状态原子更新） -- 状态更新缺口：当前 `ExecutionQueue` 代码中没有看到明确把 status 从 pending 改成 running/failed/success 的逻辑（可能在 `PipelineRunner` 内处理；若没有，需要补齐） - -建议（不改变整体架构前提）： - -- 将轮询间隔改为可配置 env：`EXECUTION_POLL_INTERVAL_MS`（默认 30000） -- 在真正执行前做一次 DB 原子“抢占”：仅当 status=pending 时更新为 running（并记录开始时间）；更新失败则放弃执行 - -### 6.4 可观测性 - -最低要求（建议后续落地到代码/日志规范）： - -- 日志字段：deploymentId、pipelineId、projectId、projectDir、status -- 队列指标：pendingQueue length、runningDeployments size -- 失败记录：捕获异常 message/stack（避免泄露敏感信息） - -### 6.5 安全与权限 - -当前接口层面需要确认： - -- `/api/deployments` 与 `/api/deployments/:id/retry` 是否需要登录/鉴权（取决于 middleware 配置） -- 若需要鉴权：建议限制为有项目权限的用户才能创建/重试部署 - -## 7. 影响与权衡（Trade-offs） - -- 继续采用内存队列：实现简单，但天然不支持多实例并发安全 -- DB 轮询恢复：可靠性提升，但会带来额外 DB 查询压力 - -## 8. 兼容性与迁移（Compatibility & Migration） - -- 文档层面不破坏现有 API -- 若引入 status 原子抢占，需要确保旧数据/旧状态兼容（例如对历史 pending 记录仍可恢复） - -## 9. 测试计划（Test Plan） - -- 集成链路：创建 deployment -> 入队 -> 触发执行（可用假 runner） -- 重启恢复：插入 pending 记录 -> initialize() -> 任务被 addTask -- 重试接口：原记录存在/不存在的分支 - -## 10. 发布计划（Rollout Plan） - -- 先补齐文档 + 最小日志规范 -- 再逐步落地：status 原子抢占 + 轮询间隔 env - -## 11. 备选方案（Alternatives Considered） - -- 引入 Redis 队列（BullMQ 等）：更可靠、支持多实例，但复杂度上升 -- 使用 DB 作为队列（表 + 锁/租约）：更可靠，但需要严格的并发控制 - -## 12. 风险与开放问题（Risks & Open Questions） - -- Q1：`PipelineRunner` 是否负责更新 Deployment.status？如果没有，状态机应由谁维护？ -- Q2：服务是否计划多实例部署？如果是，必须补齐“抢占执行”机制 - -## 13. 附录（Appendix） - -- 代码：`apps/server/libs/execution-queue.ts` -- 控制器：`apps/server/controllers/deployment/index.ts` -- Schema：`apps/server/prisma/schema.prisma` diff --git a/docs/architecture/design-0005-refactor-deply.md b/docs/architecture/design-0005-refactor-deply.md deleted file mode 100644 index 3263ec5..0000000 --- a/docs/architecture/design-0005-refactor-deply.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: 设计文档 0005 - 部署流程重构（移除稀疏检出 & 环境预设） -summary: 调整部署相关能力：移除稀疏检出；将部署环境从创建时输入改为在项目设置中预设。 -owners: - - team: backend -reviewers: - - team: frontend -status: draft -date: 2026-01-03 -version: 0.1.0 -related: - - docs: docs/api/endpoints.md - - schema: apps/server/prisma/schema.prisma ---- - -# 设计文档 0005：部署流程重构（移除稀疏检出 & 环境预设） - -## 1. 背景（Context） - -当前部署流程在“项目详情页发起部署”时包含“稀疏检出（sparse checkout）”表单项，并且流水线模板中也包含与稀疏检出相关的逻辑。 - -另外，部署时需要指定环境变量（例如 env），但目前是在“创建部署”时临时输入/选择。随着项目数量增加，这种方式容易造成不一致与误操作。 - -## 2. 目标（Goals） - -- [ ] 移除项目详情页部署表单中的“稀疏检出”相关输入项 -- [ ] 移除流水线模板中与稀疏检出相关的代码逻辑（后端模板/生成逻辑） -- [ ] 将“部署环境（env）”从创建部署时指定，调整为在“项目设置”中提前预设 -- [ ] 创建部署时仍需要选择/指定环境，但选项来源于项目设置中的预设项 - -## 3. 非目标（Non-goals） - -- 不新增多维度环境变量管理（仅覆盖本次提到的 env 单项预设） -- 不在本次引入复杂的环境权限、审批流 - -## 4. 需求与范围（Requirements & Scope） - -### 4.1 移除稀疏检出 - -#### 用户侧 - -- 项目详情页发起部署时：不再展示/提交稀疏检出字段 - -#### 系统侧 - -- 流水线模板：移除任何基于稀疏检出路径的生成/执行逻辑 - -> 说明：当前 DB 中 Deployment 仍存在 `sparseCheckoutPaths` 字段（见 `schema.prisma`），本次需求仅明确“功能不再需要”。字段是否删除/迁移由本设计后续章节确定。 - -### 4.2 部署环境 env 改为项目设置预设 - -#### 核心约束 - -- 环境变量预设需要支持多选、单选、输入框这几种类型 -- 在项目设置中新增可配置项（预设项）： - 例如：指定env 环境变量 - - 类型：单选（single select） - - key：`env`，value 及时部署是选中的候选项的值 - - options：`staging`（测试环境）、`production`（生产环境） - -#### 行为 - -- 创建部署时仍需指定环境（env），但： - - 不再由用户自由输入 - - 只允许从该项目预设的 options 中选择 - -## 5. 影响面（Impact） - -### 5.1 前端 - -- 项目详情页部署表单：移除“稀疏检出”相关 UI 与字段提交 -- 项目设置页：新增“环境预设（env）”配置入口（单选 + 选项 staging/production） -- 创建部署交互：环境选项从项目设置读取（不再硬编码/临时输入） - -### 5.2 后端 - -- 部署创建接口：校验 env 必须来自项目预设（避免非法 env） -- 流水线模板：移除稀疏检出相关的模板字段/生成逻辑 - -### 5.3 数据库 - -- 需要新增“项目设置/项目配置”承载 env 预设（落库方案待定） -- 既有 Deployment 的 `sparseCheckoutPaths` 字段：后续决定是否保留（兼容历史）或迁移删除 - -## 6. 兼容性与迁移（Compatibility & Migration） - -- 对历史部署记录： - - 若存在 `sparseCheckoutPaths`，不影响查询展示，但新建部署不再写入该字段 -- 对创建部署： - - 若项目未配置 env 预设：创建部署应失败并提示先到项目设置配置（或提供默认值策略，待确认） - -## 7. 测试要点（Test Plan） - -- 前端： - - 项目详情页部署表单不再出现稀疏检出项 - - 项目设置可保存 env 预设（单选）并在创建部署时正确展示 -- 后端： - - 创建部署：env 不在项目预设 options 内时应拒绝 - - 流水线模板：移除稀疏检出后仍能正常创建并执行 - -## 8. 实施状态（Implementation Status） - -### 已完成（后端） - -- [x] Prisma Schema：在 Project 表添加 `envPresets` 字段（String? 类型，存储 JSON） -- [x] 移除部署创建/重试接口中的 `sparseCheckoutPaths` 写入 -- [x] 在部署创建接口添加环境校验：验证 env 是否在项目 envPresets 的 options 中 -- [x] 更新 project DTO 和 controller 支持 envPresets 读写 -- [x] 移除 pipeline-runner 中的 `SPARSE_CHECKOUT_PATHS` 环境变量 -- [x] 生成 Prisma Client -- [x] 移除项目详情接口中的目录大小计算（保留工作目录状态其他信息） - -### 已完成（前端） - -- [x] 创建 EnvPresetsEditor 组件（支持单选、多选、输入框类型） -- [x] 在 CreateProjectModal 和 EditProjectModal 中集成环境预设编辑器 -- [x] 从 DeployModal 移除稀疏检出表单项 -- [x] 在 DeployModal 中从项目 envPresets 读取环境选项并展示 -- [x] 移除 DeployModal 中的动态环境变量列表（envVars Form.List） -- [x] 从类型定义中移除 sparseCheckoutPaths 字段 -- [x] 在项目详情页项目设置 tab 中添加环境变量预设的查看和编辑功能 -- [x] 移除创建项目时增加环境变量预设的功能，因为编辑环境变量预设的功能放到了项目编详细页面 -- [x] 移除项目详情页项目设置 tab 中的目录大小显示（保留工作目录状态、当前分支、最后提交等信息） - -### 待定问题 - -- Q1：项目设置存储方式 → **已决定**：使用 Project.envPresets JSON 字段 -- Q2：未配置 env 预设的默认行为 → **已实现**：若配置了预设则校验，否则允许任意值（向后兼容） -- Q3：Deployment.sparseCheckoutPaths 字段 → **已决定**：保留字段（兼容历史），但新建部署不再写入 - diff --git a/docs/changelogs/CHANGELOG.md b/docs/changelogs/CHANGELOG.md deleted file mode 100644 index 13d8aca..0000000 --- a/docs/changelogs/CHANGELOG.md +++ /dev/null @@ -1,9 +0,0 @@ -# Changelog - -所有 notable 更改应在此记录。遵循 Keep a Changelog 格式。 - -## [Unreleased] -- 初始文档目录建立。 - -## [1.0.0] - 2026-01-03 -- 初始发布 diff --git a/docs/development/setup.md b/docs/development/setup.md deleted file mode 100644 index 0b45011..0000000 --- a/docs/development/setup.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: 开发与本地环境搭建 -summary: 针对本项目的本地开发、数据库与调试指南。 -owners: - - team: backend -status: stable ---- - -# 开发与本地环境搭建 - -## 1. 安装依赖 - -建议使用 `pnpm` 管理工作区依赖： - -```bash -# 在仓库根 -pnpm install -``` - -或者只在 server 子包安装： - -```bash -cd apps/server -pnpm install -``` - -## 2. 生成 Prisma Client - -```bash -cd apps/server -npx prisma generate -``` - -如果需要执行迁移（开发场景）： - -```bash -npx prisma migrate dev --name init -``` - -数据库：项目使用 SQLite（见 `apps/server/prisma/schema.prisma`），迁移会在本地创建 `.db` 文件。 - -## 3. 启动服务 - -并行启动 workspace 中所有 dev 脚本（推荐）： - -```bash -pnpm dev -``` - -或单独启动 server： - -```bash -cd apps/server -pnpm dev -``` - -服务默认端口：`3001`。如需修改： - -```bash -PORT=4000 pnpm dev -``` - -## 4. 常见开发命令 - -- 运行测试脚本（仓库自带）： - -```bash -cd apps/server -node test.js -``` - -- TypeScript 类型检查（本地可使用 `tsc`）： - -```bash -npx tsc --noEmit -``` - -## 5. 环境变量与第三方集成 - -常见 env：`GITEA_URL`, `GITEA_CLIENT_ID`, `GITEA_REDIRECT_URI`, `PORT`, `NODE_ENV`。 - -登录采用 Gitea OAuth，未配置时某些 auth 接口会返回 401，需要先登录获取 session。 - -## 6. 运行与调试要点 - -- 代码通过装饰器注册路由（见 `apps/server/decorators/route.ts` 与 `apps/server/libs/route-scanner.ts`）。 -- Prisma client 生成路径：`apps/server/generated`。 -- 若变更 Prisma schema，请执行 `prisma generate` 并更新迁移。 diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 03a3d17..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: 快速开始 -summary: 本文档介绍如何在本地启动与运行项目的基础步骤。 -tags: [getting-started] -owners: - - team: backend -status: stable -version: 1.0.0 ---- - -# 快速开始 - -## 前置条件 - -- Node.js >= 18 -- pnpm -- 克隆权限（或访问仓库） - -## 克隆与依赖安装 - -```bash -git clone -cd foka-ci -pnpm install -``` - -说明：仓库使用 pnpm workspace，根目录脚本 `pnpm dev` 会并行启动工作区内的 `dev` 脚本。 - -## 运行服务（开发） - -- 从仓库根（并行运行所有 dev 脚本）： - -```bash -pnpm dev -``` - -- 单独运行 server： - -```bash -cd apps/server -pnpm install -pnpm dev # 等同于: tsx watch ./app.ts -``` - -服务器默认监听端口 `3001`（可通过 `PORT` 环境变量覆盖）。API 前缀为 `/api`。 - -## Prisma 与数据库 - -项目使用 SQLite（见 `apps/server/prisma/schema.prisma`）。如果需要生成 Prisma Client 或运行迁移： - -```bash -cd apps/server -npx prisma generate -npx prisma migrate dev --name init # 本地开发使用 -``` - -生成的 Prisma Client 位于 `apps/server/generated`（由 schema 中的 generator 指定）。 - -## 环境变量（常用） - -- `GITEA_URL`、`GITEA_CLIENT_ID`、`GITEA_REDIRECT_URI`：用于 OAuth 登录（Gitea）。 -- `PORT`：服务监听端口，默认 `3001`。 -- `NODE_ENV`：环境（development/production）。 - -将敏感值放入 `.env`（不要将 `.env` 提交到仓库）。 - -## 运行脚本与测试 - -```bash -cd apps/server -node test.js # 运行仓库自带的简单测试脚本 -``` - -## 其他说明 - -- 文档目录位于 `docs/`，设计模板在 `docs/.meta/templates/`。 -- API 路由由装饰器注册，路由前缀为 `/api`，在 `apps/server/middlewares/router.ts` 中可查看。 - -更多开发细节请参见 `docs/development/setup.md` 与 `docs/api/endpoints.md`。 diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 0eb700a..0000000 --- a/docs/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: 项目文档总览 -summary: 项目文档的导航页，指向快速开始、架构、API、运维等部分。 -tags: [overview] -owners: - - team: backend -status: stable -version: 1.0.0 ---- - -# 文档总览 - -欢迎来到项目文档。下列是常用文档的入口： - -- Getting Started: ./getting-started.md -- Architecture: ./architecture/adr-0001-service-design.md -- API: ./api/README.md -- Runbooks: ./runbooks/incident-response.md -- Onboarding: ./onboarding/new-hire.md -- Changelog: ./changelogs/CHANGELOG.md - -维护说明：请在变更同时更新 `owners` 与 `version`，并通过 PR 提交。 diff --git a/docs/onboarding/new-hire.md b/docs/onboarding/new-hire.md deleted file mode 100644 index 3fb9597..0000000 --- a/docs/onboarding/new-hire.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: 新成员入职指南 -owners: - - people-team -status: draft ---- - -# 新成员入职快速清单 - -1. 获取公司邮箱与账号 -2. 克隆仓库并运行 `pnpm install` -3. 阅读 `docs/getting-started.md` 与 `docs/architecture` 中关键 ADR -4. 约见导师并完成第一次 code walkthrough diff --git a/docs/runbooks/incident-response.md b/docs/runbooks/incident-response.md deleted file mode 100644 index 6f8bab1..0000000 --- a/docs/runbooks/incident-response.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: 事故响应 Runbook -summary: 处理生产事故的步骤和联系方式。 -owners: - - ops-team -status: stable ---- - -# 事故响应（Incident Response） - -## 1. 识别与分级 - -- P0: 系统不可用或数据安全泄露 -- P1: 主要功能严重受损 - -## 2. 通知 - -- 联系人：`on-call@company.example`，电话：+86-10-12345678 - -## 3. 暂时性缓解 - -- 回滚最近的部署 -- 启用备用服务 - -## 4. 根因分析与恢复 - -- 记录时间线 -- 生成 RCA 并在 72 小时内发布