应用与密钥

应用是最外层隔离单位：每个应用有唯一 appkey 与 appSecret。AppSecret 用于 Open API 签名，只在创建和重置时返回一次，列表/详情接口永不返回明文。

概念​

对象字段说明
应用appkey1-64 字符，全局唯一；所有业务接口路径的第一段
应用appSecret32 位 hex；创建/重置时返回，之后不可再查
应用name展示名，缺省等于 appkey
生命周期deleted / deletedAt删除为软删除：数据保留，默认列表隐藏，可恢复
密钥泄露处置

重置 AppSecret 后旧密钥立即失效，所有使用旧密钥的 Open API 调用会返回 1018。重置需要 privileged 角色；重置不会断开客户端 WS 连接（客户端用用户 Token，不用 AppSecret）。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#apps。
  • 已设置 X-Admin-Secret（默认 dev-admin；控制台会保存在浏览器 localStorage 的 im.admin.secret）。
  • 已创建应用并在控制台顶部选中应用（模块接口路径都带 {appkey}）。
  • 重置 AppSecret 需要 privileged 角色（根密钥默认满足）。

步骤​

  1. 创建应用

    AppKey 建议使用小写字母/数字；创建响应中 data.appSecret 只出现这一次，请立即保存到密钥管理系统。

  2. 确认应用信息

    列表接口不返回 secret；详情接口返回应用基础信息与统计计数。

  3. 重置密钥（可选）

    仅在泄露或轮换时执行；重置后同步更新所有服务端调用方。

  4. 软删除与恢复

    删除必须传 confirmAppkey 且与原值完全一致，防止误删；删除后默认列表不可见（includeDeleted=1 可查）。

    恢复接口只对已删除应用有效；未删除时返回参数错误。

参数表​

操作方法与路径请求体 / 参数
应用列表GET /api/admin/appsincludeDeleted=1|true（可选）
创建应用POST /api/admin/apps{appkey,name?}
应用详情GET /api/admin/apps/{appkey}—
重置密钥POST /api/admin/apps/{appkey}/secret/reset—
软删除DELETE /api/admin/apps/{appkey}{confirmAppkey,reason?}
恢复POST /api/admin/apps/{appkey}/restore—

示例​

创建 → 查询 → 重置 → 删除 → 恢复​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"appkey":"demo","name":"Demo 应用"}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/secret/reset" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X DELETE "http://127.0.0.1:8080/api/admin/apps/demo" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"confirmAppkey":"demo","reason":"rotate"}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps?includeDeleted=1" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/restore" \
  -H 'X-Admin-Secret: dev-admin'

常见问题​

AppSecret 丢了怎么办？​

无法找回，只能重置。重置后旧密钥立即失效，务必同步更新调用方。

删除应用会删数据吗？​

不会。删除是软删除（deleted/deletedAt 标记），数据保留且可恢复；列表默认隐藏。

重置密钥会影响在线用户吗？​

不会。客户端 WS 使用用户 Token；AppSecret 只用于服务端签名。

相关链接​