应用信息与KEY管理使用说明

构建时间2026-06-26 20:10:33（Asia/Shanghai）来源项目中间件文档 / 中间件后端来源仓../cl-midserver-2026来源提交号69b951a07311e75887b57e0400d888f89dd72cac

查看文档来源信息

• 来源目录：addons/sys_base/docs
• 来源文件：功能说明/应用信息与KEY管理使用说明.md

## 功能用途 用于维护中间件正式应用实例、应用密钥资料，以及服务态调用所需的 permanent key 生命周期。

入口位置

• PCWEB 应用信息页
• PCWEB KEY 管理页

使用前提

1. 当前模块已经在模块管理页完成正式登记。
2. 维护应用信息时，涉及 secret 的新增或更新不再依赖 APP_SECRET_KEY。
3. 服务态接入方需要先创建 permanent key，再通过换票接口换取 tempKey。

操作方法

1. 在应用信息页维护应用名称、AppID、支付资料、可见校区和所属模块。
2. 在 KEY 管理页选择目标应用，创建新的 permanent key。
3. 创建成功后立即保存明文 permanent key。
4. 服务态调用方使用 permanent key 调用 exchangeTempKey，换取 2 小时有效的 tempKey。
5. 运行时公共认证接口统一使用 tempKey，不再直接使用 permanent key。
6. 到期或停用时，在 KEY 管理页执行编辑、吊销或删除。

规则说明

1. app_wechat_apps_info 中的 appSecret、mchSecret、mchSecretV3 按提交值直接保存，不再由中间件做 AES 加密。
2. 应用信息列表和详情接口不返回完整 secret，只返回脱敏值或空值。
3. 更新应用信息时，secret 字段为空或提交掩码值表示保留原记录；填写真实值才覆盖原 secret。
4. syncWechatAppsInfo 在 includeCredentials=true 时，按当前库中保存的真实值返回给系统服务调用方。
5. 历史已经写成 enc:gcm:v1: 前缀的值不会自动还原；取消加密后会被当作普通字符串，必须重新录入真实 secret。
6. sys_external_app_keys 数据库存储的是 permanent key 的 SHA-256 摘要，不再保存明文。
7. permanent key 只在创建成功后完整展示一次，后续页面只展示摘要和状态。
8. tempKey 存储在 Redis，默认有效期 2 小时，运行时校验还会回查数据库的吊销和到期状态。

常见结果

• 应用信息维护成功后，列表可继续展示应用名称、AppID、模块归属与脱敏 secret。
• 新增 KEY 成功后，页面会一次性展示明文 permanent key。
• 吊销 KEY 后，该 permanent key 无法继续换取 tempKey。
• 删除 KEY 后，该记录从管理页移除，旧摘要不再可用。

维护提示

• 发现服务态调用突然失败时，优先核对 KEY 是否已到期、已吊销，或 tempKey 是否已过期。
• 发现微信登录、AccessToken、支付签名或同步凭证异常时，优先检查 app_wechat_apps_info 中的 secret 是否为空、是否为掩码值，或是否仍是 enc:gcm:v1: 历史值；如是，需在应用信息页重新录入真实 secret。
• 不允许把 permanent key 直接下发给前端运行时接口长期使用。
• 即使关闭全量 auto-migrate，中间件启动时也会补齐 sys_external_app_keys 的 key_type、expired_at、last_used_at、revoked_at 生命周期治理列，并把历史空 key_type 记录归一为 permanent。