docs: 完善注册短信验证码设计文档
根据评审意见修改： - 配置项移至 userService（方案一） - Redis 存储增加 scene 维度、防暴力破解策略、发送频率限制 - verify-code 增加 verify_token 供后续注册接口使用 - 补充错误处理场景（Redis失败、阿里云超时、限流等） - 增加安全注意事项（日志脱敏、token安全等） Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
d5d311c2b2
commit
72ea3f4305
@ -135,11 +135,11 @@
|
|||||||
|
|
||||||
## 6. 配置项
|
## 6. 配置项
|
||||||
|
|
||||||
在 `backend/gateway/config/config.go` 的 OSSConfig 基础上新增 SMSConfig：
|
在 `backend/services/userService/config/` 下新增 SMS 配置（采用方案一，配置跟随服务）：
|
||||||
|
|
||||||
```go
|
```go
|
||||||
// SMSConfig 短信配置
|
// SMSConfig 短信配置
|
||||||
SMSConfig struct {
|
type SMSConfig struct {
|
||||||
AccessKeyID string
|
AccessKeyID string
|
||||||
AccessKeySecret string
|
AccessKeySecret string
|
||||||
SignName string // 短信签名
|
SignName string // 短信签名
|
||||||
@ -148,9 +148,10 @@ SMSConfig struct {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
通过环境变量注入：
|
通过环境变量注入（与 gateway 的 OSS 配置分开，避免部署耦合）：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# userService 环境变量
|
||||||
SMS_ACCESS_KEY_ID=
|
SMS_ACCESS_KEY_ID=
|
||||||
SMS_ACCESS_KEY_SECRET=
|
SMS_ACCESS_KEY_SECRET=
|
||||||
SMS_SIGN_NAME=TopFans
|
SMS_SIGN_NAME=TopFans
|
||||||
@ -162,13 +163,38 @@ SMS_REGION=cn-hangzhou
|
|||||||
|
|
||||||
## 7. Redis 存储设计
|
## 7. Redis 存储设计
|
||||||
|
|
||||||
**Key 格式**: `sms:verify:{mobile}`
|
### 7.1 Key 结构（按场景区分）
|
||||||
|
|
||||||
**Value**: 6位验证码字符串
|
| 场景 | Key 格式 | 说明 |
|
||||||
|
|------|----------|------|
|
||||||
|
| 注册 | `sms:register:{mobile}` | 注册时发送的验证码 |
|
||||||
|
| 登录 | `sms:login:{mobile}` | 登录时发送的验证码（未来扩展） |
|
||||||
|
| 修改密码 | `sms:password:{mobile}` | 忘记密码时发送的验证码（未来扩展） |
|
||||||
|
|
||||||
**TTL**: 60 秒
|
### 7.2 Value 结构（Hash 类型，支持更多元数据）
|
||||||
|
|
||||||
**验证后**: 删除 Key 或标记已使用（防止重放）
|
```
|
||||||
|
Key: sms:register:13800138000
|
||||||
|
Value (Hash):
|
||||||
|
code: "123456" // 6位验证码
|
||||||
|
created_at: "1700000000" // 发送时间（Unix timestamp）
|
||||||
|
attempts: "0" // 验证失败次数（超过3次需重新获取）
|
||||||
|
used: "false" // 是否已使用
|
||||||
|
TTL: 60 秒
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7.3 防暴力破解策略
|
||||||
|
|
||||||
|
- **失败计数**：每次验证失败递增 attempts 字段，≥ 3 次后删除 Key，要求用户重新获取
|
||||||
|
- **发送频率限制**：记录 `sms:limit:{mobile}:hour`，每小时最多发送 10 次，超限返回 429
|
||||||
|
- **IP 维度限流**（可选）：记录 `sms:limit:{ip}:hour`，每 IP 每小时最多请求 30 次
|
||||||
|
|
||||||
|
### 7.4 验证后处理
|
||||||
|
|
||||||
|
验证成功后：
|
||||||
|
1. 删除验证码 Key（防止重放）
|
||||||
|
2. 标记 `sms:used:{mobile}:register` = "true"（防止同一手机号在验证成功后再次使用相同验证码）
|
||||||
|
3. 标记 5 分钟内有效，超时自动清理
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -216,11 +242,37 @@ Content-Type: application/json
|
|||||||
"code": 200,
|
"code": 200,
|
||||||
"message": "验证成功",
|
"message": "验证成功",
|
||||||
"data": {
|
"data": {
|
||||||
"verified": true
|
"verified": true,
|
||||||
|
"verify_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||||
|
"expires_in": 300
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**说明**：
|
||||||
|
- `verify_token` 用于后续注册接口的认证，后端在 Redis 中记录 `verify:register:{mobile}` = verify_token
|
||||||
|
- 注册接口需携带此 token，验证通过后才处理注册请求
|
||||||
|
- `expires_in` = 300 秒（5 分钟），超时需重新验证
|
||||||
|
|
||||||
|
**注册接口携带 token**：
|
||||||
|
```
|
||||||
|
POST /api/v1/auth/register
|
||||||
|
Authorization: Bearer {verify_token}
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"mobile": "13800138000",
|
||||||
|
"password": "xxx",
|
||||||
|
"nickname": "xxx",
|
||||||
|
"star_id": 1
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
后端逻辑：
|
||||||
|
1. 从 verify_token 中解析出 mobile
|
||||||
|
2. 检查 Redis 中 `verify:register:{mobile}` 是否与 token 匹配
|
||||||
|
3. 验证通过后删除该记录，防止重复使用
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 9. 错误处理
|
## 9. 错误处理
|
||||||
@ -228,24 +280,54 @@ Content-Type: application/json
|
|||||||
| 场景 | 错误码 | 处理方式 |
|
| 场景 | 错误码 | 处理方式 |
|
||||||
|------|--------|----------|
|
|------|--------|----------|
|
||||||
| 手机号格式错误 | 400 | 提示"手机号格式不正确" |
|
| 手机号格式错误 | 400 | 提示"手机号格式不正确" |
|
||||||
| 短信发送失败 | 500 | 提示"发送失败，请重试" |
|
| 短信发送失败（阿里云超时） | 500 | 提示"服务暂不可用，请稍后重试" |
|
||||||
| 验证码已过期 | 400 | 提示"验证码已过期，请重新发送" |
|
| 短信发送失败（配额不足） | 500 | 提示"发送失败，请联系客服" |
|
||||||
| 验证码错误 | 400 | 提示"验证码错误" |
|
| Redis 连接失败 | 500 | 提示"验证服务暂不可用" |
|
||||||
| 验证码已使用 | 400 | 提示"验证码已使用，请重新发送" |
|
| 验证码已过期 | 400 | 提示"验证码已过期，请重新获取" |
|
||||||
| 发送过于频繁 | 429 | 提示"发送过于频繁，请稍后再试" |
|
| 验证码错误 | 400 | 提示"验证码错误，剩余N次" |
|
||||||
|
| 验证码错误超过3次 | 400 | 提示"验证失败次数过多，请重新获取" |
|
||||||
|
| 验证码已使用 | 400 | 提示"验证码已使用，请重新获取" |
|
||||||
|
| 发送频率超限（60秒内重复发送） | 429 | 提示"发送过于频繁，请稍后再试" |
|
||||||
|
| 每小时发送次数超限（>10次） | 429 | 提示"当前手机号发送次数超限，请稍后再试" |
|
||||||
|
| IP 请求频率超限 | 429 | 提示"请求过于频繁，请稍后再试" |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 10. 部署说明
|
## 10. 部署说明
|
||||||
|
|
||||||
1. 在阿里云短信服务控制台创建签名和模板，获取 `SignName` 和 `TemplateCode`
|
1. 在阿里云短信服务控制台创建签名和模板，获取 `SignName` 和 `TemplateCode`
|
||||||
2. 在 `deploy/envs/user.env` 或系统环境变量中配置阿里云 AccessKey
|
2. 在 `deploy/envs/user.env` 中配置阿里云 AccessKey：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 阿里云短信配置
|
||||||
|
SMS_ACCESS_KEY_ID=your_access_key_id
|
||||||
|
SMS_ACCESS_KEY_SECRET=your_access_key_secret
|
||||||
|
SMS_SIGN_NAME=TopFans
|
||||||
|
SMS_TEMPLATE_CODE=SMS_xxxxxxx
|
||||||
|
SMS_REGION=cn-hangzhou
|
||||||
|
|
||||||
|
# 阿里云 OSS 配置（复用同一套凭证）
|
||||||
|
OSS_ACCESS_KEY_ID=your_access_key_id
|
||||||
|
OSS_ACCESS_KEY_SECRET=your_access_key_secret
|
||||||
|
OSS_STS_ROLE_ARN=acs:ram::1387642798143585:role/top-fans-oss-user
|
||||||
|
```
|
||||||
|
|
||||||
3. 重启 userService 服务
|
3. 重启 userService 服务
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 11. 待确定事项
|
## 11. 安全注意事项
|
||||||
|
|
||||||
|
1. **验证码日志脱敏**：日志中禁止记录明文验证码，只能记录手机号和发送状态
|
||||||
|
2. **verify_token 安全**：token 有效期 5 分钟，只能使用一次，验证后立即删除
|
||||||
|
3. **防暴力破解**：验证失败 3 次后强制删除验证码，要求用户重新获取
|
||||||
|
4. **限流保护**：从手机号和 IP 两个维度限制请求频率
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. 待确定事项
|
||||||
|
|
||||||
- [ ] 阿里云短信签名和模板CODE（需在阿里云控制台创建）
|
- [ ] 阿里云短信签名和模板CODE（需在阿里云控制台创建）
|
||||||
- [ ] 验证码有效期（默认 60 秒是否合适）
|
- [ ] 验证码有效期（默认 60 秒是否合适）
|
||||||
- [ ] 同一手机号发送频率限制（默认 60 秒内不能重复发送）
|
- [ ] 每小时同一手机号发送次数上限（默认 10 次）
|
||||||
|
- [ ] 验证失败次数上限（默认 3 次后强制重新获取）
|
||||||
Loading…
Reference in New Issue
Block a user