160 lines
8.3 KiB
Markdown
160 lines
8.3 KiB
Markdown
# chongming-license-gui
|
||
|
||
机器码授权的**可视化工具（厂商侧）**：密钥管理 / 签发 / 台账 / 查看校验。
|
||
|
||
供商务、售后等不习惯命令行的同学使用。所有授权逻辑都调用
|
||
[`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 对照 |
|
||
|
||
## 定位
|
||
|
||
| | 使用者 | 形态 | 签发能力 |
|
||
| --- | --- | --- | --- |
|
||
| **本工具** | 厂商（商务/售后/研发） | 桌面 GUI | ✅ 持有私钥 |
|
||
| `chongming-license` CLI | 厂商（研发/自动化） | 命令行 | ✅ 持有私钥 |
|
||
| 设备端「授权」页 | 客户 / 现场装机 | 浏览器 `/static/license` | ❌ 只导出申请码、导入 license |
|
||
|
||
**本工具不随部署产物分发** —— 签发私钥只应存在于厂商机器上。
|
||
|
||
## 界面
|
||
|
||
|
||
|
||
界面为现代浅色卡片风：白底卡片分区、主色 `#2563eb`、状态色规范化
|
||
（过期红 / 即将到期橙 / 有效绿 / 永久蓝 / 未生效紫）、全套图标与悬停/焦点态。
|
||
四个页签都套了滚动容器，小屏（1366×768）上不会再出现底部按钮被截断的情况。
|
||
|
||
样式集中在 `theme.py`（token + QSS）与 `icons.py`（内联 SVG，无二进制素材），
|
||
改主题见 [docs/界面设计.md](docs/界面设计.md)。
|
||
|
||
## 安装与运行
|
||
|
||
```bash
|
||
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 smoke_test.py
|
||
```
|
||
|
||
该脚本驱动**真实控件**跑完整流程（生成密钥 → 解析申请码 → 预览 → 签发 →
|
||
查看校验（目标机通过、异机拒绝）→ 台账入库/检索/续期/改插件/导出/删除），
|
||
并包含一组界面主题断言（样式是否真的渲染、指示器是否会变空白）。
|
||
在 Windows / macOS 上它会自动改用合成指纹（硬件指纹来源都是 Linux 侧的）。
|
||
|
||
## 四个页面
|
||
|
||
- **签发**（默认页）：私钥状态 → 签发依据（申请码 / 来源 JSON / 仅机器码）→
|
||
勾选授权插件 → 填写授权信息 → 载荷预览 → 签发并保存（可自动记入台账）。
|
||
设计目标是让你**在按下签发之前**看清"给谁、哪台设备、哪些插件、多久"。
|
||
- **台账**：已签发授权的检索、**续期**（复用台账指纹，无需再向客户索取申请码）、
|
||
**改插件**（只换插件白名单重签，有效期与生效日原样保留）、
|
||
备注批注、详情查看、`.lic` 与 CSV 导出。默认库 `~/.chongming/licenses.db`（单文件 SQLite）。
|
||
- **密钥**：生成/加载 Ed25519 密钥对，显示公钥（base64 / PEM）与公钥指纹。
|
||
- **查看 / 校验**：查看 `.lic` 内容、验签，并按"本机"或"指定机器（客户申请码）"
|
||
做指纹比对 —— 后者是**发货前自检**的关键。
|
||
|
||
每个字段的详细说明见 [docs/使用手册.md](docs/使用手册.md)。
|
||
|
||
## 台账存储：本地 SQLite 或共享 PostgreSQL
|
||
|
||
台账默认是**本机单文件**（SQLite）。团队若想共用一份台账（谁签给了谁、哪台设备
|
||
快到期，不用互相问），可在「台账」页把「存储」切到 **PostgreSQL**（默认端口 5432）：
|
||
|
||
- **可选功能**，不装驱动照样能用本地台账；
|
||
- 首次连接**自动建表**；账号无建表权限时用 `docs/pg_schema.sql` 交给 DBA 执行；
|
||
- 密码**默认不保存**，勾选"记住密码"才写入本机配置（有明文警示）；
|
||
- 密码不会出现在日志、标签或错误信息里；DSN 传递用 kwargs，异常不回显凭据。
|
||
|
||
```bash
|
||
uv sync --extra postgres # 启用 PG 支持（打包产物用 dev 依赖，已包含）
|
||
```
|
||
|
||
**关于"PG 后端是否可靠"**：不是推测 —— `tools/pg_check.py` 会用**同一套契约**
|
||
分别跑本地 SQLite 与 PostgreSQL 并逐项对比，全程在一个事务里、最后 `ROLLBACK`
|
||
（连建表都回滚，对真实库零残留）：
|
||
|
||
```bash
|
||
uv run python tools/pg_check.py --host 127.0.0.1 --port 5432 \
|
||
--dbname chongming --user postgres # 密码走 PGPASSWORD 或交互输入
|
||
```
|
||
|
||
已在 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 issue` |
|
||
| 密钥 → 生成密钥对 | `chongming-license keygen` |
|
||
| 密钥 → 加载私钥（显示公钥/指纹） | 同上输出 / `inspect --key` |
|
||
| 查看 / 校验 → 仅查看内容 | `chongming-license inspect` |
|
||
| 查看 / 校验 → 按指定机器 | `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` 里记住**私钥路径、客户名、备注、输出目录**等（便于连续签发），
|
||
**不会**记住私钥内容本身。
|
||
- 私钥在 Linux/macOS 上写为 `0600`。⚠ **Windows 没有 POSIX 权限位**，`chmod` 不生效 ——
|
||
Windows 上请把私钥放在只有你能访问的目录，并依赖磁盘加密与账号权限。
|
||
- 本仓 `.gitignore` 已忽略私钥与台账产物（`license_private*.pem`、`*_private.pem`、
|
||
`*.lic`、`licenses.db`），但这只是**兜底**：真正的防线是不要把私钥放进仓库目录。
|
||
- 发布/发包前请自行确认产物中不含私钥与台账库
|
||
（本仓没有构建脚本钩子；上游项目的构建脚本才有"扫到私钥即终止"的守护检查）。
|
||
- ⚠ 私钥丢失 = 无法再签发新授权；私钥泄漏 = 任何人都能签发授权。请离线备份。
|