湛兮
96 lines
4.7 KiB
Markdown
96 lines
4.7 KiB
Markdown
# DevOps Platform API
|
|
|
|
NestJS + TypeScript backend for the DevOps operations platform. The current local MVP provides the enterprise project skeleton, Prisma data model, configuration validation, integration client boundaries, Gitea webhook handling, Jenkins queue/build synchronization, notification provider boundaries, audit logs, BPMN process definitions, and runnable seed-backed APIs.
|
|
|
|
## Scope
|
|
|
|
- Manage projects, deploy runs, BPMN step state, Jenkins/Gitea integration state, notification delivery, audit records, and agent invocations.
|
|
- Keep all external credentials server-side.
|
|
- Use Prisma as the default data access layer. Native SQL is allowed only inside Repository methods with a documented reason.
|
|
|
|
## Local Setup
|
|
|
|
```bash
|
|
pnpm install
|
|
cp .env.example .env
|
|
pnpm prisma:generate
|
|
pnpm start:dev
|
|
```
|
|
|
|
The API listens on `http://localhost:4300` by default and runs without a local MySQL database when `USE_DATABASE_READS=false`. In that mode `/projects` and `/deploy-runs` use seed-backed repository data while keeping the same service and controller contracts intended for Prisma-backed reads.
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
pnpm lint
|
|
pnpm test
|
|
pnpm build
|
|
pnpm check
|
|
pnpm prisma:migrate:dev --name init
|
|
```
|
|
|
|
## API
|
|
|
|
- `GET /health`: dependency configuration and health summary.
|
|
- `GET /settings/integration-config`: Jenkins/Gitea/notification/LLM/Database/Redis/Secret Encryption Key configuration status. The response only exposes environment variable names, never secret values.
|
|
- `GET /projects`: configured project list.
|
|
- `GET /projects/:key`: one project by key.
|
|
- `GET /deploy-runs`: latest deploy runs.
|
|
- `POST /deploy-runs`: create a deploy run. Missing Jenkins config uses a local dry-run path; configured Jenkins calls `buildWithParameters` and returns `queued/running`.
|
|
- `POST /deploy-runs/:id/sync-jenkins`: synchronize Jenkins queue/build/log status and advance success or failure.
|
|
- `POST /deploy-runs/sync-jenkins`: synchronize all queued/running runs that have Jenkins queue/build identifiers.
|
|
- `POST /deploy-runs/:id/cancel`: cancel a deploy run.
|
|
- `POST /deploy-runs/:id/retry`: create a retry deploy run.
|
|
- `POST /webhooks/gitea`: accept Gitea push webhooks and trigger test deploy runs.
|
|
- `GET /process-definitions/release`: BPMN release process definition.
|
|
- `GET /audit-logs`: latest sanitized audit records.
|
|
- `GET /agent/invocations` and `POST /agent/invocations`: DevOps-scoped agent invocation records and mock results.
|
|
- `GET /docs`: Swagger UI.
|
|
|
|
## Data Access Rules
|
|
|
|
- Business modules access data through Repository classes, not direct Prisma calls in controllers.
|
|
- Prisma owns connection pooling, transactions, migrations, and typed models.
|
|
- Deploy run creation, status transition, step transition, and audit writes must use explicit Prisma transactions once DB writes are enabled.
|
|
- Idempotency keys are mandatory for webhook callbacks, Jenkins queue/build tracking, and manual deploy retry paths.
|
|
- Raw SQL must be parameterized, isolated in a Repository method, covered by tests, and justified in the method comment.
|
|
|
|
## Secret Rules
|
|
|
|
- Never commit real `.env`, Jenkins tokens, Gitea tokens, notification webhook URLs, LLM keys, private keys, or cookies.
|
|
- Persisted secrets belong in the `secrets` table encrypted with a deployment-provided key or in the deployment secret manager.
|
|
- Logs, audit records, integration errors, and LLM prompts must pass through redaction before storage or return.
|
|
|
|
## Agent Boundary
|
|
|
|
The Agent module is not a generic chat entrypoint. It can only support DevOps workflows:
|
|
|
|
- release risk summaries,
|
|
- Jenkins failure diagnosis,
|
|
- runbook Q&A against whitelisted sources,
|
|
- release notes drafts,
|
|
- incident review drafts.
|
|
|
|
Agent calls are read-only. They must not trigger deploys, mutate Jenkins/Gitea, or expose raw secrets. When `LLM_BASE_URL`, `LLM_API_KEY`, and `LLM_MODEL` are configured, the backend proxies DevOps-scoped prompts to `/chat/completions`; otherwise it returns local mock results with the same API shape.
|
|
|
|
## Notification Providers
|
|
|
|
`DeployNotificationService` supports the first provider boundary for:
|
|
|
|
- `NOTIFICATION_PROVIDER=wecom` with `WECOM_WEBHOOK_URL`
|
|
- `NOTIFICATION_PROVIDER=feishu` with `FEISHU_WEBHOOK_URL`
|
|
- `NOTIFICATION_PROVIDER=generic` with `NOTIFICATION_WEBHOOK_URL`
|
|
|
|
Missing provider or webhook configuration returns a skipped notification result and does not block deploy status transitions.
|
|
|
|
## Jenkins Auto Sync
|
|
|
|
Manual sync is always available through `POST /deploy-runs/sync-jenkins`. To enable a lightweight in-process poller before Redis/BullMQ is introduced:
|
|
|
|
```env
|
|
JENKINS_AUTO_SYNC_ENABLED=true
|
|
JENKINS_AUTO_SYNC_INTERVAL_MS=30000
|
|
```
|
|
|
|
The poller only scans queued/running runs that already have a Jenkins queue id or build number.
|