部署者指南：索引源与治理

这一页面向部署者 / 管理员：怎么配置源、怎么排查、以及私有化部署的建议。

配置入口

管理面板 →「小程序」页签。可以看到：

• 已合并的小程序数量、累计安装次数；
• 源列表（名称、地址、优先级、启用开关、是否官方）；
• 「各源状态」：每个源这次加载是否成功、拿到几个小程序、耗时、失败原因。

增删源

操作	说明
添加源	填名称 + 索引地址（https://… 或站内相对路径）+ 优先级，默认启用
启用 / 停用	停用的源不参与合并，但状态仍会显示
优先级	数字越小越优先；官方源始终排在最前
删除	只有非官方源能删；官方源不能删（可以停用）
保存 / 保存并刷新	「保存并刷新」会立刻回源重新拉取

配置存在整站配置（app_config.mini_sources）里，最多 20 条。

官方源

默认官方源：

https://raw.githubusercontent.com/CircleChat-Team/CircleChat-MiniProgram/main/index.json

它是只读参考值：管理面板里改过源配置之后，就以你自己的配置为准（包括把官方源停用或换地址）。

为什么 raw 链接能用

索引是 JSON，平台用 fetch 拉回来再 JSON.parse，与 Content-Type 无关。 但小程序页面不能直接用 raw 链接当 iframe 地址——raw 把 .html 也发成 text/plain，浏览器不渲染。 CircleChat 的做法是：把页面文本取回来，用 srcdoc 渲染，并注入平台自己的 SDK。

加载时机与缓存

• 启动预热：服务启动时合并加载一次（Nitro 插件），日志里会打印 [mini] 索引已加载：N 个小程序，M 个源；
• 内存缓存 30 分钟：期间打开商店不会重复回源；
• 手动刷新：管理面板「保存并刷新」立即回源。

排查

现象	排查方向
商店里一个都没有	看「各源状态」里的错误：多为超时、404、JSON 解析失败
源状态报 UNABLE_TO_VERIFY_LEAF_SIGNATURE	服务器不信任对端证书链（常见于内网 MITM 代理）。给 Node 加 --use-system-ca 或配置 NODE_EXTRA_CA_CERTS
索引里少了几条	单条 manifest 校验失败会被跳过：检查 id 是否合法、entry 是否 http(s) 或站内路径、name/entry 是否为空
页面显示源码文本	用了 raw 链接当入口；换成 jsDelivr / GitHub Pages，或依赖平台的 srcdoc 渲染
小程序提示「未拿到上下文」	握手超时：页面可能没有引入 SDK，或 SDK 加载失败（看浏览器控制台）
发送报 noPerm	授权记录里没有 message.send，让用户走「改授权」
发送报 rateLimited	触发了每分钟 10 条的限制

私有化建议

1. 自建源：把 index.json 与小程序页面放在你自己的对象存储 / GitHub Pages / jsDelivr 上，只用你自己的源、停用官方源；
2. 只保留可信源：平台信任管理员填的地址，第三方页面的脚本虽然跑在沙箱里，但仍应像安装软件一样审核来源；
3. 关注审计：「日志 → 小程序」里能看到安装、卸载、调用、代发消息；
4. 备份：索引是远端拉取的，但安装记录与 KV 数据在你自己的库里（mini_installs、mini_kv），随库一起备份。

数据落在哪

数据	位置
索引（manifest）	远端源；平台只做内存缓存
安装记录与授权	mini_installs 表（含 manifest 快照）
小程序数据	mini_kv 表，按 (app_id, ns, k) 存储
代发的消息	messages 表，via_app 列标记来源小程序
源配置	app_config.mini_sources
令牌签名密钥	app_config.mini_token_secret（首次使用自动生成）

卸载小程序会清掉对应命名空间下的 KV 数据。