chongming-license-gui/docs/使用手册.md

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

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

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

---

1. 三十秒认识这个工具

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

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

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

⚠️ 两件事必须记住

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

---

2. 三步上手

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

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

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

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

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

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

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

第三步：签发

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

把生成的 .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 台账页

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

台账库

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

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

筛选

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

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

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

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

行操作

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

续期对话框长这样：

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

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

• 顶部「原授权」是只读摘要（编号 / 客户 / 机器码 / 有效期 / 指纹个数）， 下面的勾选列表与签发页是同一个组件：项目里 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（比如客户反馈"导入失败"，或你要发货前自检）时用这一页。

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

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

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

---

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 的安装与运行）。
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）；
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 来源时会降级纳入判定并在结论里告警）。