安全

本节介绍用户名、密码、两步验证、信任设备及服务端密钥的使用方式。

账户信息

本 CMS 被设计为单用户模式。

打开后台「账户设置」即可修改当前账户。用户名和邮箱为必填项；昵称留空时前台使用用户名，头像 URL 留空时使用默认头像。

修改密码时在「新密码」中输入新值，留空则保持原密码不变。新密码至少需要 6 位，填写完成后点击「保存」提交账户信息。

登录页使用用户名和密码验证账户。连续登录失败后，系统会按客户端 IP 进行限流，并要求输入图形验证码；验证成功后失败计数会清除。登录会话默认有效期为 7 天，同一账户在其他设备重新登录后，旧会话会失效。

两步验证

在「账户设置」的「两步验证」区域点击「启用两步验证」，系统会生成一组新的 TOTP 密钥并显示二维码、手动输入密钥和 otpauth 链接。使用 Google Authenticator、Authy 或 1Password 扫码添加账户，也可以手动输入密钥。

录入认证器后，将 App 当前显示的 6 位动态码填入输入框并点击「确认启用」。只有动态码验证成功后，两步验证才会正式生效；启用后，登录时先输入用户名和密码，再输入认证器中的 6 位动态码。

停用两步验证时，在已启用区域输入当前动态码并点击「停用」。认证器不可用时，服务端也支持使用账户密码完成身份确认；停用后会清除当前 TOTP 密钥和信任设备 cookie。

信任设备

两步验证登录时勾选「信任此设备 30 天」，并可填写设备名称。验证成功后，这台设备在有效期内再次登录只需输入正确密码，不再重复输入动态码；设备记录会保存最近登录时间、IP 和到期时间，后台列表会根据保存的 IP 动态显示位置和运营商。

在「已信任设备」区域可以修改设备名称，也可以点击「撤回」立即取消信任。撤回后，该设备下次登录需要重新输入动态码；设备到期后也会自动失效。设备列表只管理通过两步验证登录时主动信任的设备，不代表当前所有浏览器会话。

应用密钥

两步验证使用的 TOTP 密钥只在启用流程中显示，确认启用后保存在服务端账户记录中。二维码、手动密钥和 otpauth 链接都等同于认证凭据，请不要公开或提交到代码仓库；需要重新绑定认证器时，先停用两步验证，再重新启用并生成新密钥。

部署环境中的应用密钥不在后台页面编辑，统一在 .env 或运行环境中配置。LOGIN_SECRET 用于签发 2FA challenge 和信任设备令牌，SSR_INTERNAL_REQUEST_SECRET 用于 SSR 内部请求，MINI_API_SECRET 用于小程序接口签名；这些变量只供服务端使用，不会下发到浏览器。配置方式和默认行为见 .env。

外部服务的密钥按照对应功能配置，例如腾讯云 COS 的 SecretId、SecretKey，以及邮件、地图和小程序服务的密钥。保存或导入设置备份时，这些字段可能以明文写入备份文件，备份文件应与 .env 一样妥善保管。

重置两步验证

如果认证器设备丢失，无法在登录页输入动态码，请在项目根目录执行重置脚本：

Bashbun run reset:2fa

脚本会读取项目根目录的 .env 数据库配置并要求确认，输入 y 或 yes 后清除所有用户的 totp_enabled 和 totp_secret。本 CMS 是单用户模式，执行后即可使用原用户名和密码登录，再到「账户设置」重新启用两步验证并绑定新的认证器。脚本不会修改密码、会话或 auth_code。

项目环境无法运行 Bun 时，可以在 PostgreSQL 管理工具或 psql 中执行：

SQLUPDATE users SET totp_enabled = false, totp_secret = NULL;

重置脚本不会删除 trusted_devices 中已有的信任设备。重新启用两步验证前，进入后台「用户」→「已信任设备」，撤回不再使用的设备；需要一次性撤回全部设备时执行：

SQLDELETE FROM trusted_devices;