Microi吾码 AI 平台治理中心

Microi吾码 AI 平台治理中心把门户编排、身份同步、权限解释、功能开关、灰度发布、服务目录、可观测告警、资源版本和可恢复导入集中到一个可安装、可升级的官方应用中。它不是另一套用户、权限或发布系统，而是继续复用吾码的 DiyToken、SaaS 租户、FormEngine、V8、微服务、应用商城、Redis 与数据库事实源。

能力总览

治理域	解决的问题	主要能力
门户编排	多业务入口散落、发布不可追踪	门户项目、插槽、资源、发布计划、解析与租户扩展 Hook
身份与权限	外部身份同步难审计、权限来源难解释	身份连接器、同步预检、冲突记录、受控应用、权限解释
灰度发布	功能只能一次性全量开启	功能开关、规则求值、发布计划、门禁校验、租户扩展门禁
服务治理	服务信息、健康和告警分散	服务目录、可观测策略、健康总览、告警求值与通知 Hook
资源版本	页面和蓝图修改后难比较、难恢复	稳定快照、SHA-256、差异查看、并发保护、事务回滚
可恢复导入	大文件导入失败后只能重来	预检、暂存、分片执行、检查点、暂停/继续、重试、条件回滚

治理中心微服务包含 7 个页面：治理总览、门户编排、身份与权限、灰度与发布、服务目录、可观测与告警、迁移导入。安装后的稳定入口为：

/micro-app/ai-platform-studio/overview

数据模型

治理资源使用 mci_ 平台表前缀，运行于当前 OsClient 对应数据库，不额外创建第二套租户字段。

表	作用
mci_portal_project	门户项目、状态与当前发布版本
mci_portal_slot	门户布局插槽、排序、可见规则
mci_portal_asset	插槽内的菜单、页面、链接和微服务资源
mci_resource_version	页面、蓝图及治理资源的版本快照、哈希和变更摘要
mci_identity_connector	外部身份源连接器及同步策略；密钥只保存密文或密钥引用
mci_identity_sync_run	每次同步计划、检查点、统计和终态
mci_identity_sync_conflict	账号、邮箱、手机号等身份冲突及人工处置记录
mci_feature_flag	功能开关、范围、规则、优先级和有效期
mci_release_plan	发布版本、环境、灰度阶段、门禁和回滚信息
mci_service_registry	服务标识、负责人、地址、协议和健康状态
mci_observability_policy	探测、阈值、聚合窗口与告警策略
mci_alert_event	告警事件、严重度、状态、确认与恢复时间
mci_import_job	导入批次、文件摘要、检查点、fencing token、统计和状态
mci_import_row	暂存行、稳定行哈希、校验结果、目标记录与回滚基线

这些表、字段、索引、菜单、权限、接口引擎和微服务由同一个应用商城包交付。普通租户不需要在 Microi.Upgrade 中增加定制迁移。

门户编排

门户发布采用“计划 → 校验 → 原子切换”的流程：

1. 在门户项目中定义稳定 ProjectKey。
2. 用插槽描述布局区域，用资源描述菜单、界面引擎页面、微服务页面或外部链接。
3. 调用 mci-portal-publish-plan 生成计划，检查重复 Key、孤立资源、无效目标和版本漂移。
4. 调用 mci-portal-publish 写入新版本并切换当前指针。
5. 客户扩展逻辑只写在 mci-portal-publish-extension；官方升级不会覆盖它。
6. 运行端通过 mci-portal-resolve 获取当前有效快照，不在浏览器拼装未经校验的草稿。

发布动作必须带预期版本或当前哈希。两个管理员同时修改时，后提交者收到冲突并重新加载，不允许最后写入者静默覆盖。

身份同步与权限解释

治理中心不替换 DiyToken，也不创建第二套用户、角色或权限 Token。外部身份验证成功后仍由吾码签发会话；同步只维护权威身份映射和现有用户、部门、角色关系。

推荐流程：

1. 创建身份连接器，保存提供方类型、匹配键、同步范围和密钥引用。
2. 调用 mci-identity-sync-plan 只读预检新增、更新、禁用和冲突数量。
3. 人工处理 mci_identity_sync_conflict 中的歧义账号。
4. 使用计划哈希调用 mci-identity-sync-apply；服务端复核身份、范围和当前版本。
5. 调用 mci-permission-explain 查看某用户获得菜单、表操作和数据范围权限的来源链。

连接器密码、OAuth Secret 和令牌不能返回给列表、导出或普通 V8。需要查看原文时必须使用独立授权动作、强身份验证票据、no-store 响应和不含明文的审计。

功能开关与灰度发布

mci_feature_flag 支持按租户、用户、角色、部门、环境和稳定百分比规则求值。百分比灰度必须使用稳定业务键计算，同一用户不能因节点或刷新变化而随机跳组。

发布计划建议至少经过：

Draft → Checking → Ready → Releasing → Completed
                  ↘ Blocked / Failed → RolledBack

mci-release-validate 在发布前检查目标版本、依赖、健康、告警、资源哈希和回滚入口；客户专属门禁写入 mci-release-gate-extension。开关命中只能决定功能是否启用，不能代替菜单、表、行权限和后端业务校验。

服务目录、可观测与告警

服务目录记录稳定 ServiceKey、负责人、运行地址、协议、环境和健康状态。可观测策略定义探测方式、超时、阈值、统计窗口和严重度；mci-observability-overview 聚合共享数据库事实，mci-alert-evaluate 生成或恢复告警。

多节点部署下需要遵守：

• 探测和告警扫描使用带租约的分布式锁，但业务去重仍依赖稳定 EventId、唯一约束或条件更新。
• 单节点内存计数只用于诊断，平台级状态写入共享数据库/Redis。
• 告警通知通过 mci-alert-notify-extension 扩展，官方更新不覆盖租户渠道逻辑。
• 健康检查区分 liveness、readiness 和依赖降级；正在排空的节点退出流量。

可恢复批量导入

治理中心的导入不是一次性把文件全部写进事务。它把“解析、校验、暂存、执行、恢复”拆成可审计状态机。

支持范围与门禁

• 支持 JSON、CSV 和 Excel；Excel 通过 V8.Office.ExcelToList 解析。
• 单次治理批次最多 2,000 行；更大文件应拆分或交给专用后台任务。
• 原始文件建议不超过 20 MB，接口 Base64 上限为 28 MB。
• 目标表和字段从当前租户元数据校验；控制面核心表、凭据字段和未知字段默认拒绝。
• 预检生成稳定计划哈希、文件哈希和逐行哈希，执行必须引用同一计划。

执行状态机

Draft → Planned → Staged → Running → Completed
                       ↘ Paused → Running
                       ↘ Failed → Retrying → Running
                       ↘ Cancelling → Cancelled
Completed / CompletedWithErrors → RollingBack → RolledBack

mci-import-execute 每片独立提交并持久化检查点、进度和 fencing token。节点退出后新持有者从最后已提交检查点继续；重复投递通过批次幂等键和逐行哈希保证副作用仅一次。回滚只撤销由本批次创建且之后未被用户修改的记录；目标已变化时记录冲突，不覆盖新数据。

界面引擎与业务蓝图版本治理

界面引擎和业务架构蓝图现在使用同一类版本合同：

• 保存前计算规范化 JSON 的 SHA-256。
• 每次真实变化自动写历史；内容未变化不制造空版本。
• 保存可携带 ExpectedHash，防止并发覆盖。
• 历史支持分页、读取、结构化差异和导出。
• 回滚不是删除历史，而是把目标快照写成一个新的当前版本，保留完整审计链。
• 当前数据与历史快照在同一数据库事务中更新。

界面引擎 MCP 工具：

工具	用途
microi_list_page_history	分页读取页面历史
microi_get_page_history	读取指定页面快照
microi_compare_page_versions	比较两个历史版本或历史与当前版本
microi_export_page_design	导出带 Schema、页面信息和哈希的设计包
microi_rollback_page_design	带预期哈希回滚并创建审计版本

业务蓝图对应提供历史列表、历史读取、版本比较、导出和回滚工具。AI 修改页面或蓝图前应先读取当前哈希，写入后再回读新哈希和历史记录。

应用商城安装与升级

官方应用 Key 为 ai-platform-studio。安装包同时包含 14 张治理表、14 个菜单、22 个接口引擎和 7 条微服务路由，并自动附带微应用运行基础资源。

接口引擎分为两类：

• 18 个官方核心使用 Managed。升级只在目标源码仍等于上一版共同基线时执行；发现客户修改会整包冲突回滚。
• 4 个租户扩展 Hook 使用 CreateIfMissing。首次安装后归租户维护，任何后续更新都不覆盖。

安装后必须回读表/字段/索引、菜单、角色权限、接口源码、微服务路由、构建资产哈希和应用版本。商城显示“已安装”不等于业务验收完成，仍需执行接口与浏览器冒烟。

最小验收清单

• [ ] 管理员可打开 7 个治理页面，普通用户无授权时失败关闭。
• [ ] 治理总览返回真实数据库统计，不依赖进程内状态。
• [ ] 门户计划可识别无效引用；发布后运行端解析到新版本。
• [ ] 身份同步先预检，冲突不自动覆盖用户；权限解释能返回来源链。
• [ ] 同一灰度键在不同 API 节点得到相同结果。
• [ ] 页面与蓝图保存、比较、导出、并发冲突、回滚均产生正确历史。
• [ ] 导入覆盖合法文件、非法字段、重复执行、暂停继续、节点退出和条件回滚。
• [ ] 服务健康与告警在重复扫描、节点切换和短暂依赖故障后无重复副作用。
• [ ] 应用商城首次安装、未修改升级、官方核心冲突、租户 Hook 保留和重复安装均通过。

相关文档

• 业务蓝图、状态机与自动化流
• 界面引擎
• 微服务
• 应用商城
• AI 开发工具