Logan.Li
ed88a18e03
- backend/docs/GUIDE.md：使用指南，每功能一句话讲清 「是什么→怎么用→实用技巧」（快速开始 3 步、流水线快速上手配置、 GitOps 概念与用法、AI 助手/批量发布/Jenkins/构建节点/工具/ 飞书通知/用户 LDAP/常见问题 FAQ） - backend/docs/API.md：接口文档（opsx-sec 骨架：通用约定/模块 索引表/重点端点 curl 示例/状态码速查） - GET /api/docs：文档 embed 进二进制，运行目录 docs/ 优先可热更新 - /docs 页面：使用指南/接口文档切换 + 左侧目录锚点导航 + markdown 渲染（marked + gfm-heading-id，深浅主题适配排版） - 侧边栏系统组新增「文档」入口（第一位）
141 lines
6.4 KiB
Markdown
141 lines
6.4 KiB
Markdown
# FlowStack 接口文档
|
||
|
||
> 与当前后端代码对齐；所有 `/api/*` 需携带登录 Token，敏感字段只写不回显。
|
||
|
||
| | |
|
||
|---|---|
|
||
| 文档版本 | v0.4 |
|
||
| Base URL | `http://<host>:9527` |
|
||
| 鉴权 | `Authorization: Bearer <token>`（`POST /api/auth/login` 获取，7 天有效） |
|
||
| 技术栈 | Go gin + SQLite（GORM） |
|
||
|
||
**典型接入流程**：登录拿 token → 管理流水线/节点/凭证 → 触发运行 → SSE 看日志 → 查发布记录。
|
||
|
||
## 通用约定
|
||
|
||
- **鉴权**：除登录、健康检查（`/health`）、入站 Webhook（`/api/hooks/*`）、SSE 日志流外，所有接口需 Bearer Token；用户管理类接口需 admin 角色
|
||
- **错误格式**：`{"error": "中文错误信息"}`，HTTP 状态码语义化（400 参数错 / 401 未登录 / 403 权限 / 404 不存在 / 409 冲突）
|
||
- **敏感字段只写不回显**：凭证内容、API Key、Token、Bind 密码等提交后永不返回，响应以 `xxxSet` 布尔表示已配置；**编辑时留空 = 保持原值**
|
||
- **时间**：ISO 8601 带时区
|
||
|
||
## 认证
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/auth/login` | POST | 登录（本地 argon2id 或 LDAP 直连验证），返回签名 token |
|
||
|
||
```bash
|
||
curl -X POST http://localhost:9527/api/auth/login \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"username":"admin","password":"xxx"}'
|
||
# → {"success":true,"token":"...","username":"admin","role":"admin","expiresAt":"..."}
|
||
```
|
||
|
||
LDAP 用户名在目录验证通过后自动建号/同步（JIT）；错误统一返回 401「用户名或密码错误」。
|
||
|
||
## 流水线
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/pipelines` | GET | 列表（每条附 `lastRun` 最近运行） |
|
||
| `/api/pipelines` | POST | 创建（name 必填；deployType: host/kubernetes 值为 `k8s`/gitops） |
|
||
| `/api/pipelines/:id` | GET | 详情（pipeline + nodes + edges + lastRun） |
|
||
| `/api/pipelines/:id` | PUT | 更新（白名单字段，含触发器/变量/缓存） |
|
||
| `/api/pipelines/:id` | DELETE | 删除（级联删节点连线） |
|
||
| `/api/pipelines/:id/nodes` | PUT | 全量保存画布节点 |
|
||
| `/api/pipelines/:id/edges` | PUT | 全量保存画布连线 |
|
||
| `/api/pipelines/:id/runs` | POST | 触发运行（body 可带 branch/env/triggerType） |
|
||
|
||
`type=jenkins` 且已关联服务器的流水线触发时走真实 Jenkins 引擎（队列→构建→增量日志回传）。
|
||
|
||
## 运行记录
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/runs` | GET | 运行列表（`?pipelineId=&status=`） |
|
||
| `/api/runs/:runId` | GET | 详情（run + stages + logs；失败含 AI `analysis`） |
|
||
| `/api/runs/:runId/logs/stream` | GET | SSE 实时日志（免鉴权；事件 connected/log，历史先回放） |
|
||
| `/api/runs/:runId/retry` | POST | 以同分支重新触发 |
|
||
|
||
## AI 与批量发布
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/ai/chat` | POST | AI 对话（JSON 返回；未配 LLM 降级规则匹配） |
|
||
| `/api/ai/chat/stream` | POST | 同上，SSE 流式（delta/done 事件） |
|
||
| `/api/ai/release` | POST | 按服务名批量触发（未导入的 Jenkins Job 自动建流水线） |
|
||
| `/api/batch/parse` | POST | 粘贴清单解析预览（纯规则） |
|
||
|
||
```bash
|
||
curl -X POST http://localhost:9527/api/ai/release \
|
||
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
|
||
-d '{"jobs":["aiops-backend","aiops-web"],"branch":"test"}'
|
||
# → {"triggered":[{"job":"aiops-backend","runId":"pr-..."}],"failed":[]}
|
||
```
|
||
|
||
## 资源管理
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/hosts` / `/api/clusters` | CRUD | 主机 / Kubernetes 集群 |
|
||
| `/api/hosts/:id/test` / `/api/clusters/:id/test` | POST | 真实 TCP 拨号连通测试 |
|
||
| `/api/credentials` | CRUD | 凭证（内容 AES 加密只写；响应含 `contentSet`） |
|
||
| `/api/build-nodes` | CRUD | 构建节点 |
|
||
| `/api/build-nodes/:id/test` | POST | 连通测试（TCP 拨号 22 端口） |
|
||
| `/api/build-nodes/:id/disk-test` | POST | dd 磁盘性能实测（256MB，本机 exec 或 SSH 远程；返回读写 MB/s） |
|
||
| `/api/tools` | GET/PUT | 工具清单与安装策略 |
|
||
| `/api/tools/:id/check` | POST | 真实执行版本探测命令 |
|
||
| `/api/webhooks` | CRUD + `/:id/test` | 出站 Webhook（HMAC-SHA256 签名发送） |
|
||
| `/api/hooks/pipeline/:id?token=` | POST | 入站触发流水线（免鉴权，token 校验） |
|
||
|
||
## Jenkins
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/jenkins-servers` | CRUD | 服务器管理（Token 加密只写） |
|
||
| `/api/jenkins-servers/:id/test` | POST | 真实连通测试（crumb + BasicAuth） |
|
||
| `/api/jenkins-servers/:id/jobs` | GET | 拉取 Job 树（folder 压平） |
|
||
| `/api/jenkins-servers/:id/import` | POST | 导入 Job 为 jenkins 类型流水线 |
|
||
|
||
## GitOps
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/gitops/apps` | GET | 应用列表（含同步/健康状态） |
|
||
| `/api/gitops/argo/apps` | GET | Argo 风格状态视图 |
|
||
| `/api/gitops/argo/sync` | POST | 触发同步（状态真实推进） |
|
||
| `/api/gitops/argo/:app/tree` / `/diff` | GET | 资源树 / 差异对比 |
|
||
|
||
## 用户与 LDAP
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/users` | GET/POST | 用户列表 / 创建本地用户（密码留空随机生成并一次性回显） |
|
||
| `/api/users/:id` | PUT/DELETE | 角色/信息更新 / 删除（不可删最后一个 admin） |
|
||
| `/api/users/:id/reset-password` | POST | 重置密码（LDAP 用户拒绝） |
|
||
| `/api/users/ldap-import` | POST | 批量导入（已 LDAP 跳过 / 本地同名转换 / 新建） |
|
||
| `/api/ldap/users` | POST | LDAP 用户预览（未启用返回 400） |
|
||
|
||
## 设置
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/settings` | GET/PUT | 单行设置：主题/通知/工具模式/AI/飞书/LDAP（敏感字段只写） |
|
||
| `/api/settings/test-llm` | POST | AI 连通测试（支持草稿值，apiKey 留空回退已存） |
|
||
| `/api/settings/test-lark` | POST | 飞书测试卡片 |
|
||
| `/api/settings/ldap/test` | POST | LDAP 测试（支持草稿 + 可选测试账号） |
|
||
| `/api/summary` | GET | 概览统计（侧边栏徽标） |
|
||
| `/api/docs` | GET | 本文档与使用指南 Markdown |
|
||
|
||
## 状态码速查
|
||
|
||
| 状态 | 含义 |
|
||
|---|---|
|
||
| 400 | 参数错误 / 未启用对应功能 |
|
||
| 401 | 未登录 / token 过期 / 用户名或密码错误 |
|
||
| 403 | 需要 admin 角色 |
|
||
| 404 | 资源不存在 |
|
||
| 409 | 名称重复等冲突 |
|
||
|
||
运行状态枚举：`pending → running → success | failed | cancelled`（Jenkins 队列阶段为 `queued`）。
|