# 安全设置

> 配置双因素认证、OAuth 登录、密码管理和登录安全策略。

URL: https://docs.serverbee.app/zh/docs/security

ServerBee 提供多层安全防护：双因素认证 (2FA)、OAuth 社交登录、密码策略和登录限流。

## 双因素认证 (2FA) [#双因素认证-2fa]

ServerBee 支持基于 TOTP (Time-based One-Time Password) 的双因素认证，兼容所有标准认证器应用（Google Authenticator、Authy、1Password 等）。

### 启用 2FA [#启用-2fa]

1. 登录后进入 Settings → Security
2. 在 **Two-Factor Authentication** 区域点击 **Setup**
3. 扫描 QR 码（或手动输入 Base32 密钥）
4. 输入认证器应用中显示的 6 位验证码
5. 点击 **Enable** 完成启用

<Callout type="info">
  启用后每次登录都需要输入 6 位 TOTP 验证码。验证码每 30 秒更新一次。
</Callout>

### 禁用 2FA [#禁用-2fa]

1. 进入 Settings → Security
2. 点击 **Disable 2FA**
3. 输入当前密码确认身份
4. 2FA 即被禁用

### API 端点 [#api-端点]

| 端点                      | 方法   | 说明               |
| ----------------------- | ---- | ---------------- |
| `/api/auth/2fa/setup`   | POST | 生成 TOTP 密钥和 QR 码 |
| `/api/auth/2fa/enable`  | POST | 验证码确认后启用 2FA     |
| `/api/auth/2fa/disable` | POST | 输入密码后禁用 2FA      |
| `/api/auth/2fa/status`  | GET  | 查询当前 2FA 状态      |

## OAuth 社交登录 [#oauth-社交登录]

ServerBee 支持三种 OAuth 提供商：

| 提供商    | 配置节              | 回调 URL                                      |
| ------ | ---------------- | ------------------------------------------- |
| GitHub | `[oauth.github]` | `{base_url}/api/auth/oauth/github/callback` |
| Google | `[oauth.google]` | `{base_url}/api/auth/oauth/google/callback` |
| OIDC   | `[oauth.oidc]`   | `{base_url}/api/auth/oauth/oidc/callback`   |

### 配置 OAuth [#配置-oauth]

在 `server.toml` 中添加 OAuth 配置（详见 [Server 配置](/zh/docs/server)）：

```toml
[oauth]
base_url = "https://monitor.example.com"
allow_registration = false

[oauth.github]
client_id = "your-github-client-id"
client_secret = "your-github-client-secret"
```

### OAuth 账号管理 [#oauth-账号管理]

* 在 Settings → Security 页面可以查看已关联的 OAuth 账号
* 点击 **Unlink** 可以解除 OAuth 账号关联
* 如果 `allow_registration = false`（默认），OAuth 首次登录不会自动创建新用户，需要管理员先创建用户再关联

<Callout type="warn">
  仅当 OAuth 提供商本身受控（自建 OIDC 或组织内部 IdP）时才应开启 `allow_registration = true`。自动创建的账号为 Member 角色，可读取**全部**监控数据（含安全事件与公网 IP）。若配合 GitHub 等公共提供商开启，等于向该提供商的所有用户开放这些数据。
</Callout>

### 登录流程 [#登录流程]

1. 在登录页面点击 OAuth 提供商按钮（如 "Login with GitHub"）
2. 跳转到提供商授权页面
3. 授权后回调到 ServerBee
4. 如果 OAuth 账号已关联现有用户，直接登录
5. 如果未关联且 `allow_registration = true`，自动创建 Member 角色用户并登录
6. 如果未关联且 `allow_registration = false`，返回错误

## 密码管理 [#密码管理]

### 修改密码 [#修改密码]

1. 进入 Settings → Security
2. 在 "Change Password" 区域输入当前密码和新密码
3. 点击 **Change Password**

密码使用 argon2 算法哈希存储，符合 OWASP 推荐标准。

### 首次启动管理员凭据 [#首次启动管理员凭据]

首次启动（数据库中没有任何用户）时，ServerBee 会自动创建管理员账号，随机生成密码，并以醒目的凭据横幅在 Server/容器日志中打印一次。用户名和密码无法通过环境变量预设。首次登录时你必须修改此密码，并可选择一个新的用户名。

## 登录安全 [#登录安全]

### 登录限流 [#登录限流]

ServerBee 对登录端点实施 IP 级别的速率限制：

* 默认每 15 分钟窗口内最多 **5 次** 失败尝试（可通过 `rate_limit.login_max` 配置）
* 超过限制后返回 429 Too Many Requests
* 过期的限流记录由后台 session\_cleaner 任务自动清理

### Agent 注册限流 [#agent-注册限流]

Agent 注册端点同样受限：

* 默认每 15 分钟窗口内最多 **10 次** 注册尝试（可通过 `rate_limit.register_max` 配置）。Railway 模板会有意覆盖为更严格的 **3 次**

### Session 安全 [#session-安全]

* Session Cookie 默认设置 `HttpOnly` + `Secure` 标志
* Session 有效期 24 小时（可配置 `auth.session_ttl`）
* 开发环境可通过 `auth.secure_cookie = false` 关闭 Secure 标志

<Cards>
  <Card title="Server 配置" href="/zh/docs/server" />

  <Card title="管理员指南" href="/zh/docs/admin" />

  <Card title="配置参考" href="/zh/docs/configuration" />
</Cards>