modify: 授权

README.md

@@ -29,6 +29,7 @@
 | **构建打包**          | PyInstaller / Nuitka 一键打包为独立可执行文件                        |
 | **Vue 3 前端**        | Element Plus UI、Pinia 状态管理、类型安全的 API 客户端               |
 | **Worker 运维管理**   | 前端经 Zenoh 向单个副本下发 restart/stop/改配置指令（超管），前端可视化列表 + 分页管理 |
+| **机器码授权**        | 离线 Ed25519 签名 license：绑定机器指纹 + 插件白名单 + 有效期，未授权插件不加载 |
 
 ---
 
@@ -356,6 +357,56 @@ external 副本走同一 `__admin__` Queryable，路由发现、指令下发与
 
 ---
 
+## 机器码授权
+
+按客户设备「机器码」签发授权：**一份 license 绑定一台机器 + 一批插件 + 有效期**，
+未授权的插件不加载、不注册路由、管理接口禁止操作。**纯离线** —— 设备用内置厂商公钥验签，
+运行期零联网（与 Zenoh localhost、Caddy `tls internal` 的 air-gapped 形态一致）。
+
+> 📖 **完整指南见 [docs/license.md](docs/license.md)** —— 密钥管理、激活流程、
+> 命令行参考、可视化工具、机器指纹与容错判定、强制执行点、安全边界、
+> 故障排查（含原因码全表）。下面只保留最小上手路径。
+>
+> 厂商侧有**两种等价工具**（共用同一份实现）：不习惯命令行的话用可视化工具
+> —— `cd utils/license-gui && uv sync && uv run chongming-license-gui`（签发 / 密钥 / 校验三页）。
+
+### 最小上手路径
+
+```bash
+# ① 厂商侧：生成密钥对（一次性）。私钥离线保管并备份，绝不进仓库/产物
+uv run chongming-license keygen -o license_private.pem
+#   → 输出公钥，按提示注入构建（CHONGMING_LICENSE_PUBKEY 环境变量 / license_public.key 文件）
+#   → 打包时缺少公钥会直接失败：缺公钥的产物会拒绝加载所有插件，等于砖头
+
+# ② 设备侧：浏览器打开 http://<设备IP>:8000/static/license，登录后「复制申请码」
+
+# ③ 厂商侧：签发
+uv run chongming-license issue --request-code "CM1-客户发来的..." \
+    --plugins aibox_sophon_adapter,ip_sound_column \
+    --customer "某某科技" --days 365 -k license_private.pem -o license.lic
+
+# ④ 设备侧：同一页面「导入并校验」→「重启网关」生效
+```
+
+签发会**自动记入台账**（`~/.chongming/licenses.db`，含机器指纹）。续期时直接复用，
+**无需再向客户索取申请码**：
+
+```bash
+uv run chongming-license list                      # 台账检索（按到期日升序）
+uv run chongming-license renew --lic-id L2026... --days 365 -k license_private.pem
+uv run chongming-license export --out ./archive --csv ./台账.csv --by-customer
+```
+
+### 三条需要记住的约束
+
+- **申请码 vs 机器码**：机器码是短哈希，只报它只能签出**精确匹配**的授权（换网卡即失效）。
+  申请码带回各来源原始值，才能签出支持换硬件的**容错**授权。
+- **开发态默认不执行拒绝**：`[license] enabled` 默认 `false`，改配置也绕不过（打包产物恒为强制校验，
+  依据 `sys.frozen`/`__compiled__` 判定）。开发时想验证门禁需手动改成 `true`。
+- **设备侧没有签发命令**：`chongming-cli` 是开发依赖，不随产物发布 —— 签发能力只存在于厂商机器上。
+
+---
+
 ## 端点类型与路由注册
 
 ### 端点类型
@@ -859,5 +910,6 @@ uv pip install -e utils/<name>            # 安装/更新工具包子包
 - [配置说明](config/README.md)
 - [插件开发指南](src/plugins/README.md)
 - [进程插件开发指南（external 模式，从开发到部署）](docs/process-plugin.md)
+- [机器码授权指南（密钥管理 / 激活流程 / 故障排查）](docs/license.md)
 - [前端开发指南](src/chongming-web/README.md)
 - [Worker 框架](utils/worker/README.md)