Logan.Li
9103b13510
权限模型（借鉴 Jenkins Role-Strategy 与云效，默认拒绝）： - 三级权限：查看（流水线+成功/失败日志）/ 发布（+构建、批量发布、重试）/ 管理（+配置、成员）；admin 全局豁免 - 权限组（管理员配置）：默认手动多选流水线（免正则，操作友好）；高级模式仅 * 通配符（cex-*） - 单流水线成员直授权作为例外补充；AI 批量发布逐 job 校验，越权明确拒绝 后端： - 新增 PipelineRole/PipelineMember 表与 /api/pipeline-roles、/api/pipelines/:id/members CRUD - RequirePipelineAccess/RequireRunAccess 中间件挂全流水线与运行路由；列表按可见性过滤并附 accessLevel/canRetry - /api/me 会话接口；logs/stream SSE 支持 ?token= 认证（原先完全免鉴权）并校验查看权限 - 凭证/主机/集群/构建节点/工具/Webhook/Jenkins/GitOps/插件/设置全部 AdminOnly；触发人以会话身份落库 前端： - useSession 会话 hook；Sidebar 菜单分级（资源/集成/系统管理 admin-only）；admin 路由守卫 - 按钮级权限：执行/配置/删除/保存/重试按等级显隐；新页「流水线权限」与流水线成员弹窗（纯点选） - 登录页记住密码；GUIDE/API 文档补权限章节
160 lines
8.6 KiB
Markdown
160 lines
8.6 KiB
Markdown
# FlowStack 使用指南
|
||
|
||
> 一句话读懂每个功能：**是什么 → 怎么用 → 实用技巧**。
|
||
|
||
## 快速开始（3 步跑通第一次发布）
|
||
|
||
1. **登录**：浏览器打开系统地址，用初始账号登录（初始密码在服务器 `data/initial-admin-password.txt` 或启动日志里）
|
||
2. **建流水线**：左侧「流水线」→ 新建流水线 → 填名称/仓库/部署方式 → 进入画布，从左侧任务库点选节点（源码→构建→部署）→ 点「保存」
|
||
3. **发布**：点「保存并运行」或「执行」，画布节点实时推进状态、底部日志滚动；结果可在「发布记录」查看，配置了飞书通知还会收到群卡片
|
||
|
||
## 流水线
|
||
|
||
**是什么**：把代码从拉取、构建、测试到部署的整个过程固化成一键可重复执行的流程。
|
||
|
||
**快速上手配置**：
|
||
- 画布编排：左侧 Task 任务库点击添加节点，拖拽摆位，从一个节点下方的连接点拖到另一个节点建立执行顺序
|
||
- 节点配置：点节点弹出右侧属性面板，修改参数（如 Git 仓库地址、镜像名）
|
||
- 基本信息 / 触发设置 / 变量和缓存 / 发布：编辑器顶部 Tab 切换，各自保存
|
||
- 触发方式：手动 / Webhook / Git Push / 定时（Cron），Webhook 触发会生成带 token 的调用地址，可直接配到 Git 仓库
|
||
|
||
**技巧**：
|
||
- `type=jenkins` 的流水线由 Jenkins 导入生成，执行时会真实触发 Jenkins 构建并回传日志
|
||
- 变量与缓存里定义的变量（如 `NODE_VERSION`）可在脚本中引用，配合 nvm 实现按次切换 Node 版本：`nvm install $NODE_VERSION`
|
||
- 流水线编辑器任务库支持搜索（按任务名/参数过滤）
|
||
|
||
## AI 智能助手
|
||
|
||
**是什么**：右下角悬浮的对话助手，用自然语言描述就能触发发布，配置 AI 后还能回答系统使用问题。
|
||
|
||
**怎么用**：
|
||
- 输入「发布 cex-agent-server、cex-agent-api 到 pre 分支」→ 出现发布计划卡片 → 确认发布 → 每个服务的运行编号（runId）直接回显
|
||
- 未在流水线里的 Jenkins Job 会自动创建流水线再触发
|
||
|
||
**技巧**：
|
||
- 在系统设置 → AI 助手里配置大模型（DeepSeek/GLM/Qwen/Kimi/Ollama 预设一键填地址）；**不配置也能用**——自动降级为本地规则匹配模式
|
||
- 发布失败时 AI 自动分析日志尾部（结论/根因/建议），在发布记录展开可见
|
||
- 流式输出支持「停止」中断长回答
|
||
|
||
## 批量发布
|
||
|
||
**是什么**：一次把多个服务按顺序或并发发布。
|
||
|
||
**怎么用**（粘贴清单模式）：
|
||
```
|
||
cex-agent-server
|
||
cex-agent-api
|
||
cex-agent-admin
|
||
```
|
||
粘贴多行服务名 → 选分支（快捷 chips：pre/test/main）→ 解析预览 → 开始串行/并发发布。
|
||
|
||
**技巧**：TAG 模式支持「服务名+版本号」成对粘贴（每行一个，或 `name=V1.0`）；`#` 开头的行是注释；也可以用 AI 助手一句话触发批量发布。
|
||
|
||
## GitOps 部署
|
||
|
||
**是什么**：把 Git 仓库当作部署状态的唯一事实来源——改配置就是改 Git，系统负责让集群和仓库保持一致。
|
||
|
||
**怎么用**：
|
||
1. 在 Git 仓库里用 Kustomize/Helm 描述每个应用的部署参数
|
||
2. 本页登记应用（仓库/路径/集群/命名空间）
|
||
3. 「同步」把仓库声明推到集群；「资源树」看应用创建了哪些 K8s 资源；「差异对比」看 Git 与集群当前的不一致
|
||
|
||
**技巧**：开启自动同步后 Git 提交即自动部署；「待同步」状态说明集群和 Git 有差异，点同步即可收敛。
|
||
|
||
## Jenkins 集成
|
||
|
||
**是什么**：把现有 Jenkins Job 导入 FlowStack 统一管理，执行时真实触发 Jenkins 并把控制台日志实时回传。
|
||
|
||
**怎么用**：左侧「Jenkins导入」→ 添加服务器（地址+用户+API Token）→ 测试连接 → 拉取 Job 树 → 勾选导入 → 在流水线列表出现 `Jenkins` 标记的流水线。
|
||
|
||
**技巧**：Token 只写不回显，编辑留空表示不修改；批量发布/AI 助手提到未导入的 Job 会自动创建流水线，无需先来导入页。
|
||
|
||
## 构建节点
|
||
|
||
**是什么**：执行构建任务的机器，支持标签调度、并发上限和健康检查。
|
||
|
||
**怎么用**：添加节点（名称/IP/标签/并发数）→「测试连接」验证可达 →「磁盘性能」跑 dd 实测读写速度（写入/读取 MB/s 直接显示在卡片上）。
|
||
|
||
**技巧**：
|
||
- 本机节点（127.0.0.1）磁盘测试直接本地执行；远程节点需先关联 SSH 凭证
|
||
- 磁盘速度颜色分级：绿 >200MB/s（SSD 级）、黄 50-200、红 <50（需关注）
|
||
|
||
## 工具配置
|
||
|
||
**是什么**：构建环境的工具清单与安装策略，Ubuntu 导向。
|
||
|
||
**技巧**：
|
||
- 每个工具带一键复制的安装命令（`apt install ...` / nvm 脚本）
|
||
- Node 用 nvm 管理：默认版本在此设置，流水线构建时 `nvm install $NODE_VERSION` 灵活切换
|
||
- 「检测」真实执行版本探测命令（如 `java -version`）；「安装」是保守策略——只检测不自动下载
|
||
- `deploy/Dockerfile.buildnode` 一键构建 Ubuntu 构建节点镜像
|
||
|
||
## 飞书 / Lark 通知与 Webhook
|
||
|
||
**是什么**：发布成功/失败自动向群推送结果卡片（应用/分支/构建/状态/时间 + 「查看构建详情」按钮直达 Jenkins）。
|
||
|
||
**怎么用**：系统设置 → 消息通知 → 填群机器人 Webhook（和可选的签名密钥）→「发送测试卡片」验证。
|
||
|
||
**技巧**：
|
||
- 单条流水线可在「基本信息」里单独填通知 Webhook，优先于全局配置
|
||
- 通用 Webhook 回调（发给第三方系统，HMAC-SHA256 签名）也在系统设置 → 消息通知里配置
|
||
|
||
## 用户与 LDAP
|
||
|
||
**是什么**：本地账号 + 企业目录（LDAP/AD）账号统一登录。
|
||
|
||
**怎么用**：
|
||
- 系统设置 → 用户目录：启用 LDAP，填服务器/Bind DN/Base DN → 测试连接（可带测试账号验证）→ 保存
|
||
- 用户管理页出现「从 LDAP 导入」→ 勾选导入；列表来源徽章区分「本地账号」和「LDAP 导入」
|
||
|
||
**技巧**：
|
||
- LDAP 用户密码在目录中管理（不落库），首登自动建号
|
||
- 未启用 LDAP 时导入按钮自动隐藏
|
||
|
||
## 环境与凭证
|
||
|
||
**是什么**：环境管理登记主机与 Kubernetes 集群（真实连通测试）；凭证集中保管敏感信息。
|
||
|
||
**技巧**：
|
||
- 凭证内容 AES 加密存储、只写不回显，编辑留空=不修改
|
||
- SSH 凭证关联构建节点后即可远程磁盘测试
|
||
|
||
## 流水线权限
|
||
|
||
**是什么**：按流水线控制「谁能看、谁能发布、谁能改」。未被授权的普通用户看不到任何流水线与发布记录（默认拒绝）；管理员始终拥有全部权限。
|
||
|
||
**三级权限**：
|
||
|
||
| 等级 | 能做什么 |
|
||
|---|---|
|
||
| 查看 | 看流水线、发布记录、发布成功/失败日志（只读，不能构建） |
|
||
| 发布 | 查看 + 触发构建、批量发布、失败重试 |
|
||
| 管理 | 发布 + 编辑流水线配置、管理该流水线的成员授权 |
|
||
|
||
**怎么授权（管理员，系统 → 流水线权限）**：
|
||
- 新建权限组 → **选择流水线**：直接勾选要授权的流水线（推荐，全程点选）
|
||
- 或 **名称匹配（高级）**：只写 `cex-*` 这类通配符（`*` 代表任意字符，无需正则），一次授权整批，之后新建的同名流水线自动纳入
|
||
- 选好权限等级，勾选成员，保存即生效
|
||
- 也可以在单条流水线里：编辑器顶栏「成员」按钮，给个别人单独授权（作为权限组的例外补充）
|
||
|
||
**普通用户能看什么**：
|
||
- 菜单只剩「发布」组（流水线/批量发布/发布记录）和「文档中心」；资源、集成、GitOps、系统管理类菜单全部隐藏（直接输 URL 也会被拦回）
|
||
- 流水线列表只显示被授权的；按钮按等级显隐：查看级只有只读入口，发布级出现「执行/保存并运行/重试」，管理级才有「保存/成员」
|
||
- 新建/删除流水线、凭证/主机/集群/构建节点等资源管理仅管理员
|
||
|
||
**技巧**：
|
||
- AI 助手批量发布同样受控：对未授权的 Job 会在结果里明确标注「无该流水线的执行权限」
|
||
- 构建日志 SSE 已要求登录（`?token=` 传递会话），未登录直接访问返回 401
|
||
|
||
## 常见问题
|
||
|
||
**初始密码在哪**：服务器 `data/initial-admin-password.txt` 或 `grep -A6 "已生成管理员账号" logs/flowstack.log`
|
||
|
||
**默认端口**：9527，可用 `PORT=xxxx ./run.sh` 覆盖
|
||
|
||
**页面打不开/跳转循环**：访问一次 `http://<地址>/?_clear=1` 清除浏览器缓存的旧重定向
|
||
|
||
**深色模式**：侧边栏底部太阳/月亮按钮，或系统设置 → 通用 → 主题模式（跟随系统可选）
|
||
|
||
**API 调用**：见「接口文档」页——所有 `/api/*` 需带登录 token（`Authorization: Bearer <token>`）
|