# LokiStack × opsx-licence 对接说明

## 状态

- 代码：双路径已接入（`LIC-`/`LICOFF-` → opsx-licence；旧 HMAC 迁移窗口内仍接受并提示）。
- 生产 product **`lokistack` 尚未在 licence.rlwj.cn 创建**（公开 `GET /api/v1/products/code/lokistack` 返回「产品不存在」）。
- 默认 API：`LICENSE_API_BASE=https://licence.rlwj.cn/api`（可用环境变量覆盖；`l123` 仅网络失败备灾）。

## Plan（产品锁）

| plan_type | 时长 | 实例（max_devices） |
|-----------|------|---------------------|
| trial | 14 天 | 1 |
| yearly | 365 天 | 默认 1，可加购 |
| perpetual | 0（永久） | 默认 1，可加购 |

计费按**部署实例**，不计登录席位。`instance_id` = `DATA_DIR/instance.id` 机器指纹，无 PII。

## 管理端创建 product（需管理员登录，本说明不含账密）

1. 打开 `https://licence.rlwj.cn` 管理后台并登录。
2. **产品** → 新建：
   - name: `LokiStack`
   - code: `lokistack`（必须完全一致）
   - features: `log_analysis`, `log_alerts`, `ai_ops`, `audit_log`
   - price_model: `perpetual`（或按需）
   - status: 启用
3. **定价计划** → 为该产品新建三条：
   - trial / 14 / max_devices=1 / price=0
   - yearly / 365 / max_devices=1
   - perpetual / 0 / max_devices=1
4. **许可证** → 选客户 + 产品 `lokistack` 签发 `LIC-`；离线场景签发 `LICOFF-`（须绑定目标实例的 `instance_id`）。

### 等价 Admin API（需 Bearer；勿把 token 写进仓）

```bash
# 创建产品
curl -sS -X POST 'https://licence.rlwj.cn/api/v1/products' \
  -H "Authorization: Bearer <ADMIN_TOKEN>" -H 'Content-Type: application/json' \
  -d '{"name":"LokiStack","code":"lokistack","version":"1.0.0","description":"LokiStack Pro","features":["log_analysis","log_alerts","ai_ops","audit_log"],"price":0,"price_model":"perpetual","status":1}'

# 创建计划（替换 PRODUCT_ID）
curl -sS -X POST 'https://licence.rlwj.cn/api/v1/plans' \
  -H "Authorization: Bearer <ADMIN_TOKEN>" -H 'Content-Type: application/json' \
  -d '{"product_id":PRODUCT_ID,"name":"体验","plan_type":"trial","price":0,"currency":"CNY","duration":14,"max_devices":1,"features":["Pro","体验","1 实例"],"sort_order":0,"status":1}'
# yearly duration=365；perpetual duration=0 —— 同结构各建一条
```

公开校验：

```bash
curl -sS 'https://licence.rlwj.cn/api/v1/products/code/lokistack'
```

## 旧 HMAC 迁移

- 已发出的本地 HMAC 码：**迁移窗口内继续可用**，设置页黄条提示换发；**禁止静默清码**。
- 换发：后台为客户建 `lokistack` 许可证 → 客户在设置页粘贴新 `LIC-`/`LICOFF-` 覆盖激活。
- 窗口结束后再关 HMAC 路径（另开刀，需产品点头）。

## 环境变量

| 变量 | 含义 |
|------|------|
| `LICENSE_API_BASE` 或 `OPSX_LICENSE_API_BASE` | 覆盖默认 `https://licence.rlwj.cn/api` |

## 对齐 Shell 的差异

| | OpsxShell | LokiStack |
|--|-----------|-----------|
| product_code | `opsxshell` | `lokistack` |
| 绑定字段 | `device_id` | `instance_id`（同语义） |
| 默认 Base | l123 主 / 国内备 | **国内主** / l123 备 |
| 落盘 | `license.opsx` | JsonDB `license` 字段 |
| 退出授权 | `clear` → remote deactivate + 删本地 | 设置→授权「退出授权」→ `POST /system/license/deactivate`；在线成功才清本地；LICOFF- 仅解本机并提示后台名额可能仍占 |

## 退出授权（本机）

- UI：设置 → 授权，Pro 态（含宽限仍 pro）管理员可见「退出授权」，二次确认；免费/未激活不渲染。成功后只重拉授权态，不整页刷新。
- 后端：`POST /api/v1/system/license/deactivate`（Admin）。
- 在线 `LIC-`：调用 `POST {LICENSE_API_BASE}/v1/license/deactivate`，body 含 `license_key`、`device_id`（=instance_id）、`activation_token`（若有）；**成功才清本地**，失败保留现状并报错。
- 离线 `LICOFF-`：只清本地，响应 `offlineLocalOnly=true`，提示后台名额可能仍占。
- 旧 HMAC：只清本地。
- 禁止在周检/校验失败路径静默清码；仅用户确认后走本接口。