HiAPI 授权保护 · 生产上线切换手册

本文件是操作层权威文档。执行前阅读《授权保护-最终方案与开发计划.md》了解设计背景。贯穿原则：每步可独立回退；已在跑的实例绝不被杀；现网先监控再强制。

前置条件检查

在任何切换操作前，确认：

[ ] nuwa 已部署，GET /license/pubkey 正常返回 Ed25519 公钥
[ ] APPSTORE_LICENSE_ED25519_PRIVATE_KEY 已在 nuwa 生产环境配置（固定密钥，勿轮换）
[ ] 管理后台 store-web 可登录，平台管理员账户可访问「授权管理」
[ ] 至少有一个测试客户已在后台创建，测试部署已通过 monitor 模式激活
[ ] hiapi-core-cpp CI 已出三平台 .so/.dll/.dylib（新协议版本），已替换到 hiapi-core-license/src/main/resources/
[ ] hiapi-cloud-license-server 已下线（或确认没有生产流量打向旧服务）

阶段 A · Monitor 模式激活（0 风险，先做）

目标：所有现存部署都联上 nuwa，完成 grandfather 登记；此阶段不强制任何行为。

操作：

nuwa 环境变量确认：

APPSTORE_LICENSE_MONITOR_MODE=true   ← 默认值,确认即可

在各宿主应用（hiapi-cloud-public 等）的 application.yml 加入：

yaml

hiapi:
  license:
    enabled: true
    mode: monitor
    server-url: https://license.hiapi.cn
    key: <从管理后台复制该客户的 license key>
    module-name: hiapi-core-public
    install-id-path: /data/hiapi/install_id

滚动重启宿主应用（按客户、按集群逐步）。
在管理后台「授权管理 → 客户详情 → 部署」确认 install 已出现，且「最近心跳」在更新。
在「配额概览」页（GET /v1/license/quota-summary）核查在线实例数，与实际 pod 数吻合。

回退：hiapi.license.enabled=false 完全跳过授权，无须重启 nuwa。

阶段 B · 切换 nuwa 到强制模式

目标：nuwa 全局关闭 monitor mode，使 EnforceQuota=true 的客户开始实质拦截。

操作：

在管理后台「授权管理」顶部确认"当前处于监控模式"提示存在。
修改 nuwa 部署环境变量：
```
APPSTORE_LICENSE_MONITOR_MODE=false
```
滚动重启 nuwa（无状态服务，零中断）。
刷新管理后台，确认顶部提示变为"当前处于强制模式"（绿色 ✓）。
此时各客户默认仍不强制（EnforceQuota=false），全局配置切换对现网零影响。

回退：改回 APPSTORE_LICENSE_MONITOR_MODE=true 重启 nuwa。

阶段 C · 逐客户灰度开启 EnforceQuota

目标：对个别客户启用配额强制，验证拦截逻辑正确后逐步全量。

操作：

在管理后台「客户详情 → 配额与状态」，找到目标测试客户。
开启「配额强制」开关（el-switch），点击「保存」。
验证：
- 超出 maxInstances 的新 pod 尝试启动 → 在 enforce 模式下，ModuleFetch 返回 403，应用起不来（这正是"起不来"）。
- 正在运行的 pod 心跳正常，不受影响（"已在跑的放行"）。
- 超出 maxTenants 的新租户注册 → TenantReport 返回 status=REJECT。
验收 OK 后，逐一为各客户开启 EnforceQuota。

回退：在管理后台关闭目标客户的 EnforceQuota 开关即可，立即生效（无需重启）。

阶段 D · 客户端切换 enforce 模式（阶段 4 最终步）

目标：客户端不再只激活+心跳，而是强制下发并加载闸门模块。

前提：

nuwa 的 /license/module/fetch 已能正常下发（已通过阶段 B/C 验证配额）
hiapi-core-public-obf.jar（ProGuard 混淆后）已通过管理后台上传给每个客户

操作：

将宿主应用配置改为：
yaml
```
hiapi:
  license:
    mode: enforce
```
一个集群一个集群地滚动，每个集群验收后再推下一个。
验收：应用正常启动且功能正常（登录/验证码/上传可用）。
若启动失败（license init failed），立即回退：mode: monitor，重启，排查 nuwa 日志。

回退：mode: monitor，重启即可（模块不加载，Spring 正常启动）。

阶段 E · 退役旧服务

确认所有客户均已切换到 nuwa 后：

停止并下线 hiapi-cloud-license-server 进程/容器（已标记 DEPRECATED.md）。
DNS：将旧 license 域名（若有）指向 nuwa 或 404 页面。
删除旧的 hardcoded AES key/OSS URL 的相关监控告警。
更新 .env 模板：移除旧 LICENSE_SERVER_* 变量说明，加入新 APPSTORE_LICENSE_* 文档。

生产安全红线（任何阶段均适用）

场景	正确处理	错误处理（已修复）
nuwa 临时不可达	客户端走离线宽限（7天），只打严重日志，不退进程	~~exit(0) 崩生产~~
配额超限新实例	enforce：阻止新实例 fetch 模块；已在跑的不影响	~~全部踢掉~~
部署中 pod 重启	install_id 从文件恢复，心跳续期，无感	~~生成新 install_id 超配额~~
Windows 加载 native	deleteOnExit，进程退出后清理	~~Files.delete 已加载 dll 崩溃~~

关键配置速查

位置	变量/配置	说明
nuwa 环境	`APPSTORE_LICENSE_ED25519_PRIVATE_KEY`	Ed25519 私钥（固定，勿轮换）
nuwa 环境	`APPSTORE_LICENSE_MONITOR_MODE`	`true`=监控, `false`=强制（默认 true）
客户端 yml	`hiapi.license.enabled`	kill-switch（false=完全跳过）
客户端 yml	`hiapi.license.mode`	`monitor` / `enforce`
客户端 yml	`hiapi.license.key`	管理后台发放的授权 key
客户端 yml	`hiapi.license.install-id-path`	K8s 挂 Secret/PVC
CI Secret	`LICENSE_ED25519_PUBKEY_B64`	nuwa 公钥，嵌入 C++ native 库

HiAPI 授权保护 · 生产上线切换手册 ​

前置条件检查 ​

阶段 A · Monitor 模式激活（0 风险，先做） ​

阶段 B · 切换 nuwa 到强制模式 ​

阶段 C · 逐客户灰度开启 EnforceQuota ​

阶段 D · 客户端切换 enforce 模式（阶段 4 最终步） ​

阶段 E · 退役旧服务 ​

生产安全红线（任何阶段均适用） ​

关键配置速查 ​