渠道与白标

同一套代码可以交付成多个渠道（channel）。渠道决定这一份安装包”叫什么、长什么样、从哪里升级”，且渠道之间互不升级 —— 这是正确性要求，不是配置项。

三类渠道

渠道	用途	分发面
`official`	正式发布	更新服务器 `release.picoaide.com/official/` + GitHub Release（完整历史归档）
`beta`	预发布（含 `-beta` / `-rc` / `-alpha` 的版本 tag）	更新服务器 `release.picoaide.com/beta/` + GitHub Pre-release
`<brand-id>`	企业定制 / 白标交付	只经更新服务器 `release.picoaide.com/<brand-id>/`（不进公开 Release 与构建产物）

每个渠道在更新服务器上有独立目录，结构与官方完全同构：

<渠道>/latest.json
<渠道>/releases/<版本>/picoaide-server-<版本>-amd64.zip
<渠道>/releases/<版本>/SHA256SUMS

渠道内容随镜像走

渠道不是运行时上传的配置，而是构建期注入并固化在镜像里：

镜像构建 --build-arg CHANNEL=<渠道>
        ├─ ENV PICOAI_CHANNEL=<渠道>        ← 运行期渠道身份
        ├─ /opt/picoaide/CHANNEL            ← 权威声明文件
        └─ /opt/picoaide/channel/           ← 渠道内容（名称 / 文案 / 标识 / 主题色）

渠道内容包含：

类别	内容
标识	显示名、短名（侧边栏）、标题、标语
文案	登录页与客户端欢迎语、门户欢迎语
素材	亮/暗两套 logo、favicon、主题色
客户端	深链 scheme（浏览器 SSO 回调）、应用源 scheme（`desktop.app_origin_scheme`，WASM 应用 origin，全部渠道必填）、数据根目录、内置服务端地址、安装包名与应用 ID

desktop.app_origin_scheme 是 2026-09-19 新增的必填字段（含 official / beta；官方与预发渠道取值 = picoaide-app）：它决定 WASM 应用在客户端里的 origin （<scheme>://<app_id>）。缺字段 / 非法 / 与深链 scheme 同值 / 跨渠道重复 ⇒ 构建期 CI 中止，该渠道本次没有产物（不会静默回落）。加字段请先在渠道仓改好并 push 再打 tag （CI 从渠道仓 origin/main 拉取）。字段规则与后果见渠道包字段参考 §4.4b。

这些内容同时作用于客户端登录页、客户端界面、管理后台侧栏与门户页 —— 一处配置，全产品一致。在服务端不可达或服务端版本较旧时，客户端使用随包副本展示品牌，不会回落到厂商标识。

发布矩阵（哪些 tag 产出哪些渠道）

触发	构建的渠道	说明
预发 tag（`vX.Y.Z-beta.N` / `-rc` / `-alpha`，含连字符）	只构建 `beta`	品牌渠道的客户端不会在预发 tag 产出；要提前出包只能用 `workflow_dispatch`
正式 tag（纯 `vX.Y.Z`）	全部渠道（official + beta + 各品牌渠道）	品牌渠道的镜像与安装包只出现在该渠道自己的更新目录
非 tag（PR / 分支推送）	只构建 `official`	用于门禁与冒烟，不作为交付物

⇒ 给品牌渠道加/改字段（如 app_origin_scheme）时：必须在渠道仓改好并 push，然后等 正式 tag（预发 tag 不会为品牌渠道出包）；否则客户拿到的仍是旧行为的包。

部署侧要保证的三个值自洽

值	由谁决定	说明
本部署的渠道	镜像自带（`/opt/picoaide/CHANNEL`）	`.env` 的 `PICOAI_CHANNEL` 留空即可；填了必须与镜像一致
更新清单地址	`PICOAI_UPDATE_ENDPOINT`，留空 = 本渠道默认目录	留空不等于关闭；关闭请显式写 `off`
清单里的 `channel_id`	更新服务器上对应目录的 `latest.json`	必须与本部署渠道相同

服务端在启动与检查更新时会强制校验：

PICOAI_CHANNEL 非法 → 拒绝启动（不会回落到 official：回落会让定制部署接受官方清单、把品牌”洗掉”）；
镜像内渠道与进程渠道不一致（典型成因：.env/compose 覆盖了镜像声明）→ 拒绝启动；
清单 channel_id 与本部署不一致 → 判为”检查更新不可用”，而不是”没有新版本”，让人看见并修，绝不静默跨渠道升级。

从旧版本升级过来的部署注意：compose 的默认值不再写死渠道。如果 .env 里手工留着 PICOAI_CHANNEL=official，定制渠道部署会被判为不一致 —— 删掉这一行即可。

排障

现象	原因
一直不显示”发现新版本”	渠道三值不一致（最常见：改了 `PICOAI_CHANNEL` 却没改端点，或反之）；`docker compose logs server` 会打印 `manifest channel "official" != this server's channel "…"`；也可能 `PICOAI_UPDATE_ENDPOINT` 被显式设成了 `off`
容器启动即退出，打印”渠道配置非法”	`PICOAI_CHANNEL`（或镜像内渠道标记）不是合法渠道 id；修拼写或删掉覆盖
容器启动即退出，打印”渠道不一致”	`.env`/compose 覆盖的渠道与镜像内容不同；删掉覆盖或改成与镜像一致
升级后品牌没了	正常路径下不应发生（启动两道校验 + 清单渠道比对）。若发生，说明有人手工指定了错误镜像/清单：立即停止升级并排查

客户端数据隔离（渠道可共存）

渠道化客户端的配置、会话、连接器凭据与浏览器数据存放在各自的数据目录中，不同渠道的客户端可以装在同一台机器上而互不影响（官方渠道保持原有目录与行为不变）：

官方渠道：~/.picoaide-harness；
定制渠道：按渠道派生的独立目录（不会与官方目录混用）；
应用的用户数据目录与 Windows 应用标识同样按渠道区分，避免两个客户端互相顶掉单实例锁。

浏览器 SSO 回调使用渠道自己的深链 scheme，登录回调不会串到另一个渠道的客户端。

客户端升级与渠道的关系

员工客户端不需要知道自己属于哪个渠道：它只问”我登录的那台服务端”，而服务端的渠道由它自己的镜像在结构上决定。因此不存在”客户端渠道与服务端渠道不一致”的状态，也不存在跨渠道被升级洗牌的可能。

企业定制的安装包由服务端门户直接下发（见客户端分发与升级），员工机器全程不需要外网。