用临时管理账户恢复 Keycloak 管理访问并清理恢复入口-未完纪

失去 Keycloak 管理权限时，重新设置启动参数不一定能找回入口。首次创建系统与恢复已有系统使用不同的机制：启动时的 bootstrap 选项只在 master 域尚不存在时创建临时账户；已有安装的恢复，应使用专门的 bootstrap-admin 命令。

本文经授权翻译整理自 Keycloak Team 的官方指南 Bootstrapping and recovering an admin account。2026 年 10 月 5 日核对的官方下载页显示 26.8.0；原文未明确首次发布日期。本文完整保留两种引导方式、交互与环境变量、加强认证场景和恢复后清理要求。全部命令仅供静态阅读，没有建立账户、读取秘密、删除凭据或更改任何认证策略。

“临时”不表示会自动过期删除

通过本指南方法创建的管理用户或管理服务账户都是临时账户，只应存在到恢复永久、更加安全的管理访问为止。恢复完成后必须手动删除。管理控制台警告条、标签和日志会提醒管理员这是临时账户，但这些提示不能替代清理工作。

原创技术示意图：依官方恢复流程绘制；临时管理入口须手动清理，不代表本文实际操作过服务。

首次启动：只在 master 域不存在时引导

start 与 start-dev 都支持创建临时管理用户或服务账户的配置选项。它们属于常规配置，可以通过命令行、环境变量等受支持的配置来源设置。原文用命令行直接提供示例密码 pass 和客户端秘密 secret 展示参数，不能将这些弱示例值用于部署。

本文按官方 All configuration 中的变量名整理为下表，并采用其“尽可能使用非 CLI 配置提供秘密”的建议。密码和秘密应由受控的秘密注入流程提供，不要把真实值写进脚本、仓库或共享终端历史。

用途	非秘密标识	秘密变量
临时管理用户	KC_BOOTSTRAP_ADMIN_USERNAME	KC_BOOTSTRAP_ADMIN_PASSWORD
临时管理服务账户	KC_BOOTSTRAP_ADMIN_CLIENT_ID	KC_BOOTSTRAP_ADMIN_CLIENT_SECRET

准备好相应环境变量后，再按既有部署配置执行 bin/kc.sh start，或仅在开发环境用 bin/kc.sh start-dev。Windows 对应 bin\kc.bat。这不是完整的生产启动配置，数据库、主机名和 TLS 等配置仍须保留。

这些账户总是在 master 域中创建，而且只有该域还不存在的首次启动才生效。如果 master 已经存在，仅改变这些变量不会重置现有管理员密码，也不是恢复已有部署权限的开关。用户名或客户端 ID 可省略，默认均为 temp-admin。

已有部署：先停下所有节点，再执行专用命令

bootstrap-admin 可以在 Keycloak 第一次启动之前运行，也可以用于恢复已有系统。但执行前必须停止所有 Keycloak 节点，不能只停准备运行命令的那一个节点。对于已有系统，要复用正常启动时的配置，特别是数据库相关选项，确保命令指向原来的数据库；连错数据库可能只是在另一套空库里创建了新系统，并没有恢复目标服务。

如果在首次启动前运行该命令，它会创建初始 master 域，因此后续服务器第一次启动时的 bootstrap 用户或服务账户选项会被忽略。这也是“先运行命令，再改启动引导密码”不会达到预期的原因。

如果安装已经通过 build 生成优化构建，官方建议为恢复命令加上 --optimized，跳过构建检查；此时移除命令行中的构建期选项，只保留运行期选项。若不加 --optimized，bootstrap-admin 可能隐式创建或更新优化构建；在服务器使用的同一份安装上执行，会影响下一次服务启动。恢复计划因此不仅要核对数据库，还要核对构建状态和正常启动参数。

创建临时管理用户

不提供其他参数时，命令会按需要提示输入信息：

# 仅在所有节点停止、目标数据库配置已确认后使用。
bin/kc.sh bootstrap-admin user

若需要明确指定用户名并从环境变量取密码，使用 --password:env。这里传的是变量名 PASS_VAR，不是密码本身；该变量应预先由受控流程注入。

bin/kc.sh bootstrap-admin user --username tmpadm --password:env PASS_VAR

对应的 Windows 入口是 bin\kc.bat，选项含义相同。示例没有列出每个部署各自的数据库配置；它们必须通过现有配置文件、环境变量或匹配正常启动的运行期选项提供，不可省略这个前提。

创建临时管理服务账户

自动化场景更适合服务账户。交互方式如下：

bin/kc.sh bootstrap-admin service

也可显式指定客户端 ID，并从环境变量读取客户端秘密：

bin/kc.sh bootstrap-admin service --client-id tmpclient --client-secret:env=SECRET_VAR

此命令创建客户端 ID 为 tmpclient 的临时管理服务账户。若没有提供相应参数或变量，交互模式会提示缺少的必要信息。客户端 ID 可以省略并采用 temp-admin，秘密则必须提供。

禁止交互提示时，缺参数会直接失败

--no-prompt 用于不允许等待人工输入的场景。它不会跳过密码要求，也不会替你生成安全密码。下面是原文用于说明失败条件的例子：若没有可用的密码环境配置，命令会报缺少密码。

# 故意用于说明缺参数失败；不是完整可用的恢复配置。
bin/kc.sh bootstrap-admin user --username tmpadm --no-prompt

如果希望不输入用户名，并直接采用默认值，可在已设置 PASS_VAR 的前提下运行：

bin/kc.sh bootstrap-admin user --password:env PASS_VAR --no-prompt

用户名、客户端 ID 也可以从环境变量读取。以下使用明确的变量名替代原页尖括号占位符：

bin/kc.sh bootstrap-admin user \
  --username:env USERNAME_VAR --password:env PASS_VAR

bin/kc.sh bootstrap-admin service \
  --client-id:env CLIENT_ID_VAR --client-secret:env SECRET_VAR

这两段是二选一的创建方法，不能理解为每次恢复都需要创建两种入口。环境变量也不是天然保密容器：注入范围应限制到必要进程，恢复后清除临时配置，并避免在诊断输出里打印其值。

启用了 OTP 或无密码认证时，通过服务账户恢复

若目标域强制 OTP、无密码登录或其他高级认证，临时用户名和密码可能无法走通既有登录流程。官方要求在这种场景创建临时管理服务账户，再通过管理接口执行必要恢复操作。专用创建命令结束后，应使用原配置重新启动服务，再让管理 CLI 连接正确的 Keycloak 实例。

原文用以下命令登录管理 CLI。这里保留客户端和秘密的占位符，不包含真实凭据；http://localhost:8080 是本机示例，远程管理应使用已配置且可信的 HTTPS 地址。

bin/kcadm.sh config credentials \
  --server http://localhost:8080 --realm master \
  --client <service_account_client_name> \
  --secret <service_account_secret>

实际操作时，秘密应从受控来源取得，不能将上面的占位文本当作凭据。即使通过环境变量在 shell 中展开给 --secret，展开后的值仍属于进程参数，可能被本机进程检查或审计记录捕获；应按所在环境的管理工具秘密处理规范执行，限制操作会话与记录的访问，及时清理恢复凭据。

以丢失 OTP 设备为例，先查询目标用户的凭据列表：

bin/kcadm.sh get users/{userId}/credentials -r {realm-name}

返回的是 CredentialRepresentation 对象数组。逐项找到 type 为 otp 的对象，并核实其 ID 确实属于要恢复的用户与目标域。不要把“删除 OTP”扩大为清空该用户的全部凭据，更不能套用到不相关用户。

下面的删除会真实移除指定认证凭据，属于改变安全状态的操作。 只有在管理员已获授权、用户与 credentialId 已核实、恢复与重新登记方案准备妥当后，才可执行；删除后无法依靠同一个凭据继续认证，可能需要重新绑定 OTP。本文仅保留官方示例，不执行它。

# 有损凭据删除示例；必须逐项核对目标，不可直接复制占位符运行。
bin/kcadm.sh delete users/{userId}/credentials/{credentialId} -r {realm-name}

该例说明如何移除阻挡恢复的一个 OTP 凭据，不是在建议永久关闭多因素认证。后续应按实际域策略恢复长期管理访问、重新登记合适的认证因子，并审计本次管理变更。无密码或其他认证方式需要按实际配置处理，不能把 OTP 的删除路径当成所有认证问题的万能修复。

验证永久入口，再删除临时入口

恢复完成的标准应是永久管理账户能够按预期安全策略登录，并具备所需管理能力；临时账户能登录只说明恢复通道建立成功。确认永久入口后，手动移除此次创建的临时管理用户，或对应的临时管理服务账户/客户端，清理注入的密码、客户端秘密与恢复专用配置，并核查相关审计记录。

官方页没有给出一个适用于所有账户类型的统一清理命令，本文也不编造删除对象的 ID 或命令。应在实际管理界面或经过核对的管理 API 中确认对象类型和标识后清理；不要只关闭浏览器、退出 CLI，或忽略临时账户横幅。永久账户恢复、强认证恢复和临时入口移除，是这次恢复工作的三个不同完成条件。

资料：官方恢复指南、配置参考、数据库配置、26.8.0 下载页。本文未进行服务启动、构建、数据库或认证操作；没有发现命令文本问题不代表已经完成部署或安全验证。

文章版权归作者所有，未经允许请勿转载。

THE END

用临时管理账户恢复 Keycloak 管理访问并清理恢复入口