341 lines
11 KiB
Markdown
341 lines
11 KiB
Markdown
# Ops Licence 许可证管理系统
|
||
|
||
Ops Licence 是供内部人员使用的离线许可证签发管理系统。系统通过“平台名称 + Workspace”维护授权对象，支持许可证签发、签发记录查询、续期和 `licence.key` 下载，并提供可复制到其他 Go 项目的本地验证 SDK。
|
||
|
||
系统不依赖目标平台调用在线接口。许可证由内部人员在管理页面生成后，手动交付给使用方；使用方通过 Go SDK 在本地完成真实性、授权对象、有效期和配额验证。
|
||
|
||
## 主要功能
|
||
|
||
- 授权对象：以“平台名称 + Workspace”作为唯一授权标识，区分大小写。
|
||
- 直接签发：设置生效日期、到期日期和全部配额，生成并下载许可证文件。
|
||
- 续期：从原签发记录发起，生成一份新的许可证文件，原记录和原文件保持不变。
|
||
- 签发记录：查看签发类型、授权对象、有效期、配额、签发时间和前一份许可证。
|
||
- 再次下载：从历史签发记录重新下载当时生成的许可证文件。
|
||
- 本地验证：Go SDK 不访问许可证管理系统，也不绑定具体机器。
|
||
- 简约 Web 管理界面：前端已经嵌入 Go 可执行文件，无需单独部署静态站点。
|
||
|
||
当前系统不包含登录、会话、在线激活、许可证吊销和机器绑定功能。
|
||
|
||
## 业务规则
|
||
|
||
### 授权对象
|
||
|
||
平台名称与 Workspace 共同组成一个授权对象，两者都不能为空。同一组合不能重复，并且按原始大小写精确匹配。
|
||
|
||
- 没有签发记录时：允许修改、删除。
|
||
- 存在任意签发记录后：禁止修改、删除。
|
||
|
||
### 日期
|
||
|
||
生效日期和到期日期均采用 `YYYY-MM-DD`，按照 `Asia/Shanghai` 自然日判断，首尾日期都包含在有效期内。到期日期不能早于生效日期。
|
||
|
||
### 配额
|
||
|
||
每次直接签发或续期都会保存当次全部配额的完整快照。这里的“全部配额快照”是指：签发记录会固定保存下面 11 个配额在当次签发时的数值，以后不会跟随其他记录变化。续期页面会预填上一份许可证的配额，但提交后会生成新的独立记录。
|
||
|
||
所有配额都是非负整数，`0` 表示该项未授权：
|
||
|
||
| 字段 | 含义 |
|
||
| --- | --- |
|
||
| `max_database` | 数据库数量上限 |
|
||
| `max_middleware` | 中间件数量上限 |
|
||
| `max_network_device` | 网络设备数量上限 |
|
||
| `max_security` | 安全设备数量上限 |
|
||
| `max_storage` | 存储设备数量上限 |
|
||
| `max_pc` | PC 数量上限 |
|
||
| `max_server` | 服务器数量上限 |
|
||
| `max_user` | 用户数量上限 |
|
||
| `max_role` | 角色数量上限 |
|
||
| `max_permission` | 权限数量上限 |
|
||
| `max_menu` | 菜单数量上限 |
|
||
|
||
## 快速启动
|
||
|
||
### 1. 准备 PostgreSQL
|
||
|
||
数据库名称必须精确为 `ops_licence`。服务首次启动时会自动执行内嵌迁移，创建本项目自己的数据表：
|
||
|
||
- `schema_migrations`
|
||
- `authorization_subjects`
|
||
- `signing_keys`
|
||
- `licence_issuances`
|
||
|
||
不需要手工建表，也不会使用其他项目的业务表。
|
||
|
||
### 2. 配置 YAML
|
||
|
||
本地配置文件为 `D:\work\license\etc\license.yaml`。配置只包含服务监听地址、数据库 DSN 和当前签发密钥文件：
|
||
|
||
```yaml
|
||
server:
|
||
listen_addr: "127.0.0.1:8080"
|
||
|
||
database:
|
||
dsn: "postgresql://username:password@127.0.0.1:5432/ops_licence?sslmode=disable"
|
||
|
||
signing:
|
||
private_key_file: "D:\\work\\license\\secrets\\signing-private.pem"
|
||
certificate_file: "D:\\work\\license\\secrets\\signing-certificate.json"
|
||
```
|
||
|
||
注意：
|
||
|
||
- `listen_addr` 必须使用回环 IP，例如 `127.0.0.1:8080`。
|
||
- DSN 必须显式包含用户名、密码、单一主机、端口、数据库名和 `sslmode`。
|
||
- 支持的 `sslmode` 为 `disable`、`require`、`verify-ca`、`verify-full`。
|
||
- 数据库用户名或密码包含特殊字符时，需要使用 URL 百分号编码。
|
||
- DSN 不要添加 `TimeZone` 等额外查询参数。
|
||
- 服务只读取 YAML，不需要配置数据库环境变量；运行用户已有的 `PG*` 数据库连接环境变量需要清除。
|
||
- 签发私钥和签发密钥凭证必须使用绝对路径，并且必须相互匹配。
|
||
|
||
### 3. 启动服务
|
||
|
||
在项目目录执行：
|
||
|
||
```powershell
|
||
.\bin\ops-licence.exe serve --config D:\work\license\etc\license.yaml
|
||
```
|
||
|
||
启动成功后访问：
|
||
|
||
```text
|
||
http://127.0.0.1:8080
|
||
```
|
||
|
||
## 页面操作
|
||
|
||
### 新建授权对象
|
||
|
||
1. 打开“授权对象”。
|
||
2. 点击“新建授权对象”。
|
||
3. 填写平台名称和 Workspace 后保存。
|
||
|
||
如果填写错误，只要该对象还没有签发记录，就可以从详情页修改或删除。
|
||
|
||
### 直接签发
|
||
|
||
1. 打开授权对象详情。
|
||
2. 点击“直接签发”。
|
||
3. 选择生效日期、到期日期并填写全部配额。
|
||
4. 点击“签发并下载”。
|
||
5. 将下载得到的 `{许可证ID}.licence.key` 文件手动交付给使用方。
|
||
|
||
签发成功后记录不可修改、不可删除。
|
||
|
||
### 续期
|
||
|
||
1. 打开“签发记录”。
|
||
2. 进入需要续期的记录详情。
|
||
3. 点击“续期”。
|
||
4. 确认或调整日期和配额。
|
||
5. 提交后下载新生成的 `{许可证ID}.licence.key`。
|
||
|
||
续期不会覆盖旧记录，也不会让旧文件失效；新记录会保存其来源许可证 ID。
|
||
|
||
## 密钥管理
|
||
|
||
许可证采用两级 Ed25519 信任链：
|
||
|
||
1. 根私钥签发“签发密钥凭证”。
|
||
2. 签发私钥签发具体的许可证。
|
||
3. SDK 内置根公钥，先验证签发密钥凭证，再验证许可证签名。
|
||
|
||
根私钥不需要部署到许可证管理服务器。服务器运行时只需要当前签发私钥和对应的签发密钥凭证。
|
||
|
||
### 更换签发密钥
|
||
|
||
使用现有根私钥签发一组新的签发密钥和凭证：
|
||
|
||
```powershell
|
||
.\bin\ops-licence.exe keys issue `
|
||
--root-private D:\keys\root-private.pem `
|
||
--private-out D:\keys\signing-private-2026.pem `
|
||
--certificate-out D:\keys\signing-certificate-2026.json
|
||
```
|
||
|
||
输出文件不能预先存在。生成后修改 YAML 中的两个 `signing` 文件路径并重启服务。
|
||
|
||
更换签发密钥不需要重新生成或复制 SDK，因为新签发密钥仍由同一个根私钥签发。只有主动更换根信任时，才需要更新 SDK 内置根公钥并重新复制 SDK。
|
||
|
||
### 重新建立根信任
|
||
|
||
当前项目已经包含根公钥。下面的命令只用于明确决定更换整套根信任时，不属于日常签发密钥轮换：
|
||
|
||
```powershell
|
||
go run .\cmd\root-keygen `
|
||
--private-out D:\keys\new-root-private.pem `
|
||
--sdk-public-out D:\keys\root_public_key.go
|
||
```
|
||
|
||
生成后需要用新的 `root_public_key.go` 替换 SDK 中的根公钥文件，再用新根私钥签发新的签发密钥。更换根信任后必须重新分发 SDK。
|
||
|
||
## Linux 部署
|
||
|
||
项目提供了 Linux systemd 和 Nginx 配置模板：
|
||
|
||
- `deploy/ops-licence.service`
|
||
- `deploy/nginx.conf`
|
||
|
||
### 文件位置
|
||
|
||
建议按模板放置：
|
||
|
||
```text
|
||
/usr/local/bin/ops-licence
|
||
/etc/ops-licence/ops-licence.yaml
|
||
/etc/ops-licence/keys/signing-private.pem
|
||
/etc/ops-licence/keys/signing-certificate.json
|
||
/var/lib/ops-licence
|
||
```
|
||
|
||
Linux YAML 示例：
|
||
|
||
```yaml
|
||
server:
|
||
listen_addr: "127.0.0.1:8080"
|
||
|
||
database:
|
||
dsn: "postgresql://username:password@database-host:5432/ops_licence?sslmode=disable"
|
||
|
||
signing:
|
||
private_key_file: "/etc/ops-licence/keys/signing-private.pem"
|
||
certificate_file: "/etc/ops-licence/keys/signing-certificate.json"
|
||
```
|
||
|
||
### systemd
|
||
|
||
创建与模板一致的 `ops-licence` 系统用户和目录后，安装并启动服务：
|
||
|
||
```bash
|
||
sudo install -m 0755 dist/ops-licence /usr/local/bin/ops-licence
|
||
sudo install -m 0644 deploy/ops-licence.service /etc/systemd/system/ops-licence.service
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now ops-licence
|
||
sudo systemctl status ops-licence
|
||
```
|
||
|
||
查看运行日志：
|
||
|
||
```bash
|
||
sudo journalctl -u ops-licence -f
|
||
```
|
||
|
||
### Nginx
|
||
|
||
`deploy/nginx.conf` 将 HTTPS 请求反向代理到 `127.0.0.1:8080`。部署时将其中证书路径替换为实际路径，并把配置放入 Nginx 的站点配置目录后重新加载 Nginx。
|
||
|
||
Go 可执行文件已经包含前端资源，Nginx 只需要代理所有路径，不需要另外复制 `web/dist`。
|
||
|
||
## Go SDK 接入
|
||
|
||
将整个 `sdk/licence` 目录复制到目标 Go 项目中，保持目录内所有文件完整。目标项目不需要连接许可证管理系统。
|
||
|
||
使用时传入许可证文件路径，以及目标程序实际使用的平台名称和 Workspace：
|
||
|
||
```go
|
||
result, err := licence.VerifyFile(
|
||
"/etc/example/licence.key",
|
||
licence.Subject{
|
||
PlatformName: "平台名称",
|
||
Workspace: "workspace",
|
||
},
|
||
)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
|
||
databaseLimit := result.Quotas.MaxDatabase
|
||
expiresOn := result.ExpiresOn
|
||
```
|
||
|
||
`VerifyFile` 会一次完成：
|
||
|
||
- 文件格式和大小检查。
|
||
- 根公钥到签发密钥的凭证验证。
|
||
- 许可证签名验证。
|
||
- 平台名称与 Workspace 精确匹配。
|
||
- 按 `Asia/Shanghai` 日期检查是否生效、是否到期。
|
||
- 所有配额非负检查。
|
||
|
||
可以通过 `errors.Is` 区分主要验证结果：
|
||
|
||
```go
|
||
switch {
|
||
case errors.Is(err, licence.ErrNotYetValid):
|
||
// 许可证尚未生效
|
||
case errors.Is(err, licence.ErrExpired):
|
||
// 许可证已经到期
|
||
case errors.Is(err, licence.ErrSubjectMismatch):
|
||
// 平台名称或 Workspace 不匹配
|
||
case errors.Is(err, licence.ErrInvalidSignature):
|
||
// 许可证签名无效
|
||
case err != nil:
|
||
// 文件格式、签发密钥凭证或配额无效
|
||
}
|
||
```
|
||
|
||
复制后，SDK 的 Go 导入路径以目标项目的模块路径为准。
|
||
|
||
## HTTP 接口
|
||
|
||
管理页面使用以下接口，接口不要求登录或会话：
|
||
|
||
| 方法 | 路径 | 用途 |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/v1/dashboard` | 获取首页统计 |
|
||
| `GET` | `/api/v1/subjects` | 查询授权对象 |
|
||
| `POST` | `/api/v1/subjects` | 新建授权对象 |
|
||
| `GET` | `/api/v1/subjects/:id` | 获取授权对象详情 |
|
||
| `PUT` | `/api/v1/subjects/:id` | 修改未签发的授权对象 |
|
||
| `DELETE` | `/api/v1/subjects/:id` | 删除未签发的授权对象 |
|
||
| `POST` | `/api/v1/subjects/:id/licences` | 直接签发并下载许可证 |
|
||
| `GET` | `/api/v1/licences` | 查询签发记录 |
|
||
| `GET` | `/api/v1/licences/:id` | 获取签发记录详情 |
|
||
| `GET` | `/api/v1/licences/:id/download` | 再次下载许可证 |
|
||
| `POST` | `/api/v1/licences/:id/renew` | 续期并下载新许可证 |
|
||
|
||
## 构建
|
||
|
||
构建环境：Go `1.25.1`、Node.js、pnpm。
|
||
|
||
前端构建结果会直接写入 `internal/webui/dist`：
|
||
|
||
```powershell
|
||
Set-Location D:\work\license\web
|
||
pnpm.cmd install
|
||
pnpm.cmd build
|
||
```
|
||
|
||
前端有变化时，先构建前端，再构建 Go 程序。
|
||
|
||
Windows：
|
||
|
||
```powershell
|
||
Set-Location D:\work\license
|
||
go build -buildvcs=false -o bin\ops-licence.exe .\cmd\ops-licence
|
||
```
|
||
|
||
Linux AMD64：
|
||
|
||
```powershell
|
||
Set-Location D:\work\license
|
||
$env:GOOS = "linux"
|
||
$env:GOARCH = "amd64"
|
||
go build -buildvcs=false -o dist\ops-licence .\cmd\ops-licence
|
||
```
|
||
|
||
## 项目目录
|
||
|
||
```text
|
||
cmd/ops-licence 服务与签发密钥命令
|
||
cmd/root-keygen 根密钥生成工具
|
||
deploy Linux systemd 与 Nginx 模板
|
||
docs 设计、实施与使用文档
|
||
etc 本地 YAML 配置
|
||
internal 服务端实现、数据库迁移和内嵌前端
|
||
sdk/licence 可复制的 Go 本地验证 SDK
|
||
web Vue 管理界面源码
|
||
bin Windows 可执行文件
|
||
dist Linux 可执行文件
|
||
```
|