创建版本并纳入 Bundle

示例的来源版本 ID 12345 和资源版本 0.3.0 必须替换为有权读取的准确不可变目录记录。以下 Resource Locator 中的 source-environment 是来源环境占位符；使用前从资源目录取得完整 Locator，保持来源环境、Bundle、资源类型和资源键一致，不根据名称猜测。

平台应用定义、不可变版本和 Bundle 版本是不同对象。平台应用先创建自己的不可变版本，再由 Bundle 锁定并组合交付。

平台自动托管，无需自行部署静态站点

开发者提交源码、创建平台应用版本，再通过 Bundle 安装或升级交付。平台负责构建产物的托管部署、生成实际入口和提供同源环境配置。不需要执行 site create、site deployment create，也不需要手工上传静态文件、配置域名、网关或授权地址。 “自动托管”省去的是单独的站点部署；应用版本创建和 Bundle 安装或升级仍须完成。

创建平台应用时已经确定唯一归属 Bundle。创建应用版本不会修改 Bundle 清单；其他 Bundle 不能把该应用列为自己的资源，跨包协作使用明确的资源引用与配置。创建版本成功即已不可变，没有第二次“发布”或“冻结”操作。

创建应用版本时，服务端根据归属 Bundle 读取一次数据库定义快照，以实际定义修订编译已选择的领域引用，结果随应用版本保存。CLI 不查询或提交 Bundle 源码提交 ID；已有版本不会因当前 Bundle 定义变化而重新编译。应用自己的源码仍使用其专属项目和准确 Git 提交。

创建版本与安装链路

本文完整流程面向 ENVIRONMENT_HOSTED_APP。普通外链不进入前端构建和平台授权链路。

Platform Application
  -> Platform Application Version
  -> Bundle Manifest
  -> Immutable Bundle Version
  -> Workspace Bundle Install
  -> Platform-managed Hosting + Same-origin Configuration
  -> 物化精确应用资源与来源凭据

所有平台应用版本创建都必须传入完整 --git-commit-id。环境托管应用先按前端版本固定 Git 标签并完成构建，再传入 --artifact-id 创建应用版本；服务核对制品与指定提交一致。使用 CLI 0.131.0 或更新版本。非托管入口不传 --artifact-id，误传会被拒绝。 --git-commit-id 仍可用于普通外链等非环境托管配置版本创建，但不能恢复历史 TRUSTED_EXTERNAL_APP 的启动和平台授权。执行前逐级读取目标子命令的 --help。

通过 Bundle Service 的平台应用作者入口创建定义和专属项目，项目类型由平台目录选择：

baijimu bundle resource platform-application create \
  --workspace-id <workspaceId> \
  --bundle-id <bundleId> \
  --platform-app-id <platformAppId> \
  --name <name>

平台应用项目的模板归档和 baijimu.platform-application.json 初始内容属于 PLATFORM_APPLICATION 项目类型目录，不由创建命令指定。

项目初始化后会包含 baijimu.platform-application.json。入口、配置 Schema、Manifest 和可选的业务页面声明都在这个文件中维护；字段是原生 JSON 对象或数组，不是再次编码的 JSON 字符串。

环境托管前端使用 ENVIRONMENT_HOSTED_APP，入口为版本内相对根路径，例如 /index.html。源码须先提交到项目主线，再用 project build create --version <frontendVersion> 发布前端。平台创建或复用不可变 Git 标签 v<frontendVersion> 并固定提交；成功结果返回精确 artifactId 与完整提交。应用的 --version 是不可变应用版本号，前端发布版本和应用版本分别管理。

配置环境托管前端

新开发的 React/Vite 平台应用使用作者配置 7.3.0。只有提供渠道管理入口时才需要 channelManagement。应用清单不声明 targets 或方法名单。示例中的 /index.html 指向版本构建产物内的入口。

{
  "schemaVersion": "7.3.0",
  "entry": {
    "urlTemplate": "/index.html",
    "type": "ENVIRONMENT_HOSTED_APP",
    "openMode": "WORKSPACE_TAB"
  },
  "pages": []
}

不要把通用宿主地址当成内置页面

PLATFORM_ROUTE 只适用于平台管理端源码已经注册并随平台发布的真实内置路由。不得把 /workspace/{workspaceId}/platform-app/{platformAppId} 作为 Bundle 应用的默认入口；该地址是平台应用宿主的通用承载路由，不会自动把项目中的 React 页面注册成内置页面。

入口不能包含外部域名、查询串、hash 或 {installId}；平台负责生成实际 accessUrl 并追加安装标识。

前端使用标准 SDK 的 createPlatformApplicationClientFromHostedConfiguration() 初始化，从同源 /.well-known/baijimu-platform-application.json 读取当前环境配置。应用归档不能覆盖该文件，也不能把授权地址、API 域名或发布目录固化进源码。见 Web 接入与运行态调用。

构建资源与路由

新创建的应用版本使用 SDK 10.2.0，在每个精确应用版本独立的 HTTPS origin 根路径运行。Vite 使用默认根路径，或在 vite.config.ts 中显式设置：

export default defineConfig({
  base: "/",
  // 其他 Vite 配置
});

标准构建动作使用 pnpm run build。JavaScript、CSS 和公共资源可以引用根路径 /assets/...，无需拼接发布目录。平台仍保存不可变应用版本，并通过 Bundle 安装或升级交付；根路径托管保留不可变版本及安装、升级流程。

新建 SPA 模板默认使用 BrowserRouter，无需配置版本目录 basename；平台站点为前端路由提供根 index.html 回退。开发者可以改用 HashRouter，对外页面链接随之使用 /#/...。安装后应通过实际 accessUrl 验证首页，并直接刷新一个深层路由，确认业务页面正常。还应验证普通 href 页面直达，包括未登录时授权后返回同一页面。只检查 index.html 和静态资源返回 200 不足以完成验证。

已有部署继续使用原配置和入口。历史 SDK 6 归档首次安装到新环境前，必须升级 SDK、重新构建并创建新应用版本；不能把旧归档直接搬到根路径，也不增加应用实体的托管模式字段。

当前入口与历史类型迁移的完整规则见入口类型与应用清单。

应用创建结果已经包含唯一绑定的项目 ID，不再重复创建应用或另行绑定同一个项目。

提交项目文件后，环境托管应用先按前端构建发布指定前端发布版本并等待构建成功，再用结果中的完整提交和制品 ID 创建应用版本：

baijimu workspace project build create <projectId> \
  --workspace-id <workspaceId> \
  --version <frontendVersion>

前端发布成功后，核对结果的 releaseVersion、完整提交和 artifactId，再创建应用版本：

baijimu bundle resource platform-application version create <platformAppId> \
  --workspace-id <workspaceId> \
  --project-id <projectId> \
  --bundle-id <bundleId> \
  --version <semanticVersion> \
  --git-commit-id <fullCommitId> \
  --artifact-id <artifactId>

数据库 Bundle 无需源码项目。创建应用版本前，先把它引用的资源精确版本写入归属 Bundle 的当前定义；服务端使用同一次数据库快照和定义修订解析引用。应用版本创建不会自动把自己加入 Bundle 的资源选择。

版本创建接收应用源码 sourceGitCommitId（CLI 的 --git-commit-id），托管应用还必须指定 artifactId；不接收 bundleSourceGitCommitId。服务端读取并解析所属 Bundle 的数据库定义及其实际修订。无需向应用版本创建请求传入 Bundle Git 提交或伪造提交值；应用自己的 --git-commit-id 仍必填。Git Bundle 作者入口已退役；当前 Bundle 引用解析使用数据库定义，历史不可变内容保持原样。

CLI 不会隐式构建或读取 HEAD。环境托管应用缺少制品 ID、制品不属于同一工作区和项目、状态不是 READY、生产者或类型不符、提交与 --git-commit-id 不一致时，创建失败。服务不查询最新制品，不按应用版本反查制品。外链配置同样要求完整提交，但不要求前端构建；历史可信外部应用仍不能启动或取得平台 token。

平台应用服务校验显式传入的项目 ID 必须属于同一工作区且类型为 PLATFORM_APPLICATION，并要求它与平台应用主记录中的 sourceProjectId 一致，再从显式提交读取配置文件，并对环境托管应用核对精确 Artifact 的身份与提交。每个平台应用使用一对一绑定的专属项目；平台应用不能在创建或首次采用来源项目后改绑。CLI 0.15.0 起不再接收 methodDefinitionsJson，也不需要 @file 把 JSON 作为命令参数传输。@file 仍可用于其他明确声明接受“JSON 或 @文件”的命令，但不是平台应用版本内容协议。创建成功只会生成新的不可变版本，不会修改已有版本。

迁移历史外部应用

当前 App Gateway 拒绝 TRUSTED_EXTERNAL_APP 启动和平台授权。即使定义或版本创建成功，也不能据此判断应用可用。历史 STATIC_SPA 站点没有同源配置入口，并不表示平台缺少环境托管能力。迁移目标是让平台托管新应用版本，不需要为旧站点补配置入口；旧站点地址也不会自动成为新版本的入口。迁移必须完成整个交付链：

将前端源码放入该应用专属的 PLATFORM_APPLICATION 项目。新建应用由 bundle resource platform-application create 同时创建专属项目。历史应用若缺少合法来源项目，应由应用 Owner 核实迁移路径，不能调用已退役的项目绑定命令。
把入口改为 ENVIRONMENT_HOSTED_APP 和 /index.html，移除外部地址与 {installId} 模板。将作者配置改为 7.3.0，保留业务需要的配置，采用 SDK 10.2.0 的模块对象调用并移除新版本的 targets。外部能力通过本包 Module 属性绑定，同时删除旧 Bundle 依赖声明。
升级标准 SDK，改为同源配置初始化；删除自实现的 PKCE、token 存储和手工部署地址，保证相对资源路径和 SPA 路由可迁移。
提交主线，用 project build create --version 固定前端发布版本并等待成功，再传入结果中的 --git-commit-id 和 --artifact-id 创建应用版本。
用新的 Bundle 版本锁定平台应用版本，升级目标安装，从实际入口验证授权和业务能力。

只创建前端版本、只改入口类型或只升级 SDK 都不能替代完整迁移。原外部站点若继续独立运营，应使用自己的后台授权；工作区中不需要平台能力的普通链接可以使用 EXTERNAL_URL。

纳入 Bundle 并安装

应用版本创建后，按定义编辑流程读取数据库当前定义及修订，在根级 resources 中选择 Owner 返回的 platformAppId（作为 resourceKey）、resourceType: PLATFORM_APPLICATION 和精确应用版本。保留其他资源、属性及配置，按 expectedRevision 提交完整定义，再以返回的新修订创建 Bundle 版本。应用名称不能代替稳定资源键；前端源码及应用版本继续使用自己的 Git 提交，Bundle 不需要 Git 项目。

创建 Bundle 版本后，通过 Bundle 安装或升级操作物化平台应用。不要绕过 Bundle 另造一条安装记录来模拟产品交付。

安装或升级前预览所选 Bundle 的精确版本与资源计划。计划不包含其他 Bundle 的安装任务、兼容性范围告警或自动降级。外部提供方缺失不阻止平台应用定义与前端安装。

新应用直接调用同包 Module，无需目标清单、映射或方法授权。安装交付应用资源凭据，调用时读取 RCS 当前入口；Runtime 负责方法合同与用户权限。目标缺失、凭据撤销或权限拒绝保持明确失败。

安装或升级交付精确应用资源与来源凭据，无需另行执行应用绑定命令。用当前 CLI 查询 Owner 实际应用与访问入口：

baijimu bundle resource platform-application workspace list --workspace-id <workspaceId>
baijimu runtime bundle resource launch-context <applicationResourceLocator> \
  --workspace-id <workspaceId>

applicationResourceLocator 使用工作区应用列表返回的完整定位符。读取结果不创建安装或补签凭据；现存应用若凭据缺失或已撤销，应按 platform-app reauthorize --help 使用显式重新授权流程，不能靠普通升级恢复。

验证清单

安装或升级后至少确认：

平台应用版本已经创建且内容不可变。
版本记录的 sourceProjectId 和 sourceGitCommitId 与所选 Artifact 的提交一致。
Bundle 版本内容引用的是同一个平台应用版本。
工作区应用目录从 Runtime Owner 返回实际应用及精确资源版本。
平台应用安装记录的 installId 保持稳定，版本已经更新。
accessUrl 指向当前环境托管的实际版本入口，已追加真实 installId，且不包含 token。
根路径中的 HTML、JavaScript、CSS 和公共资源都返回 200；直接刷新 SPA 深层路由仍显示正确页面。
同源环境配置可读取，配置 contractVersion 为 2.0.0，applicationOrigin 与当前页面一致且不含 releasePath；打开入口会校验工作区成员和当前精确应用资源，再进入 PKCE 授权链路。
回跳只携带一次性 code，并能成功兑换 token。
已声明能力可调用，未声明能力被拒绝。
分享 Manager 的 /bundle-app/{bundleId}/{platformAppId} 入口时，未安装工作区会提示安装整个 Bundle，安装成功后返回并打开应用。
新应用没有 targets 也能完成首次来源凭据交付；真实调用验证同包范围、用户权限和撤销拒绝。已有应用的凭据缺失或撤销不会因普通升级被自动恢复。

创建应用版本后还需更新和升级 Bundle

只创建平台应用新版本不会改变 Bundle，也不会升级已安装产品。必须更新 Bundle Manifest、创建新 Bundle 版本并升级目标安装。

选择专用 Runtime

使用工作区默认 Runtime 时可省略 --application-runtime-id。安装到专用 Runtime 时，Bundle 安装、 platform-app workspace list 和 platform-app workspace launch-context 均传入同一个明确的 Runtime ID。从该 Runtime 的应用列表选择完整资源定位符，不要切换工作区默认 Runtime 来替代选择。

管理员维护发布

管理员使用 baijimu-back 0.34.0 或更新版本的 bundle maintenance platform-app publish，托管应用同样传入 --artifact-id、完整 --git-commit-id 和维护原因。管理员入口不绕过制品归属、提交和完整性校验；非托管入口不传制品。Module 维护发布不接受该参数。

创建版本并纳入 Bundle

本页内容