modify: 台账更改插件
This commit is contained in:
@@ -1,10 +1,20 @@
|
||||
# chongming-license-gui
|
||||
|
||||
机器码授权的**可视化工具（厂商侧）**：密钥管理 / 签发 / 查看校验。
|
||||
机器码授权的**可视化工具（厂商侧）**：密钥管理 / 签发 / 台账 / 查看校验。
|
||||
|
||||
供商务、售后等不习惯命令行的同学使用，功能与 `uv run chongming-license`（CLI）对等。
|
||||
所有授权逻辑都调用 [`chongming-license`](../license/) 库 —— 本包**只做界面**，
|
||||
不重复实现密码学、载荷格式或规范化（一旦有两处实现，就会出现"自己签的自己验不过"）。
|
||||
供商务、售后等不习惯命令行的同学使用。所有授权逻辑都调用
|
||||
[`chongming-license`](https://pypi.org/project/chongming-license/)（内部包）——
|
||||
本包**只做界面**，不重复实现密码学、载荷格式或规范化（一旦有两处实现，
|
||||
就会出现"自己签的自己验不过"）。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 读者 | 内容 |
|
||||
| --- | --- | --- |
|
||||
| [docs/使用手册.md](docs/使用手册.md) | 商务 / 售后 / 技术支持 | 三步上手、逐字段说明、场景速查、FAQ、原因码全表 |
|
||||
| [docs/界面设计.md](docs/界面设计.md) | 维护界面的人 | 设计 token、控件规范、如何改主题、维护红线 |
|
||||
| [packaging/README.md](packaging/README.md) | 出包的人 | 打包成免安装 exe（PyInstaller / Nuitka）、安全闸门、产物自检 |
|
||||
| 本文 | 研发 / 集成 | 定位、安装运行、安全边界、与 CLI 对照 |
|
||||
|
||||
## 定位
|
||||
|
||||
@@ -16,95 +26,134 @@
|
||||
|
||||
**本工具不随部署产物分发** —— 签发私钥只应存在于厂商机器上。
|
||||
|
||||
## 界面
|
||||
|
||||
|
||||
|
||||
界面为现代浅色卡片风：白底卡片分区、主色 `#2563eb`、状态色规范化
|
||||
（过期红 / 即将到期橙 / 有效绿 / 永久蓝 / 未生效紫）、全套图标与悬停/焦点态。
|
||||
四个页签都套了滚动容器，小屏（1366×768）上不会再出现底部按钮被截断的情况。
|
||||
|
||||
样式集中在 `theme.py`（token + QSS）与 `icons.py`（内联 SVG，无二进制素材），
|
||||
改主题见 [docs/界面设计.md](docs/界面设计.md)。
|
||||
|
||||
## 安装与运行
|
||||
|
||||
```bash
|
||||
cd utils/license-gui
|
||||
uv sync
|
||||
uv run chongming-license-gui
|
||||
```
|
||||
|
||||
依赖 `chongming-license` 从内部索引拉取（见 `pyproject.toml` 的 `[[tool.uv.index]]`）。
|
||||
若在同仓并行开发该库，可改用 `pyproject.toml` 里注释掉的 path 依赖
|
||||
（**必须带 `editable = true`**，否则改库代码后需重新 `sync` 才生效）。
|
||||
|
||||
无图形环境（SSH / CI）下可做冒烟检查：
|
||||
|
||||
```bash
|
||||
QT_QPA_PLATFORM=offscreen uv run python -c "
|
||||
from PySide6.QtWidgets import QApplication
|
||||
from chongming_license_gui.app import MainWindow
|
||||
app = QApplication([]); w = MainWindow(); w.show()
|
||||
print('界面构建成功')
|
||||
"
|
||||
QT_QPA_PLATFORM=offscreen uv run python smoke_test.py
|
||||
```
|
||||
|
||||
## 三个页面
|
||||
该脚本驱动**真实控件**跑完整流程（生成密钥 → 解析申请码 → 预览 → 签发 →
|
||||
查看校验（目标机通过、异机拒绝）→ 台账入库/检索/续期/改插件/导出/删除），
|
||||
并包含一组界面主题断言（样式是否真的渲染、指示器是否会变空白）。
|
||||
在 Windows / macOS 上它会自动改用合成指纹（硬件指纹来源都是 Linux 侧的）。
|
||||
|
||||
### 签发（默认页）
|
||||
## 四个页面
|
||||
|
||||
日常最高频的操作。让操作者在**按下签发之前**就看清"给谁、哪台机器、哪些插件、多久"。
|
||||
- **签发**（默认页）：私钥状态 → 签发依据（申请码 / 来源 JSON / 仅机器码）→
|
||||
勾选授权插件 → 填写授权信息 → 载荷预览 → 签发并保存（可自动记入台账）。
|
||||
设计目标是让你**在按下签发之前**看清"给谁、哪台设备、哪些插件、多久"。
|
||||
- **台账**：已签发授权的检索、**续期**（复用台账指纹，无需再向客户索取申请码）、
|
||||
**改插件**（只换插件白名单重签，有效期与生效日原样保留）、
|
||||
备注批注、详情查看、`.lic` 与 CSV 导出。默认库 `~/.chongming/licenses.db`（单文件 SQLite）。
|
||||
- **密钥**：生成/加载 Ed25519 密钥对，显示公钥（base64 / PEM）与公钥指纹。
|
||||
- **查看 / 校验**：查看 `.lic` 内容、验签，并按"本机"或"指定机器（客户申请码）"
|
||||
做指纹比对 —— 后者是**发货前自检**的关键。
|
||||
|
||||
- **签名私钥**：显示当前生效的私钥路径与公钥指纹（签发前核对，避免拿错密钥）
|
||||
- **签发依据**（三选一）：
|
||||
- *申请码*（推荐）—— 粘贴 `CM1-...`，自动解析出机器码与各来源指纹，支持换硬件容错
|
||||
- *来源 JSON 文件* —— `show --json` 的导出文件
|
||||
- *仅机器码* —— 精确匹配、无容错（界面会明确警示）
|
||||
- **授权插件**：勾选式列表，自动从 `<项目根>/config/workers/*/config.toml` 读出本项目实际插件；
|
||||
也可手工添加任意 type；支持全选/全不选/移除
|
||||
- **授权信息**：客户、授权编号（留空自动生成）、备注、密钥标识、有效期（N 天 / 指定日期 / 永久）
|
||||
- **预览与签发**：载荷 JSON 预览（与签名用的是同一个对象，所见即所签）→ 签发并保存
|
||||
每个字段的详细说明见 [docs/使用手册.md](docs/使用手册.md)。
|
||||
|
||||
### 台账
|
||||
## 台账存储：本地 SQLite 或共享 PostgreSQL
|
||||
|
||||
已签发授权的检索与管理。**签发页签发的每一份都会自动入库**（含机器指纹）。
|
||||
台账默认是**本机单文件**（SQLite）。团队若想共用一份台账（谁签给了谁、哪台设备
|
||||
快到期，不用互相问），可在「台账」页把「存储」切到 **PostgreSQL**（默认端口 5432）：
|
||||
|
||||
- **检索**：客户 / 机器码 / 插件 / 状态 / 关键字 / 即将到期窗口；按到期日升序，最急的在前
|
||||
- **概览**：总数与有效/即将到期/已过期/永久/未生效计数
|
||||
- **续期**：选中一条 →「续期选中…」→ 只改要变的部分 → 续期并保存。
|
||||
**指纹复用自台账，无需再向客户索取申请码**；默认生成新编号（新旧都留台账可追溯），
|
||||
旧记录自动加上 `已续期 → <新编号>` 批注
|
||||
- **备注**：人工批注，重新导入 license 不会覆盖（载荷里的 `note` 是签名内容的一部分，
|
||||
台账的 `note` 是厂商自己的批注）
|
||||
- **详情**：查看各来源指纹与**原始 license 文件内容**（当初签发的那份）
|
||||
- **导出**：`.lic`（可选按客户分目录）+ CSV 清单（UTF-8 BOM，Excel 中文不乱码）
|
||||
- **可选功能**，不装驱动照样能用本地台账；
|
||||
- 首次连接**自动建表**；账号无建表权限时用 `docs/pg_schema.sql` 交给 DBA 执行；
|
||||
- 密码**默认不保存**，勾选"记住密码"才写入本机配置（有明文警示）；
|
||||
- 密码不会出现在日志、标签或错误信息里；DSN 传递用 kwargs，异常不回显凭据。
|
||||
|
||||
台账库默认 `~/.chongming/licenses.db`，可在此页切换；单文件 SQLite，可直接进备份。
|
||||
```bash
|
||||
uv sync --extra postgres # 启用 PG 支持（打包产物用 dev 依赖，已包含）
|
||||
```
|
||||
|
||||
### 密钥
|
||||
**关于"PG 后端是否可靠"**：不是推测 —— `tools/pg_check.py` 会用**同一套契约**
|
||||
分别跑本地 SQLite 与 PostgreSQL 并逐项对比，全程在一个事务里、最后 `ROLLBACK`
|
||||
（连建表都回滚，对真实库零残留）：
|
||||
|
||||
- **生成密钥对**：一键生成 Ed25519 密钥对，私钥写为 `0600` 的 PEM，
|
||||
公钥自动复制到剪贴板（下一步注入构建就要用）
|
||||
- **加载现有私钥**：显示对应公钥与指纹，用于确认"这把私钥对应哪把公钥"
|
||||
- 公钥 base64（可直接填进 `[license] public_key`）与 PEM 都可单独复制
|
||||
```bash
|
||||
uv run python tools/pg_check.py --host 127.0.0.1 --port 5432 \
|
||||
--dbname chongming --user postgres # 密码走 PGPASSWORD 或交互输入
|
||||
```
|
||||
|
||||
### 查看 / 校验
|
||||
|
||||
- 打开 `.lic` 查看全部字段（不验签也能看）
|
||||
- 填公钥后验签，给出结论 + 原因码 + 命中/不匹配的来源
|
||||
- **指纹比对基准**可选：
|
||||
- *本机指纹* —— 在厂商机器上通常对不上，属正常
|
||||
- *指定机器*（填客户设备的申请码）—— **发货前自检**的关键：
|
||||
确认这份 license 确实是为目标设备签发的，而不是只验出"签名有效"
|
||||
已在 PostgreSQL 16 上跑通全部 19 项对比（排序/过滤大小写/状态分桶/批注与入库时间
|
||||
保留/导出文件名与 CSV 编码/删除），GUI 实际路径（`holder.open_postgres` → 自动建表
|
||||
→ 入库 → 重连 → 版本校验 → 导出）也做了端到端验证。细节见
|
||||
[docs/使用手册.md 4.9](docs/使用手册.md)。
|
||||
|
||||
## 与 CLI 的对应关系
|
||||
|
||||
CLI（`chongming-license`）由 `chongming-license` 包提供，**本仓不安装它**
|
||||
（当前环境里没有该命令）。装了 CLI 的环境可按下表对照：
|
||||
|
||||
| GUI 操作 | CLI |
|
||||
| --- | --- |
|
||||
| 详情面板 / 状态栏 | `chongming-license verify` |
|
||||
| 签发 → 签发并保存 | `chongming-license issue` |
|
||||
| 密钥 → 生成密钥对 | `chongming-license keygen` |
|
||||
| 密钥 → 加载私钥（显示公钥/指纹） | `chongming-license keygen` 的输出 / `inspect --key` |
|
||||
| 密钥 → 加载私钥（显示公钥/指纹） | 同上输出 / `inspect --key` |
|
||||
| 查看 / 校验 → 仅查看内容 | `chongming-license inspect` |
|
||||
| 查看 / 校验 → 指定机器 | `chongming-license verify --request-code` |
|
||||
| 查看 / 校验 → 按指定机器 | `chongming-license verify --request-code` |
|
||||
| 台账 → 详情面板 | `chongming-license verify` |
|
||||
| 台账 → 改插件 | `chongming-license issue`（`--plugins` 换白名单，机器码与日期照抄台账） |
|
||||
|
||||
批量签发（一次几十台）建议直接用 CLI 脚本化；GUI 面向单台/少量、需要人工核对信息的场景。
|
||||
|
||||
## 开发
|
||||
|
||||
```bash
|
||||
uv run python smoke_test.py # 全流程 + 主题断言（无头）
|
||||
uv run python tools/screenshot.py # 重新生成 docs/images/ 里的文档截图
|
||||
```
|
||||
|
||||
截图脚本会重定向 `QSettings` 与台账库到临时目录、当场生成一次性密钥，
|
||||
**不接触真实的私钥、台账与配置**。
|
||||
|
||||
## 打包分发
|
||||
|
||||
```bash
|
||||
uv sync --group dev # 装打包工具
|
||||
uv run python packaging/build_pyinstaller.py # 方式一：快，约 2.5 分钟
|
||||
uv run python packaging/build_nuitka.py # 方式二：真编译，更小更快但慢
|
||||
```
|
||||
|
||||
产物在 `dist/`，是**免安装单文件 exe**，发给厂商内部同事用。两个脚本都自带：
|
||||
|
||||
- **私钥守卫**：源码树里出现私钥 / `*.lic` / `licenses.db` 时**中止构建** ——
|
||||
这个工具含签发能力，私钥随包发出去等于任何人都能签发授权；
|
||||
- **产物自检**：构建后自动跑 `<exe> --selftest`，并在 **offscreen 与系统原生两个
|
||||
平台插件**下各验一遍（后者才证明 Qt 的平台插件真的打进产物了），覆盖 QtSvg、
|
||||
复选框指示器、Ed25519 签发验签、orjson、台账、插件发现与整窗渲染。
|
||||
|
||||
细节、两种方式的取舍与趟坑见 [packaging/README.md](packaging/README.md)。
|
||||
|
||||
## 安全注意
|
||||
|
||||
- 本工具会在 `QSettings` 里记住**私钥路径、客户名、备注、输出目录**（便于连续签发），
|
||||
- 本工具会在 `QSettings` 里记住**私钥路径、客户名、备注、输出目录**等（便于连续签发），
|
||||
**不会**记住私钥内容本身。
|
||||
- 私钥文件权限为 `0600`，且 `.gitignore` 忽略 `license_private*.pem`。
|
||||
- `uv run build` 会扫描构建产物，发现私钥即终止构建。
|
||||
- 私钥在 Linux/macOS 上写为 `0600`。⚠ **Windows 没有 POSIX 权限位**，`chmod` 不生效 ——
|
||||
Windows 上请把私钥放在只有你能访问的目录，并依赖磁盘加密与账号权限。
|
||||
- 本仓 `.gitignore` 已忽略私钥与台账产物（`license_private*.pem`、`*_private.pem`、
|
||||
`*.lic`、`licenses.db`），但这只是**兜底**：真正的防线是不要把私钥放进仓库目录。
|
||||
- 发布/发包前请自行确认产物中不含私钥与台账库
|
||||
（本仓没有构建脚本钩子；上游项目的构建脚本才有"扫到私钥即终止"的守护检查）。
|
||||
- ⚠ 私钥丢失 = 无法再签发新授权；私钥泄漏 = 任何人都能签发授权。请离线备份。
|
||||
|
||||
## 完整文档
|
||||
|
||||
见仓库 [docs/license.md](../../docs/license.md)：激活流程、命令行参考、机器指纹与容错判定、
|
||||
强制执行点、安全边界、故障排查（含原因码全表）。
|
||||
|
||||
Reference in New Issue
Block a user