本文说明如何从旧登录系统切换到新的用户管理/登录系统（包含用户注册、密码管理）。

1. 开启新的登录模式

在 .env 中设置：

VITE_ENABLE_NEW_AUTH=True

含义：

• False：旧登录系统（默认，逻辑简单）。
• True：新的用户管理/登录系统（注册、密码管理、找回密码、会话管理等）。

开启前请先完成 Redis 与 SMTP 配置，否则注册与找回密码功能不可用。

2. Redis 配置（Session、验证码、锁定）

新的用户管理/登录系统依赖 Redis 保存临时与安全相关的数据。

Redis 主要用于：

• 临时保存验证码（注册/重置）
• 登录频控与账号锁定状态
• 短期会话与安全状态

Docker 快速启动 Redis

docker run -d --name jiuwen-redis -p 6379:6379 redis:latest

说明：使用 Docker 启动 Redis 不需要手动下载或安装任何依赖。

如不使用 Docker，可自行在本机安装 Redis 服务（不同系统安装方式不同），本文不展开。

.env 配置

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=

若 Redis 未设置密码，请保持 REDIS_PASSWORD 为空。

3. SMTP 邮件服务配置（验证码邮件）

SMTP 用于发送注册与找回密码验证码。

获取 SMTP 授权码

以 QQ/163 邮箱为例：

1. 登录网页版邮箱。
2. 进入“设置 -> 账号”。
3. 开启 POP3/IMAP/SMTP 服务。
4. 生成 16 位授权码。

注意：SMTP_PASSWORD 必须填写授权码，而不是邮箱登录密码。 警告：使用邮箱登录密码代替 SMTP 授权码通常会失败，或被服务商拦截。

.env 配置示例

SMTP_HOST=smtp.qq.com
SMTP_PORT=465
SMTP_USER=your_email@qq.com
SMTP_PASSWORD=your_16_digit_auth_code
SMTP_ALIAS=OpenJiuwen Support

4. 行为说明（新登录逻辑）

• 验证码为 6 位数字，10 分钟过期。
• 发送验证码有 60 秒频率限制。
• 登录失败最多 5 次，失败会锁定 30 分钟。
• 登录成功或重置密码后会清除锁定与失败计数。

5. 切换前检查清单

• .env 变量名与 .env.example 完全一致。
• VITE_ENABLE_NEW_AUTH=True 时，Redis 正在运行。
• SMTP 参数正确，SMTP_PASSWORD 为授权码。
• 防火墙已放行 6379（Redis）与 465（SMTP）。

启用新的登录系统后，旧登录行为可能发生变化。 请确保客户端能够处理 Token 过期与重新登录流程。

警告

如果您计划将本服务部署在公网或不受信任的网络环境中，强烈建议在部署前对整体系统进行安全风险评估，并采取必要的防护与加固措施。