运维平台 API

这是运维平台后端服务，基于 NestJS、TypeScript 和 Prisma 构建。后端负责账号鉴权、成员管理、项目权限、发布记录、Jenkins/Gitea 集成、通知、审计、流程定义和 Agent 运维能力。

范围

• 只维护运维平台 API，不包含前端页面代码。
• 外部系统密钥只保存在服务端，接口不会返回完整密钥。
• 数据访问默认使用 Prisma；如必须使用原生 SQL，只能放在 Repository 中并说明原因。
• 本地未配置 MySQL 时，项目、发布记录、账号和配置能力会使用内存降级数据，便于开发调试。

本地启动

pnpm install
pnpm prisma:generate
pnpm start:dev

默认监听地址为 http://localhost:4300。未配置 DATABASE_URL 或 USE_DATABASE_READS=false 时，不会强制连接 MySQL。

常用命令

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 或暴露密钥。