# 安全加固实施指南

## 当前状态

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

## 已实现的安全功能

### 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")`）
  - 错误堆栈保留
- **用法**：
  ```typescript
  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` | 初始管理员密码（不设置则自动生成） | 自动生成 |