515 lines
15 KiB
Markdown
515 lines
15 KiB
Markdown
# 滑块验证码后端验证实现计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 为现有的纯前端滑块验证码组件添加后端数据验证，提高安全性，防止前端绕过攻击。
|
||
|
||
**Architecture:** 采用前后端分离架构。后端负责生成验证码数据（包括加密的缺口位置）和验证用户提交的滑动位置。前端负责UI交互和与后端API通信。使用token机制确保验证码的一次性使用。
|
||
|
||
**Tech Stack:**
|
||
- 前端：React, TypeScript, Ant Design, Axios
|
||
- 后端：Django REST Framework (假设), Python, 加密库（如hashlib, hmac）
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
### 前端文件
|
||
- Modify: `src/components/SliderCaptcha/SliderCaptcha.tsx` - 修改为从后端获取验证码数据并发送验证请求
|
||
- Modify: `src/components/SliderCaptcha/captchaUtils.ts` - 移除本地生成逻辑，保留工具函数
|
||
- Modify: `src/utils/request.ts` - 添加验证码API请求方法
|
||
- Modify: `src/pages/SliderCaptchaDemo/SliderCaptchaDemo.tsx` - 更新演示页面以使用新的后端验证
|
||
|
||
### 后端文件（设计指导）
|
||
- Create: `captcha/views.py` - 验证码API视图
|
||
- Create: `captcha/serializers.py` - 数据序列化器
|
||
- Create: `captcha/urls.py` - URL路由
|
||
- Create: `captcha/utils.py` - 加密和验证工具函数
|
||
|
||
---
|
||
|
||
## Task 1: 后端API设计与实现
|
||
|
||
**Files:**
|
||
- Create: `captcha/views.py`
|
||
- Create: `captcha/serializers.py`
|
||
- Create: `captcha/urls.py`
|
||
- Create: `captcha/utils.py`
|
||
|
||
- [ ] **Step 1: 设计验证码数据生成算法**
|
||
|
||
后端需要生成验证码数据，包括：
|
||
1. 随机背景图片URL（或使用预设图片库）
|
||
2. 缺口位置（x, y坐标）
|
||
3. 加密的token（包含缺口位置信息，带签名防篡改）
|
||
4. 滑块图片（可由前端根据缺口位置生成，或后端提供）
|
||
|
||
加密方案：
|
||
- 使用HMAC-SHA256对缺口位置进行签名
|
||
- token格式：`base64(x,y):signature`
|
||
- 密钥使用Django的SECRET_KEY
|
||
|
||
```python
|
||
# captcha/utils.py
|
||
import hmac
|
||
import hashlib
|
||
import base64
|
||
import json
|
||
from django.conf import settings
|
||
|
||
def generate_captcha_token(x: int, y: int) -> str:
|
||
"""生成验证码token，包含加密的缺口位置"""
|
||
data = json.dumps({'x': x, 'y': y}).encode('utf-8')
|
||
signature = hmac.new(
|
||
settings.SECRET_KEY.encode('utf-8'),
|
||
data,
|
||
hashlib.sha256
|
||
).hexdigest()
|
||
token_data = base64.urlsafe_b64encode(data).decode('utf-8')
|
||
return f"{token_data}:{signature}"
|
||
|
||
def verify_captcha_token(token: str, x: int, y: int, tolerance: int = 5) -> bool:
|
||
"""验证token和用户提交的坐标"""
|
||
try:
|
||
token_data, signature = token.split(':')
|
||
data = base64.urlsafe_b64decode(token_data)
|
||
# 验证签名
|
||
expected_signature = hmac.new(
|
||
settings.SECRET_KEY.encode('utf-8'),
|
||
data,
|
||
hashlib.sha256
|
||
).hexdigest()
|
||
if not hmac.compare_digest(signature, expected_signature):
|
||
return False
|
||
# 解析原始坐标
|
||
original = json.loads(data)
|
||
# 验证用户坐标是否在容差范围内
|
||
return (abs(original['x'] - x) <= tolerance and
|
||
abs(original['y'] - y) <= tolerance)
|
||
except Exception:
|
||
return False
|
||
```
|
||
|
||
- [ ] **Step 2: 创建验证码API视图**
|
||
|
||
```python
|
||
# captcha/views.py
|
||
from rest_framework.views import APIView
|
||
from rest_framework.response import Response
|
||
from rest_framework import status
|
||
from django.core.cache import cache
|
||
import random
|
||
from .utils import generate_captcha_token, verify_captcha_token
|
||
|
||
class GenerateCaptchaView(APIView):
|
||
"""生成验证码数据"""
|
||
def get(self, request):
|
||
# 生成随机缺口位置（实际应用中应根据图片尺寸调整）
|
||
x = random.randint(50, 250)
|
||
y = random.randint(20, 120)
|
||
|
||
# 生成token
|
||
token = generate_captcha_token(x, y)
|
||
|
||
# 缓存token，有效期5分钟
|
||
cache_key = f"captcha:{token}"
|
||
cache.set(cache_key, {'x': x, 'y': y}, 300)
|
||
|
||
# 返回数据（实际应用中应返回真实图片URL）
|
||
return Response({
|
||
'token': token,
|
||
'bg_image': '/static/captcha/bg1.jpg', # 示例背景图
|
||
'gap_x': x,
|
||
'gap_y': y,
|
||
'width': 320,
|
||
'height': 160,
|
||
'gap_size': 40
|
||
})
|
||
|
||
class VerifyCaptchaView(APIView):
|
||
"""验证用户提交的滑块位置"""
|
||
def post(self, request):
|
||
token = request.data.get('token')
|
||
user_x = request.data.get('x')
|
||
user_y = request.data.get('y')
|
||
|
||
if not all([token, user_x is not None, user_y is not None]):
|
||
return Response(
|
||
{'error': '缺少必要参数'},
|
||
status=status.HTTP_400_BAD_REQUEST
|
||
)
|
||
|
||
# 从缓存获取原始数据（可选，用于额外验证）
|
||
cache_key = f"captcha:{token}"
|
||
cached_data = cache.get(cache_key)
|
||
|
||
if not cached_data:
|
||
return Response(
|
||
{'error': '验证码已过期或无效'},
|
||
status=status.HTTP_400_BAD_REQUEST
|
||
)
|
||
|
||
# 验证token和坐标
|
||
if verify_captcha_token(token, int(user_x), int(user_y)):
|
||
# 验证成功，删除缓存（一次性使用）
|
||
cache.delete(cache_key)
|
||
return Response({'success': True, 'message': '验证成功'})
|
||
else:
|
||
return Response(
|
||
{'success': False, 'message': '验证失败'},
|
||
status=status.HTTP_400_BAD_REQUEST
|
||
)
|
||
```
|
||
|
||
- [ ] **Step 3: 创建URL路由**
|
||
|
||
```python
|
||
# captcha/urls.py
|
||
from django.urls import path
|
||
from .views import GenerateCaptchaView, VerifyCaptchaView
|
||
|
||
urlpatterns = [
|
||
path('generate/', GenerateCaptchaView.as_view(), name='generate-captcha'),
|
||
path('verify/', VerifyCaptchaView.as_view(), name='verify-captcha'),
|
||
]
|
||
```
|
||
|
||
- [ ] **Step 4: 在Django项目中注册路由**
|
||
|
||
在项目的`urls.py`中添加：
|
||
```python
|
||
from django.urls import path, include
|
||
|
||
urlpatterns = [
|
||
# ... 其他路由
|
||
path('api/captcha/', include('captcha.urls')),
|
||
]
|
||
```
|
||
|
||
- [ ] **Step 5: 创建序列化器（可选，用于数据验证）**
|
||
|
||
```python
|
||
# captcha/serializers.py
|
||
from rest_framework import serializers
|
||
|
||
class VerifyCaptchaSerializer(serializers.Serializer):
|
||
token = serializers.CharField(required=True)
|
||
x = serializers.IntegerField(required=True)
|
||
y = serializers.IntegerField(required=True)
|
||
```
|
||
|
||
- [ ] **Step 6: 提供示例背景图片**
|
||
|
||
在`static/captcha/`目录下放置几张背景图片，用于验证码显示。
|
||
|
||
---
|
||
|
||
## Task 2: 前端API集成
|
||
|
||
**Files:**
|
||
- Modify: `src/utils/request.ts`
|
||
- Modify: `src/components/SliderCaptcha/SliderCaptcha.tsx`
|
||
- Modify: `src/components/SliderCaptcha/captchaUtils.ts`
|
||
|
||
- [ ] **Step 1: 在request.ts中添加验证码API方法**
|
||
|
||
在`api_request`对象中添加captcha模块：
|
||
|
||
```typescript
|
||
// 在request.ts的api_request对象中添加
|
||
const captcha = {
|
||
generate: () =>
|
||
request.public.get("/api/captcha/generate/"),
|
||
|
||
verify: (data: { token: string; x: number; y: number }) =>
|
||
request.public.post("/api/captcha/verify/", data),
|
||
};
|
||
|
||
export const api_request = {
|
||
// ... 其他模块
|
||
captcha, // 添加这一行
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 2: 修改SliderCaptcha组件，使用后端API**
|
||
|
||
修改`SliderCaptcha.tsx`，主要变更：
|
||
1. `loadCaptcha`函数改为从后端获取数据
|
||
2. `doVerify`函数改为发送验证请求到后端
|
||
3. 添加token状态管理
|
||
4. 处理API错误
|
||
|
||
```typescript
|
||
// SliderCaptcha.tsx 关键修改部分
|
||
const SliderCaptcha: React.FC<SliderCaptchaProps> = ({
|
||
width = 320,
|
||
height = 160,
|
||
gapSize = 40,
|
||
tolerance = 5,
|
||
onSuccess,
|
||
onFail,
|
||
onRefresh,
|
||
className = "",
|
||
style = {},
|
||
}) => {
|
||
const [status, setStatus] = useState<CaptchaStatus>("loading");
|
||
const [captchaData, setCaptchaData] = useState<CaptchaResult | null>(null);
|
||
const [sliderX, setSliderX] = useState(0);
|
||
const [message, setMessage] = useState("向右滑动完成验证");
|
||
const [token, setToken] = useState<string>(""); // 新增token状态
|
||
|
||
// ... 其他状态和ref
|
||
|
||
const loadCaptcha = useCallback(async () => {
|
||
setStatus("loading");
|
||
setSliderX(0);
|
||
setMessage("向右滑动完成验证");
|
||
try {
|
||
// 从后端获取验证码数据
|
||
const response = await api_request.captcha.generate();
|
||
const data = response.data;
|
||
|
||
// 使用后端返回的数据生成前端验证码
|
||
const captchaResult = await generateCaptcha(
|
||
data.bg_image,
|
||
data.width,
|
||
data.height,
|
||
data.gap_size
|
||
);
|
||
|
||
setCaptchaData(captchaResult);
|
||
setToken(data.token); // 保存token
|
||
setStatus("ready");
|
||
} catch (error) {
|
||
console.error("获取验证码失败:", error);
|
||
setMessage("验证码加载失败，请刷新重试");
|
||
setStatus("fail");
|
||
}
|
||
}, []);
|
||
|
||
const doVerify = useCallback(async () => {
|
||
if (!isDraggingRef.current || !captchaData || !token) return;
|
||
isDraggingRef.current = false;
|
||
setStatus("verifying");
|
||
|
||
try {
|
||
// 发送到后端验证
|
||
const response = await api_request.captcha.verify({
|
||
token,
|
||
x: sliderX,
|
||
y: captchaData.gapY // 如果后端需要Y坐标
|
||
});
|
||
|
||
if (response.data.success) {
|
||
setStatus("success");
|
||
setMessage("验证成功");
|
||
onSuccess?.();
|
||
} else {
|
||
setStatus("fail");
|
||
setMessage("验证失败，请重试");
|
||
setSliderX(0);
|
||
onFail?.();
|
||
setTimeout(() => {
|
||
handleRefresh();
|
||
}, 1000);
|
||
}
|
||
} catch (error) {
|
||
console.error("验证请求失败:", error);
|
||
setStatus("fail");
|
||
setMessage("验证失败，请重试");
|
||
setSliderX(0);
|
||
onFail?.();
|
||
setTimeout(() => {
|
||
handleRefresh();
|
||
}, 1000);
|
||
}
|
||
}, [captchaData, sliderX, token, onSuccess, onFail]);
|
||
|
||
// ... 其他代码保持不变
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 3: 更新captchaUtils.ts**
|
||
|
||
移除本地生成逻辑，但保留`generateCaptcha`函数用于前端渲染。实际上，我们可以保留现有函数，因为它只是用于生成Canvas图像，不涉及安全逻辑。
|
||
|
||
但需要修改`getRandomImage`函数，因为图片现在由后端提供：
|
||
|
||
```typescript
|
||
// captchaUtils.ts 修改
|
||
/**
|
||
* 获取验证码图片（现在由后端提供，此函数可保留用于兼容）
|
||
*/
|
||
export const getRandomImage = (width: number, height: number): string => {
|
||
// 实际应用中，这个URL应该来自后端API
|
||
// 这里保留作为fallback
|
||
const seed = randomInt(1, 1000);
|
||
return `https://picsum.photos/seed/${seed}/${width}/${height}`;
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 4: 更新演示页面**
|
||
|
||
修改`SliderCaptchaDemo.tsx`，展示后端验证的使用方式，并更新说明文档。
|
||
|
||
---
|
||
|
||
## Task 3: 安全增强与测试
|
||
|
||
**Files:**
|
||
- Modify: `src/components/SliderCaptcha/SliderCaptcha.tsx`
|
||
- Create: 测试用例
|
||
|
||
- [ ] **Step 1: 添加请求频率限制**
|
||
|
||
在前端添加请求间隔限制，防止暴力破解：
|
||
|
||
```typescript
|
||
// SliderCaptcha.tsx 中添加
|
||
const lastVerifyTime = useRef(0);
|
||
const VERIFY_COOLDOWN = 1000; // 1秒冷却时间
|
||
|
||
const doVerify = useCallback(async () => {
|
||
const now = Date.now();
|
||
if (now - lastVerifyTime.current < VERIFY_COOLDOWN) {
|
||
setMessage("操作过于频繁");
|
||
return;
|
||
}
|
||
lastVerifyTime.current = now;
|
||
|
||
// ... 验证逻辑
|
||
}, []);
|
||
```
|
||
|
||
- [ ] **Step 2: 添加错误处理和重试机制**
|
||
|
||
```typescript
|
||
// SliderCaptcha.tsx 中添加重试逻辑
|
||
const [retryCount, setRetryCount] = useState(0);
|
||
const MAX_RETRIES = 3;
|
||
|
||
const doVerify = useCallback(async () => {
|
||
// ... 验证逻辑
|
||
|
||
if (!response.data.success) {
|
||
if (retryCount < MAX_RETRIES) {
|
||
setRetryCount(prev => prev + 1);
|
||
setMessage(`验证失败，还有${MAX_RETRIES - retryCount}次机会`);
|
||
} else {
|
||
setMessage("验证次数已用完，请刷新页面");
|
||
setStatus("fail");
|
||
}
|
||
}
|
||
}, [retryCount]);
|
||
```
|
||
|
||
- [ ] **Step 3: 后端安全增强**
|
||
|
||
1. 添加请求频率限制（Django Ratelimit）
|
||
2. 记录验证尝试次数
|
||
3. 添加IP黑名单机制
|
||
4. 使用HTTPS传输
|
||
|
||
```python
|
||
# 后端安全增强示例
|
||
from django.core.cache import cache
|
||
from django_ratelimit.decorators import ratelimit
|
||
|
||
class VerifyCaptchaView(APIView):
|
||
@ratelimit(key='ip', rate='5/m', method='POST')
|
||
def post(self, request):
|
||
# ... 验证逻辑
|
||
pass
|
||
```
|
||
|
||
- [ ] **Step 4: 编写单元测试**
|
||
|
||
为后端API编写测试用例，确保：
|
||
1. token生成和验证的正确性
|
||
2. 过期token的处理
|
||
3. 错误坐标的验证
|
||
4. 频繁请求的限制
|
||
|
||
---
|
||
|
||
## Task 4: 部署与监控
|
||
|
||
**Files:**
|
||
- Modify: Django设置文件
|
||
- Create: 监控脚本
|
||
|
||
- [ ] **Step 1: 配置缓存后端**
|
||
|
||
确保Django使用Redis或Memcached作为缓存后端，用于存储验证码token：
|
||
|
||
```python
|
||
# settings.py
|
||
CACHES = {
|
||
'default': {
|
||
'BACKEND': 'django_redis.cache.RedisCache',
|
||
'LOCATION': 'redis://127.0.0.1:6379/1',
|
||
'OPTIONS': {
|
||
'CLIENT_CLASS': 'django_redis.client.DefaultClient',
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 添加日志记录**
|
||
|
||
记录验证码生成和验证事件，用于监控和调试：
|
||
|
||
```python
|
||
# views.py 中添加日志
|
||
import logging
|
||
logger = logging.getLogger(__name__)
|
||
|
||
class GenerateCaptchaView(APIView):
|
||
def get(self, request):
|
||
logger.info(f"验证码生成: IP={request.META.get('REMOTE_ADDR')}")
|
||
# ... 生成逻辑
|
||
|
||
class VerifyCaptchaView(APIView):
|
||
def post(self, request):
|
||
logger.info(f"验证码验证: IP={request.META.get('REMOTE_ADDR')}, token={token[:10]}...")
|
||
# ... 验证逻辑
|
||
```
|
||
|
||
- [ ] **Step 3: 监控和告警**
|
||
|
||
设置监控指标：
|
||
1. 验证码生成频率
|
||
2. 验证成功率
|
||
3. 失败尝试次数
|
||
4. 异常请求模式
|
||
|
||
---
|
||
|
||
## 执行选项
|
||
|
||
**计划已保存到 `docs/plans/2026-06-13-slider-captcha-backend-verification.md`。两种执行方式：**
|
||
|
||
**1. Subagent-Driven（推荐）** - 我为每个Task分配一个子代理，任务间进行审查，快速迭代
|
||
|
||
**2. Inline Execution** - 在当前会话中执行任务，使用executing-plans，批量执行并设置检查点
|
||
|
||
**请选择执行方式？**
|
||
|
||
**如果选择Subagent-Driven：**
|
||
- **必需子技能：** 使用superpowers:subagent-driven-development
|
||
- 每个Task一个子代理 + 两阶段审查
|
||
|
||
**如果选择Inline Execution：**
|
||
- **必需子技能：** 使用superpowers:executing-plans
|
||
- 批量执行并设置检查点供审查
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **后端实现需要Django项目配合**：本计划假设后端使用Django REST Framework，需要后端开发人员配合实现。
|
||
2. **图片资源**：需要准备验证码背景图片，或使用图片生成服务。
|
||
3. **安全性考虑**：务必使用HTTPS，保护SECRET_KEY，定期轮换密钥。
|
||
4. **性能优化**：考虑使用CDN加速图片加载，缓存验证码数据。
|
||
5. **用户体验**：添加加载动画、错误提示、重试机制。
|