# 根哥软件开发 · 开发者管理后台 — 第三方软件接入文档
> 本管理后台基于 EdgeOne Pages + Functions + KV 构建，为多品牌 SaaS 软件提供统一的品牌注册、等级控制、升级码配额管理、审计追踪能力。任何符合本接入规范的客户端软件，均可被本后台统一管控。
>
> 当前版本：v2.0 | 最后更新：2026-08-05 | 域名：admin.ligen.cn
## 目录
1. 快速开始
2. 认证鉴权
3. 品牌注册表
4. 平台签名通道
5. 数据面代理
6. Provision 初始化
7. 环境变量参考
8. 错误码参考
9. 品牌数据模型
10. 完整接入清单
---
## 1. 快速开始
接入本管理后台后，你的软件将获得以下能力：
- **品牌注册与隔离** — 每个品牌独立数据库、独立凭证、独立配额
- **等级上限控制** — 超管设 maxLicenseLevel，品牌方不得越级发放升级码
- **升级码配额管理** — trial/pro/enterprise 三档配额，自动核销与扣减
- **全链路审计** — 关键操作（查看密码、调整配额等）自动留痕
- **数据面代理** — 控制面转发请求到你的 NestJS/后端，由你自行处理业务
```
┌─ 管理后台 (admin.ligen.cn) ───────────────────┐
│ EdgeOne Pages + Functions + KV │
│ 品牌注册表 / 等级上限 / 配额管理 / 审计 │
└──────────────────┬──────────────────────────────┘
│ Bearer Token / HMAC-SHA256
▼
┌─ 你的数据面 (NestJS / 任意后端) ────────────────┐
│ EXE 客户端 → POST /api/v1/provision/init │
│ → 写入品牌独立 MySQL + COS 配置 │
│ → 返回初始化结果 │
└──────────────────┬──────────────────────────────┘
│
┌─ 品牌 EXE 客户端 ──────────────────────────────┐
│ 本地 SQLite + 远程数据面 │
│ 可离线使用本地功能 │
└─────────────────────────────────────────────────┘
```
> 接入本管理后台 **不需要** 你部署任何额外数据库或服务器。你只需在软件中实现规定的 HTTP 接口，即可被后台统一管控。
## 2. 认证鉴权
### 2.1 超管登录（管理后台自身）
```
POST /api/auth/login HTTP/1.1
Host: admin.ligen.cn
Content-Type: application/json
{
"username": "super_admin",
"password": "你的超管密码"
}
// 响应
{
"accessToken": "eyJ...",
"refreshToken": "rft_...",
"expiresIn": 3600
}
```
### 2.2 后续请求携带 Token
```
GET /api/tenants HTTP/1.1
Host: admin.ligen.cn
Authorization: Bearer eyJ...
```
### 2.3 品牌方登录（数据面）
品牌方管理员账号由超管在后台创建品牌时自动生成（格式 `admin@品牌key`）。品牌方通过你的数据面登录接口完成认证。控制面只存管理员初始密码（一次性交付），后续认证全由数据面接管。
## 3. 品牌注册表
### 3.1 数据面读取品牌列表
数据面启动后，通过控制面 API 拉取所有已创建的品牌配置（含加密的数据库连接串、COS 凭证），按 `brandKey` 建立动态路由。
```
GET /api/registry/brands HTTP/1.1
Host: admin.ligen.cn
Authorization: Bearer {your_registry_token}
// 响应
{
"data": [{
"brandKey": "heaifei",
"brandName": "河爱非遗",
"status": "active",
"dbHost": "127.0.0.1",
"dbPort": 3306,
"dbName": "feiyi_heaifei",
"dbUser": "feiyi_heaifei",
"dbPasswordEncrypted": "AES-256-GCM密文...",
"storage": {
"bucket": "heaifei-1234567890",
"region": "ap-guangzhou",
"secretIdEncrypted": "...",
"secretKeyEncrypted": "..."
},
"maxLicenseLevel": "pro",
"quotas": {
"trial": { "total": 50, "used": 3, "remaining": 47 },
"pro": { "total": 200, "used": 12, "remaining": 188 },
"enterprise": { "total": 1000, "used": 0, "remaining": 1000 }
}
}]
}
```
> 注册表接口使用独立 Token（非超管登录 Token），需在 EdgeOne 环境变量 `REGISTRY_TOKEN` 配置，与超管会话隔离。
## 4. 平台签名通道
### 4.1 签名机制
当你的客户端/数据面需要以高权限操作品牌配置时（如更新配额、查看管理员密码），控制面会验证 HMAC-SHA256 签名。
```js
const crypto = require('crypto');
function sign(payload, secret) {
const timestamp = Date.now().toString();
const body = typeof payload === 'string' ? payload : JSON.stringify(payload);
const signature = crypto
.createHmac('sha256', secret)
.update(timestamp + '\n' + body)
.digest('hex');
return { timestamp, signature };
}
// 使用时附加到请求头:
// X-Platform-Timestamp: 1691234567890
// X-Platform-Signature: 3f8c2a...
```
签名密钥 `PLATFORM_SECRET` 配置在 EdgeOne 环境变量中，由你设定并与控制面共享。
## 5. 数据面代理
### 5.1 用途
控制面可将部分请求透明转发到你的数据面（如品牌方初始化数据库、生成升级码等），无需品牌客户端直连你的公网服务。
```
POST /api/proxy/heaifei/v1/brands/heaifei/upgrade-codes HTTP/1.1
Host: admin.ligen.cn
Authorization: Bearer {超管Token}
Content-Type: application/json
{
"level": "pro",
"quantity": 10
}
// 控制面验证权限后，以 {brandKey} 对应的 apiBaseUrl 转发:
// POST {品牌apiBaseUrl}/api/v1/brands/heaifei/upgrade-codes
```
> 代理仅在品牌创建时填写了 `apiBaseUrl` 时才生效。如果你的数据面不对外暴露，可不开放此通道。
## 6. Provision 初始化
### 6.1 品牌初始化流程
1. 超管在后台创建品牌条目（brandKey + 等级上限 + 配额）
2. 品牌方拿到管理员账号密码，登录 EXE 客户端
3. EXE 通过数据面 `POST /api/v1/provision/init` 上报品牌自有的 MySQL / COS 配置
4. 数据面验证后，写回控制面 KV 中的 `dbHost/dbPasswordEncrypted/storage` 字段
5. 此后数据面启动时从注册表拉取完整配置，动态路由到品牌数据库
```
POST /api/v1/provision/init HTTP/1.1
Host: {你的数据面地址}
Content-Type: application/json
Authorization: Bearer {品牌方Token}
{
"brandKey": "heaifei",
"dbConfig": {
"host": "10.0.0.1",
"port": 3306,
"database": "feiyi_heaifei",
"username": "root",
"password": "品牌方自己的MySQL密码"
},
"storageConfig": {
"bucket": "heaifei-cos",
"region": "ap-guangzhou",
"secretId": "AKID...",
"secretKey": "..."
}
}
// 响应
{
"success": true,
"message": "品牌 heaifei 已初始化",
"dbUrlMasked": "10.0.*.*:3306/feiyi_heaifei"
}
```
数据面处理完成后，需调用控制面 API 更新品牌状态为 `active`:
```
PUT /api/tenants/heaifei HTTP/1.1
Host: admin.ligen.cn
Authorization: Bearer {超管Token}
Content-Type: application/json
{
"op": "status",
"status": "active"
}
```
## 7. 环境变量参考
| 变量名 | 用途 | 必填 |
|---|---|---|
| TENANT_SECRET_KEY | KEK 主密钥，用于加密品牌数据库密码等敏感字段 (AES-256-GCM) | ✅ |
| REGISTRY_TOKEN | 数据面拉取品牌注册表的 Bearer Token（独立于超管会话） | ✅ |
| PLATFORM_SECRET | HMAC-SHA256 签名密钥（跨服务互信） | ✅ |
| JWT_SECRET | 超管 JWT 签名密钥 | ✅ |
| REFRESH_SECRET | Refresh Token 签名密钥 | ✅ |
| SESSION_TTL | 超管会话有效期（秒），默认 3600 | ❌ |
| AUDIT_RETENTION_DAYS | 审计日志保留天数，默认 90 | ❌ |
| RATE_LIMIT_PER_MINUTE | 每分钟请求限制，默认 100 | ❌ |
> 所有环境变量在 EdgeOne Pages 控制台 → 环境变量中配置，无需 .env 文件。
## 8. 错误码参考
| 错误码 | HTTP 状态 | 含义 |
|---|---|---|
| UNAUTHORIZED | 401 | 未登录或 Token 过期 |
| FORBIDDEN | 403 | 无权限执行此操作 |
| RESOURCE_NOT_FOUND | 404 | 品牌/资源不存在 |
| VALIDATION_FAILED | 400 | 参数校验失败（message 中含具体字段） |
| INVALID_PARAMETER | 400 | 参数取值非法（如不支持的 action） |
| CONFLICT | 409 | brandKey 重复或状态冲突 |
| RATE_LIMITED | 429 | 请求频率超限 |
| QUOTA_EXCEEDED | 400 | 升级码配额不足 |
| LEVEL_LIMITED | 400 | 超出品牌等级上限（maxLicenseLevel） |
| INTERNAL_ERROR | 500 | 服务端内部错误 |
```
{
"error": "VALIDATION_FAILED",
"message": "brandKey 仅支持小写字母数字和连字符，3–32 字符"
}
```
## 9. 品牌数据模型
```json
{
// ---- 标识 ----
"brandKey": "heaifei", // 唯一键，仅小写字母数字+连字符 3–32
"brandName": "河爱非遗", // 显示名称
"status": "active", // pending | active | suspended | deleted
"createdAt": "2026-08-05T10:00:00.000Z",
"updatedAt": "2026-08-05T12:00:00.000Z",
// ---- 管理员 ----
"adminAccount": "admin@heaifei", // 自动生成
"adminInitialPassword": "aB3$xK9...", // 16位，创建时回显一次
"adminPasswordSetAt": "2026-08-05T10:00:00.000Z",
// ---- 等级与配额 ----
"maxLicenseLevel": "pro", // null(不限制) | trial | pro | enterprise
// 各等级可发放上限（total=-1 无限）
"quotaTrial": 50, "quotaUsedTrial": 3,
"quotaPro": 200, "quotaUsedPro": 12,
"quotaEnterprise": 1000, "quotaUsedEnterprise": 0,
// ---- 数据库 (品牌方自带库，Provision 后填充) ----
"dbHost": "10.0.0.1",
"dbPort": 3306,
"dbName": "feiyi_heaifei",
"dbUser": "feiyi_heaifei",
"dbPasswordEncrypted": "AES-256-GCM密文...",
"kekVersion": "v1", // KEK 版本标识
// ---- 存储 (COS) ----
"storage": {
"bucket": "heaifei-1234567890",
"region": "ap-guangzhou",
"secretIdEncrypted": "...",
"secretKeyEncrypted": "..."
},
// ---- 网络 ----
"domainId": "zhinao.ligen.cn", // 品牌域名
"apiBaseUrl": "https://adminapi.ligen.cn", // 数据面地址（代理用）
// ---- 其他 ----
"remark": "河爱非遗品牌",
"meta": {}, // 扩展元数据
"provision": { // 开通状态
"initiatedAt": "2026-08-05T11:00:00.000Z",
"status": "completed"
}
}
```
## 10. 完整接入清单
1. **注册管理后台账号** — 获取超管权限，在 `/#/tenants` 创建品牌条目
2. **配置环境变量** — 在 EdgeOne Pages 控制台设置 `TENANT_SECRET_KEY` / `REGISTRY_TOKEN` / `PLATFORM_SECRET` / `JWT_SECRET` / `REFRESH_SECRET`
3. **实现数据面 Provision 接口** — `POST /api/v1/provision/init`，接收品牌方 MySQL/COS 配置，加密后回写控制面
4. **实现品牌注册表拉取** — 数据面启动时 `GET /api/registry/brands`（带 `REGISTRY_TOKEN`），按 brandKey 建立数据库连接池
5. **实现 HMAC-SHA256 签名** — 使用 `PLATFORM_SECRET` 对高权限操作签名
6. **（可选）配置代理转发** — 品牌创建时填写 `apiBaseUrl`，控制面将通过 `/api/proxy/:brandKey/*` 转发请求
7. **（可选）实现升级码核销回调** — 品牌方在 EXE 中生码后，数据面调用 `POST /api/upgrade-codes` 核销配额
8. **测试** — 创建测试品牌 → Provision 初始化 → 验证数据面能正确读写品牌独立数据库
> 完成以上 8 步后，你的软件即完全接入管理后台。超管可在后台统一管控所有品牌的等级上限、配额、审计日志。
---
本文档随管理后台代码同步更新。如有疑问，查看 `edge-functions/_tenants.js` 与 `edge-functions/_rbac.js` 源码获取最新实现细节。