FlowStack/backend/docs/API.md

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

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 与 accessLevel；普通用户仅返回被授权的）
/api/pipelines	POST	创建（管理员）
/api/pipelines/:id	GET	详情（pipeline + nodes + edges + lastRun + accessLevel；需「查看」）
/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 引擎（队列→构建→增量日志回传）。

流水线权限

三级等级：viewer 查看 / operator 发布 / owner 管理；管理员全局豁免。未被授权的普通用户默认不可见任何流水线。

接口	方法	说明
/api/me	GET	当前会话（username/role/isAdmin）
/api/pipeline-roles	GET	权限组列表（管理员；附 matchedPipelines 匹配数）
/api/pipeline-roles	POST	创建（name/scopeMode=manual
/api/pipeline-roles/:id	PUT/DELETE	更新 / 删除（管理员）
/api/pipelines/:id/members	GET	单流水线直接成员 + 命中的权限组（需「查看」）
/api/pipelines/:id/members	POST	添加/更新成员等级（需「管理」；body: username/level）
/api/pipelines/:id/members/:mid	DELETE	移除直接授权（需「管理」）

资源（主机/集群/凭证/构建节点/工具/Webhook）、Jenkins 服务器、GitOps、插件与系统设置接口均要求管理员。

运行记录

接口	方法	说明
/api/runs	GET	运行列表（?pipelineId=&status=；普通用户仅返回被授权流水线的，每条附 canRetry）
/api/runs/:runId	GET	详情（run + stages + logs；失败含 AI analysis；需「查看」）
/api/runs/:runId/logs/stream	GET	SSE 实时日志（需登录：?token= 传会话 token 且需「查看」；事件 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	粘贴清单解析预览（纯规则）

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）。