初始化 2FA 绑定

1. 接口定位

• 接口名称: 初始化 2FA 绑定
• 所属域: admin/account
• 业务目标: 为当前管理员生成 TOTP 密钥与首次备份码，用于后续确认绑定

2. 请求定义

• Method: POST
• Path: /adminx/account/2fa/setup/init
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 非幂等（每次调用会生成新的 secret 与 backupCodes）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员 token

Body 参数

该接口无需业务参数，建议传空对象：

{}

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	object	业务数据

data 字段

字段	类型	说明
secret	string	TOTP 共享密钥（仅初始化阶段返回）
otpauthURL	string	otpauth URL，可用于二维码展示
backupCodes	array of string	备份码明文（仅本接口返回一次，后续仅保留哈希）

5. 业务规则

• 当前管理员身份由 token 决定，绑定对象固定为 token 对应的管理员账号。
• 服务会在 Redis 缓存初始化态（默认 10 分钟），等待 setup/confirm 确认。
• 若重复调用，会覆盖上一次未确认的初始化态数据。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
-	缺少管理员 token	由管理员鉴权链路返回
-	初始化态写入失败	由 Redis 客户端返回

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/account/2fa/setup/init", {
  method: "POST",
  headers: {
    operationID: "adminx-2fa-setup-init-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "otpauthURL": "otpauth://totp/OpenIM-AdminX:1000000001?secret=JBSWY3DPEHPK3PXP&issuer=OpenIM-AdminX",
    "backupCodes": [
      "58392014",
      "19402857",
      "77512030",
      "00819472",
      "63020491",
      "44221890",
      "92350117",
      "11028463"
    ]
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. 生成 TOTP key（secret + otpauthURL）。
3. 生成 backup code 及其哈希。
4. 将初始化态写入 Redis（10 分钟过期）。
5. 返回 secret、otpauthURL、backupCodes 明文。

9. 变更记录

• 2026-04-07: 首版发布，新增管理员 2FA 初始化绑定接口文档。