License Server 使用指南

DolphinDB License Server 是企业级部署和云原生场景下的高级许可证管理方案，它通过中心化的服务端和健壮的客户端心跳机制，实现了对分布式集群资源的精细化管控、实时监控和高可用保障，特别适合大规模、跨地域的生产环境。

注：使用 License Server 时，建议使用 2.00.16.3 及以上版本 server。

1. License Server 架构

DolphinDB License Server 架构将传统的单节点 license 文件模式升级为服务端-客户端模式，通过心跳机制实现动态监控和资源调控。在给用户颁发 license 后，云上可能启动多个 DolphinDB 节点，通过 License Server 控制这些节点使用的总硬件资源不超过 license 的限制。

整体思路

将 license 中的 maxCores 和 maxMemory 作为上限，控制所有普通节点的配置项中的 workerNum 和 maxMemSize 的总和不超过 maxCores 和 maxMemory 。

云上节点分为两种角色，License Server 和普通节点。普通节点启动后先向 License Server 发送心跳，并附带自身配置项中的 workNum 和 maxMemSize，License Server 会根据自身硬件资源池的剩余资源进行校验：若扣除该节点所需资源后仍有余量，则允许其启动；否则拒绝启动。若 License Server 一段时间未收到某节点的心跳，则在资源池中自动释放相应节点的资源。

普通节点工作流程：

  • 启动时，若配置项中启用 useLicenseServer=True，系统会读取本地 licenseServer.lic 文件，获取 licenseToken，并在加密后通过心跳线程发送至配置项中指定的 License Server 进行校验。同时，节点会发起资源申请请求，并在心跳中携带自身信息，包括机器指纹、workNum、maxMemSize、机器物理核数，以及可选配置项 bindCores（用于指定节点绑定的 CPU 核）。系统根据 License Server 的返回结果决定是否允许启动。

    节点成功启动后，会根据 License Server 返回的 license 信息更新本地相关配置（如 maxNodes、clientName、expiration、modules）。此外，License Server 还会下发一个 userToken，后续通信将基于该 userToken 进行。

  • 正常运行时，节点需持续向 License Server 发送心跳并接收返回结果。节点运行状态分为 normal 和 waitingClose 两种，并根据心跳返回值进行状态切换或触发关闭。当连续 15 秒心跳失败时，节点将进入 waitingClose 状态。

    • normal：正常运行，每 3 秒发送一次心跳（基于 userToken 通信）。若连续 5 次未收到服务端响应，或服务端返回 token 错误、资源不足错误，则切换至 waitingClose 状态；若收到无相关用户或 licenseToken 错误，则直接关闭节点。

    • waitingClose：该状态 1min 发送一次心跳，如果是断网、服务器宕机等原因未正常收到服务器回复持续 48 小时，后续将调整为 14天（待发布），与普通授权文件失效后使用时间对齐。失败则节点自身关闭；否则服务器返回 token 错误或资源不足错误达到 120 次，关闭节点；收到服务器返回无相关用户错误、licenseToken 错误，直接关闭节点。发送心跳时走新节点启动的逻辑，需要重新验证 licenseToken，若被允许启动则进入 normal 状态并且更新 userToken ，否则继续 waitingClose 。

  • 正常关闭时，节点会先停止发送心跳，然后通知 License Server，将占用的硬件资源归还至资源池 。

2. 配置

使用 License Server 时，需配置 useLicenseServer、coreAffinity（可选）参数，配置详见功能配置 License Server 客户端配置。

3. 监控函数

使用 License Server 时，DolphinDB 提供以下函数，方便用户查看资源使用情况。

  • getLicenseUsag：显示当前用户的资源总量与占用量。

  • getNodeLicenseUsage：显示当前用户的所有节点资源占用细节。

  • getHostLicenseUsage：显示当前用户的所有主机的资源占用细节。

4. 部署

本章针对单节点部署模式、普通集群部署模式、高可用集群部署模式下，使用 License Server 时的配置进行说明，以方便用户查阅使用。关于单节点部署、普通集群部署、高可用集群部署，参见部署 ，此处不做详细说明。

4.1 licenseServer.lic

使用 License Server 前，需先从 DolphinDB 获取 licenseServer.lic 授权文件。licenseServer.lic 文件格式如下：

  • 第一行：客户名称。

  • 第二行：licenseToken。

4.2 服务配置部署

使用 License Server 时，需配置 useLicenseServer、coreAffinity（可选）参数，具体需配置的文件如下

controller.cfg、agent.cfg、cluster.cfg。

本节将对三台服务器（P1、P2、P3）的高可用集群部署模式下，使用 License Server 时的配置操作进行说明。单节点模式部署、普通集群模式部署，与高可用集群部署模式类似，只是涉及的配置文件不同。

4.2.1 上传授权文件

分别登录服务器 P1、P2、P3。

  • 将 licenseServer.lic 文件，分别上传至服务器 <DolphinDB 安装路径>/server 路径下。

4.2.2 修改配置文件

分别登录服务器 P1、P2、P3。

  • 修改 controller.cfg、agent.cfg、cluster.cfg 配置文件，增加 useLicenseServer=True 配置，如下：

#进入配置文件目录
cd <DolphinDB>/server/clusterDemo/config
#修改 controller.cfg、agent.cfg、cluster.cfg 配置文件
vi controller.cfg #增加 useLicenseServer=True 配置
vi agent.cfg      #增加 useLicenseServer=True 配置
vi cluster.cfg    #增加 useLicenseServer=True 配置

4.2.3 启动服务与验证

分别登录服务器 P1、P2、P3。

  • 进入到 <DolphinDB 安装路径>/server/clusterDemo 路径下，启动服务。

cd <DolphinDB 安装路径>/server/clusterDemo
sh ./startController.sh
sh ./startAgent.sh

查看日志：controller.log、agent.log、datanode.log 。

2026-03-26 17:04:55.318776000,dc9d <INFO>:Start server with licenseServer
2026-03-26 17:04:55.318869000,dc9d <INFO>:LicenseHeartBeatSender init with workerNum=8, maxMemSize=16, bindCores=, physicalCores=64
2026-03-26 17:04:55.319193000,dc9d <INFO>:Connect to license server ip:port
2026-03-26 17:04:55.319848000,dc9d <INFO>:[LicenseHeartBeatSender] no cache
2026-03-26 17:04:55.324681000,dc9d <INFO>:starting dolphindb server...
...
2026-03-26 17:04:58.326409000,55bc <INFO>:[LicenseHeartBeatSender] Send heart beat to license server, host:, port:, and get flag 0
2026-03-26 17:05:01.328127000,55bc <INFO>:[LicenseHeartBeatSender] Send heart beat to license server, host:, port:, and get flag 0
...

登录 WEB：

  • 查看各节点的 license 的许可证类型为 LicenseServer 。

  • 通过监控函数查看系统资源情况。

5. 更新 License

使用 License Server 时，可以通过离线和在线的方式更新 License。

5.1 离线更新

server 版本为 2.00.16.3 到 2.00.18 之间的版本，须通过离线的方式更新 License，不支持在线更新。

通过getLicenseUsage 查看授权是否已更新。如果服务端已更新，则重启集群即可。

getLicenseUsage()

更新前，返回如下：到期日期为 2026.12.31

更新后，返回如下：到期日期为 2027.12.31

重启集群

集群重启成功后，通过getAllLicenses查看各节点授权是否已更新。

use ops
getAllLicenses()

返回如下：

5.2 在线更新

server 版本为 2.00.18 及之后的版本，在服务端更新授权过期时间后，客户端会自动更新授权过期时间，无需任何操作。

  • 通过getLicenseUsage 查看 License 授权是否已更新。

getLicenseUsage()

返回如下

  • 通过getAllLicenses查看各节点授权是否已更新

use ops
getAllLicenses()

返回如下：

后端日志：

6. License Server + 加密狗

License Server 支持通过加密狗进行授权校验。加密狗作为一种硬件安全设备，用于管理软件授权许可。只有在插入指定加密狗的服务器上，授权软件才能正常运行，从而有效保障授权的安全性与唯一性。

“License Server + 加密狗”是一种典型的场地授权解决方案。对于场地授权客户，推荐采用该方案。客户可在企业内部基于加密狗私有化部署一套 License Server，实现授权的统一管理与分发，无需为每台服务器单独采集硬件指纹或向 DolphinDB 申请授权，从而简化授权流程并提升管理效率。

6.1 加密狗的使用

使用加密狗部署 License Server 前，需先从 DolphinDB 获取已授权的加密狗设备。

  • 将加密狗插在需要使用的 linux 服务器上（使用限制：不支持Windows系统 ， 机器上只能插一个加密狗，默认使用最先读到的 0 号设备）。

  • 安装 udev 规则（权限模式：普通用户默认没有 USB 设备的读取权限，第一次使用需要用 root 权限配置规则）。若缺少 udev 规则，服务启动时会报错并提示。安装方法如下：ft.rules

// 拷贝规则文件
cp ft.rules /etc/udev/rules.d/
// <执行以下命令加载新权限> 或 <重新插拔加密狗> 均可
udevadm control --reload-rules && udevadm trigger

  • 在配置文件中配置参数 licenseFromDongle=true 。

  • 启动 DolphinDB 服务。

  • 日志确认。

日志文件中含加密狗相关的日志打印，搜索 dongle 关键字，包括启动结束阶段加密狗日志，以及每 10 秒一次的加密狗心跳检测。

正常启动：
Reading license from ROCKEY-ARM dongle for license server...
Dongle share memory not initialized, acquiring lock.
Acquired dongle license server lock, leaseExpire=2026-03-30 12:00:00
Successfully read license from ROCKEY-ARM dongle.
正常关闭：
[DongleLease] Shutdown flag detected, stopping renewer.
[DongleLease] Releasing dongle lock...
[DongleLease] Lock released successfully (share memory cleared).
[DongleLease] Lease renewer thread terminated.
续期失败：
[DongleLease] Failed to open dongle for renewal.
[DongleLease] Renewal failed, failCount=1/3
[DongleLease] Renewal failed, failCount=2/3
[DongleLease] Renewal failed, failCount=3/3
[DongleLease] Max retries reached. Shutting down license server.
锁被抢占：
[DongleLease] Lock lost! Another process took over. License server must exit.
[DongleLease] Lock taken by another process. Shutting down immediately.

6.2 注意事项说明

通过加密狗使用 License Server 时，需注意以下事项。

  • 加密狗中的 license 数据由 DolphinDB 预先写入，用户无法自行修改。

  • 加密狗需始终插在 License Server 所在服务器上，拔出会导致服务关闭。

  • 加密狗所在服务器只能同时启动一个 DolphinDB 服务 ，超过一个会启动失败。

7. 附录

本章将介绍在使用 License Server 时常见问题与解决方案。

7.1 文件不存在

报错信息：<ERROR>:The license server license file：<Path>/licenseServer.lic not exist。如下图：

报错原因：licenseServer.lic 不存在。

解决方案：确保 licenseServer.lic 已上传到 <DolphinDB>/server 路径下。

7.2 无法解析心跳包

报错信息：<ERROR>:Failed connect to license server with exception: Failed to parse license heart beat。如下图：

报错原因：licenseServer.lic 格式错误（windows 与 linux 回车换行的区别）。

解决方案

  • 避免复制粘贴 licenseServer.lic 文件内容，直接上传 licenseServer.lic 文件。

  • 或者 vi 打开 licenseServer.lic，底行模式下 set ff 查看文件类型，如果 ff=dos，则 set ff=unix，保存退出。

7.3 文件不正确

报错信息：<ERROR>:The licenseServer.lic is incorrect。如下图：

报错原因：licenseServer.lic 格式错误。

解决方案

  • 不要修改 licenseServer.lic 文件中任何内容。

  • 联系 DolphinDB 技术支持。

7.4 拒绝启动

报错信息：<ERROR>:The license server refuses to start the node。如下图：

报错原因：内存、核数、节点数等资源不足。

解决方案

  • 修改配置文件，减少相应资源配置。

  • 或者申请更多资源。

7.5 心跳返回 flag=1

报错信息：<ERROR>:The server will shutdown, after heartBeat 118 times in waitingClose state。如下图：

报错原因：内存、核数、节点数等资源不足。

解决方案

  • 2 小时内释放其它节点资源（代替该节点而新启动的节点所占的资源）。

  • 2 小时内申请更多资源。

7.6 心跳返回 flag=2

报错信息：<ERROR>:The server will shutdown, after receive the flag 2 from license server。如下图：

报错原因：无相关授权用户。

解决方案：联系 DolphinDB 技术支持。

7.7 心跳返回 flag=3

报错信息：<ERROR>:The server will shutdown, after receive the flag 3 from license server。如下图：

报错原因：licenseToken 错误。

解决方案：联系 DolphinDB 技术支持。

7.8 网络异常（断网）

报错信息：<ERROR>:Failed to connect to host ip:port with error code: 110 。如下图：

报错原因：客户端（普通节点）与服务端（license server）网络不通。

解决方案：2 天内网络恢复连通后，节点自动恢复。超过该时间后，节点自动关闭。后续会调整为14天（待发布），与普通授权文件失效后使用时间对齐。

7.9 License Server 异常

报错信息：<ERROR>:Failed to connect to host ip:port with error code: 111 。如下图：

报错原因：License Server 服务异常。

解决方案：2 天内 License Server 恢复正常后，节点自动恢复。超过该时间后，节点自动关闭。后续会调整为14天（待发布），与普通授权文件失效后使用时间对齐。