NyanZone Registry 文档

概览

NyanZone Registry 维护一份与 Koishi 官方市场同步的数据副本，并额外计算评分、可移植性等指标，供其他镜像或工具复用。公共接口无需凭证即可访问；需要写入或查询受保护数据时，请在请求体中携带 master_token。

基础路径所有公共接口位于 /k/market 前缀下，可直接通过 HTTPS 访问。

数据兼容输出格式与官方完全一致，可直接替换。

安全策略受保护的接口统一使用 token 做鉴权，可通过已有 API 验证。

公共镜像接口

1. 获取市场数据

GET /k/market/index.json 返回完整的插件列表、元数据与评分信息，与官方市场使用的结构一致。在 Koishi 中将市场源指向该地址即可完成替换。

提示：数据会保持按需更新，若需要缓存可叠加 CDN，但请确保遵循 Cache-Control 响应头。

2. 镜像健康信息

GET /k/market/statistics 用于监控镜像运行情况，包括插件总数、可移植插件数、评分队列长度等指标。这些数据已在首页与状态页中展示，也可集成到 Prometheus/Grafana。

curl https://registry.nyan.zone/k/market/statistics
# {
#   "total_plugins": 1240,
#   "portable_plugins": 1187,
#   "queue_size": 0,
#   "total_requests": 98231,
#   "last_scored_at": "2024-05-02T11:07:21+08:00"
# }

评分服务

若你运营自建镜像，可复用我们的评分结果。通过 POST /k/market/ratings 提交插件名数组即可获得最新的评分详情。

POST /k/market/ratings
{
  "registry": "YOUR_REGISTRY_NAME",
  "token": "YOUR_TOKEN",
  "packages": [
    "koishi-plugin-chathub",
    "koishi-plugin-openai"
  ]
}

返回值如下，可直接写入你的镜像数据库。单次请求支持批量查询，系统会自动处理限流与缓存。

{
  "ranges": [
    {
      "name": "koishi-plugin-chathub",
      "rating": 4.5,
    }
  ],
  "reserve": ["koishi-plugin-chathub"]
}

reserve 表示插件未命中评分缓存，已进入评分队列。请在稍后重试以获取最新结果。轮询我们建议采用退避策略，避免频繁请求同一插件。

常见问题

自动提交如何工作？ 分类面板在检测到变更后 10 秒内自动提交，如需立即同步可点击“手动提交”。
评分多久刷新一次？ 插件更新或评分过期时会自动重新计算，也可以将插件加入队列后稍后重试。
可以将评分结果用于其他项目吗？ 可以，只需遵守授权策略并在请求中正确携带标识。

Koishi 第三方镜像 API

概览

公共镜像接口

1. 获取市场数据

2. 镜像健康信息

评分服务

常见问题