许可证管理

功能概述

机制概述

KaiwuDB 使用许可证管理用户登录和数据库操作权限，以保障数据库的安全性与合法使用。

许可证控制以下两类资源的使用上限：

节点数量：集群中允许加入的最大节点数。
测点数量：集群中允许写入的最大测点数。

KaiwuDB 部署完成后无需立即配置许可证，自动进入 14 天试用期。许可证与部署环境的硬件信息绑定，防止同一许可证在多套环境中使用，更多信息，参见许可证防滥用。

试用期

KaiwuDB 部署完成后自动进入** 14 天试用期**。试用期起始时间因部署方式而异：单机部署以数据库启动完成时间为准，集群部署以集群初始化完成时间（即 init 执行成功的时间）为准。试用期结束后，若未配置有效许可证，业务功能将受到限制。

试用期内，所有功能不受限制，用户权限与许可证有效状态一致，更多信息，参见基于许可证的用户权限。

使用 kwbase sql 登录数据库时，控制台会展示到期时间，例如：

License expiration date: 2026-05-30 07:53:20+00:00 (trial)

用户也可通过执行 SHOW LICENSE 可查看试用期状态：edition 字段显示 trial，expiration_time 字段显示到期时间：

SHOW LICENSE;
  product | version | edition | customer |      expiration_time       | endpoint_limit | node_limit | endpoint_used | node_used
----------+---------+---------+----------+----------------------------+----------------+------------+---------------+-----------
          |         | trial   |          | 2026-01-30 07:53:20+00:00  |              0 |          0 |             0 |         3

测点管理

测点指时序表的数据列（即数据采集指标），例如温度、湿度、电压、用电量等。测点数 = 设备数 × 时序表数据列数。

当写入的测点数量超过许可证限制的测点数量，用户可以向已有设备读写数据，但是无法创建时序表、向时序表中添加列。同时，数据写入速度也受到限制。

当许可证中的测点数量设置为 -1 时，不限制测点数量。

系统每 24 小时自动检查并更新已使用的测点数量。用户也可以通过 REFRESH LICENSE USAGE SQL 语句手动更新已使用的测点数量。

执行 SHOW LICENSE 可查看当前已用测点数量。当已使用的测点数量超过许可证限制的测点数量时，用户可以通过删除时序表、时序表的列或者时序表中某一设备的数据来保证数据的读写速度。

节点管理

KaiwuDB 许可证支持限制集群节点数量，用于控制许可证配置和集群扩容。

说明

集群启动和初始化过程中，节点数量不受限制。

配置许可证时，系统校验集群当前节点数是否超过许可证限制。如果集群中的当前节点数量未超过许可证限制的节点数量时，用户可以设置许可证成功。否则，设置失败。此时，用户需要先缩容集群，等节点数量满足许可证要求后，再设置许可证。

扩容集群时，系统执行以下两项校验，两项均通过方可扩容：

新增节点数未超过许可证节点数限制。
新节点的硬件信息（主板 UUID、网卡 MAC、IP:PORT）与许可证绑定信息匹配。

若新节点硬件信息与许可证不匹配，扩容失败并报错。

建议

申请许可证时，提前将所有可能用于扩容的节点信息一并提交，避免因节点不在许可证范围内导致后续扩容失败。

许可证防滥用

许可证与部署环境绑定，防止同一许可证在多套环境中使用。许可证绑定以下节点信息，任意一项发生变更，许可证自动失效：

绑定信息	说明
节点主板 UUID	服务器主板唯一标识
网卡 MAC 地址	物理网卡硬件地址
SQL 服务地址	KaiwuDB 节点的 IP:PORT
集群 ClusterID	KaiwuDB 集群唯一标识

设置许可证时：系统校验所有节点信息是否与许可证匹配，全部通过则许可证生效。

集群重启时：系统重新校验各节点环境信息。若节点信息与许可证不匹配，节点可正常启动，但集群许可证失效。执行 SHOW LICENSE 可查看失效原因，edition 字段将显示 some nodes do not match license。

配置与管理

申请许可证

许可证与部署环境绑定，申请前需先采集各节点信息。

前提条件

已完成 KaiwuDB 部署。
各节点已安装 dmidecode，且运行 KaiwuDB 的用户具有 sudo 免密执行 dmidecode -s <option> 的权限。
节点服务地址不为回环地址（127.0.0.1 / localhost）。

步骤

在所有需要绑定许可证的节点上执行以下命令，采集节点硬件和运行信息：
```
kwbase collect <data-dir>
```
<data-dir> 为该节点的数据目录。命令执行成功后，当前目录下将生成采集文件，命名格式为 collect-{FQDN-IP}.bin。有关 kwbase collect 命令的详细信息，参见 kwbase collect。
将所有节点的采集文件发送至 KaiwuDB 技术支持open in new window，申请 .lic 格式的许可证文件。

配置许可证

前提条件

已获取 .lic 格式的许可证文件。
当前登录用户具有 admin 权限（标准安全模式）或 sysadmin 权限（三权分立模式）。
集群当前节点数未超过许可证的节点数限制。

步骤

复制 .lic 文件中的许可证码。
执行以下命令将许可证配置到集群：
```
SET CLUSTER SETTING cluster.license = '<your-license-code>';
```
将 <your-license-code> 替换为许可证码。
执行 SHOW LICENSE 确认许可证已生效。

有关 cluster.license 参数的详细信息，参见集群实时参数。

查看许可证

许可证配置完成后，可通过以下方式查看许可证信息：

系统视图：查询 kwdb_internal.kwdb_license，可查看到期时间、测点限制数、已用测点数、节点限制数、已用节点数等信息。
SQL 语句：执行 SHOW LICENSE。

说明

如果集群各节点的启动时间不同，各节点检查许可证状态的时间点也会不同。在极端情况下，部分节点检查到的许可证状态可能与其他节点不一致。

更新许可证

系统每 24 小时自动检查许可证是否超期。管理员或系统管理员需在许可证到期前完成更新，确保数据库持续运行。

步骤

向 KaiwuDB 技术支持open in new window 申请新的许可证文件。

执行以下命令更新许可证：

SET CLUSTER SETTING cluster.license = '<your-license-code>';

执行 SHOW LICENSE 确认新许可证已生效，expiration_time 字段已更新。

升级后重新申请许可证

从 3.1.1 及之前版本升级到 3.2.0 及以后版本后，原有许可证自动失效，需重新申请并配置。

注意

升级完成后、配置新许可证之前，禁止进行扩容操作。

步骤

完成集群升级。
在各节点执行以下命令采集环境信息，有关 kwbase collect 命令的详细信息，参见 kwbase collect。
```
kwbase collect <data-dir>
```
将采集文件提交至 KaiwuDB 技术支持open in new window，申请新版许可证。
按照配置许可证完成配置后方可继续使用。

附录

基于许可证的用户权限

说明

试用期内，用户权限与许可证有效状态一致。

标准安全模式

用户	未设置有效许可证	许可证有效	许可证超期 30 天内	许可证超期 30 天后
管理员	- 登录数据库。 - 设置 `cluster.license` 集群变量。	正常登录并管理数据库。	正常登录并管理 KaiwuDB 数据库。	- 登录数据库。 - 设置 `cluster.license` 集群变量。
普通用户	拒绝登录数据库。	正常登录并管理数据库。	拒绝新的会话连接。	拒绝登录数据库。服务器端自动断开已建立的会话连接。

三权分立模式

用户	未设置有效许可证	许可证有效	许可证超期 30 天内	许可证超期 30 天后
系统管理员	- 登录 KaiwuDB 数据库。 - 设置 `cluster.license` 集群变量。	正常登录并管理数据库。	正常登录并管理 KaiwuDB 数据库。	- 登录数据库。 - 设置 `cluster.license` 集群变量。
安全管理员	拒绝登录数据库。	正常登录并管理数据库。	拒绝新的会话连接。	拒绝登录数据库。服务器端自动断开已建立的会话连接。
审计管理员	拒绝登录数据库。	正常登录并管理数据库。	拒绝新的会话连接。	拒绝登录数据库。服务器端自动断开已建立的会话连接。
普通用户	拒绝登录数据库。	正常登录并管理数据库。	拒绝新的会话连接。	拒绝登录数据库。服务器端自动断开已建立的会话连接。

常见问题

执行 SQL 时提示没有有效许可证。

原因：试用期已结束，或已配置的许可证失效。
解决方法：申请并配置新的有效许可证，参见申请许可证和配置许可证。

设置许可证后扩容失败，提示节点信息不匹配

原因：新扩容节点的硬件信息不在许可证的绑定范围内。
解决方法：确认节点信息是否与申请时提交的一致；如不一致，重新申请包含新节点信息的许可证。

重启集群后，执行业务 SQL 提示没有有效许可证

原因：重启后某节点的运行信息与许可证不匹配，例如服务器更换、IP 变更等。
解决方法：执行 SHOW LICENSE 查看 edition 字段确认具体原因，然后申请与当前环境匹配的新许可证。

`kwbase collect` 提示无法采集 MAC 地址

原因：节点服务地址配置为回环地址（127.0.0.1 或 localhost），回环地址无法关联物理网卡 MAC。
解决方法：将服务地址修改为实际物理网卡的 IP，重新部署后再执行采集。节点本身不受影响，仅无法用于许可证绑定申请。

# 许可证管理

# 功能概述

# 机制概述

# 试用期

# 测点管理

# 节点管理

# 许可证防滥用

# 配置与管理

# 申请许可证

# 配置许可证

# 查看许可证

# 更新许可证

# 升级后重新申请许可证

# 附录

# 基于许可证的用户权限

# 标准安全模式

# 三权分立模式

# 常见问题

# 执行 SQL 时提示没有有效许可证。

# 设置许可证后扩容失败，提示节点信息不匹配

# 重启集群后，执行业务 SQL 提示没有有效许可证

# kwbase collect 提示无法采集 MAC 地址