管理端登录与恢复

版本边界

本页适用于包含常驻管理服务的版本。旧版镜像没有设备会话协议，升级时应整体替换镜像并保留 /data。

Web 管理端使用设备码配对。设备码只负责短时授权；配对成功后，浏览器使用服务端签发的会话。无需配置用户名、密码或管理 access_token，也不要将凭据放进 URL。

首次连接

先启动管理服务，然后在管理服务所在机器执行：

bash

onebots auth bootstrap --data-dir /path/to/data

Docker 用户在容器内执行，onebots 为容器名示例：

bash

docker exec onebots onebots auth bootstrap --data-dir /data

打开管理页，将终端输出的设备码填入配对表单。设备码五分钟有效，只能兑换一次，不要发送到聊天群或保存到日志。没有账号、适配器或协议时，也可以登录管理端。

在管理服务所在机器运行 onebots auth device --data-dir /path/to/data（Docker 内同样使用 docker exec），把五分钟内一次性有效的码填入新浏览器。也可在 TUI 选择“授权新浏览器设备”。追加设备不会使已有设备退出。

控制台的“设备会话”列出授权时间、到期时间及当前设备，支持确认后撤销指定会话。最多保留 16 个有效会话；达到上限先撤销不再使用的设备。每次授权有效期为 30 天，访问和重启不续期。会话编号不是登录凭据。

升级前没有签发时间的旧会话须重新授权；已有明确期限的旧会话保留原到期时间。认证存储升级后不要直接回退到不支持多设备格式的旧管理程序，也不要还原旧认证文件来复活已撤销凭据。

如果退出请求失败，页面不会宣称已经撤销。可以重试；如果凭据已经失效，清除本地凭据后重新授权。

已经配对的工作区不会重新开放首次初始化。仅再次连接可使用 auth device；需要找回控制权并撤销所有旧设备时，执行：

bash

onebots auth recover --data-dir /path/to/data
# Docker
docker exec onebots onebots auth recover --data-dir /data

把恢复码填入同一个配对表单。签发恢复码不会让现有会话失效，成功兑换会撤销所有旧设备及未兑换的追加设备码，只保留本次授权。

在支持私有运行时 Secret 的部署平台上，可以使用显式部署授权：

随机码可在可信机器上生成：

bash

node --input-type=module -e "import { randomBytes } from 'node:crypto'; process.stdout.write(randomBytes(32).toString('base64url'))"

同码重启不会重新签发或延长有效期。初始码和恢复码不能相互复用。有效的本地恢复码优先；如曾申请本地恢复码，请使用它，或等它过期后再注入全新的部署恢复码。每类部署码最多记录 16 次，超过上限使用本机恢复入口。

HF 操作示例见 Docker 部署。本地 HF 容器恢复已验证，真实 HF 云端环境仍未实测。

现象	处理
首次配对命令被拒绝	工作区可能已经配对，追加设备使用 `auth device`，恢复控制权使用 `auth recover`，不要删除认证文件。
设备码失效	五分钟过期、已兑换或被新码替换都可能导致拒绝。申请全新码；多次错误输入后等待一分钟再尝试。
本机命令无法连接	确认管理服务正在运行，`--data-dir` 与它使用的工作区一致，当前用户拥有本地控制连接权限。
退出后旧浏览器不能访问	属于正常撤销结果，使用新设备码重新授权。
部署恢复没有生效	检查 Secret 名称、是否同时配置两种码、是否复用历史码，以及是否存在仍有效的本地恢复码。

认证材料保存在私有控制目录，不随业务配置传给网关。不要编辑或删除认证文件来绕过恢复步骤。平台密钥和协议出口的 access_token 与管理登录无关，继续按对应平台和协议文档配置。