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 登录」按钮。Kuboard 只接入一个 IdP，点按钮即整页跳转到该身份系统，在企业侧完成身份认证（含企业侧 MFA）后，自动跳回 Kuboard 并完成登录。
OIDC 用户没有 Kuboard 密码，账号密码与 MFA 均由身份提供方管理，Kuboard 仅在首次认证时自动创建对应的本地账号。
登录失败会回到登录页并给出可直接处理的原因（如「当前访问地址不在白名单」「IdP 未完成 MFA」）；若浏览器直接显示一个只带错误码的页面，说明失败发生在跳转 IdP 之前（白名单未配置或当前地址未登记）。
TIP
点击「使用 XXX 登录」没反应或报错，一般是 IdP 侧配置问题，请管理员检查。IdP 的接入配置见 OIDC 单点登录。
首次登录
管理员创建的账号，默认密码为 Kuboard123。首次登录后请立即修改：点击右上角头像 → 修改密码。
- 默认密码 3 天内有效，到期不修改将无法登录；
- 主动修改后，新密码 90 天内有效；修改时不允许继续使用默认密码或最近用过的历史密码（规则详见 password）。
会话过期与登录后回跳
- 登录会话默认 30 分钟（以系统配置为准），无操作超过该时长需要重新登录。
- 会话超时前，系统会在后台静默续期，正常操作一般不会被打断。
- 会话真正过期后会跳回登录页；重新登录成功会自动回到刚才的页面，不必重新导航一次。
- 未登录时直接访问某个受保护的地址，同样会记住目标地址，登录后回到那里。
- 管理员开启「同一账号仅允许单点登录」（默认开启）时，在新设备/浏览器登录会踢掉旧设备上的会话，这是预期行为，不是故障。
TIP
回跳只接受本站内的页面地址，外部链接不会被跟随。
常见问题
管理员忘记密码：由另一位管理员登录后在「用户管理」中找到该用户，执行重置密码。密码会被重置为 Kuboard123，用默认密码登录后立即修改。
账号被锁定：连续输错密码 5 次后锁定 60 分钟。可等待自动解锁，或由管理员在用户管理中执行解锁。
提示「不能使用默认密码 / 不能使用历史密码」：默认密码、当前密码与最近用过的密码都不能再使用，换一个新密码即可。
MFA 验证器丢失 / 恢复码用尽：先用恢复码登录（登录页 MFA 窗口选「恢复码」，输入 16 字符恢复码），登录后可重新生成恢复码；恢复码也用尽则联系管理员解绑，详见 MFA 多因素认证。
登录页没有「OIDC 登录」按钮：管理员未启用或未正确配置 OIDC，请管理员检查。
登录后跳到不该去的页面：重新登录一次即可，无需其他处理。若你从某个深层地址被踢出后又登入，应自动回到那个地址；若没回到，从左侧菜单重新进入即可。
相关页面与接口文档
- OIDC 单点登录 —— IdP 接入与自检、OIDC MFA 信任策略、IdP 主动登出
- MFA 多因素认证 —— TOTP 绑定/解绑、恢复码管理
- 修改与重置密码 —— 密码策略配置、个人改密操作
- 访问密钥（Key/Secret） —— MCP 与自动化场景的 AK/SK 认证
本节涉及的接口详见 Swagger UI 的「登录接口」分组。
