CodePlanet 在线更新站部署规范

> 适用基址：https://www.conbos.cn/CodePlanetr/Update/ > Manifest Schema：[docs/schemas/update-manifest-v1.schema.json](../schemas/update-manifest-v1.schema.json) > 验签实现：UpdateManifestVerifier（RSA-SHA256 + canonical JSON） > 公钥：仓库 resources/config/update.pub → 安装包内 {InstallRoot}/config/update.pub > R3 客户端行为：Launcher 拉取 manifest → 验签 → Apply 或 Skip；Apply 流程含 SHA256、staging、ProjectValidator、保留 logs/；验签/Apply 失败 不阻断 本地旧版启动（T31）。

---

1. 重要区分：更新站 ≠ 整个 bin/ 目录

不要把开发机整个 bin/ 文件夹原样上传到 conbos。 更新站只发布 manifest 中 zipUrl / setupUrl / plugins[].path 所指向的文件。

---

2. 在线目录结构（规范）

https://www.conbos.cn/CodePlanetr/Update/
├── manifest.json                          # 必需；RSA 签名索引
├── projects/                              # 项目包（T13 / T37）
│   └── {name}/
│       └── {name}-{version}.zip           # 例：demo/demo-1.0.0.zip
├── runtime/                               # 可选：Runtime 组件升级
│   └── CodeRuntimeSetup-{version}.exe
├── launcher/                              # 可选：Launcher 组件升级
│   └── CodePlanetrSetup-{version}.exe
└── editor/                                # 可选：Editor 组件升级
    └── CodeEditorSetup-{version}.exe

本仓库 NSIS 产物（发布根 dist/CodePlanet/，与 manifest setupUrl 对齐）：

构建：powershell -File scripts\build_nsis_packages.ps1（需 D:\NSIS\makensis.exe；先 deploy_staging.ps1 -Config Release）。

可选扩展（manifest 中 plugins[].path 为相对 URL 时）：

├── plugins/
│   └── BuiltinFunctions-{version}.dll

URL 规则：

• Launcher 固定请求：https://www.conbos.cn/CodePlanetr/Update/manifest.json
• manifest 内 projects[].zipUrl、runtime.setupUrl 为 相对 manifest 所在目录 的路径（正斜杠 /）
• 示例："zipUrl": "projects/demo/demo-1.0.0.zip" →

https://www.conbos.cn/CodePlanetr/Update/projects/demo/demo-1.0.0.zip

---

3. manifest.json 字段要求

3.1 必需顶层字段

3.2 runtime 对象

3.3 launcher / editor 对象（R3 扩展，可选）

与 runtime 相同字段：minVersion、setupUrl、setupSha256。示例：

• "setupUrl": "launcher/CodePlanetrSetup-1.5.1.exe"
• "setupUrl": "editor/CodeEditorSetup-1.5.1.exe"

Launcher 在 Apply 成功或跳过项目更新后，对低于 manifest 版本的组件 非阻断 提示运行对应 setup（不阻断 Launch）。

3.4 plugins[] 元素

> R1.5 Launcher 仅做 manifest 验签与 Warning；插件 DLL 在线替换 Apply 留 R3。

3.5 projects[] 元素

3.6 样例

见仓库：

• [examples/update/manifest.sample.json](../../examples/update/manifest.sample.json)（占位签名）
• [examples/update/manifest.bad-signature.json](../../examples/update/manifest.bad-signature.json)（验签失败测试）

---

4. 签名与 canonical JSON（必须一致）

签名步骤（运维/发布脚本须与客户端相同）：

1. 从 manifest 移除 signature 字段 2. 按 固定字段顺序 生成 compact UTF-8 JSON（无多余空白）：

• 顶层：schemaVersion → publishedAt → runtime → launcher（若有）→ editor（若有）→ plugins → projects
• runtime / launcher / editor 内：minVersion → setupUrl → setupSha256
• plugins[] 每项：id → minVersion → path
• projects[] 每项：name → version → zipUrl → zipSha256

3. 对 canonical 字节做 SHA-256 4. RSA PKCS#1 v1.5 私钥签名 → Base64 写入 signature

客户端公钥路径（已安装机器）：

1. {InstallRoot}/config/update.pub 2. 回退：resources/config/update.pub（开发仓库）

---

5. 项目 zip 包规范（projects/{name}/{name}-{version}.zip）

5.1 命名

5.2 zip 内容（解压目标 = USER/projects/{folder}/）

zip 根目录 应直接包含项目文件夹内容（不要多包一层无意义父目录）：

demo-1.0.0.zip
├── demo.yslib
├── scripts/
│   └── …
├── assets/          # 若有
└── logs/            # 可选；覆盖安装时客户端须保留已有 logs/（R3 Apply）

打包来源（开发机）：

# 示例：从仓库 USER 或 examples 种子打包
cd E:\HuaweiMoveData\Users\MateBookXPro\Desktop\CodePlanetr\USER\projects\demoV1.0
# 选中 demo.yslib、scripts 等，压缩为 demo-1.0.0.zip（根即为项目文件）

5.3 SHA256

Get-FileHash -Algorithm SHA256 .\demo-1.0.0.zip
# 将 Hash 小写 hex 写入 manifest projects[].zipSha256

---

6. 产线安装包与 bin/ 的对应关系（客户机，非更新站）

客户机 首次安装 时，由安装程序或运维脚本部署 完整运行时（可参考 scripts/deploy_staging.ps1 产出）：

{InstallRoot}/                    # 例：C:\Program Files\CodePlanet\
├── CodePlanetr.exe               # 产线入口
├── CodeRuntime.exe               # R2 交付（R1.5 可暂缺）
├── CodeEditor.exe                # Ops（维护用，产线可选）
├── Qt5*.dll / platforms/ …       # windeployqt 产物
├── plugins/
│   └── BuiltinFunctions.dll
├── config/
│   ├── FunctionLib.ini
│   └── update.pub                  # 验签公钥（与 manifest 私钥配对）
├── translations/
│   └── codeplanet_en.qm
└── USER/                           # 用户项目与偏好（可随安装包带 demo 种子）
    └── projects/
        └── demo/
            └── demo.yslib

从开发 bin/ 到安装包的映射：

在线更新站不上传上述 exe/DLL 全量（除非未来 manifest 扩展整包 setupUrl 指向 runtime/CodePlanetSetup-x.exe）。

---

7. 服务端技术要求

---

8. Launcher 能力分界（R1.5 / R3）

---

9. 发布检查清单（运维）

• [ ] 生成项目 zip，计算 zipSha256
• [ ] 编写 manifest（无 signature）
• [ ] 按 §4 生成 canonical JSON 并 RSA 签名
• [ ] 上传 manifest.json 到 /CodePlanetr/Update/
• [ ] 上传 zip 到 manifest 中 zipUrl 对应路径
• [ ] 浏览器/curl 可访问 manifest 与 zip URL
• [ ] R3 Apply 后：按 [R3-更新Apply与E2E测试计划.md](../AST审计执行报告/R3-更新Apply与E2E测试计划.md) 执行 T-UPD 系列

---

10. 参考

• [docs/附录-路径与日志约定.md](../附录-路径与日志约定.md)
• [docs/AST审计执行报告/R3-更新Apply与E2E测试计划.md](../AST审计执行报告/R3-更新Apply与E2E测试计划.md)（R3 Apply 后统一回归）
• [docs/项目目标与架构终点.md](../项目目标与架构终点.md) §3.5