# chongming 机器码授权工具 · 使用手册

面向**商务、售后、技术支持**同事。不需要懂命令行，也不需要懂密码学 ——
照着本手册做，就能把客户设备的"申请码"变成一份能用的授权文件。

> 本手册讲**怎么用**。授权是怎么验的、私钥为什么不能外传、设备端强制执行点在哪，
> 见仓库 [README](../README.md)；界面是怎么设计的见 [界面设计.md](界面设计.md)。

---

## 1. 三十秒认识这个工具

**它做什么**：把客户设备导出的**申请码**，变成一份 `license_*.lic` 授权文件。

**它不做什么**：不联网、不连设备、不装东西 —— 全程在你自己的电脑上离线完成。
客户设备那边只需要做两件事：导出申请码给你、导入你发回的 `.lic`。

| | 使用者 | 在哪 | 能不能签发 |
| --- | --- | --- | --- |
| **本工具** | 厂商（商务/售后/研发） | 桌面软件 | ✅ 需要私钥 |
| `chongming-license` 命令行 | 厂商（研发/自动化） | 终端 | ✅ 需要私钥 |
| 设备端「授权」页 | 客户 / 现场装机 | 浏览器 `http://<设备IP>:8000/static/license` | ❌ 只能导出申请码、导入 license |

> ⚠️ **两件事必须记住**
> 1. **私钥只在本机**，绝不随部署产物、安装包、邮件分发。私钥泄漏 = 任何人都能签发授权。
> 2. 本工具是**厂商侧**工具，装在你的办公电脑上，不要给客户。

---

## 2. 三步上手

### 第一步：准备私钥（只做一次）

打开「**密钥**」页，点「**生成密钥对**」。

![密钥页](images/03-keys.png)

- 私钥会写到你指定的路径（默认 `license_private.pem`），**离线备份到 U 盘/密码管理器**。
- 公钥会自动复制到剪贴板 —— 下一步"把公钥注入设备"就要用它。
- 记住页面上显示的**公钥指纹**（形如 `3F9A-1C2B-…`）。之后每次签发前都核对一眼，
  能避免"拿错密钥签了一批授权"这种最难排查的事故。

如果公司已经有一把私钥（比如研发那边统一管理），用下半部分「**加载现有私钥**」选中它即可。

### 第二步：让客户导出申请码

告诉客户（或现场同事）在设备上打开 `http://<设备IP>:8000/static/license`，
点「导出申请码」，把那一串 `CM1-…` 复制给你（微信/邮件都行，**可以带换行和空格**）。

> 客户回传**申请码**而不是机器码：机器码是哈希，反推不出各个硬件标识，
> 只能签出"精确匹配、换硬件即失效"的授权；申请码带完整指纹，才能享受换硬件容错。

### 第三步：签发

打开「**签发**」页，粘贴申请码 → 点「解析申请码」→ 勾选要授权的插件 →
填客户名 → 点「**签发并保存…**」。

![签发页](images/01-issue.png)

把生成的 `.lic` 文件发给客户，让他在设备「授权」页导入并**重启网关**即可生效。

---

## 3. 页面详解

### 3.1 签发页

日常最高频的操作。设计目标是：**在你按下"签发"之前**，就能看清"给谁、哪台设备、哪些插件、多久"。

#### 签名私钥

| 字段 | 含义 | 怎么填 |
| --- | --- | --- |
| 当前 | 正在生效的私钥文件 | 显示路径；未加载时会提示去「密钥」页 |
| 公钥指纹 | 这把私钥对应公钥的短指纹 | 签发前**核对它**与设备端显示的一致 |

#### 签发依据（三选一）

| 方式 | 什么时候用 | 容错能力 |
| --- | --- | --- |
| **申请码**（推荐） | 绝大多数情况 | ✅ 换网卡/换 eMMC 不影响授权 |
| 来源 JSON 文件 | 客户/研发给了 `show --json` 的导出文件 | ✅ 同上 |
| 仅机器码 | 实在拿不到申请码，客户只报了机器码 | ❌ 精确匹配，**换一块网卡就失授权** |

选「申请码」后：把 `CM1-…` 粘进输入框 → 点「**解析申请码**」。
下方会显示：

- **解析结果**：机器码 + 指纹来源统计。若出现 ⚠（没有任何可信来源 / 无来源指纹），
  整块文字会变成警示色 —— 这是签发前最该被看见的信息。
- **来源指纹**：逐条列出这台设备的硬件标识。

> **可信来源 / weak 来源是什么？**
> 授权按"多个硬件指纹里命中若干个"来判定，而不是全中才算。
> `machine_id`（systemd machine-id）被标为 **weak**：同一个系统镜像刷到不同机器上会重复，
> 让它计票等于给"整盘拷贝到另一台机器"白送一票，所以**它不参与判定**，只作参考。

#### 授权插件

勾选这台设备上要生效的插件。

- 列表会**自动读取**你填的「项目根」目录下 `config/workers/*/config.toml`，列出该项目实际有哪些插件。
- 读不到时会退回到常见候选，并在列表下方用警示色写明"已用常见候选"—— 别把它当成真实清单。
- 也可以手工输入任意插件 type 后点「添加」。
- 设备上装了但**没被勾选**的插件，导入授权后会被拒绝加载。

#### 授权信息

| 字段 | 含义 | 怎么填 |
| --- | --- | --- |
| 客户名称 | 写给谁，台账检索靠它 | 建议统一格式，如"华东水务集团" |
| 授权编号 | license 的唯一编号 | **留空自动生成**（`L<日期>-<随机>`），一般不用手填 |
| 备注 | 合同号等，仅展示/审计 | 如 `合同 SM-2026-0417` |
| 密钥标识 | 写进 license 的 `kid` 字段 | 可选，如 `vendor-2026` |
| 有效期 | N 天 / 指定到期日 / 永久有效 | 三选一；未选中的输入框会自动禁用 |

#### 预览与签发

- **预览**里是即将被签名的完整载荷 JSON —— 与真正签名用的是**同一个对象**，所见即所签。
  按「刷新预览」随时核对。
- 「签发后记入台账」默认勾选，建议保持：台账存了机器指纹，**下次续期不用再找客户要申请码**。
- 点「**签发并保存…**」选择保存位置 → 完成。

> 签发完会再弹一张回执确认：编号、客户、机器码、插件、有效期、公钥指纹。
> 把 `.lic` 发给客户前，建议扫一眼这张回执。

### 3.2 台账页

已签发授权的检索与管理。**签发页签发的每一份都会自动入库**。

![台账页](images/02-registry.png)

#### 台账库

| 字段 | 说明 |
| --- | --- |
| 存储 | **本地 SQLite**（默认，单文件）或 **PostgreSQL**（团队共用一份，见 [4.9](#49-团队共用台账postgresql)） |
| 路径（本地） | 台账库文件位置，默认 `~/.chongming/licenses.db`（单文件 SQLite，直接拷走即备份） |
| 连接（PostgreSQL） | 连接串摘要 + 「连接设置…」，**不显示密码** |
| 概览 | 总数 + 有效 / 即将到期 / 已过期 / 永久 / 未生效 / 当前筛选数 |
| 签名私钥 | 续期要用私钥；未加载时会提示去「密钥」页 |

首次指定一个不存在的路径 → 点「打开 / 新建」即可创建空台账。
选 PostgreSQL 时点「打开 / 新建」建立连接（首次会自动建表）。

#### 筛选

客户（模糊）、机器码（模糊、大小写不敏感）、插件 type（精确）、
关键字（同时匹配编号/机器码/客户/备注）、状态、以及「即将到期」的判定窗口（默认 30 天）。

列表按**到期日升序**，最急的排在最前。

| 状态 | 含义 | 颜色 |
| --- | --- | --- |
| 未生效 | 生效日期还没到 | 紫 |
| 已过期 | 到期日已过 | 红 |
| 即将到期 | 在判定窗口内（默认 30 天内） | 橙 |
| 有效 | 正常可用 | 绿 |
| 永久有效 | 无到期日 | 蓝 |

> 判定顺序是"未生效 → 永久 → 已过期 → 即将到期 → 有效"。
> 所以一份"生效日期在未来"的授权即使同时填了过去的到期日，也显示为**未生效**。

#### 行操作

| 按钮 | 作用 |
| --- | --- |
| **续期选中…** | 打开续期对话框：只改要变的部分，**直接复用台账里的机器指纹，无需再向客户索取申请码** |
| **改插件…** | 重签一份只换了插件白名单的新授权：**有效期与生效日原样保留**，指纹同样复用台账 |
| 编辑备注 | 人工批注（"已电话确认续期"、"设备已返修"）。**重新导入 license 不会覆盖它** |
| 复制机器码 | 复制选中行的机器码 |
| 查看详情 | 摘要 + **当初签发的那份 license 原始内容**，可直接复制 |
| 删除记录 | 只删台账记录，**不影响已经发给客户的 .lic**（那些文件仍然有效） |

**续期对话框**长这样：

![续期对话框](images/06-renew.png)

- 上半部分是**原授权**（只读），下半部分是**新授权**（可改）。
- 编号默认「生成新授权编号」：新旧两条都留在台账，可追溯；需要沿用原编号也可以切换。
- 旧记录会自动加上 `已续期 → <新编号>` 批注。

**改插件对话框**用于"客户说设备上少了一个插件能用"这类需求：

![改插件对话框](images/07-change-plugins.png)

- 顶部「原授权」是只读摘要（编号 / 客户 / 机器码 / 有效期 / 指纹个数），
  下面的勾选列表与签发页是同一个组件：项目里 `config/workers` 下的插件自动列出，
  原来授权过的插件**始终留在列表里并预勾选**（哪怕项目里已经删掉那个插件），
  找不到的 type 还可以手工添加。
- 列表下方「变更」一行实时显示 `新增：… / 移除：…`。
  **移除**的插件会额外亮出告警：客户导入新文件后该插件会被拒载（`plugin_not_licensed`）。
- **有效期与生效日原样保留**（这一条是刻意的：要延长有效期请用「续期选中…」）。
- 编号默认「生成新授权编号」，旧记录会自动加上 `已变更插件 → <新编号>` 批注；
  选「沿用原授权编号」则替换台账里那份记录（审计追溯只剩新版，一般不建议）。

> **为什么不能直接改文件？** 授权文件是签名过的，签名覆盖整个载荷 —— 改任何一个字段
> （包括插件白名单）都会让签名失效，只能**用私钥重签一份新的**。
> 另外授权**没有吊销机制**：旧 `.lic` 在它自己的到期日之前仍然有效，
> 只能靠客户导入新文件把它们覆盖掉。所以改插件本质上是"再发一份授权"。

#### 导出归档

- **导出 .lic**：把当前筛选结果原样导出，文件名形如 `L20260921-312629_3ECA-D113-….lic`；
  可选「按客户分子目录」，直接打包发给对应客户。
- **导出 CSV 清单**：给商务对账用，UTF-8 BOM 编码，Excel 双击打开**中文不乱码**。

### 3.3 密钥页

见 [第一步](#第一步准备私钥只做一次)。补充说明：

| 字段 | 说明 |
| --- | --- |
| 私钥保存到 | 生成密钥对时的写入路径 |
| 公钥 base64 | 可直接填进设备配置 `[license] public_key` 的那一行，点「复制」取走 |
| 公钥 PEM | 另一种格式（`-----BEGIN PUBLIC KEY-----`），按需使用 |
| 加载现有私钥 | 选中已有私钥后显示对应公钥与指纹，用来确认"这把私钥对应哪把公钥" |

### 3.4 查看 / 校验页

拿到一份 `.lic`（比如客户反馈"导入失败"，或你要发货前自检）时用这一页。

![校验通过](images/04-inspect-ok.png)

| 区域 | 说明 |
| --- | --- |
| license 文件 | 选或填 `.lic` 路径 |
| 公钥 | 验签用的公钥（base64 或 PEM）；**留空则只查看内容、不验签** |
| 指纹比对基准 | **按本机**（在你自己电脑上通常对不上，属正常）／**按指定机器**（填客户申请码） |
| 校验结论 | 成功/失败横幅 + 原因码 + 命中与不匹配的来源明细 |
| 内容 | license 的完整 JSON |

> **发货前自检的正确做法**：选「按指定机器」并填入**客户设备的申请码**。
> 只验签名只能证明"这文件是我们签的"，验不出"是不是给这台设备签的"。
> 填了申请码，工具才会真正核对机器指纹。

校验失败时长这样（下面是"拿 A 设备的授权去校 B 设备"）：

![异机被拒绝](images/05-inspect-fail.png)

---

## 4. 场景速查

### 4.1 第一次给一台新设备签发

「密钥」页确认私钥已加载并记下指纹 → 客户导出申请码 → 「签发」页解析申请码 →
勾选插件 → 填客户名与有效期 → 签发并保存 → 把 `.lic` 发给客户导入 → 重启网关。

### 4.2 设备续期（客户联系不上、或换人对接）

「台账」页搜到那台设备（按客户名或机器码）→ 选中 → 「**续期选中…**」→
选有效期 → 「续期并保存…」。

**全程不需要再找客户要申请码** —— 续期复用台账里存的指纹。这是台账最大的价值。

### 4.3 客户换了网卡 / 主板，提示授权失效

授权是按"多个硬件指纹命中若干"判定的，阈值是 **3 个可信来源**：

- 换一块网卡 → 少一票（网卡 MAC 不匹配），其余仍命中 → **通常仍可用**。
- 换了主板或整机返修后主板序列号变了 → 可能跌破阈值 → 需要**续期/重新签发**。

做法同 4.2：从台账复用指纹重新签发一份。注意换了几件硬件后可能连台账里的旧指纹也
不足以命中，此时请让客户**重新导出申请码**，按 4.1 走一遍。

### 4.4 发货前自检

「查看 / 校验」页 → 选刚签发的 `.lic` → 填公钥 → 选「按指定机器」→ 粘贴**这台设备**的申请码 → 点「校验」。
看到绿色「✓ 授权有效」再发货。

### 4.5 查某客户的所有授权

「台账」页 → 客户框填客户名（模糊匹配）→ 「查询」。

### 4.6 批量交付 / 归档

「台账」页 → 筛选出要交付的范围 → 「导出」区选目录 → 「导出 .lic」→
需要按客户分包就选「按客户分子目录」。

对账要表格时用「导出 CSV 清单」。

### 4.7 换电脑 / 密钥交接

1. 在新电脑上装好本工具（见 [README](../README.md) 的安装与运行）。
2. 把**私钥文件**从安全备份中取回，放到新电脑（不要走微信/邮件）。
3. 「密钥」页 →「加载现有私钥」→ 选中它 → **核对公钥指纹与之前记录的一致**。
4. 台账库默认在 `~/.chongming/licenses.db`，一并拷到新电脑对应位置；
   或在「台账」页「浏览…」指向拷过来的库文件。

### 4.8 调整"即将到期"的判定窗口

「台账」页 →「状态」行右侧的「__ 天内」改成你要的值（比如 90）→ 点「查询」。
之后「只看即将到期」也按这个窗口筛选。

### 4.9 团队共用台账（PostgreSQL）

默认每人的台账是**自己电脑上的单文件**，互相看不见。若希望商务/售后/研发看到
**同一份台账**（谁签给了谁、哪台设备快到期，不用互相问），可以改成共用一个
PostgreSQL 库。**这是可选功能**：没配就还是本地 SQLite，不影响使用。

#### 一次性准备（找 IT / DBA）

1. 准备一个 PostgreSQL 库（版本 12+ 即可，公司内网直连最省事）。
2. 建一个账号，日常使用给 `SELECT / INSERT / UPDATE / DELETE` 权限即可；
   若允许建表，工具**首次连接会自动建表**，无需人工干预。
3. 如果账号**没有建表权限**，把仓库里的 `docs/pg_schema.sql` 交给 DBA 执行一次
   （里面就是表 + 索引 + 版本表）。

#### 每台电脑上的配置

「台账」页 →「存储」改成 **PostgreSQL** → 点「连接设置…」：

| 字段 | 怎么填 |
| --- | --- |
| 主机 / 端口 | 数据库地址，PostgreSQL 默认端口 **5432** |
| 数据库 | 库名 |
| 用户 / 密码 | 上一步建的账号 |
| SSL 模式 | 内网直连常用 `prefer`；要求加密选 `require` |
| Schema | 默认 `public`，除非 DBA 指定了别的 |
| **记住密码** | 勾选后写入本机配置，下次启动自动连接（**明文保存**，见下方提醒） |

不确定填得对不对，先点「**测试连接**」—— 它会真的连一次并告诉你结果。
保存后用「打开 / 新建」建立连接，「概览」显示记录数即成功。

#### 密码怎么存（请想清楚再勾）

- **不勾「记住密码」**（推荐给安全要求高的环境）：密码只存在于本次运行的内存里。
  关掉工具再打开需要重新输入；签发时若未连接，会在"记入台账"环节提示去连接。
- **勾了「记住密码」**：密码明文保存在本机（Windows 是注册表
  `HKCU\Software\chongming\license-gui`），下次启动自动连接。
  共享电脑、或数据库账号权限较大的场合**不要勾**。取消勾选会删除已保存的密码。

> 说明：工具的既有约定是"配置里只记路径、不记内容"（私钥就是这么处理的）。
> 这里之所以提供"记住密码"，是因为每天手输数据库密码对商务同事门槛太高 ——
> 但默认是**不勾**，由你自己权衡。

#### 多个同事同时用会不会冲突？

不会。PostgreSQL 本身支持并发，多人同时签发/续期/查询都安全（本地 SQLite 版同样
支持多开窗口）。同一份授权被两人同时写入时按授权编号幂等覆盖。

#### 常见问题

**「连接设置…」测试连接失败？**
按提示依次确认：主机端口是否可达（能不能 ping 通、5432 是否放通）、库名对不对、
账号密码、以及 PostgreSQL 的 `pg_hba.conf` 是否允许你这台机器的 IP 连接。

**提示"建表失败"？**
账号没有建表权限。把 `docs/pg_schema.sql` 交给 DBA 执行一次，之后就能正常用。

**提示"台账库结构版本为 X，本程序支持 Y"？**
这个库是另一个版本的工具建的。先导出台账（export），再换用匹配版本的工具；
不要手工改版本号。

**换回本地台账？**
「存储」改回「本地 SQLite」→「打开 / 新建」。本地库里的数据一直都在，不会因为
用过 PostgreSQL 而丢失。切后端时工具会断开当前连接，避免"界面显示一个库、
实际写另一个库"。

**切了 PostgreSQL 后，签发时提示记台账失败？**
说明当时没连上（多半是没勾"记住密码"，本次运行还没连接过）。授权文件已经正常
生成，不影响交付；到「台账」页连一下即可，或重新签发一次（会幂等入库）。

---

## 5. 常见问题（FAQ）

**Q：签发页显示的公钥指纹，和设备端不一致？**
说明两边用的不是同一把密钥 —— 设备固件里内置的公钥不是你手上这把私钥对应的公钥。
用**正确的私钥**签发，或请研发把对应公钥注入构建产物（`CHONGMING_LICENSE_PUBKEY`
环境变量或 `license_public.key` 文件）。签出来的授权在这种设备上一定会验签失败。

**Q：台账是空的 / 台账库打不开？**
台账是你**本机**的记录，不会从别处同步。默认路径 `~/.chongming/licenses.db`，
若该文件不存在，点「打开 / 新建」会创建一个空台账。
若提示"结构版本为 X，本程序支持 Y"，说明这个库是另一个版本的工具建的 ——
先用匹配版本导出，或换用对应版本的工具。

**Q：申请码解析失败？**
- 确认是 `CM1-` 开头、三段式、没被截断（提示"校验和不符"就是抄漏了）。
- 让客户重新导出一次再发；换行和空格没问题，工具会自动清理。

**Q：插件列表读不到本项目插件？**
「项目根」要指向项目根目录（该目录下应有 `config/workers/*/config.toml`）。
点「重新加载插件列表」重试；仍读不到时会用常见候选并提示，此时请**手工添加**实际插件 type。

**Q：提示"已签发但记入台账失败"？**
授权文件**已经正常生成**，只是没记进台账。通常是台账库路径不可写或文件被占用。
到「台账」页检查「台账库」路径是否可写，然后手工把这份 `.lic` 补录：签发时不用重签，
用「查看 / 校验」确认文件没问题即可，只是这次要在台账里补一条（或下次签发给同一台设备时自然会入库）。

**Q：客户导入后仍然提示未授权？**
按顺序排查：
1. 公钥指纹是否一致（见上）；
2. 「查看 / 校验」页选「按指定机器」填客户申请码，看结论与原因码（见[附录 A](#附录-a校验原因码全表)）；
3. 设备上的插件 type 是否在授权白名单内（授权插件勾选齐全了吗）；
4. 设备是否**重启过网关**（导入后需重启生效）；
5. 设备系统时间是否被改早过（会触发时钟防线）。

**Q：导出的 CSV 用 Excel 打开中文乱码？**
本工具导出的 CSV 带 UTF-8 BOM，双击不会乱码。若你另存/转存过，可能丢失了 BOM ——
重新从「导出 CSV 清单」导出一次即可。

**Q：误删了台账记录怎么办？**
记录删了就是删了（不影响已发出去的授权文件）。只要那份 `.lic` 还在客户或你手里，
可以到「签发」页按新客户重新签发，或在「查看 / 校验」页确认文件有效后手工补录台账。
**建议定期备份 `licenses.db`**（单文件，拷走即可）。

**Q：一份 license 能给多台设备用吗？**
不能。授权绑定的是机器指纹。多台设备请各签一份（批量场景建议走命令行脚本化）。

**Q：能改一份已经发出去的授权的有效期吗？**
不能改，只能**重新签发**一份新的（用「续期」或重新签发），再让客户导入覆盖。
旧的 `.lic` 在到期日之前仍然有效。

**Q：能改一份已经发出去的授权的授权插件吗？**
也不能改文件本身 —— 授权文件是签名过的，改了签名就失效。正确做法是**重签**：
台账页选中那条 →「改插件…」，勾好新白名单后另存一份新 `.lic` 交给客户导入。
有效期与生效日会**原样保留**，只有白名单变；旧文件在它自己的到期日之前仍然有效
（授权没有吊销机制，只能靠客户导入新文件覆盖）。

**Q：台账库能直接拷走 / 备份吗？**
可以。它是单文件 SQLite，直接复制 `licenses.db` 即可；恢复时拷回原位置或在「台账」页指向它。

**Q：同时开两个窗口操作台账安全吗？**
安全。台账库用 WAL 模式并设了等待超时，可以多开窗口。

**Q：私钥文件的权限真的被保护了吗？**
在 Linux/macOS 上私钥写为 `0600`（仅本人可读写）。**Windows 没有 POSIX 权限位**，
chmod 不生效 —— Windows 上请把私钥放在只有你能访问的目录（例如个人目录而非共享盘），
并依赖磁盘加密与账号权限保护。

---

## 6. 安全须知

| 事项 | 要求 |
| --- | --- |
| 私钥存放 | 只放厂商机器；**离线备份**（U 盘 / 密码管理器 / 保险柜） |
| 私钥分发 | ❌ 绝不进 Git、不进安装包、不进部署产物、不走即时通讯 |
| 私钥丢失 | 无法再签发新授权（已发出去的授权不受影响，直到到期） |
| 私钥泄漏 | 任何人都能签发有效授权 —— 等同于授权体系失效，需更换密钥对并重新部署公钥 |
| 本工具本身 | 厂商侧工具，**不随部署产物分发** |
| 公钥 | 可以公开，需要注入到设备构建产物中 |

**本工具记住了什么**（存于系统配置，方便连续签发）：
私钥**路径**、客户名、备注、密钥标识、默认天数、项目根目录、台账库路径、导出目录、校验用公钥。
**不会记住私钥内容本身。**

---

## 7. 术语表

| 术语 | 含义 |
| --- | --- |
| **机器码** | 由设备硬件指纹算出的短标识，形如 `BC60-D20E-F863-7236-68E2-6A24`（24 位十六进制，4 位一组）。单向哈希，反推不出原始指纹 |
| **申请码** | `CM1-…` 开头的一段文本，包含设备**各来源的原始指纹**。首次申请授权时请客户回传它 |
| **来源指纹** | 设备的各项硬件标识（主板序列号、eMMC CID、CPU 序列号、网卡 MAC、DMI product_uuid、systemd machine-id） |
| **weak 来源** | 同镜像刷机会重复的标识（`machine_id`），**不参与判定**，仅作参考 |
| **公钥指纹** | 公钥的短摘要（16 位十六进制），用来"一眼确认用的是哪把密钥" |
| **kid** | 密钥标识，写在 license 里便于区分签发批次 |
| **台账** | 本机记录已签发授权的 SQLite 库，可用于续期时复用机器指纹 |
| **license / .lic** | 签发给客户的授权文件（JSON 格式，含载荷与 Ed25519 签名） |

---

## 8. 与命令行的对应关系

| 本工具的操作 | 等价命令行 |
| --- | --- |
| 密钥 → 生成密钥对 | `chongming-license keygen` |
| 密钥 → 加载私钥（看公钥/指纹） | `chongming-license keygen` 输出 / `inspect --key` |
| 签发 → 签发并保存 | `chongming-license issue` |
| 查看 / 校验 → 仅查看内容 | `chongming-license inspect` |
| 查看 / 校验 → 校验（按指定机器） | `chongming-license verify --request-code` |
| 台账 → 详情面板 | `chongming-license verify` |
| 台账 → 续期 / 导出 | CLI 的 `registry` 相关子命令 |
| 台账 → 改插件 | `chongming-license issue`（`--plugins` 换白名单，机器码与日期照抄台账） |

**批量签发（一次几十台）建议直接用 CLI 脚本化**；本工具面向单台/少量、
需要人工核对信息的场景。

---

## 附录 A：校验原因码全表

「查看 / 校验」页的「原因码」字段取值与含义：

| 原因码 | 含义 | 怎么办 |
| --- | --- | --- |
| `ok` | 授权有效 | 正常 |
| `license_missing` | 未找到授权文件 | 检查设备上 license 文件路径 |
| `license_malformed` | 授权文件格式错误或内容损坏 | 传输中损坏，重新发送 |
| `signature_invalid` | 签名校验失败（可能被篡改或非本厂商签发） | 核对公钥指纹；确认是本工具签发的 |
| `unsupported_alg` | 用了不支持的签名算法 | 授权文件版本不对，重新签发 |
| `no_public_key` | 设备未配置厂商公钥，无法校验 | 请研发把公钥注入构建产物 |
| `machine_mismatch` | 机器码不匹配（不是为本机签发的） | 用**这台设备**的申请码重新签发 |
| `not_yet_valid` | 授权尚未生效 | 到了生效日期会自动生效 |
| `expired` | 授权已过期 | 续期 |
| `clock_rollback` | 检测到系统时间被回拨，校验中止 | 校正设备时间后重启网关 |
| `plugin_not_licensed` | 该插件不在授权白名单内 | 重新签发并勾选该插件 |
| `fingerprint_unavailable` | 本机无法采集硬件指纹 | 设备环境异常，联系研发 |
| `disabled` | 授权校验未启用（开发/测试模式） | 仅开发/测试环境会出现 |

## 附录 B：授权状态对照

| 状态 | 判定条件（按优先级） |
| --- | --- |
| 未生效 | 生效日期 > 今天 |
| 永久有效 | 没有到期日 |
| 已过期 | 到期日 < 今天 |
| 即将到期 | 到期日 ≤ 今天 + 判定窗口（默认 30 天） |
| 有效 | 其余情况 |

## 附录 C：机器指纹来源

| 来源 | 说明 | 是否参与判定 |
| --- | --- | --- |
| `board_serial` | 主板序列号（设备树/DMI） | ✅ |
| `emmc_cid` | eMMC 芯片 CID | ✅ |
| `cpu_serial` | CPU 序列号 | ✅ |
| `mac` | 物理网卡 MAC（字典序最小那块） | ✅ |
| `product_uuid` | DMI product_uuid | ✅ |
| `machine_id` | systemd machine-id | ❌ weak，仅参考 |

判定规则：只比对 license 与本机**都有**的来源，命中数 ≥ **3** 即认定同一台设备
（双方都只有 weak 来源时会降级纳入判定并在结论里告警）。