# 运维平台 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`。
- `20260612093000_add_jenkins_external_trigger` 会扩展发布记录触发来源，用于保存 Jenkins 直接构建导入的 run。
- 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` 提供；源码不保存固定默认口令。
- 普通成员创建或重置密码时，后端会生成一次性临时密码并仅在本次接口响应中返回给超级管理员。

超级管理员初始化配置集中在 `src/auth/auth.constants.ts`、`prisma/seed.js` 和服务器环境变量。服务启动和种子数据只负责确保超级管理员账号存在并保持最高权限；如果超级管理员已修改密码，后续初始化不会覆盖密码。

如果数据库中已经存在旧密码哈希，或者超级管理员忘记密码，平台内不提供找回入口，只能在服务器执行受控重置命令：

```bash
pnpm reset:super-admin-password
```

该命令面向已构建的服务器部署目录，会自动读取当前目录的 `.env.production`。执行前必须临时设置 `SUPER_ADMIN_RESET_PASSWORD`，脚本不会输出明文密码。源码调试可先执行 `pnpm build`，或使用 `pnpm reset:super-admin-password:dev`。

## 关键接口

- `POST /auth/login`：登录，返回 token 和当前账号信息。
- `GET /auth/me`：查询当前登录账号。
- `POST /auth/change-password`：修改当前登录账号密码。
- `POST /auth/forgot-password`：普通成员忘记密码，通知超级管理员处理。
- `GET /members`：超级管理员查询成员列表和项目权限。
- `POST /members`：超级管理员创建普通成员，返回一次性临时密码。
- `PATCH /members/:id/permissions`：超级管理员更新普通成员项目权限。
- `POST /members/:id/reset-password`：超级管理员为普通成员生成一次性临时密码。
- `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 状态，仅超级管理员可用。
- `POST /deploy-runs/import-jenkins`：扫描已纳管 Jenkins job 最近构建并导入平台外直接构建记录，仅超级管理员可用。
- `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`：超级管理员初始化密码，服务启动或执行种子数据时必填。
- `SUPER_ADMIN_RESET_PASSWORD`：服务器重置脚本使用的一次性超级管理员重置密码，执行重置时必填。
- `SECRET_ENCRYPTION_KEY`：服务端密钥加密密钥，生产环境保存 Agent 密钥时必须配置。
- `DATABASE_URL`：MySQL 连接地址。
- `USE_DATABASE_READS`：是否启用 Prisma 数据读写。
- `PRISMA_CONNECT_ON_BOOT`：启动时是否主动连接数据库。
- `REDIS_URL`：Redis 连接地址，`/health` 会执行真实 PING，Jenkins 自动同步和通知 outbox 重试会优先使用 BullMQ 调度。
- `JENKINS_BASE_URL`、`JENKINS_USERNAME`、`JENKINS_API_TOKEN`：Jenkins 集成配置。
- Jenkins 配置缺失时，发布单会在 Jenkins 步骤失败，不会模拟成功；生产环境需要提供完整 Jenkins 配置，并建议开启 `JENKINS_AUTO_SYNC_ENABLED=true` 持续同步队列和构建状态。
- `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 或暴露密钥。

## 开源许可

本仓库使用 MIT License。提交公开仓库前请确认 `.env`、部署密钥和真实第三方 token 未进入 Git 历史或提交内容。