Title: 微服务（前端微应用）
Canonical: https://microi.net/doc/system-engine/micro-app.html
Page-Modified: 2026-11-06T10:59:12.000Z
Source: published HTML document body; page revision is not a capability verification date.
# 微服务（前端微应用）
MICROI · VUE 3 · AI DELIVERY
## 一个工程，四种运行方式
吾码 MicroService 是面向定制业务界面的前端微应用体系。同一份发布物既能独立运行，也能作为后台菜单完整页面、表单引擎定制组件，或由 V8.OpenAppDialog 打开指定路由。
查看运行方式 (https://microi.net/doc/system-engine/micro-app.html#%E5%9B%9B%E7%A7%8D%E8%BF%90%E8%A1%8C%E6%96%B9%E5%BC%8F)浏览 AI 应用案例 ↗ (https://microi.net/apps.html)
01独立运行同一套帐号、租户与动态验证码
02菜单直开一个应用可按路由绑定多个菜单
03弹层打开Dialog / Drawer 与业务回调
04表单嵌入定制组件加载指定业务路由
先理解这里的“微服务”
本文的 MicroService 是可独立构建和发布的前端微应用，不等同于 .NET、Java 后端微服务。页面和交互放在 MicroService；事务、权限校验与可信数据写入继续放在接口引擎或后端原子能力中。
吾码官网 AI 应用广场 (https://microi.net/apps.html) 中的大部分 AI 应用均采用 MicroService 实现。这样既能独立展示和访问，也能无缝嵌入吾码菜单、表单与业务弹层，而不必把每个定制页面都打进 Microi.Client 主包。
例如，星河现场·旗舰抽奖互动平台 (https://microi.net/app-detail.html?app=event-lottery-studio)（event-lottery-studio）可从官网应用卡片直接体验。未登录用户可查看应用首页；创建抽奖项目或凭加入码参与时，先使用吾码账号登录。没有账号可从应用中的“注册账号”前往吾码官网完成手机号验证和密码设置，再返回应用登录。正式开奖、中奖记录和领奖核销由服务端接口引擎处理；彩排结果不写入正式中奖表。官方应用包包含后台菜单、业务表、接口引擎和微服务运行资产，租户安装与官网集中体验是两个独立入口。
该应用的活动流程为：创建草稿 → 配置奖项与公开规则 → 导入名单或分享加入码 → 发布 → 签到 → 固化本轮资格 → 服务端抽取 → 揭晓 → 凭码领奖与核销。主持台可分页管理参与者、设置发布前的公开权重、排除不合格人员、授权或停用主持人／审计员／核销员。正式规则发布后锁定；当前轮次准备或抽取后，必须先揭晓或取消，再准备下一轮。支持公平随机与公开权重，未实现的保底或任意自定义规则会明确拒绝。每批名单最多 500 人、单轮资格最多 10000 人、单轮中奖最多 500 人。
本应用 v1.1.2 适用于 MySQL 租户，要求平台 v8.5.0 或更新版本及应用资产 v3 发布协议；不支持的数据库类型会在执行业务 SQL 前明确拒绝。更新时先升级平台，再从应用商城更新此应用。安装后从“旗舰抽奖互动 → 抽奖工作台”直接打开 /studio，复用宿主当前租户与 DiyToken，无需在应用里再次输入密码。该菜单按应用 Key 与路由声明，由安装器解析本租户的运行服务及页面，不固定官方租户 Id。应用包中的 Managed 网关会同步修复后的事务、权限与随机实现，保留活动业务数据；新领奖码由后端按租户和接口绑定保护，无需手工配置 LotteryClaimKey。存量 AES 领奖码仍需保留原租户密钥以兼容读取。CSV 离线名单的中奖者，由 Owner 或 ClaimStaff 在揭晓后核验身份并发放现场凭证；真实账号中奖者仍从“我的奖品”领取凭证。现场凭证仅临时显示并自动清除，发放审计不保存明文。彩排初始化与页面切换会丢弃旧请求，迟到响应不会覆盖用户已经选择的舞台。安装到目标租户后核对实际 API 指向该租户，并走完创建、参与、揭晓与核销流程。
## 真实案例：同一能力融入不同业务位置
[威讯 CRM 客户地图微服务嵌入吾码后台菜单，展示客户分布、聚合点位与附近客户列表: https://file.microi.net/itdos/official-docs/images/dcf2f6a25884c9c032ccb5439a7fa7d0c2f6c52b7960adc9cc2afc03658a4bc4/202610/microservice-crm-customer-map.png]
案例 1 · 菜单路由CRM 客户地图地图、客户分类、距离检索与业务导航在同一微服务页面完成，并保留吾码菜单、页签和登录态。
[数据库定时备份微服务通过 V8.OpenAppDialog 在吾码 SaaS 引擎中弹层打开: https://file.microi.net/itdos/official-docs/images/5b6c224b84cd272061102de632f2f41167776960f2b0933b48931d8dd3c30a89/202610/open-app-dialog.png]
案例 2 · 弹层数据库定时备份在 SaaS 引擎列表上方打开指定微服务路由；背景页面、菜单和登录态均保留。
[生产计数报工工作台作为吾码平台菜单中的微服务路由打开: https://file.microi.net/itdos/official-docs/images/3ab84eff173308423d155157b13f986ac64cfbe31671db5b88eccc373f23c317/202610/menu-production-counter.jpg]
案例 3 · 菜单路由生产计数报工工作台深色大屏式工作台直接占据菜单内容区，宿主导航仍可正常使用。
[成品打包工作台作为吾码平台菜单中的另一个微服务路由打开: https://file.microi.net/itdos/official-docs/images/4acf55745d5274f2ec23383150c97356df9d52790ba3b886c0ad3edb0c8cff74/202610/menu-packing-workbench.jpg]
案例 4 · 菜单路由成品打包工作台一个 MicroService 可以维护多个页面，并让不同菜单直达各自 RoutePath。
## 四种运行方式
STANDALONE
### 独立运行
直接打开微服务地址。若浏览器已有有效登录态则自动进入；否则显示吾码帐号密码登录。验证码是否出现由当前租户 EnableCaptcha 动态决定。
适合：官网 AI 应用、外部入口、专用工作台、独立演示。
MENU ROUTE
### 平台菜单直开
后台菜单使用 OpenType=MicroService，URL 指向 /micro-app/{OsClient}/{AppKey}/{RoutePath}，直接打开应用内的指定路由。
适合：生产工作台、驾驶舱、复杂双栏页面、全屏业务操作。
OPEN APP DIALOG
### 弹层打开
在前端 V8 事件中调用 V8.OpenAppDialog，按 AppKey 和 RoutePath 打开 Dialog 或 Drawer，并通过回调返回结果。
适合：复杂配置、分步操作、跨表选择、详情工作台。
FORM COMPONENT
### 表单引擎中引用
表单字段使用 DevComponent，通过稳定的 DevComponentPath 别名匹配微服务页面，并在表单当前位置加载该页面的 RoutePath。
适合：表单内嵌看板、联动工作区、复杂选择器、租户专属业务区域。
### 一句话选择
你的需求 | 首选能力 | 原因 |
只是“是否继续” | V8.ConfirmTips | 无需引入完整页面。 |
普通新增、编辑、详情 | 表单引擎 / V8.OpenAnyForm | 权限、字段与校验已经标准化。 |
已内置在主前端的组件 | V8.OpenDialog | 直接复用 Microi.Client 组件。 |
表单中固定嵌入复杂业务区域 | DevComponent + MicroService 路由 | 与表单同屏，复用登录态、表单数据和权限上下文，又能独立发布。 |
复杂弹层，有联动、表格、上传或分步操作 | MicroService + V8.OpenAppDialog | 独立组件化开发，仍保留平台上下文。 |
完整工作台或同一应用多个业务页面 | MicroService + 菜单路由 | 可让多个菜单分别打开不同内部路由。 |
需要独立访问、独立版本、AI 维护与商城交付 | MicroService | 一个工程覆盖四种入口和独立发布。 |
### 管理员来源工具
菜单、弹窗和表单嵌入中的“微服务”图标、文字及源码定位详情，仅向当前登录用户 Level >= 9999 展示。普通用户和受限访问密钥会话不显示这些辅助入口，业务页面、 顶部页签关闭及弹窗操作仍按原权限正常使用。
管理员可关闭菜单页右上角当前实例的来源标识，切换页面或账号后恢复；用户等级降低时， 入口及已打开的来源详情同步隐藏。此行为随 Microi.Client 前端升级生效，无需改动微服务 应用包或菜单；实际源码读取、MCP 修改和发布继续由后端独立鉴权。
菜单页右上角胶囊可从图标或文字区拖动，关闭按钮独立操作。移动超过 4px 后按拖动 处理，松开不会误开详情；位置限制在当前内容区与可见视口内，窗口或内容区缩放时 自动约束。位置只属于当前页面实例，不保存为账号偏好，切换实例或账号后恢复。
管理员也可右击顶部微服务页签，选择【微服务详情】。该入口复用胶囊的详情弹层， 按右击的页签读取 AppKey、页面及源码位置；右击非当前页签不会切换或重挂业务页。 即使关闭了胶囊，仍可从页签打开详情。普通菜单、普通用户与受限访问密钥不显示此项。
## 整体架构
1在线 AI / MCP / VS Code创建或维护 Vue 3 源码
2私有源码与版本租户隔离、文件清单与哈希
3构建与发布不可变版本资产和路由清单
4独立 / 菜单 / 弹层 / 表单四种入口复用同一发布物
### 核心数据边界
数据 | 存储与职责 |
应用主数据 sys_microistore | 统一保存平台应用、Web、UniApp、MicroService 的名称、类型、分类、发布、预览和统计。 |
私有源码 mci_ai_app_file | 保存源码文件清单；实际内容进入当前租户私有 HDFS。 |
版本 mci_ai_app_version | 保存构建版本、状态、预览地址和变更说明。 |
运行时 sys_microiservice | 保存 MsKey、版本、入口、构建清单、文件列表和发布时间。 |
页面路由 sys_microiservice_page | 一个微服务可包含多个页面，是菜单、弹层与表单定制组件 RoutePath 的事实源。 |
菜单 sys_menu | OpenType=MicroService 时绑定微服务及其具体页面。 |
源码与构建产物必须分开：源码默认进入私有存储；编译后的 HTML、JS、CSS、图片和字体进入公有发布存储供浏览器加载。不要把大体积 JS/CSS 作为内联 JSON 长期保存在数据库字段里。
## 在线使用：AI 应用工作台
适合快速创建页面、让 AI 迭代代码、在线修复小问题、预览和发布。
### 创建微服务
- 登录吾码后台，进入 AI 引擎 的 AI 应用。
- 点击 新建微服务。
- 填写应用名称、应用 Key 和需求描述。
- 建议开启 生成骨架，系统会生成可运行的基础源码。
- 创建后自动进入开发工作台。
应用 Key 是运行时唯一标识，对应 sys_microistore.AppKey 和 sys_microiservice.MsKey。建议使用稳定的英文、数字、-、_ 组合，例如 microi-official，不要因为页面名称变化而反复修改 AppKey。
一个范围较大的应用应使用一个稳定的微服务承载多个页面。例如“吾码官网微服务”可以包含 SaaS 租户管理、安装向导、运维工具等页面，不必为每一个弹窗新建一个微服务。
### 编辑、预览和发布
工作台提供以下能力：
操作 | 用途 |
源码树 | 查看应用全部目录和文件。 |
保存源码 | 在线保存当前文件到私有 HDFS。 |
运行/发布 | 生成在线预览，并同步微服务运行元数据。 |
预览视图 | 在工作台内查看最新运行效果。 |
版本记录 | 查看构建版本、状态、预览地址和创建时间。 |
下载源码ZIP | 下载当前私有源码，供备份或本地继续开发。 |
下载编译ZIP | 下载最新编译产物。 |
制作离线包 | 生成可在无外网环境安装的 .microi-app.json 应用包。 |
发布应用商城 | 将私有源码、最新构建产物和运行时信息发布到应用商城。 |
推荐在线流程：
text
```
创建微服务 → AI 生成或人工编辑 → 保存源码 → 运行/发布
→ 预览验收 → 制作离线包或发布应用商城
```
在线编辑适合快速迭代；依赖较多、需要完整 Vite 插件、单元测试或长期多人协作时，建议使用 VS Code 本地工程。
当前公开 Web、UniApp 和 MicroService 的体验入口使用本租户可信 API 的 /micro-app/{tenantLower}/{AppKey}/index.html，租户段为 OsClient 小写，AppKey 来自当前应用权威记录。入口直接返回已提交的 HTML，浏览器地址栏保持固定地址，不顶层跳转到 typed v3、CDN/NAS 或版本目录。AI 工作台和商城同时核对真实类型与公开范围，已安装应用使用安装目标租户的元数据。
HTML 引用的 JS/CSS/图片等清单内资产仍可在副本校验和健康检查通过后经 FileServerBak 分流；未就绪时保留原存储读取。历史版本、带签名的文件地址与私有应用保留原访问规则，不会因入口优化变成公开资源。当前入口、资产实际分流与费用下降分别验收，不能只凭 CDN 直链 200 或文件已复制宣布完成。
## 本地使用：Microi VS Code 插件
适合完整 Vue/Vite 工程开发、依赖管理、本地调试、正式构建和批量源码维护。
### 准备工作
- 安装 Microi 吾码 VS Code 插件。
- 打开工作区并执行吾码初始化。
- 配置目标服务器的 ApiBaseUrl、OsClient，并登录目标租户。
- 在吾码资源管理器中选择对应服务器。
### 常用命令
可以在吾码资源树或 VS Code 命令面板中执行：
命令 | 作用 |
创建前端微服务 | 创建 Vue/Vite 工程、安装依赖，并注册微服务草稿。 |
拉取服务器前端微服务 | 从当前租户的在线 AI 应用私有 HDFS 拉取完整源码；只有运行产物、未保存源码的应用会明确拒绝拉取。 |
构建前端微服务 | 清理 dist，执行 npm run build，校验入口文件。 |
推送前端微服务到数据库 | 上传已有 dist，更新运行时、版本和页面路由。 |
构建并推送前端微服务 | 构建、上传产物、同步路由，并尝试把源码同步到在线 AI 应用。 |
同步微服务源码到在线 AI 应用 | 仅把本地源码同步到在线 AI 应用的私有 HDFS。 |
正式交付优先使用 构建并推送前端微服务。推送时系统会基于服务端当前版本自动生成下一个版本，首次通常是 v1.0.0，并更新 BuildVersion、EntryPath、构建清单、文件哈希、文件数量和发布时间。
插件创建项目后会自动安装依赖。需要独立启动本地开发服务器时，也可以进入项目目录执行：
bash
```
npm install
npm run dev
```
本地独立运行用于页面开发；Token、OsClient、菜单信息和弹窗数据只有放入吾码宿主后才是完整的，因此不能用独立预览代替最终验收。
### 本地项目结构
text
```
Microi-V8-Engine/
示例服务器 (api.example.com)/
Demo.Product.Internal/
AI应用/
microi-official/
.microi-micro-app.json
microi.routes.json
package.json
package-lock.json
tsconfig.json
vite.config.ts
index.html
src/
main.ts
App.vue
components/
pages/
composables/
domain/
services/
platform/
microi.ts
```
目录隔离规则为 Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}。因此不同服务器或租户即使存在相同 appKey，也不会覆盖同一份本地源码。
同一个租户可以创建多个微服务，例如：
text
```
Microi-V8-Engine/示例服务器 (api.example.com)/Demo.Product.Internal/AI应用/demo-official
Microi-V8-Engine/示例服务器 (api.example.com)/Demo.Product.Internal/AI应用/platform-service
```
旧版直接平铺在 Microi-MicroApp/ 下的项目仍会在资源树中以“旧目录”显示，但插件不会擅自移动；所有新建和拉取操作都写入 Microi-V8-Engine/.../AI应用/{appKey}。拉取先从 sys_microistore 读取应用主数据，再从 mci_ai_app_file 读取私有 HDFS 源码，不是读取 sys_microiservice 的公有编译产物。离线安装时若未包含源码，微服务仍可运行和预览，但必须回到原开发端或包含源码的服务器拉取。
### 完整源码拉取与大文件
VS Code 插件从开发工具 5.8.6 起，将源码清单与完整工程下载分开：先读取私有文件清单，再逐文件下载到临时目录，校验大小、SHA-256 及下载前后的远端清单。已上传的 tools/node-22/node.exe 等超过 20 MB 的二进制文件也会完整拉取，不会被当成无需下载的文件过滤。
如果旧插件提示“文件超过单文件读取限制 20971520 bytes”，请更新 Microi吾码 VS Code 扩展后重新拉取；该限制属于旧插件的上下文读取方式，不是上传成功后的工程下载容量。已有 GetApplicationContext / GetApplicationFile 接口的服务端无需为本次修复重新部署。
下载失败、大小/哈希不符或期间其他开发者更新源码时，插件清理临时文件并停止应用，保留本地工程及同步基线。已有本地修改仍按三方差异检查处理，冲突合并后再推送；不得把“拉取成功”理解为允许覆盖他人更新。
### AI 应用默认前端架构
新建 Web、MicroService、H5，以及整体升级的存量 AI 应用，默认采用 Vue 3 单文件组件、Composition API、Vite 和 TypeScript。这里的 ESM 是浏览器模块标准，Vue 3 + Vite 本身仍以 ESM 组织源码，二者不是互斥选项。这个选择针对吾码生态：与 Microi.Client、Microi.UI 和团队既有 Vue 经验一致，方便升级、维护和二次开发；它不代表其它生态只能使用 Vue。
- 使用
```
微服务 CSS 即使当前使用 iframe，也必须能在非 iframe/sandbox 策略变化时安全运行：主题变量和通用控件规则挂在 AppKey 唯一根容器（例如 [data-mci-ui-root="your-app-key"]）下，不能只用会被宿主或其它应用共同命中的裸 [data-mci-ui-root]；禁止用 :root、html、body、裸 *、裸 button 改写宿主。背景网格等装饰层使用根容器内的 position:absolute，禁止 position:fixed; inset:0 覆盖吾码左侧菜单。宿主容器同时使用 paint containment 作为第二道边界，但不能替代子应用样式命名空间。
所有微服务必须即时跟随吾码主题色、明暗模式和界面密度。首次挂载、宿主数据更新及缓存页签重新显示时，读取 themeColor、themeMode、themeTokens 和 uiDensity，把 uiDensity.variables 写入本应用唯一根容器，并同步 data-mci-ui-density。iframe 不继承父页面 CSS，因此需要显式接收这些值。嵌入时以宿主快照为准，不用应用内旧个人设置覆盖宿主，也不通过重新挂载页面刷新主题，以免丢失未保存表单。
使用 --mci-ui-scale 和传入的字号、控件尺寸、间距变量调整表格、表单、按钮、页头及弹窗各区；禁止整页 zoom/transform:scale。浅色、深色及非默认主题色分别保持表面和文字可读，边角、关闭渐变及阴影等开关也从 themeTokens 应用到本页面。全局 CSS 文件改为带作用域导入或 AppKey 命名空间，避免商城等页面的通用类名污染个人中心。
玻璃材质由 themeTokens.material 标识，固定语义值包括 materialSurface/materialOverlay/materialControl/materialRowHover、materialText/materialTextSecondary/materialTextMuted、materialBorder/materialControlBorder/materialFocus、主操作按钮的 materialPrimaryBg/materialPrimaryHover/materialPrimaryText，以及原有模糊和饱和度。大面板只铺一层低透明表面，内部画布透明；静态边界保持细暗，活动控件及键盘焦点再加强，不能通过容器 opacity 淡化文字或图片。实色模式清除旧材质令牌，原生选项菜单等无法采样宿主背景的区域采用同调实色回退。
真正的独立 iframe 不继承父页面 CSS。吾码当前微应用 iframe 沙箱隔离脚本时，可见 DOM 会投影在宿主的 micro-app-body；宿主兼容样式必须限定精确 AppKey 根及其所属投影区域，也包含该区域内的弹窗，不把规则扩散到其他应用。子应用仍消费主题快照、保持自身样式隔离，不读取父 DOM、不传入任意 CSS 或壁纸地址，也不借主题消息改变用户偏好或权限。
加载骨架同样消费宿主主题：themeTokens.skeletonSurface/skeletonHeader/skeletonBase/skeletonHighlight 是固定安全语义字段。玻璃时保留骨架布局并使用半透明材质，实色时清空这些材质覆盖并沿原生骨架默认值；不能只适配 el-loading-mask 而漏掉微服务、模块或表单加载层的祖先白底。第三方独立文档未消费这些字段时，需要在其自身源码适配，宿主不会跨文档注入CSS。
交付前需在真实菜单和弹窗宿主中覆盖 90/100/110 密度、明暗切换、4K 与窄屏，测量输入框、按钮、表格行、页头和弹窗的实际尺寸，并确认未保存值及内部路由保留。仅独立预览或源码字符串检查不代表宿主验收通过。AI 开发此类页面前必须读取 microi.skills/microi-microservice/SKILL.md 的主题与密度契约。
菜单型微服务遵守“单一纵向滚动所有者”契约：外层宿主只负责可用区尺寸并隐藏自身溢出， 边界提供框架兜底滚动。普通长页面只需让内容自然增高，超出可用区时由框架显示一条滚动条；如果子应用需要内部 sticky 工具栏或虚拟列表，则把自己的滚动容器约束为 height: var(--micro-app-available-height)（或等价的确定高度）并设置 overflow-y:auto，此时内容不会再溢出 ，框架兜底条会自动消失，只保留子应用的一条。仅在自动高度元素上写 overflow:auto 不算真正的自适应滚动容器，也不会制造第二条滚动条。
自动化验收至少断言：点击微服务内部菜单时主框架 URL/Tab 不变、微服务左栏 DOM 不重建、骨架屏只出现在内容区；吾码左上角 Logo 可见，主菜单不出现来自子应用的网格线、按钮或主题样式；浏览器前进/后退能恢复子应用内部页面。
### 支持的宿主动作
action | data 示例 | 行为 |
closeTab | {} | 关闭当前吾码 Tab；不能关闭固定 Tab 或最后一个 Tab。 |
navigate | { path:'/mic-project', query:{ id:'01H...' } } | 打开或激活一个当前用户可访问的站内路由，原 Tab 保留。 |
replaceTab | { path:'/mic-project' } | 用目标站内路由替换当前 Tab，并移除旧 Tab。 |
back | {} | 返回吾码站内的上一个路由；没有站内历史时回到系统首页。 |
forward | {} | 前进到下一个吾码站内路由；没有可前进历史时不跳转。 |
reloadTab | {} | 重新解析入口并重载当前微服务；顶部 Tab 右键【刷新】也会重载微服务。 |
setTabTitle | { title:'成品打包完成' } | 修改当前 Tab 标题，最长 80 个字符。 |
showMessage | { message:'保存成功', messageType:'success' } | 使用吾码主框架消息提示；类型支持 success / warning / error / info，只接受纯文本。 |
openForm | { tableName:'Biz_Order', formMode:'Add', defaultValues:{} } | 打开标准表单；省略 sysMenuId 时继承当前微服务宿主冻结的菜单身份，显式值保持。跨表时传其真实菜单上下文，由后端验证表、菜单、动作和记录权限；不授予管理员权限。查看/编辑还须提供 id。 |
openPlatformPrint | { printId:'mic-print-id', dataApi:'https://api.example.com/apiengine/get-print-data?OsClient=tenant-a', title:'普通打印' } | 打开吾码 Print Engine 普通打印预览；不发送蓝牙原生命令。 |
微服务需要提供“普通打印”时，不要直接访问 window.parent 或复制平台打印弹窗。应先用 宿主下发的 apiBase/osClient 构造同源数据地址，再调用打印桥：
js
```
const host = window.microApp?.getData?.() || {};
const dataApi = new URL('/apiengine/get-print-data', host.apiBase);
dataApi.searchParams.set('OsClient', host.osClient);
dataApi.searchParams.set('Id', currentBusinessId);
const printRequestId = callMicroiHost('openPlatformPrint', {
printId: currentPrintTemplateId, // mic_print.Id
dataApi: dataApi.toString(),
title: '普通打印'
});
```
printId 只接受 1～128 位字母、数字、下划线或连字符。dataApi 必须是绝对 HTTP(S) 地址，和当前 apiBase 同源，路径以 /apiengine/ 开头，并明确携带与当前页面一致的 OsClient；禁止把 Token 或帐号密码写入 URL。宿主结果中的 accepted:true 只表示 Print Engine 预览已经打开，不代表浏览器已经打印或打印机已经出纸。
openPlatformPrint 是平台普通打印桥，不是 BLE/SPP 蓝牙代理。标签机原生命令与设备连接 继续遵守蓝牙打印机 (https://microi.net/doc/system-engine/bluetooth-printer.html)说明；独立运行时没有宿主能力， 应隐藏/禁用该按钮或使用应用自己的独立预览方案。
常用组合示例：
js
```
// 打开另一个吾码菜单，当前微服务 Tab 继续保留
callMicroiHost('navigate', {
path: '/mic-project-list',
query: { projectId: '01H...' }
});
// 把当前微服务 Tab 替换为订单详情
callMicroiHost('replaceTab', {
path: '/diy/form-page/order-table/01H...',
query: { SysMenuId: 'order-menu-id' }
});
callMicroiHost('back');
callMicroiHost('setTabTitle', { title: '成品打包 · HD26001' });
callMicroiHost('showMessage', { message: '保存成功', messageType: 'success' });
```
路由动作只接受以 / 开头的吾码站内地址，也接受 { name, params, query, hash } 路由对象；外部 URL、协议相对地址、反斜杠路径以及登录/访问密钥/内部重定向路由会被拒绝。目标路由仍须存在于当前登录用户加载后的路由表，并继续经过主框架路由守卫；该桥接不会扩大菜单或数据权限。
若提供 requestId，宿主会尽力通过 data listener 返回结果：
js
```
window.microApp?.addDataListener?.((payload) => {
if (payload?.type !== 'micro-app:host-action-result') return;
if (!payload.success) {
console.warn(payload.error?.code, payload.error?.message);
}
});
```
closeTab、navigate、replaceTab 会卸载或切换当前子应用，结果事件只能视为尽力通知，业务流程不能依赖它持久化数据。应先等待业务接口成功，再发出关闭或跳转动作。
hostCapabilities.mode=tab 只出现在菜单型微服务宿主。通过 V8.OpenAppDialog 打开的页面应继续使用下节的 app-dialog:success / app-dialog:cancel / app-dialog:error；不要在弹窗中调用 closeTab 代替关闭弹窗。
## 子应用向弹窗返回结果
js
```
// 成功：触发 OnSuccess 并关闭
window.microApp.dispatch({
type: 'app-dialog:success',
data: { taskId: '01H...', osClient: 'customer_a' }
});
// 取消：触发 OnCancel 并关闭
window.microApp.dispatch({
type: 'app-dialog:cancel',
data: { reason: 'user-cancel' }
});
// 失败：触发 OnError，弹窗保持打开
window.microApp.dispatch({
type: 'app-dialog:error',
data: { message: 'OsClient 已存在' }
});
```
同时兼容 success、cancel、error 简写类型。
## 构建产物访问与版本
当前公开体验使用无版本号的 API 固定入口：
text
```
{可信ApiBase}/micro-app/{tenantLower}/{AppKey}/index.html
```
例如，官方应用的入口为 https://api.microi.net/micro-app/itdos/{AppKey}/index.html。入口按当前已提交清单返回 HTML，GET/HEAD 不以顶层 30x 跳到 typed v3、CDN/NAS 或版本目录；页面加载完成后地址栏仍保留固定入口。清单中的资产可以独立分流，不要求它们全部留在 API origin。
需要显式查看历史版本时，读取该已发布版本实际返回的 CDN URL：
text
```
{可信FileServer}/{tenantLower}/micro-app/{AppKey}/{exactPublishedVersion}/index.html
```
例如，某已回读版本的 FileServer 为 https://file.microi.net、版本为 v1.0.3：
text
```
https://file.microi.net/itdos/micro-app/microi-official/v1.0.3/index.html
```
保留 FileServer 自有路径前缀，使用已回读版本的实际地址，不从数字 CurrentVersion 猜测语义 AppVersion。历史目录及其清单内文件验证后不可覆写成不同字节；对象缺失或摘要不符时报告该历史版本未恢复，不能换成当前文件冒充历史或回滚成功。
/micro-app/v3/tenants/.../kinds/runtime/apps/.../assets/... 是内部资产解析协议，原始 microi/application-assets/v3/... 是存储校验对象；两者都不作为用户的当前体验地址。旧的 /micro-app/{OsClient}/{AppKey}/{version}/... 短 API 和 ?version= 不能视为通用 V3 历史读取入口。用户明确选择的历史地址、签名地址与私有应用保持原访问语义，不转换成 current。
数据库中 v3 完成态的相对 PreviewUrl/PublicPublishPath 与 typed StableResolverPath 保持原协议值；官网、工作台和商城在展示层转换公开当前入口，不为统一链接批量改写应用、历史快照或安装记录。平台菜单的 /micro-app/{OsClient}/{MsKey}/{RoutePath} 仍是登录宿主导航，与上述独立 HTML 入口分开。
## 应用商城、离线包与跨 HDFS 安装
在线 AI 工作台可以直接制作离线包或发布到 sys_microistore。应用商城中两个容易混淆的字段是：
字段 | 说明 |
ApplicationType | 运行时应用类型：普通平台包兼容 Regular / Platform，独立应用使用 Web / UniApp / MicroService。新建普通离线包默认 Regular，既有商城平台应用和通知仍可能为 Platform。 |
Category | 游戏、企业应用、办公、教育、行业应用、平台能力等业务分类。 |
PublisherType | 官方应用或社区应用来源；仅作为搜索字段，不再拆分一级页签。 |
### 普通应用与平台启动包的存储边界
微服务应用包应包含：
- sys_microistore 应用信息。
- 私有源码文件及内容。
- 最新公有构建产物。
- sys_microiservice 运行时信息。
- sys_microiservice_page 页面路由。
- 包版本、来源租户和必要的基础元数据。
#### 普通应用
应用商城“配置应用包”中的“同时发布源码 ZIP”只控制私有源码是否随包交付；无论是否勾选，真正的离线包都必须包含可验证的最新运行产物。因此未携带源码的应用仍应可以运行和预览，只是不能在目标服务器继续在线开发。平台自有的打包接口必须自带时间格式化回退，不得依赖客户“系统设置”的全局 DateNow，更不能为了补函数覆盖客户维护的全局 V8。
普通应用安装到另一个租户时，平台不会直接引用发布者的 HDFS 地址，而是把私有源码和公有构建文件重新上传到安装者自己的 HDFS，再写入目标租户的运行时和路由。因此发布者使用 MinIO、安装者使用阿里云 OSS 或其他已支持存储时，也可以完成迁移。
声明“同时发布源码”的包若实际没有源码，生成或安装必须失败；目标租户写入私有 HDFS 后还要回读 mci_ai_app_file，不能返回“安装成功”后才在工作台显示无源码。原开发服务器已有可运行原生组件菜单时，重复制作或验证安装包不得把它改写成微服务菜单；目标端需要迁移的菜单才绑定 /micro-app/host，并把新 Url 写成包含当前租户和稳定 MsKey 的 /micro-app/{OsClient}/{MsKey}/{route}，显式旧地址继续保留。微服务友好路由优先使用 MsKey，后端同时兼容历史服务 Id 路由；前端把旧菜单 URL、MsKey 路由和 Id 路由绑定到同一宿主组件，这些地址可并存。
#### 仅共享编译运行产物
Web 应用若只交付公有运行产物，可显式采用 RuntimeAssetsOnly=true + IncludeSource=false。此模式只接受协议 v3 中已验证、 已提交的 SharedPublicRuntime；不复制构建文件，也不在目标租户安装业务表、 接口引擎或数据。它与普通包的“不包含源码”选项、平台启动包的 DatabaseOnlyBuild 分别处理，省略开关时保持原有行为。
请求和既有商城行的资源选择必须为空，不能用此模式静默抛弃上一版资源。 发布仍需先检查资源快照，再绑定同一摘要发布，最后下载实际包核验源码与资源均为零。 完整条件与 MCP 调用顺序见 应用商城：仅共享编译运行产物 (https://microi.net/doc/system-engine/app-store.html#%E4%BB%85%E5%85%B1%E4%BA%AB%E7%BC%96%E8%AF%91%E8%BF%90%E8%A1%8C%E4%BA%A7%E7%89%A9)。
#### 受信任的平台启动包
受信任的平台启动包可以显式采用 Source=NotIncluded + Build=DatabaseOnly + StorageMode=db。它只携带编译产物，最多 256 个文件、5MB，逐文件 Base64、大小和 SHA-256 必须回读一致；该模式可作为 microi-platform-service 一类小型内置能力的长期启动与恢复介质，不要求目标租户先具备 HDFS。它不是普通应用的容量替代品，也不能携带可编辑源码、私钥或租户秘密。
因此，若目标租户 HDFS 未配置、不可访问或上传失败，普通应用安装、源码同步、上传和文件预览应终止并显示明确错误，不能只写数据库记录后留下无法打开的页面；平台内置 DatabaseOnly 运行产物和通知中心恢复入口仍应可用。HDFS/CDN 若作为平台内置运行产物的镜像，只有逐文件回读并与同一 RuntimeManifestHash 一致后才可启用，失败时继续使用数据库权威产物。
离线交付流程：
text
```
AI 应用工作台“制作离线包”
→ 下载 .microi-app.json
→ 目标租户应用商城“安装离线包”
→ 后台任务重传 HDFS、安装运行时和页面
→ 绑定/检查菜单并验收
```
在线商城流程：
text
```
AI 应用工作台“发布应用商城”
→ sys_microistore.ApplicationType=MicroService
→ 目标租户应用商城安装
→ 下载官方应用包并重传到目标 HDFS
```
## 上线验收清单
- 已确认 sys_microistore.AppKey 与 sys_microiservice.MsKey 一致。
- 普通应用的源码在私有 HDFS、构建产物在公有 HDFS；受信任 DatabaseOnly 平台启动包明确记录为数据库运行产物且不携带源码。
- BuildVersion、EntryPath、AssetManifestJson 和构建文件清单完整。
- microi.routes.json 与 sys_microiservice_page 一致。
- 菜单绑定了正确的 MicroServiceId、MicroServicePageId 和路由。
- 表单嵌入场景中，字段 DevComponentPath 能匹配页面 LegacyComponentPaths；指定路由、自动高度、字段值回写以及 Add/Edit/View/只读模式均已验证。
- 目标端需要迁移的 LegacyMenuUrls/LegacyComponentPaths 菜单已绑定 /micro-app/host，且旧菜单 URL、稳定 MsKey 路由和历史服务 Id 路由均能打开同一页面；原开发服务器仍可运行的原生组件菜单保持不变。
- 真实主站 URL 不携带 Token，页面仍能调用需要登录的接口。
- Dialog 的成功、取消、失败回调都已测试。
- 同一微服务的多个菜单至少连续往返切换 8 轮，不出现 app name conflict、白屏、永久骨架屏或菜单内容串页。
- 缓存范围内返回旧 Tab 时，表单输入、筛选、内部路由和滚动位置保持；打开第 6 个菜单实例后，最久未使用的隐藏实例被淘汰且再次进入可正常冷启动。
- 关闭当前/其它/全部 Tab 以及退出登录后，对应微应用实例已销毁；恢复页签后 Token、OsClient、权限、主题和可用视口均为当前值。
- 目标分辨率下没有横向溢出、遮挡或右侧内容看不全。
- 普通应用在商城安装后使用目标租户自己的 HDFS 文件地址；DatabaseOnly 平台启动包使用同租户数据库稳定入口。
- 发布后的 active 文件清单与本地构建完全一致；旧 dist/ 元数据已可逆归档，Private、非 dist/ 及其它应用文件未受影响。
## 常见问题
### 带租户菜单提示微服务不存在
例如主站地址 /#/micro-app/loctek/microi-3d-engine/designer 应调用 MicroApp/Resolve，参数为 OsClient=loctek、AppKey=microi-3d-engine、RoutePath=/designer。若实际 AppKey 是 loctek、RoutePath 是 /microi-3d-engine/designer，说明宿主仍按旧格式拆分了新地址，应更新 PC 前端镜像并刷新浏览器缓存；已有双格式兼容的宿主无需批量改旧菜单。后端不根据 AppKey===OsClient 猜测和重写应用身份。
### 流式发布提示门禁表或索引缺失
mci_app_stream_gate_transition 和发布门禁相关列/索引由应用商城责任包维护。更新目标租户的应用商城责任包，通过已有“升级租户数据库”入口核验责任包安装，安装完成后回读物理表、列及唯一索引，再重新盘点源码、版本和发布基线。不要执行已退役 Upgrade25，也不要手动 reset 锁、fence、Storage 或 active/committed 指针。dry-run 不应切换运行版本；“旧运行版本未切换”还可能来自资产校验失败或真实 CAS 漂移，应按原始错误和回读结果分别处理。
### 历史安装应用持续产生对象存储下载
历史安装应用可能保持 PublishState=LegacyUnverified 和协议 2，同时已经具有可用的稳定入口。旧版后台别名巡检每 30 秒扫描候选，会重复下载版本目录与稳定入口中的完整文件校验哈希；模型、音视频等大文件较多时，即使没有用户打开应用，也可能产生大量服务端 OSS 公网流量。CDN 访问统计不能覆盖这类直接读取对象存储的费用，应结合存储访问日志中的 SDK、对象路径和周期核对。
包含持久检查点修复的后端，在受保护的 mci_ai_app_version.BuildLog 中记录独立的 InstalledAliasReconciliation/1 检查点。权威摘要绑定当前租户、应用、版本、运行服务和完整公开文件清单，排除检查点自身；元数据发生变化时，下次巡检立即重新校验。它保留 LegacyUnverified、协议 2 以及原有 V3 指针，不把历史别名校验记成一次正式 V3 发布。
当前结果 | 下次完整文件校验 |
第一次成功 | 5 分钟后 |
第二次连续稳定成功 | 30 分钟后 |
第三次及以后连续稳定成功 | 24 小时后 |
校验或复制失败 | 依次退避 5、10、20、40、60 分钟，之后保持 60 分钟 |
发生修复复制会重新累计稳定次数。每轮昂贵读取前先持久化 Verifying，使进程重启后仍遵守退避；数据库无法保存检查点时不开始全量下载。未知或不合法的非空 BuildLog 不接管、不覆盖。租约、主库完整回读和条件写入继续约束并发发布；检查点只更新所属版本的 BuildLog，不改变版本号或 UpdateTime。
排查时查看后台巡检回执的 VerifiedCheckpointSkipped、RetryBackoffSkipped 与 NextCheckAtUtc，并在等待窗口内确认同一文件的重复 GET 减少。正式验收仍需覆盖全部实际运行节点，核对后端已部署该修复、元数据变更后重新校验及失败后的恢复。源码修改、测试通过或镜像上传均不能单独证明线上流量已经下降。
### PublicPublishPath 没有租户前缀
先检查 sys_microiservice.StorageMode。microi-platform-service 等受信任平台启动包使用 StorageMode=db、MsUrl=db 从目标租户数据库内联产物运行，安装器可将 PublicPublishPath 保存为 micro-app/{AppKey}/{Version}；该值没有租户前缀不等于缺文件。不要直接补前缀或切换为 file。普通 file 应用应核对 AssetsJson/AssetManifestJson 内每项 HdfsPath/FilePathName、当前租户 FileServer 与实际对象，按正常重新安装或发布流程修复；单改商城展示字段不能证明运行入口恢复。
### 子租户发布提示 sys_osclients 门禁行数量必须为1，Actual=0
这是服务端应用发布门禁未读到有效配置的错误，不表示正常子租户必须使用主租户账号。服务器在线、管理员有效与发布能力就绪是不同状态，应同时查看 ApplicationAssetStreamGateReady 和原始错误。
租户登记的权威来源是 API 启动主租户的 SaaS 主控库。后端以当前子租户的 OsClient + OsClientType + OsClientNetwork 查询唯一启用且未删除的登记行；应用、私有源码、版本和公有编译文件仍属于子租户。旧后端错误地查询业务库同名表时，即使主控登记完整也会报 Actual=0。升级包含该修复的后端后，应在原子租户 MCP 回读状态，再使用最新发布基线重试；集群应统一更新节点，避免新旧代码使用不同配置源。
不要为此切换主租户 MCP、索要主租户账号或 SSH、复制业务库登记行、调用补登记接口或绕过门禁。EnsureOwnedTenantRuntimeRegistration 是独立的主控恢复操作，其权限要求不能作为子租户发布的前置条件。门禁列和审计结构缺失由平台核验主控库责任包；真正缺少子租户应用表时再升级目标租户应用商城。
新租户的主控登记使用 LegacyOpen / 2 / 0 默认值，不继承父租户的发布状态和代次。修复不重置已有门禁，也不改变发布权限；重复、禁用、软删除或坐标不匹配仍拒绝发布。源码同步或本地预览成功不能作为正式上线回执。
### 页面空白
先检查菜单动态路由是否带有 MicroAppUrl、MicroServiceRoutePath 等 meta，以及 ComponentPath 是否为 /micro-app/host。若首次进入正常、连续切换后无数据、永久骨架屏或白屏，而刷新恢复，应继续检查缓存所有权：Vue 外层宿主必须 keepAlive:false， 才能使用原生 keep-alive；不能同时缓存两层，也不能给不同顶部 Tab 复用同一个固定实例名。宿主还应在恢复时强制同步上下文并复核真实可见 DOM。若宿主把菜单 Id 当成 AppKey，通常是菜单绑定字段不完整。
控制台若只出现 chrome-extension://... Failed to fetch dynamically imported module，先用无扩展浏览器或无痕窗口复测；该地址属于浏览器扩展，不足以单独证明微服务产物加载失败。真正的微服务资源错误应能对应到 /micro-app/{OsClient}/{AppKey}/{BuildVersion}/... 或实际发布域名，并结合 Network 状态码、宿主诊断信息和可见 DOM 判断。
首次打开时，宿主分别检查资源下载和页面渲染：资源下载最多等待 60 秒，资源齐备后的 beforemount 才开始 12 秒渲染检查。下载超过 12 秒但仍在正常进行时，不会提前销毁微服务。下载停滞或脚本始终没有渲染内容时仍只自动重建一次，最终显示诊断信息；成功仍以真实可见内容为准。此修复需要更新 PC 框架镜像。
### 切回页签后状态丢失或出现双重生命周期
不要把菜单微服务的主框架 meta.keepAlive 改回 true。正确做法是保留 Vue 外层 keepAlive:false，由平台 单独保活，并让子应用监听 appstate-change。若第 6 个及之后的实例重新进入时冷启动，这是受控 LRU 淘汰，不是缓存失效；若 5 个以内也总是冷启动，则检查实例名是否随时间随机变化、入口 URL 是否被追加了每次不同的参数，以及子应用是否在 afterhidden 主动清空状态。
### 页面或静态资源 404
依次检查：
- sys_microiservice 是否存在且启用。
- BuildVersion 和 EntryPath 是否正确。
- AssetManifestJson 是否包含请求文件。
- 构建产物是否已上传到公有 HDFS。
- Vite 构建的资源基础路径是否适配 /micro-app/...。
协议 v3 还需检查当前租户 sys_config.FileServer（包含公有桶路径）及已提交版本的 ReleasePrefix / AssetManifestJson。CDN 文件返回 200、API 运行入口返回 404 时， 先确认 API 实际读取的是同一租户文件域名和对象路径；不要重复发布或切换到其它租户。 运行网关读取配置失败时应返回存储不可用，不再静默使用平台默认文件域名。
### MinIO 发布停在 CDN 历史版本对象读取，返回 HTTP 404
若不可变版本资产已全部校验，而发布状态为 RepairRequired / ProjectionPending，并提示“CDN 历史版本对象读取失败”，应区分首次复制时目标对象尚不存在与存储故障。只有提供商验证的明确缺对象结果，才允许从已校验版本补写目标对象。
存储提供商 | 允许补写所需的缺对象证据 |
MinIO / Amazon S3 | 实际签名 GET 返回 HTTP 404，且完整、不超过 8 KiB 的 S3 XML 中含精确 NoSuchKey；若提供 Key 或 BucketName，还必须匹配本次请求。 |
阿里云 OSS | 实际 OSS SDK 服务异常的 ErrorCode 精确等于 NoSuchKey。 |
HDFS 将已验证结果放入结构化 DataAppend.StorageReadErrorCode；MinIO/S3 同时给出 StorageReadHttpStatusCode=404。发布器不从诊断 Msg、对象路径或桶名中的文字推断缺对象；普通代理 404、NoSuchBucket、AccessDenied、错误 XML、超限、截断和超时仍失败关闭。错误正文不写入资产，签名 URL 不回显。
升级全部 API 节点后，保留原 RequestId、版本、清单哈希及首次 finalize 的前置条件，先回读状态，再原样重放该 finalize 请求恢复投影。不要手工修改发布状态、删除版本或重建同版本任务。
完成后应同时确认 Completed=true、投影不再待处理、运行服务与页面登记完整、稳定/版本入口及 JS/CSS 字节哈希一致，并在业务页面验证交互。文件上传成功或入口返回 200 仍不足以确认发布完成。
### HTTP/IP 私有部署提示“固定入口缺少 HTTPS 公有文件域名”
如果对象复制和签名回读已经通过，随后出现该提示，应检查当前租户的可信 FileServer 配置与 API 版本。自建 MinIO 的 HTTP/IP 地址不属于官方 CDN，不能被阿里云 CDN 刷新的 HTTPS 限制阻断。
公有文件地址 | CDN 刷新规则 |
主机名精确匹配 static.itdos.com（不区分大小写） | 必须使用 HTTPS；继续校验刷新资产与入口的主机、端口一致，并等待官方 CDN 刷新完成。 |
其它合法 HTTP/HTTPS 域名或 IP 地址 | 不适用官方阿里云 CDN 刷新；不请求其刷新凭据，也不提交刷新任务。 |
非绝对 HTTP(S) 地址，或带用户名密码、Query、Fragment | 拒绝发布，不能借“不适用刷新”接受无效地址。 |
地址只来自当前认证租户的可信文件配置与已校验发布路径，不接受请求方指定任意刷新目标。“不适用刷新”不表示已执行缓存清除，也不跳过对象投影、大小/SHA-256 回读、租户隔离和原任务完整性门禁。
更新全部 API 节点后，先回读原任务，再沿原 RequestId、版本、清单与首次 finalize 前置条件恢复；无需为此修改业务微服务源码或手工改成 HTTPS。完成仍须确认原任务完成、入口与资产哈希一致，以及页面真实可用。
### 入口文件存在，但提示 HTML 无效或脚本类型错误
文件内容正确仍可能被错误的 HTTP Content-Type 阻止加载。浏览器需要以下类型：
文件 | 正确响应类型 |
.html / .htm | text/html |
.js / .mjs | text/javascript |
.css | text/css |
.json / .map | application/json |
.wasm | application/wasm |
框架上传时统一设置 MinIO、S3、OSS 的对象类型，OSS 分片上传也在初始化时设置。 历史对象若返回 application/octet-stream，API 网关按已提交清单中的文件路径归一类型； HTML 仍须通过完整文档、大小和 SHA-256 校验，存储 XML 错误页继续拒绝，nosniff 保留。 明确不兼容的类型不会被当成合法页面。
此修复需要更新全部 API 节点。旧对象的 CDN 直接入口仍需通过存储管理修正类型， 或按正常发布流程生成新版本；API 网关兼容不会修改对象元数据或清除 CDN 缓存。 普通应用的 StorageMode=db 只作应急恢复，文件链路验收通过后恢复 file 模式。
### SDK 提示登录身份已过期
确认子应用使用宿主传入的运行时 Token，并执行 setToken(ctx.token) 或模板的 configureMicroiV8()。不要只读取子应用自身 localStorage，也不要把 Token 放到 URL。
### app name conflict
不要在子应用中自行注册固定的宿主实例名。吾码宿主会按页面/弹窗实例生成唯一 name；若使用自定义宿主，也必须让 name 包含菜单或实例维度。
### 后台选择微服务页面没有数据
检查 sys_microiservice_page 是否已有当前微服务的路由数据；重新推送项目可以按 microi.routes.json 同步页面。
### 表单定制组件提示“组件未找到”
依次检查：微服务及页面是否已发布并启用、字段 DevComponentPath 是否能与页面 LegacyComponentPaths 归一化后匹配、当前主前端是否存在同路径本地 Vue 组件，以及当前账号是否能读取目标微服务页面。若组件能打开但接口提示无权限，再核对宿主菜单的 ModuleEngineKey、DiyTableId 和角色授权。
### MCP 查询不到应用
先确认 MCP 连接的服务器、OsClient 和登录账号是否正确。若提示 Token 失效，应重新登录或刷新 MCP 会话；不要把鉴权失败误判为应用不存在。
### 在线修改后本地还是旧代码
每次修改已有微服务前，都要重新完整拉取当前租户的私有源码，与本地按路径、原始字节大小和 SHA-256 核对，再使用上次同步基线做三方合并。完整下载由 IDE/MCP 工具处理；microi_get_application_context 默认返回的元数据预览不代表源码已经完整下载。
记录编辑前的 SourceManifestHash，同步源码时传 expectedSourceManifestHash。缺失或过期的编辑基线会在上传前被拒绝，不能只获取新哈希来重试旧代码；远端变化时必须重新合并并构建。已有源码的覆盖同步要求服务端支持原子源码 CAS。
路由更新必须同时保留其它页面、实际组件注册以及 LegacyComponentPaths/LegacyMenuUrls。旧协议更新空 RouteMetaJson 时保留现有兼容别名；V3 发布快照遗漏现有启用路由或兼容别名时拒绝切换，返回 MICROSERVICE_ROUTE_BASELINE_LOST。明确停用页面请保留路由并设置 IsEnable=0。
在线源码和本地目录是两个工作副本。在线修改后可下载源码 ZIP，再与本地 Git 工作区合并；本地修改后执行 同步微服务源码到在线 AI 应用。多人同时编辑前应先约定主工作副本，避免互相覆盖。
### 商城安装时 HDFS 失败
检查目标租户的 HDFS 类型、Endpoint、Bucket、访问密钥、私有/公有桶权限和网络连通性。普通应用安装过程必须能按包策略写入私有源码和公有构建产物；不要因为平台内置 DatabaseOnly 页面可以打开，就把对象存储检查误判为通过。反过来，HDFS 故障也不应让 microi-platform-service、应用商城页面和通知中心恢复入口一起失效。
### 本地商城源被安全策略拦截
服务端可能把访问 localhost、内网 IP 的远程商城源识别为 SSRF 风险。开发环境应通过受控配置明确允许可信地址，生产环境不要为了测试直接关闭全局 SSRF 防护。