Kuboard 用户登录
本页说明如何登录 Kuboard：登录页由哪些部分组成、几种认证方式如何选择、首次登录要做什么、会话过期怎么办，以及常见登录问题的排查。
适用对象：Kuboard Web 界面的普通用户与管理员。各认证方式的详细配置见 OIDC 单点登录、MFA 多因素认证、修改与重置密码、访问密钥（Key/Secret）。
登录页
登录页中部是登录表单，由用户名、密码输入框组成，右上角可切换界面语言与暗色模式。管理员启用了 OIDC 或 Webhook 用户库时，表单上方会出现「用户来源」选择；启用了 OIDC 时，表单下方会出现「使用 XXX 登录」按钮。
登录页只显示管理员已启用的登录方式。只开了内建用户库时，登录页只有用户名/密码表单。
认证方式与选择
| 登录方式 | 登录页入口 | 是否由 Kuboard 管密码 | 适用场景 |
|---|---|---|---|
| 内建用户库（用户名+密码） | 表单直接登录 | 是 | 小团队默认方式 |
| Webhook 用户库 | 先选「用户来源 → 外部用户库」，再填用户名+密码 | 否，由外部服务校验 | 已有外部账号体系 |
| OIDC SSO 单点登录 | 「使用 XXX 登录」按钮，整页跳转 | 否，由身份提供方（IdP）管理 | 企业统一身份认证 |
| MFA 动态口令 | 叠加在用户名/密码之上，登录时多输一步 6 位口令 | — | 提高账号安全 |
MFA（Multi-Factor Authentication，多因素认证）不是独立的账号密码入口，而是叠加在其他登录方式之上的第二重校验，账号安全要求较高时启用，细节见 MFA 多因素认证。
用户名/密码登录
以内建用户库或 Webhook 用户库的账号为例：
- 填写用户名与密码；如管理员启用了多种用户来源，先在「用户来源」处选对来源。
- 点登录。已绑定 MFA 的账号会弹出「MFA 验证」窗口，见下节。
- 登录成功进入首页。
登录页会记住你上次填写的用户名与选择的登录方式，下次打开时默认选中同一种方式。
TIP
Webhook 用户库在登录页的操作与内建用户库完全一致，只是用户名/密码会交给外部服务校验，Kuboard 不保存密码。
MFA 二次验证
已绑定 MFA 的账号，密码校验通过后会弹出「MFA 验证」窗口，输入以下任一种：
- 动态口令：6 位数字，来自手机上的身份验证器 App（如 Google Authenticator）；
- 恢复码（Recovery Codes）：16 字符的一次性恢复码，验证器丢失时的备用入口。
输入框按长度自动区分：不超过 6 位按动态口令处理，超过则按恢复码处理。
若账号未绑定 MFA、而管理员开启了强制绑定，登录不会失败，而是登录后直接跳到 MFA 绑定页，完成绑定后才能正常进入系统。
WARNING
MFA 的绑定、解绑与恢复码管理都在登录之后进行，详细操作见 MFA 多因素认证。若验证器丢失且恢复码用尽，需联系管理员解绑。
OIDC 单点登录
管理员配置了 OIDC（OpenID Connect）后，登录页出现「使用 XXX 登录」按钮。接入多个 IdP 时，按钮上方会多一个「OIDC 提供方」下拉框，先选择企业身份系统再点按钮。点击后整页跳转到该身份系统，在企业侧完成身份认证（含企业侧 MFA）后，自动跳回 Kuboard 并完成登录。
OIDC 用户没有 Kuboard 密码，账号密码与 MFA 均由身份提供方管理，Kuboard 仅在首次认证时自动创建对应的本地账号。
TIP
点击「使用 XXX 登录」没反应或报错，一般是 IdP 配置问题，请管理员检查。IdP 的接入配置见 OIDC 单点登录。
首次登录
管理员创建的账号，默认密码为 Kuboard123。首次登录后请立即修改：点击右上角头像 → 修改密码。
- 默认密码 3 天内有效，到期不修改将无法登录；
- 主动修改后，新密码 90 天内有效；修改时不允许继续使用默认密码或最近用过的历史密码（规则详见 password）。
会话过期
- 登录会话默认 30 分钟（以系统配置为准），无操作超过该时长需要重新登录。
- 会话超时前，系统会在后台静默续期，正常操作一般不会被打断。
- 会话真正过期后会跳回登录页，重新登录成功会自动回到刚才的页面。
- 管理员开启「同一账号仅允许单点登录」（默认开启）时，在新设备/浏览器登录会踢掉旧设备上的会话，这是预期行为，不是故障。
常见问题
管理员忘记密码：由另一位管理员登录后在「用户管理」中找到该用户，执行重置密码。密码会被重置为 Kuboard123，用默认密码登录后立即修改。
账号被锁定：连续输错密码 5 次后锁定 60 分钟。可等待自动解锁，或由管理员在用户管理中执行解锁。
提示「不能使用默认密码 / 不能使用历史密码」：默认密码、当前密码与最近用过的密码都不能再使用，换一个新密码即可。
MFA 验证器丢失 / 恢复码用尽：先用恢复码登录（登录页 MFA 窗口选「恢复码」，输入 16 字符恢复码），登录后可重新生成恢复码；恢复码也用尽则联系管理员解绑，详见 MFA 多因素认证。
登录页没有「OIDC 登录」按钮：管理员未启用或未正确配置 OIDC，请管理员检查。
登录后跳到不该去的页面：重新登录一次即可，无需其他处理。
相关页面与接口文档
- OIDC 单点登录 —— IdP 配置、多 IdP、OIDC MFA 信任策略
- MFA 多因素认证 —— TOTP 绑定/解绑、恢复码管理
- 修改与重置密码 —— 密码策略配置、个人改密操作
- 访问密钥（Key/Secret） —— MCP 与自动化场景的 AK/SK 认证
本节涉及的接口详见 Swagger UI 的「登录接口」分组。
