fix: 移除 doc
This commit is contained in:
@@ -1,7 +0,0 @@
|
|||||||
# 文档拥有者
|
|
||||||
|
|
||||||
- backend: backend-team@example.com
|
|
||||||
- ops: ops-team@example.com
|
|
||||||
- product: product-team@example.com
|
|
||||||
|
|
||||||
每个文档请在 front-matter 中声明 `owners` 字段。
|
|
||||||
@@ -1,116 +0,0 @@
|
|||||||
---
|
|
||||||
title: 设计文档模板
|
|
||||||
summary: 记录一个功能/模块的设计方案、权衡与落地计划（建议配套 ADR）。
|
|
||||||
owners:
|
|
||||||
- team: <team>
|
|
||||||
reviewers:
|
|
||||||
- <name-or-team>
|
|
||||||
status: draft
|
|
||||||
date: 2026-01-03
|
|
||||||
version: 0.1.0
|
|
||||||
related:
|
|
||||||
- adr: docs/architecture/adr-xxxx-<slug>.md
|
|
||||||
- pr: <link>
|
|
||||||
- issue: <link>
|
|
||||||
---
|
|
||||||
|
|
||||||
# 设计文档：<标题>
|
|
||||||
|
|
||||||
## 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 等
|
|
||||||
@@ -1,22 +0,0 @@
|
|||||||
---
|
|
||||||
title: Runbook 模板
|
|
||||||
owners:
|
|
||||||
- ops: ops-team
|
|
||||||
status: draft
|
|
||||||
---
|
|
||||||
|
|
||||||
# Runbook 标题
|
|
||||||
|
|
||||||
## 触发条件
|
|
||||||
|
|
||||||
## 负责人
|
|
||||||
|
|
||||||
## 联系方式
|
|
||||||
|
|
||||||
## 暂时性缓解
|
|
||||||
|
|
||||||
## 恢复步骤
|
|
||||||
|
|
||||||
## 验证
|
|
||||||
|
|
||||||
## 回滚（如果适用）
|
|
||||||
@@ -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`
|
|
||||||
@@ -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` 自动生成示例请求/响应片段。是否需要我继续生成？
|
|
||||||
@@ -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
|
|
||||||
@@ -1,26 +0,0 @@
|
|||||||
---
|
|
||||||
title: ADR 0001 - 服务设计决策
|
|
||||||
date: 2026-01-03
|
|
||||||
authors:
|
|
||||||
- backend-team
|
|
||||||
status: accepted
|
|
||||||
---
|
|
||||||
|
|
||||||
# ADR 0001: 服务设计与部署模型
|
|
||||||
|
|
||||||
## 背景
|
|
||||||
|
|
||||||
需要选择微服务还是单体部署以便平衡开发速度与运维复杂度。
|
|
||||||
|
|
||||||
## 决策
|
|
||||||
|
|
||||||
采用模块化单体（modular monolith）作为初始阶段部署方式，关键模块解耦、接口明确，后续按需拆分服务。
|
|
||||||
|
|
||||||
## 影响
|
|
||||||
|
|
||||||
- 优点：降低初期运维成本，便于本地调试与 CI 集成。
|
|
||||||
- 缺点：需要在代码边界设计中预留拆分点。
|
|
||||||
|
|
||||||
## 备注
|
|
||||||
|
|
||||||
在拆分时优先考虑数据库边界和独立部署能力。
|
|
||||||
@@ -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`
|
|
||||||
@@ -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`
|
|
||||||
@@ -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 字段 → **已决定**：保留字段（兼容历史），但新建部署不再写入
|
|
||||||
|
|
||||||
@@ -1,9 +0,0 @@
|
|||||||
# Changelog
|
|
||||||
|
|
||||||
所有 notable 更改应在此记录。遵循 Keep a Changelog 格式。
|
|
||||||
|
|
||||||
## [Unreleased]
|
|
||||||
- 初始文档目录建立。
|
|
||||||
|
|
||||||
## [1.0.0] - 2026-01-03
|
|
||||||
- 初始发布
|
|
||||||
@@ -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` 并更新迁移。
|
|
||||||
@@ -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 <repo-url>
|
|
||||||
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`。
|
|
||||||
@@ -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 提交。
|
|
||||||
@@ -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
|
|
||||||
@@ -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 小时内发布
|
|
||||||
Reference in New Issue
Block a user