dc940d2598
- 新增海报生成接口，支持从网页URL或HTML内容生成海报图像 - 新增PDF生成接口，支持从网页URL或HTML内容生成PDF文档 - 添加Swagger API文档注释，完善接口描述和参数说明 - 实现HTML内容参数支持，允许直接传入HTML结构生成海报/PDF - 添加输入验证和标准化响应格式 - 引入DOMPurify库对HTML内容进行安全过滤 - 更新环境变量配置，支持API密钥认证和CORS设置 - 优化上传逻辑，统一返回标准响应结构 - 添加构建脚本支持Docker镜像打包和推送
88 lines
2.6 KiB
Markdown
88 lines
2.6 KiB
Markdown
# 设计文档：为 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 密钥值
|
||
- 验证中间件和错误处理中不会泄露敏感信息
|
||
|
||
### 速率限制
|
||
- 考虑在未来的版本中实现速率限制以防止暴力破解尝试 |