Skip to content

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/:

  1. Web Nginx 反代:前端不直连后端,所有 /api 与业务 API 请求统一经 Nginx 转发给 Gateway。
  2. 会话与成员校验:Gateway 验证 Access JWT 与 Redis 在线会话;若访问业务项目接口,会向 System 核对当前用户是否为该项目的有效成员(带缓存)。
  3. 签发 60 秒 Context:Gateway 签发一枚有效期 60 秒、绑定目标服务 audience 的签名 Context,转发请求给业务后端。
  4. 业务服务本地验签:业务后端通过 Starter SDK 本地验签并建立请求上下文,校验接口权限。业务查询可按项目配置的数据范围过滤记录。Context 验签在业务服务内完成。
异常现象排查顺序
工作台缺少入口检查项目成员是否启用、应用入口是否登记、前端挂载路径是否正确。
接口返回 401检查会话是否有效、请求是否经过网关、目标服务的公钥与 audience 是否匹配。
接口返回 403检查当前角色是否具备接口声明的权限码,授权变更后是否已重新建立会话。
列表返回为空用同一账号核对所属组织、当前项目、行级数据范围与业务筛选条件。

3. 三条核心设计边界 ​

Kaiwu 的绝大多数架构取舍,都可以归结为这三条边界:

  1. Gateway 不持有权限事实:Gateway 只做身份、会话与路由;权限的唯一事实源在 System,避免两套权限数据互相漂移。
  2. Kaiwu 自己也是一个项目:平台自身的成员、角色与菜单全部存放在内置项目 project_code=system 下,与业务项目走同一套表和授权链路,没有“特权旁路”。
  3. 生成的业务项目必须能离开平台:项目工厂对每个业务项目只生成一次——既可以由 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 双模型路由、按权限查询与写前预览确认。

下一步 ​

Apache License 2.0