ai-chatbot/lib/security/IMPLEMENTATION_GUIDE.md

安全加固实施指南

当前状态

本项目已实施多层安全防护。以下为实际部署情况：

已实现的安全功能

1. 速率限制（Rate Limiting）

• 文件：lib/security/rate-limiter.ts
• 中间件入口：middleware.ts → proxy.ts
• 功能：
  • 聊天接口：每分钟 60 次
  • 认证接口：每分钟 5 次
  • 文件上传：每分钟 60 次
  • 图片代理：每分钟 3000 次
  • 画布保存：每分钟 300 次
  • 实时画布：每分钟 600 次
  • UI 轮询：每分钟 1200 次
  • 通用 API：每分钟 100 次
• 注意：当前使用内存存储，多实例部署时建议迁移至 Redis（见下方中长期建议）

2. 可疑请求检测

• 文件：lib/security/request-monitor.ts
• 功能：
  • 检测可疑路径（/.env、/.git 等）
  • 检测可疑 User-Agent
  • 记录但不立即阻止（避免误报）
• 状态：已实现并通过中间件自动运行

3. 输入清理和验证

• 文件：lib/security/input-sanitizer.ts
• 功能：
  • 移除命令注入字符
  • 移除危险关键词
  • 防止路径遍历
  • 防止 XSS 攻击
• 状态：工具函数已就绪，需在各 API 路由中逐步接入

4. IP 黑名单

• 文件：lib/security/ip-blocklist.ts
• 功能：基于配置的 IP 黑名单拦截
• 状态：已通过中间件自动运行

5. HTTP 安全头

• 文件：next.config.ts (headers 配置)
• 已添加：
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: SAMEORIGIN
  • Referrer-Policy: strict-origin-when-cross-origin
  • Permissions-Policy: camera=(), microphone=(), geolocation=()
  • Content-Security-Policy（根据开发/生产环境自动调整）

6. 认证安全

• 文件：app/(auth)/auth.config.ts, app/(auth)/auth.ts
• 改进：
  • trustHost 已改为条件启用（Vercel 环境自动开启，其他环境需设置 AUTH_TRUST_HOST=true）
  • Session cookie 使用 httpOnly + sameSite: lax + secure（HTTPS 环境）
  • 单会话强制（regular 用户）
  • bcrypt 密码哈希 + 时序攻击缓解

7. 结构化日志

• 文件：lib/logger.ts
• 功能：
  • JSON 格式输出（生产环境）
  • 日志级别过滤（LOG_LEVEL 环境变量）
  • 模块名标记（createLogger("ModuleName")）
  • 错误堆栈保留
• 用法：

  import { createLogger } from "@/lib/logger";
  const log = createLogger("MyService");
  log.error("Operation failed", error, { userId: "123" });
  

待改进项

短期（1-2 周）

1. 在所有 API 路由中接入 Zod 输入验证
2. 将现有 console.error 调用迁移至结构化日志
3. 为 service 层 catch 块添加错误日志记录

中期（1-2 月）

1. 将内存速率限制迁移至 Redis（@upstash/ratelimit）
2. 实施更细粒度的速率限制策略
3. 添加结构化日志的持久化存储
4. 集成错误追踪服务（Sentry 等）

长期（3-6 月）

1. 部署 WAF
2. 实施 SELinux 策略
3. 建立安全审计流程
4. CI/CD 中集成 SAST 和依赖扫描

环境变量

新增安全相关环境变量（详见 .env.example）：

变量	说明	默认值
AUTH_TRUST_HOST	是否信任代理 Host 头（非受信环境不要开启）	false
LOG_LEVEL	日志级别（debug/info/warn/error）	开发: info, 生产: warn
ADMIN_EMAIL	初始管理员邮箱（create-admin.ts）	admin@example.com
ADMIN_PASSWORD	初始管理员密码（不设置则自动生成）	自动生成