外观

插件市场与离线安装 ​

管理员在“扩展中心 → 插件市场”查找扩展，在“插件管理”配置、启停和卸载。先确认所用版本包含插件支持。

1. 配置市场来源 ​

通常无需配置：plugins.catalog_url 留空时使用 ZeroDeNet 公开市场，统一市场暂不可用时回退到兼容目录。留空不代表禁用市场，也不要求先填写所有插件发布者公钥。

部署时需要确保插件文件能持久保存。使用项目提供的 Docker Compose 时，插件目录已挂载到 /var/lib/zboard/plugins；自定义部署参见插件持久化。插件文件、数据库和凭证加密密钥应一起备份。

只有使用自建签名目录或预设发布者信任时，才需要在已有 YAML 中添加对应配置：

yaml
plugins:
  directory: /var/lib/zboard/plugins
  catalog_url: "https://YOUR_CATALOG_HOST/catalog.json"
  trusted_publishers:
    your.catalog.publisher: "BASE64_ED25519_PUBLIC_KEY"

将示例替换为分发方提供并经你核实的目录与公钥。自定义 catalog_url 接受宿主的签名目录格式，不能填写 GitHub 仓库首页、公开市场 API 或任意 JSON。配置文件的挂载方式见存储与备份，目录格式见发布约定。修改 YAML 后重启 ZBoard；日常安装、配置和启停无需重启。

2. 从市场安装 ​

  1. 打开“扩展中心 → 插件市场”，搜索需要的插件并进入详情。
  2. 核对发布者、项目主页、使用文档及版本说明；在已有通道中选择正式版、候选版（RC）或开发版（Dev）。
  3. 点击“在线安装”。ZBoard 自动选择当前服务器平台的安装包，下载后展示包内清单、能力、兼容性和签名指纹。
  4. 确认插件及版本无误后点击“确认安装”，到插件管理页完成配置、测试并启用。

公开市场中已准入的发布者密钥用于验证在线安装；通常不会出现陌生离线包的首次信任勾选框。签名校验不保证代码没有风险，详见市场信任规则。

首次安装默认停用。安装成功只表示包已保存并完成宿主校验，不代表外部服务已连接。没有当前平台的包、没有适用发行版或安装包超过 32 MiB 时，详情页会说明原因；也可下载适合其他服务器的 .zbplugin 文件。

3. 离线安装 ​

  1. 从发布者的可信渠道取得 .zbplugin 文件，单包最大 32 MiB。
  2. 在“插件管理”打开“离线导入”，选择文件并点击“查看插件”。选择文件和预览都不会安装或运行插件。
  3. 核对名称、版本、发布者、所需能力、页面范围和签名指纹。首次导入未知来源时，独立核实发布者与指纹，再勾选“我已确认来源，信任此插件的签名密钥”。
  4. 点击“确认导入”，成功后配置、测试并启用。

旧版包没有附带公钥时，使用弹窗的“旧版插件包兼容选项”提供发布者 .pub 文件内容。离线安装同样检查签名、摘要、能力和平台，不是绕过验证的方式。

4. 配置、启停和更新 ​

  • 配置：在详情页点击“配置插件”，优先使用插件提供的表单。保存后再测试；测试使用已保存配置。高级 JSON 会整体替换配置，秘密值不回显，使用前保留安全的原始配置来源。
  • 启停：启用后才提供页面和服务；停用会停止运行、撤销插件会话，但保留配置与私有数据。
  • 更新：先备份并阅读版本说明，点击“切换发布版本”或导入同一插件的新包。成功保留原启停状态；候选包或迁移校验失败时保留旧版本与数据。
  • 恢复：当前宿主只保留正在使用的包，不提供本地历史版本回滚。切换已发布版本仍要重新安装并通过数据兼容检查，不等于恢复备份；不要依赖旧界面中的历史版本提示。
  • 卸载：停止运行并移除程序，保留配置、私有数据和记录。“清除保留数据”是卸载后的独立操作，执行前确认不再需要这些数据。

更多数据保留规则见插件范围与数据。插件停用或卸载不会撤销已完成的核心订单、订阅或账户操作。

常见问题 ​

现象检查方向
没有插件入口当前账号是否为管理员，面板版本是否支持插件。
市场加载失败服务器能否访问公开市场和发行下载地址；自建目录是否过期或配置错误。网络不可用时可从可信来源取得包后离线导入。
版本或安装按钮不可用所选通道是否有适用版本、服务器平台是否受支持、包是否超过 32 MiB。
签名、公钥或发布者冲突不要替换公钥强行安装；核对插件 ID、发布者、既有签名指纹和下载来源。
提示未测试当前版本这是发布者的测试覆盖提示；接口、能力和平台不兼容才会阻止安装，市场也会按发行元数据筛选版本。
安装后没有扩展页面是否已配置并启用，以及插件贡献的是公开页、用户页、管理页还是纯后台服务。
服务启动或更新失败查看详情页“操作记录”，检查平台、已保存配置和数据迁移错误；提交问题时移除密钥、授权码和令牌。

ZeroDeNet