湛兮
fd472e3346
- integrations/redis: 新增 BullMQ 连接参数工厂并复用 Redis 模块导出\n- notifications/wecom: 优先使用 BullMQ 周期调度 outbox 重试，Redis 不可用时降级进程内定时器\n- README/RTK/.env.example: 同步通知 outbox 重试和 Redis/BullMQ 配置说明
124 lines
7.1 KiB
Markdown
124 lines
7.1 KiB
Markdown
# 运维平台 API
|
||
|
||
这是运维平台后端服务，基于 NestJS、TypeScript 和 Prisma 构建。后端负责账号鉴权、成员管理、项目权限、发布记录、Jenkins/Gitea 集成、通知、审计、流程定义和 Agent 运维能力。
|
||
|
||
## 范围
|
||
|
||
- 只维护运维平台 API，不包含前端页面代码。
|
||
- 外部系统密钥只保存在服务端，接口不会返回完整密钥。
|
||
- 数据访问默认使用 Prisma；如必须使用原生 SQL，只能放在 Repository 中并说明原因。
|
||
- 本地未配置 MySQL 时，项目、发布记录、账号和配置能力会使用内存降级数据，便于开发调试。
|
||
|
||
## 本地启动
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm prisma:generate
|
||
pnpm start:dev
|
||
```
|
||
|
||
默认监听地址为 `http://localhost:4300`。未配置 `DATABASE_URL` 或 `USE_DATABASE_READS=false` 时，不会强制连接 MySQL。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
pnpm prisma:generate
|
||
pnpm lint
|
||
pnpm test
|
||
pnpm build
|
||
pnpm check
|
||
pnpm prisma:migrate:dev --name init
|
||
pnpm prisma:seed
|
||
```
|
||
|
||
## 数据库迁移与 Jenkins 部署
|
||
|
||
- 迁移历史从 `prisma/migrations/20260611000000_baseline_current_schema` 开始，空库可以直接执行 `pnpm prisma migrate deploy` 初始化当前 schema。
|
||
- 生产库在启用 Prisma 迁移历史前已经存在表结构；`deploy/deploy-devops-platform-api-from-jenkins.sh` 会检测完整表结构并自动将基线迁移标记为已应用，再执行 `pnpm prisma migrate deploy`。
|
||
- Jenkins 服务器使用 `/usr/local/bin/deploy-devops-platform-api-from-jenkins`，该脚本应与仓库 `deploy/deploy-devops-platform-api-from-jenkins.sh` 保持一致。
|
||
- 如需紧急跳过迁移，可在服务器环境中设置 `PRISMA_MIGRATE_DEPLOY_ENABLED=false`，但不能在存在 schema 变更的版本长期使用该开关。
|
||
- 新增表或字段时必须提交新的 `prisma/migrations/<timestamp>_<name>/migration.sql`，不要再用手工 SQL 直接改生产库。
|
||
|
||
## 内置账号
|
||
|
||
- 超级管理员账号：`zhanxi`
|
||
- 超级管理员初始密码：生产环境通过 `SUPER_ADMIN_INITIAL_PASSWORD` 注入；本地未配置时使用开发兜底口令。
|
||
- 普通成员初始密码：`111111`
|
||
|
||
超级管理员初始化配置集中在 `src/auth/auth.constants.ts` 和服务器环境变量。生产环境缺少 `SUPER_ADMIN_INITIAL_PASSWORD` 时 API 会拒绝初始化超级管理员，避免默认口令上线；如果超级管理员已修改密码，后续初始化不会覆盖密码。
|
||
|
||
## 关键接口
|
||
|
||
- `POST /auth/login`：登录，返回 token 和当前账号信息。
|
||
- `GET /auth/me`：查询当前登录账号。
|
||
- `POST /auth/change-password`：修改当前登录账号密码。
|
||
- `POST /auth/forgot-password`：普通成员忘记密码，通知超级管理员处理。
|
||
- `GET /members`：超级管理员查询成员列表和项目权限。
|
||
- `POST /members`：超级管理员创建普通成员，初始密码固定为 `111111`。
|
||
- `PATCH /members/:id/permissions`：超级管理员更新普通成员项目权限。
|
||
- `POST /members/:id/reset-password`：超级管理员将普通成员密码重置为 `111111`。
|
||
- `PATCH /members/:id/status`：超级管理员启用或禁用普通成员。
|
||
- `GET /messages`：超级管理员查询消息通知。
|
||
- `POST /messages/:id/handled`：超级管理员将消息标记为已处理。
|
||
- `GET /agent/config`：超级管理员查询 Agent 配置，密钥只返回脱敏值。
|
||
- `PUT /agent/config`：超级管理员保存 Agent 的 `key`、`baseURL` 和 `model`。
|
||
- `POST /agent/config/test`：超级管理员测试已保存的 Agent 配置。
|
||
- `GET /projects`：查询当前账号有权限访问的项目。
|
||
- `GET /projects/:key`：查询项目详情，需要只读或构建权限。
|
||
- `GET /projects/:key/refs`：查询项目分支和标签，需要只读或构建权限。
|
||
- `GET /deploy-runs`：查询当前账号有权限项目的发布记录。
|
||
- `POST /deploy-runs`：创建发布单并触发构建，需要构建权限。
|
||
- `POST /deploy-runs/:id/cancel`：取消发布单，需要构建权限。
|
||
- `POST /deploy-runs/:id/retry`：重试发布单，需要构建权限。
|
||
- `POST /deploy-runs/:id/sync-jenkins`：同步单个发布单 Jenkins 状态，需要构建权限。
|
||
- `POST /deploy-runs/sync-jenkins`：同步全部 Jenkins 状态，仅超级管理员可用。
|
||
- `GET /audit-logs`：超级管理员查询脱敏审计日志。
|
||
- `GET /settings/integration-config`：超级管理员查询集成配置状态。
|
||
- `GET /health`：运行健康检查。
|
||
- `GET /docs`：Swagger 接口文档。
|
||
|
||
## 权限规则
|
||
|
||
- 未登录访问受保护接口会返回 `登录已失效，请重新登录`。
|
||
- 普通成员首次登录或被重置密码后，必须先调用 `POST /auth/change-password` 修改密码。
|
||
- 超级管理员拥有全部项目的全部权限，不需要单独授权。
|
||
- 普通成员默认没有任何项目权限。
|
||
- 只读权限可以查看项目和发布记录，不能触发构建。
|
||
- 构建权限包含只读能力，可以对授权项目触发构建、取消、重试和同步单个 Jenkins 状态。
|
||
- 成员管理、消息通知、系统设置、审计日志和 Agent 配置仅超级管理员可访问。
|
||
|
||
## 密钥规则
|
||
|
||
- Agent `key` 保存到服务端 `secrets` 表或本地内存配置，接口只返回脱敏值。
|
||
- 生产环境保存 Agent 密钥必须配置 `SECRET_ENCRYPTION_KEY`。
|
||
- 审计、错误、日志和返回体不能包含完整 token、webhook、cookie、私钥或 Agent key。
|
||
- Agent 调用只使用后端保存的系统级配置，不信任前端传入的模型配置。
|
||
|
||
## 环境变量
|
||
|
||
- `AUTH_TOKEN_SECRET`：登录 token 签名密钥。
|
||
- `AUTH_TOKEN_TTL_SECONDS`：登录 token 有效期，默认 43200 秒。
|
||
- `SUPER_ADMIN_INITIAL_PASSWORD`：生产环境初始化超级管理员时的初始密码。
|
||
- `SECRET_ENCRYPTION_KEY`：服务端密钥加密密钥，生产环境保存 Agent 密钥时必须配置。
|
||
- `DATABASE_URL`：MySQL 连接地址。
|
||
- `USE_DATABASE_READS`：是否启用 Prisma 数据读写。
|
||
- `PRISMA_CONNECT_ON_BOOT`：启动时是否主动连接数据库。
|
||
- `REDIS_URL`：Redis 连接地址，`/health` 会执行真实 PING，通知 outbox 重试会优先使用 BullMQ 调度。
|
||
- `JENKINS_BASE_URL`、`JENKINS_USERNAME`、`JENKINS_API_TOKEN`：Jenkins 集成配置。
|
||
- `GITEA_BASE_URL`、`GITEA_TOKEN`、`GITEA_WEBHOOK_SECRET`、`GITEA_WEBHOOK_RELAY_BASE_URL`：Gitea 集成与 Jenkins relay 诊断配置。
|
||
- `NOTIFICATION_PROVIDER`、`WECOM_WEBHOOK_URL`、`FEISHU_WEBHOOK_URL`、`NOTIFICATION_WEBHOOK_URL`：通知集成配置。
|
||
- `NOTIFICATION_OUTBOX_RETRY_ENABLED`、`NOTIFICATION_OUTBOX_RETRY_INTERVAL_MS`、`NOTIFICATION_OUTBOX_RETRY_DELAY_MS`、`NOTIFICATION_OUTBOX_MAX_ATTEMPTS`、`NOTIFICATION_OUTBOX_BATCH_SIZE`：通知 outbox 自动重试配置；配置 `REDIS_URL` 时使用 BullMQ 调度，否则降级为进程内定时器。
|
||
- `LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL`：Agent 配置的环境变量后备值。
|
||
|
||
## Agent 边界
|
||
|
||
Agent 不是通用聊天入口，只支持运维工作流：
|
||
|
||
- 发布风险摘要
|
||
- Jenkins 失败诊断
|
||
- 运维手册问答
|
||
- 发布说明草稿
|
||
- 事故复盘草稿
|
||
|
||
普通成员使用 Agent 时必须绑定自己有权限访问的项目。Agent 调用只读，不会触发发布、修改 Jenkins、修改 Gitea 或暴露密钥。
|