安全与管理员认证

管理员账户

面板第一次启动时没有任何账户，打开面板会进入安装引导：先选数据库（SQLite 或 PostgreSQL，可先测试连接），再自己填写管理员用户名与密码。密码不会被生成、也不会打印到日志，通过校验后以 Argon2id 哈希入库。

• 无人值守部署可以在首次启动前设置 ADMIN_PASSWORD，启动时直接建好账户；DATABASE_URL / STORE_PATH 一旦指定存储，引导就只负责建账户
• 忘了密码用下面的 CLI 重置，重置不会绕过 2FA

管理员认证

• 密码使用 Argon2id 哈希存储，旧的 SHA-256 哈希会在登录时自动迁移
• 会话有效期 7 天
• 普通受保护接口支持管理员会话或 API_KEY；2FA 管理接口只接受管理员会话，不能用 API_KEY 绕过

双重身份验证（2FA）

1. 使用管理员账户登录面板。
2. 打开 账户设置，选择 设置双重验证。
3. 用任意兼容 TOTP 的验证器扫描二维码，或手动输入页面中的设置密钥。
4. 输入 6 位动态口令完成绑定。
5. 复制或下载页面一次性显示的 10 枚恢复码，并确认已安全保存。

启用后登录需要密码加动态口令，也可以使用一枚未使用的恢复码。恢复码具备防重放保护。关闭 2FA 需要当前密码和动态口令或恢复码。

TOTP Secret 通过 APP_ENCRYPTION_KEY 以 AES-GCM 加密存储。

密码重置

忘记密码时通过 CLI 命令重置：

# 随机生成新密码
docker compose exec tunnel-manager ./tunnel-manager --reset-password

# 设置为指定密码
docker compose exec tunnel-manager ./tunnel-manager --set-password=新密码

WARNING

重置密码不会绕过已启用的 2FA。若 TOTP 加密密钥遗失，需要在服务停止时恢复正确的 APP_ENCRYPTION_KEY。

人机验证（Cloudflare Turnstile）

登录、注册与找回密码可接入 Cloudflare Turnstile 人机验证（可选项）：

1. 在 Cloudflare Turnstile 控制台创建 widget，将本站域名加入允许域名（本地调试需包含 localhost）。
2. 打开 管理后台 → 设置，在「人机验证」卡片中启用并填写 Site Key 与 Secret Key（Secret 仅首次填写或修改时提交，留空表示保持不变）。
3. 开启后，登录、注册、发送验证码与重置密码接口均需通过验证；验证令牌单次有效，每次提交后自动刷新。

Turnstile Secret 通过 APP_ENCRYPTION_KEY 以 AES-GCM 加密存储，接口响应不会返回密钥本身。

登录限流

密码登录、两步验证、通行密钥登录、注册、邮箱验证码、找回与重置密码都受登录限流保护。同一账号或同一来源 IP 的失败次数超出额度后会暂时拒绝请求，返回 429 与 Retry-After（秒），响应体带 retry_after 与提示文案；登录成功会清空该账号的失败计数。

登录成功过的网段视为常用网段，额度更宽。数值、开关与触发时的管理员通知都在 管理后台 → 设置 → 登录保护 配置。被限流的尝试写入审计日志（操作类型 login_throttled）。

APP_ENCRYPTION_KEY 备份清单

该密钥同时保护以下数据，必须与 data/ 目录一起备份：

• TOTP Secret（2FA 绑定关系）
• Cloudflare OAuth 访问令牌与刷新令牌

密钥丢失或被替换后，已启用 2FA 的服务会拒绝管理员登录，OAuth 连接也需要重新授权。