Docs/ 安全/ 认证与 2FA

认证与 2FA

使用密码或 Google OAuth 登录保护你的 sh0 实例，并通过双因素认证添加额外的保护层。

sh0 支持两种认证方式。两者都会生成用于后续所有 API 请求和控制台访问的 JWT 令牌。

密码认证

默认认证方式。首次安装时，sh0 会创建一个管理员账户，默认凭据显示在服务器日志中。你应该在首次登录后立即更改密码。

Terminal

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

响应包含有效期 30 天的 JWT 令牌：

Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "role": "admin"
    }
  }
}

sh0 登录页面，包含邮箱和密码字段

Google OAuth

对于 sh0 Cloud 用户，Google 登录可作为登录方式使用。这使用 Google 的 OAuth 2.0 流程，通过 JWKS 进行 ID 令牌验证。

在登录页面点击 使用 Google 登录。
使用你的 Google 账户进行认证。
sh0 验证 ID 令牌并创建或关联你的账户。

带有 Google 登录按钮的登录页面

Note

对于自托管实例，Google OAuth 需要配置带有 OAuth 凭据的 Google Cloud 项目。参见 设置 → 认证 输入你的 Client ID 和 Client Secret。

启用双因素认证

双因素认证（2FA）通过在常规凭据之外要求输入基于时间的一次性密码（TOTP）来增加额外的安全层。

在控制台中导航到 设置 → 安全。
点击 启用 2FA。
使用认证器应用（Google Authenticator、Authy、1Password 等）扫描二维码。
输入认证器应用中的 6 位验证码以完成设置验证。
将备用恢复码保存在安全的位置。

2FA 设置界面，显示二维码和验证字段

启用后，每次登录都需要在输入邮箱和密码后提供 6 位 TOTP 验证码。

Terminal

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "totp_code": "123456"
  }'

Warning

如果你丢失了认证器应用的访问权限和备用恢复码，需要直接访问服务器并通过 CLI 重置 2FA：sh0 auth reset-2fa --email [email protected]

备用恢复码

启用 2FA 时，sh0 会生成 10 个一次性备用恢复码。如果你无法访问认证器应用，每个恢复码可替代 TOTP 验证码使用一次。

Example Backup Codes

a1b2c3d4e5
f6g7h8i9j0
k1l2m3n4o5
p6q7r8s9t0
u1v2w3x4y5
z6a7b8c9d0
e1f2g3h4i5
j6k7l8m9n0
o1p2q3r4s5
t6u7v8w9x0

Danger

将备用恢复码存储在安全的离线位置（密码管理器、保险柜中的打印纸）。如果丢失认证器设备，这些恢复码是你唯一的恢复方式。它们仅在 2FA 设置时显示一次。

你可以随时从 设置 → 安全 → 重新生成备用恢复码 重新生成备用恢复码。这将使所有之前生成的恢复码失效。

更改密码

要更改密码：

前往 设置 → 个人资料。
点击 更改密码。
输入当前密码和新密码。
如果已启用 2FA，会提示你输入 TOTP 验证码。

个人设置中的更改密码表单

密码在存储前使用 Argon2id 进行哈希处理。sh0 强制要求最低密码长度为 8 个字符。

Tip

更改密码后，所有现有会话仍然有效。要使所有会话失效，请使用安全设置中的 撤销所有会话 按钮。

会话管理

sh0 使用 JWT 令牌进行会话管理。令牌默认有效期为 30 天。你可以从控制台查看和管理活跃会话。

活跃会话列表，显示浏览器、位置和最后活动时间

在会话面板中，你可以：

查看活跃会话： 查看你登录的所有设备和浏览器。
撤销会话： 使特定会话失效（例如，如果你在共享计算机上忘记登出）。
撤销所有会话： 从所有位置登出。在怀疑凭据被泄露时使用。

Terminal

curl -X DELETE https://your-server:9000/api/auth/sessions \
  -H "Authorization: Bearer YOUR_TOKEN"

Multi-Server

Teams & RBAC