HN 系列 Wiki

主题

这页专门说明 plugins/HNCore/auth.yml 的用途、字段含义，以及 HNCore 统一托管授权接入 该怎么配。

如果你只是普通服主、当前也没有接任何 HN 系列付费模块，这页可以先不看；但如果你正在接：

  • HN 系列付费插件
  • 需要通过 HNCore 统一校验授权的内部模块
  • 基于 NapcatPlugin 授权中心的商品 code / license-key 体系

那这页建议必看。

这份配置是干什么的 ​

auth.yml 的目标不是取代业务插件配置，而是把 授权中心地址、授权码、本地缓存策略 统一收口到 HNCore 管理。

也就是说，推荐做法是：

  • 授权中心地址只配置在 HNCore/auth.yml
  • 各个商品的 productCode -> license-key 只配置在 HNCore/auth.yml
  • 下游插件只在代码里声明自己是谁、商品 code 是什么，然后交给 HNCoreAPI.registerLicensedPlugin(...) 接入

一个最小示例 ​

yml
auth:
  enabled: true

  center:
    base-url: "https://你的域名/plugin/napcat-plugin-hn-license-center/api"
    timeout-ms: 5000
    heartbeat-interval-ms: 1800000

  cache:
    enabled: true
    grace-period-seconds: 86400

  runtime:
    server-id: "lobby-1"
    public-ip: ""
    fingerprint: ""

  products:
    hn-ai-plugin:
      license-key: "HN-ABCD-EFGH-IJKL"

配置块说明 ​

auth.enabled ​

是否启用整套统一授权接入。

  • false：HNCore 会认为统一授权未启用
  • true：开始读取授权中心、缓存与商品授权码配置

如果这里是 false，/hncore status 会直接显示：

  • 统一授权：未启用

auth.center.base-url ​

授权中心的完整 API 基址。

要点：

  • 这里应填写 已包含 /api 的完整基址
  • 通常就是 NapcatPlugin 暴露出来的 /plugin/<插件ID>/api
  • HNCore 会基于这个地址继续访问 verify / heartbeat / health 等接口

例如：

text
https://your-domain/plugin/napcat-plugin-hn-license-center/api

最常见错误：

  • 只填了站点根域名
  • 少写了 /plugin/<id>/api
  • 地址能打开首页，但不是授权中心 API 基址

auth.center.timeout-ms ​

授权中心请求超时时间，单位毫秒。

默认 5000，一般够用。

如果你的授权中心在跨地域网络环境里，或反向代理链较长，可以适当调高。

auth.center.heartbeat-interval-ms ​

运行中心跳间隔，单位毫秒。

默认 1800000，也就是 30 分钟。

这项主要影响：

  • 已注册授权插件的运行期保活频率
  • 授权中心能多快感知插件实例仍然在线

cache ​

auth.cache.enabled ​

是否启用本地授权缓存与离线宽限策略。

需要注意：

  • 这不是“无脑离线可用”开关
  • 只有当授权中心返回 可验签 token 时，这个缓存策略才会真正生效
  • 如果当前主流程仍是纯在线 verify / heartbeat，这项即使打开，也可能只是在为后续协议做准备

auth.cache.grace-period-seconds ​

离线宽限期，单位秒。

默认 86400，即 24 小时。

它的含义是：

  • 当本地缓存已建立且仍满足校验要求时，授权中心短时不可达时可以给出一个有限宽限窗口
  • 不是永久离线授权

runtime ​

这组字段属于 可选上报信息。

auth.runtime.server-id ​

推荐填写一个固定、可读的服务器实例 ID，例如：

  • lobby-1
  • survival-a
  • rpg-main

这样做的好处是：

  • 更方便授权中心记录实例来源
  • 将来如果启用更强绑定策略，更容易按服精确识别
  • 多服场景下更容易排查“到底是哪台服在验权 / 心跳”

auth.runtime.public-ip ​

可选的显式公网 IP。

  • 留空：通常由授权中心自行识别
  • 明确填写：适合你非常确定代理链、回源链和实际出口 IP 的场景

auth.runtime.fingerprint ​

可选的运行环境指纹。

适合后续做更严格的宿主机 / 实例级绑定；当前常规接入可以先留空。

products ​

这里是最关键的一块：

yml
products:
  <productCode>:
    license-key: "..."

例如：

yml
products:
  hn-ai-plugin:
    license-key: "HN-ABCD-EFGH-IJKL"
  hn-mail-plugin:
    license-key: "HN-ZZZZ-YYYY-XXXX"

要点：

  • productCode 必须和下游插件代码里注册时使用的商品 code 一致
  • 不要写展示名代替 code
  • 一个商品 code 对应一个授权码

如果这里完全没配，/hncore status 会提示：

  • 统一授权：未就绪（尚未配置任何 productCode -> license-key）

最短接入步骤 ​

服主侧 ​

  1. 打开 plugins/HNCore/auth.yml
  2. 把 auth.enabled 改成 true
  3. 填写 auth.center.base-url
  4. 在 products 下补上对应 productCode -> license-key
  5. 执行：
text
/hncore reload
/hncore status

二开插件侧 ​

推荐通过：

java
HNCoreAPI.registerLicensedPlugin(this, options)

或者：

java
HNCoreAPI.registerLicensedPlugin(this, CoreManagedLicenseOptions.builder()...build())

把插件注册到 HNCore 的统一授权体系中。

怎么确认配置是否已经生效 ​

优先执行：

text
/hncore status

当前状态命令会直接显示：

  • 统一授权是否启用
  • 是否缺少 auth.center.base-url
  • 是否缺少商品授权码
  • 授权缓存是否启用
  • 当前已托管的商品数量

如果你是开发者，还可以进一步使用：

java
var health = HNCoreAPI.checkManagedLicenseServiceHealth();

来做更显式的健康检查。

常见问题 ​

1. 为什么我明明开了 auth.enabled，但还是显示未就绪？ ​

优先检查：

  • auth.center.base-url 是否为空
  • products 是否至少配置了一项
  • 地址是否真的写到了授权中心 API，而不是网站首页

2. 为什么 base-url 要求包含 /api？ ​

因为 HNCore 不是拿这个地址做页面跳转，而是直接拼接授权中心 API 路径。

如果你只填根域名，后续 verify / heartbeat 请求地址通常就会错误。

3. 我没有安装 NapcatPlugin，可以先配这页吗？ ​

可以先写，但如果授权中心本身并不存在或不可访问，健康检查与实际验权仍然会失败。

4. 普通服主需要先配这页吗？ ​

不需要。

如果你当前只是使用 HNCore 自身脚本、工具箱、共享存储或 ClusterBus，而没有接付费模块，这页可以先保持默认关闭。

建议联动阅读 ​

HN 系列插件文档

Copyright © 2024