凭据创建与管理
开放平台凭据（AppId / AppSecret / AesKey）的创建、配置、轮换与排错——对接前的第一步。
开放平台凭据管理
外部系统（商城 / 自助机 / 第三方 ERP）要调极客场馆 OpenAPI，必须先在管理后台创建一对凭据—— AppId 公开标识 + AppSecret 签名密钥。本文讲怎么创建、配置、轮换、排错。
凭据有哪几样东西
| 字段 | 性质 | 用途 |
|---|---|---|
| AppId | 公开标识 | 跟着请求头发送，类似用户名（例 gk_open_20260527_fjb2ui） |
| AppSecret | 32 字节 base64 签名密钥 | 用于请求签名，只在创建/轮换时返回一次，泄露立即作废 |
| AesKey | 32 字节 AES-256 数据密钥 | 启用加密通道时下发，用于敏感字段端到端加密，仅这一次能拿到 |
⚠️ AppSecret / AesKey 创建后只返回一次——关闭那个弹窗就再也看不到。必须立刻 保存到对接方安全的地方（密钥管理服务 / 环境变量），千万别截图发群、别提交 git。
谁能创建
- 门店管理员（gym_admin）或品牌管理员（brand_admin），有
INTEGRATION_OPEN_APIcapability - 平台管理员可跨品牌帮门店创建（场馆 onboarding 阶段常用）
创建无审批流，提交即生效。唯一例外：含 wallet:deduct scope（线下扣款权限）的
凭据，架构预留了审批入口——当前没启用、走默认放行，未来上紧时会卡审批。
创建流程（5 步）
Step 1 · 进管理后台
后台路由：/gym-manage/open-api（菜单”开放平台 → 凭据管理”）。
页面顶部”+ 新建凭据”按钮。
Step 2 · 填字段
| 字段 | 必填 | 说明 |
|---|---|---|
名称 (name) | ✅ | 给凭据起个识别名，比如”商城对接-2026”，≤ 64 字符。仅给运营自己看 |
权限范围 (scopes) | ✅ | 多选：member:read / order:read / wallet:read / wallet:deduct。最小权限原则：商城对接通常 member:read + order:read 就够 |
| IP 白名单 | ❌ | 逗号分隔多个 IP；扣款类凭据强烈建议填，没填等于互联网任意 IP 都能用 |
每秒请求数 (rateLimitQps) | ❌ | 默认 20；流量大的对接方按需调高 |
过期时间 (expiresAt) | ❌ | 留空表示不过期；建议给短期合作配明确过期日 |
环境 (environment) | ✅ | prod（真实数据真实扣款）/ sandbox（数据真实但扣款不落账，用来跑联调） |
启用加密通道 (enableAesChannel) | ❌ | 勾上则同时下发 AesKey，敏感字段（如会员手机号）走端到端 AES 加密 |
Step 3 · 保存 + 立刻复制 secret
点保存后弹窗显示 AppId + AppSecret（+ AesKey 如有），这是唯一能看 secret 的机会。
复制到密钥管理服务 / .env，确认存好后再关弹窗。
Step 4 · 把 AppId / AppSecret 给对接方
按”开放平台总览”和”开发者接入文档”里的签名格式给对接方接入。
Step 5 · 上线监控
凭据列表页可查每个凭据的：状态（active / disabled）/ 当前 QPS / 最近调用时间 / 调用次数 / 最后一次错误。
后续运维
轮换 Secret
每 6 个月或怀疑泄露时点”轮换 Secret”——新 secret 一次性显示、旧 secret 立即失效。 对接方要同步切换 secret 否则签名报错。没有”灰度切换”——切就是切。
禁用 / 启用
把 status 从 active 切 disabled——所有调用立即被拒（HTTP 403），但凭据保留、
配置可改、随时切回 active。比删除柔性。
删除
逻辑删除（deleted=1）。建议先 disable 观察一周确认对接方真没在用了再删。
常见错误排查
40101 SignatureInvalid 签名错
按概率从高到低排查：
- PATH 拼接错 — 待签 PATH 必须含
/api前缀、不含 query string、不含 fragment - query 没排序 — 多个 query 参数必须按 key 字典序排列再拼接
- 空 body 误算 — 空 body 时签名里的 body 部分用
SHA256("")，不是空字符串 - AppSecret 粘贴问题 — 复制时遗漏字符或多了空白
- 行尾换行 — 待签字符串末尾有多余
\n
具体签名格式见 开发者接入文档。
40102 ClockSkew 时间偏移
签名带 timestamp，服务端容忍 ±300s。对接方机器没挂 NTP 时钟漂太多会被拒。
让对接方挂 NTP（chrony / ntpd）。
40103 ScopeRequired 权限不足
凭据 scopes 数组没包含当前接口要的权限。后台编辑凭据 → 勾上对应 scope → 保存。
不需要重发 secret。
40104 IpDenied IP 白名单拒绝
凭据配了白名单但当前 IP 不在内。后台编辑凭据 → IP 白名单加上对接方公网出口 IP。
40301 CredentialDisabled 凭据禁用
凭据 status=disabled 或 deleted=1。后台启用即可恢复。
42901 RateLimited 限流
对接方 QPS 超过凭据配额。临时方案：提高 rateLimitQps；长期方案：让对接方做客户端限流 + 重试退避。
