# 设计文档：为 ERPTurbo_Poster API 添加身份验证

## 架构决策

### 1. 认证方法选择

#### 选项1：HTTP Bearer 认证
- 优点：符合 OAuth 2.0 和 JWT 标准，通用性好
- 缺点：需要客户端设置 `Authorization: Bearer <token>` 头

#### 选项2：自定义请求头（X-API-Key）
- 优点：简单实现，易于理解
- 缺点：非标准方法

#### 选项3：查询参数
- 优点：易于测试，无需设置请求头
- 缺点：API 密钥可能记录在服务器日志中

**决策**：采用 HTTP Bearer 认证作为主要方法，同时支持 `X-API-Key` 头作为备选方案，以提供灵活性。

### 2. 密钥存储方案

#### 选项1：环境变量
- 优点：简单，与现有配置方式一致
- 缺点：不适合管理大量密钥或动态更新

#### 选项2：配置文件
- 优点：便于管理多个密钥
- 缺点：需要额外的文件管理

#### 选项3：数据库存储
- 优点：支持动态管理
- 缺点：增加复杂性，对于此项目过于复杂

**决策**：使用环境变量存储允许的 API 密钥列表，以保持简单性并符合现有架构。

### 3. 密钥格式和生成

#### 考虑因素：
- 长度：足够长以防止暴力破解
- 字符集：避免混淆字符
- 生成方式：安全的随机生成

**决策**：实现安全的 API 密钥生成器，创建至少 32 位的随机密钥，使用字母数字字符。

### 4. 错误响应处理

#### 要求：
- 不泄露敏感信息（如密钥验证失败还是其他错误）
- 提供适当的错误代码

**决策**：返回通用的 401 未授权响应，不具体说明认证失败的原因。

### 5. 实现策略

#### 中间件方法：
- 创建一个认证中间件函数
- 在应用层统一应用到需要保护的路由
- 保持路由处理函数的整洁性

**决策**：实现中间件函数，便于维护和重用。

### 6. 向后兼容性

#### 考虑：
- 是否需要临时选项来支持现有客户端
- 部署期间的平稳过渡

**决策**：默认启用认证，但可以配置环境变量来临时禁用认证，以便现有客户端逐步迁移到使用 API 密钥。

### 7. 健康检查端点

#### 要求：
- 健康检查端点必须无需认证，以便监控系统正常工作

**决策**：仅对 `/api/v1/poster` 和 `/api/v1/pdf` 端点应用认证，保持 `/status` 端点开放。

## 安全考虑

### 传输安全
- 强烈建议通过 HTTPS 使用 API，避免在 HTTP 连接中传输 API 密钥

### 日志安全
- 确保认证失败时不记录 API 密钥值
- 验证中间件和错误处理中不会泄露敏感信息

### 速率限制
- 考虑在未来的版本中实现速率限制以防止暴力破解尝试