Kaiwu 是怎么运作的
10 分钟看懂 Kaiwu 的整体架构、请求链路与三条核心边界,帮你判断它是否适合你的团队。
1. 独立产品仓与起步模板,各自演进
Kaiwu 不是一个大杂烩单仓。入口仓只保留初始化脚本与编排,真正的代码按职责拆成相互独立的 Git 仓库:
| 仓库 | 角色 | 说明 |
|---|---|---|
kaiwu-gateway-service | 唯一外部入口(8088) | 同源路由转发、JWT 与会话校验、签发内部 Context |
kaiwu-system-service | 控制面后端 | 管理用户、项目、角色、菜单、字典、多语言与项目工厂 |
kaiwu-system-web | 平台管理前端(8000) | 工作台入口、权限中心、字典/多语言/配置管理界面 |
kaiwu-system-starter | 业务服务 SDK | 供业务后端引入的 Maven 依赖,负责本地验签与上下文注入 |
kaiwu-web-starter | 产品前端起步仓 | 无平台依赖的独立 React 起步模板,内置 /__mock/ 运行时与 @/kaiwu 接入层 |
kaiwu-deploy(可选) | GitOps 部署声明 | 使用 Kubernetes / ArgoCD 交付时按环境生成 |
2. 一次请求如何走通
以订单中心为例,浏览器从工作台打开 /apps/order-center/,页面请求同源的 /order-center-api/:
- Web Nginx 反代:前端不直连后端,所有
/api与业务 API 请求统一经 Nginx 转发给 Gateway。 - 会话与成员校验:Gateway 验证 Access JWT 与 Redis 在线会话;若访问业务项目接口,会向 System 核对当前用户是否为该项目的有效成员(带缓存)。
- 签发 60 秒 Context:Gateway 签发一枚有效期 60 秒、绑定目标服务
audience的签名 Context,转发请求给业务后端。 - 业务服务本地验签:业务后端通过 Starter SDK 本地验签并建立请求上下文,校验接口权限。业务查询可按项目配置的数据范围过滤记录。Context 验签在业务服务内完成。
| 异常现象 | 排查顺序 |
|---|---|
| 工作台缺少入口 | 检查项目成员是否启用、应用入口是否登记、前端挂载路径是否正确。 |
| 接口返回 401 | 检查会话是否有效、请求是否经过网关、目标服务的公钥与 audience 是否匹配。 |
| 接口返回 403 | 检查当前角色是否具备接口声明的权限码,授权变更后是否已重新建立会话。 |
| 列表返回为空 | 用同一账号核对所属组织、当前项目、行级数据范围与业务筛选条件。 |
3. 三条核心设计边界
Kaiwu 的绝大多数架构取舍,都可以归结为这三条边界:
- Gateway 不持有权限事实:Gateway 只做身份、会话与路由;权限的唯一事实源在 System,避免两套权限数据互相漂移。
- Kaiwu 自己也是一个项目:平台自身的成员、角色与菜单全部存放在内置项目
project_code=system下,与业务项目走同一套表和授权链路,没有“特权旁路”。 - 生成的业务项目必须能离开平台:项目工厂对每个业务项目只生成一次——既可以由
project new一次生成双仓(BASIC_SCAFFOLD),也可以让产品从kaiwu-web-starter先出前端,再由project adopt纳管并仅生成配套后端(ADOPT_FRONTEND)。交付后 Kaiwu 永不覆盖业务源码,平台升级与业务迭代互不牵制。
4. 产品与 AI 在哪一步参与,如何保证可交付
大模型能写出“能跑”的代码,但容易漏掉权限、数据库迁移、敏感日志脱敏与发布契约。Kaiwu 把产品探索与 AI 工程边界清晰分层:
- 产品先出正式前端(Mock 阶段):产品与 AI 从
kaiwu-web-starter起步(内置 Umi Mock 运行时、501 兜底与/__mock/角色面板),通过@/kaiwu只读接入层调用平台能力(可自由更换 UI 组件库)。业务规则(docs/business-rules.md)与验收场景(docs/acceptance-scenarios.md)随源码提交,由pnpm verify:mock、pnpm test:scenarios与pnpm test:browser自动校验,在product分支验收后经handoff/*MR 交给开发。 - 平台纳管与项目生成:开发对已有产品前端运行
./kaiwu project adopt <前端仓> --apply登记项目、导入清单和首次角色并生成配套 Spring Boot 后端;或使用受校验ProjectBlueprint由版本化模板确定性渲染双仓脚手架。 - 真实联调与跨环境交付:业务仓自带
AGENTS.md、后端scripts/verify.sh与前端pnpm verify门禁。后端权限注解、前端按钮与kaiwu/menus.yml必须三端同码,DataScopeConventionTest检查归属字段与索引,并提示疑似漏声明的接口;前端使用pnpm dev:real走 Gateway 联调,生产构建确保/__mock/返回 404。上线阶段,代码通过独立仓库与 GitOps 交付,字典、菜单、参数、角色授权、定时任务与项目级引用式多语言则通过project sync与「配置移交」在测试和生产环境间可控对齐。
5. 开箱即用的企业底座能力
除了项目工厂与双仓交付机制,Kaiwu 还为所有接入项目提供统一的平台基础能力:
- MySQL 与达梦 DM8 双数据库支持:平台控制面首次部署原生可选 MySQL 或国产达梦 DM8(配备独立
kaiwu-dm-migrator与实例参数预检)。 - 跨环境配置移交(ADR 0042):6 类 YAML 全量快照 + 三方基线 diff 预览,角色授权按组确认、删除逐项勾选、新建定时任务默认停用。
- 按角色 × 部门的行级数据范围(
kaiwu-data-scope):Gateway 在签名 Context 携带ds,业务服务在 SQL 层自动注入隔离条件,零同步回调。 - STS 对象存储与安全 Excel:长期密钥加密留在平台,业务只取限定前缀的 STS 临时凭证且只存
storage_ref + object_key;kaiwu-excel防公式注入与 ZIP 炸弹。 - 统一待办与受控 AI 助手:
TodoClient按业务键表达或签/会签并随业务闭环;AI 助手支持PLAN / ANSWER双模型路由、按权限查询与写前预览确认。