shenyifei dc940d2598 feat(api): 添加海报和PDF生成功能

- 新增海报生成接口，支持从网页URL或HTML内容生成海报图像
- 新增PDF生成接口，支持从网页URL或HTML内容生成PDF文档
- 添加Swagger API文档注释，完善接口描述和参数说明
- 实现HTML内容参数支持，允许直接传入HTML结构生成海报/PDF
- 添加输入验证和标准化响应格式
- 引入DOMPurify库对HTML内容进行安全过滤
- 更新环境变量配置，支持API密钥认证和CORS设置
- 优化上传逻辑，统一返回标准响应结构
- 添加构建脚本支持Docker镜像打包和推送

2025-11-20 17:51:35 +08:00

2.6 KiB

Raw Permalink Blame History

设计文档：为 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 密钥值
验证中间件和错误处理中不会泄露敏感信息

速率限制

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

2.6 KiB Raw Permalink Blame History Unescape Escape