dc940d2598
- 新增海报生成接口，支持从网页URL或HTML内容生成海报图像 - 新增PDF生成接口，支持从网页URL或HTML内容生成PDF文档 - 添加Swagger API文档注释，完善接口描述和参数说明 - 实现HTML内容参数支持，允许直接传入HTML结构生成海报/PDF - 添加输入验证和标准化响应格式 - 引入DOMPurify库对HTML内容进行安全过滤 - 更新环境变量配置，支持API密钥认证和CORS设置 - 优化上传逻辑，统一返回标准响应结构 - 添加构建脚本支持Docker镜像打包和推送
192 lines
9.6 KiB
Markdown
192 lines
9.6 KiB
Markdown
# 项目上下文
|
||
|
||
## 项目目的
|
||
ERPTurbo_Poster 是一个基于 Web 的服务，可以从网页内容生成海报和 PDF。该服务使用 Puppeteer 渲染网页并将其转换为图像（海报）或 PDF。它设计用于处理 HTML 内容转换并支持适当的字体嵌入，还支持多种存储后端，包括本地存储、腾讯云 COS 和阿里云 OSS。该服务特别适用于需要将网页内容转换为视觉呈现形式的场景，如营销海报生成、报告PDF生成、电子书制作、网页存档等。
|
||
|
||
**核心价值**：
|
||
- 将动态网页内容转换为静态视觉格式
|
||
- 支持批量文档生成和处理
|
||
- 提供RESTful API接口，易于集成
|
||
- 多云存储支持，灵活的部署选项
|
||
|
||
## 技术栈
|
||
- **运行时环境**: Node.js (v20+)
|
||
- **Web 框架**: Express.js (v5.0.0)
|
||
- **浏览器自动化**: Puppeteer v24.29.1（用于网页渲染和截图）
|
||
- **云存储 SDK**:
|
||
- ali-oss v6.17.1 (阿里云对象存储)
|
||
- cos-nodejs-sdk-v5 v2.8.3 (腾讯云对象存储)
|
||
- **开发工具**:
|
||
- dotenv v8.2.0 (环境变量管理)
|
||
- body-parser v2.2.0 (请求体解析，支持10MB限制)
|
||
- node-fetch v3.3.2 (HTTP 请求)
|
||
- swagger-jsdoc v6.2.8 & swagger-ui-express v5.0.1 (API 文档)
|
||
- dompurify v3.3.0 (HTML清理，防止XSS攻击)
|
||
- jsdom v27.2.0 (DOM操作，用于HTML处理和清理)
|
||
- **模块系统**: ES6+ JavaScript 模块 (ESM)，使用 .mjs 和 .js 扩展名
|
||
|
||
## 项目约定
|
||
|
||
### 代码风格
|
||
- **模块系统**: ES6+ JavaScript 模块（文件扩展名为 .mjs 和 .js）
|
||
- **变量声明**: 尽可能使用 const 进行变量声明，需要可变时使用 let
|
||
- **函数定义**: 使用函数声明定义路由处理程序和工具函数
|
||
- **异步操作**: 统一使用 async/await 模式
|
||
- **错误处理**: 在 Puppeteer 操作周围使用 try/catch 块进行错误处理，并在 finally 块中进行资源清理
|
||
- **命名约定**:
|
||
- 类名使用 PascalCase（例如，BrowserManager、StorageManager）
|
||
- 函数和变量名使用 camelCase
|
||
- **文档**: 为函数使用 JSDoc 风格的注释，包含参数文档
|
||
- **代码安全**: 添加安全头部（X-Content-Type-Options、X-Frame-Options、X-XSS-Protection）和内容类型验证
|
||
- **代码结构**: 每个模块导出具体的函数或类，通过 import/export 进行模块化管理
|
||
|
||
### 架构模式
|
||
- **模块化架构，关注点分离**：
|
||
- `server.mjs`：主要应用程序入口点和 Express 服务器设置，整合各模块
|
||
- `lib/`：包含可重用模块
|
||
- `browser.js`：Puppeteer 浏览器管理，包含页面池和浏览器生命周期管理
|
||
- `storage.js`：多提供商存储抽象（本地/COS/OSS），提供统一的存储接口
|
||
- `routes.js`：海报/PDF 生成的 API 路由处理程序，包含业务逻辑
|
||
- `constants.js`：应用程序常量和配置，如字体样式定义
|
||
- `params.js`：请求参数处理和验证，生成截图参数
|
||
- `utils.js`：用于字符串操作和 HTML 转换的工具函数
|
||
- `auth.js`：API认证中间件，支持多种认证方式（Bearer Token、API Key Header、Query Parameter）
|
||
- `response.js`：标准化API响应格式，包含错误处理和成功响应结构
|
||
- `swagger.js`：Swagger API文档配置和注释定义
|
||
- **单例模式**: BrowserManager 和 StorageManager 实例使用单例模式
|
||
- **资源管理**: 请求范围的资源管理（在处理程序中获取页面，在 finally 块中返回到池）
|
||
- **API 文档**: 使用 Swagger 注解进行 API 文档生成，定义了 POST /api/v1/poster 和 POST /api/v1/pdf 等接口
|
||
- **安全设计**:
|
||
- API密钥认证机制，支持Bearer Token和X-API-Key Header两种方式
|
||
- DOMPurify集成用于HTML内容清理，防止XSS攻击
|
||
- 请求大小限制（10MB）和内容类型验证
|
||
- 安全HTTP头部配置（CSP、XSS保护等）
|
||
- **响应标准化**: 统一的API响应格式，包含success、data、message、code字段
|
||
|
||
### 测试策略
|
||
- **单元测试**: [当前未实现 - 建议添加 Jest 或 Mocha 测试框架]
|
||
- **集成测试**: [当前未实现 - 建议添加 Supertest 进行 API 接口测试]
|
||
- **端到端测试**: [当前未实现 - 建议添加 Puppeteer 集成测试]
|
||
- **安全测试**: [当前未实现 - 建议添加 OWASP ZAP 或类似工具进行安全扫描]
|
||
- **性能测试**: [当前未实现 - 建议添加 Artillery 或 K6 进行负载测试]
|
||
- **手动测试**: 在开发环境进行功能验证，通过 Swagger UI 进行接口测试
|
||
|
||
### Git 工作流
|
||
- **分支策略**: 使用功能分支模型，主分支为 main，开发在 feature 分支进行
|
||
- **提交信息**: 使用约定式提交格式 (e.g., feat: add pdf generation, fix: resolve memory leak)
|
||
- **代码审查**: 通过 Pull Request 进行代码审查和合并
|
||
- **版本管理**: 使用语义化版本控制 (Semantic Versioning)
|
||
- **发布流程**: 通过 Git 标签管理版本发布，支持自动化部署
|
||
|
||
## 领域上下文
|
||
- **核心功能**:
|
||
- 从网页 URL 或直接 HTML 内容生成海报图像和 PDF 文档
|
||
- 支持自定义参数：宽度、高度、设备缩放、图片质量、编码格式等
|
||
- 支持 JSON 格式输入转 HTML（通过 jsonToHtml 工具函数）
|
||
- 提供健康检查接口 /status 和 API 文档接口 /api-docs
|
||
- 多格式输出：PNG、JPEG图片格式，A4标准PDF格式
|
||
- 批量处理能力：支持通过API调用进行批量文档生成
|
||
- **内容转换类型**:
|
||
- 网页截图（海报），可自定义视口尺寸和设备缩放
|
||
- 从网页或直接 HTML 内容生成 PDF（A4 格式）
|
||
- **字体渲染**: 包含通过嵌入的 font-face 声明对中文字体的特殊处理，确保中文字符的正确显示，支持PingFang字体家族
|
||
- **资源管理**: 浏览器页面使用池化管理以高效处理并发请求，避免浏览器实例过多导致的资源消耗，支持动态调整池大小
|
||
- **存储策略**: 支持多提供商存储抽象，允许在本地、腾讯云 COS 或阿里云 OSS 存储之间切换，通过环境变量灵活配置
|
||
- **API安全**: 完整的API密钥认证体系，支持多种密钥配置和临时禁用认证的开发模式
|
||
|
||
## 重要约束
|
||
- **Puppeteer 环境**: 在部署环境中需要安装 Chrome/Chromium 浏览器，或使用系统已安装的 Chrome
|
||
- **并发限制**: 并发性受池中可用浏览器页面数量的限制，可以通过调整 browser.js 中的 initBrowser 参数来改变页面数
|
||
- **存储配置**: 存储配置必须通过环境变量正确设置，否则可能导致上传失败
|
||
- **内存管理**: 需要定期清理浏览器实例以防止内存泄漏，browser.js 包含了自动清理机制
|
||
- **大文件处理**: 大文件上传可能需要调整 Express body parser 限制（当前设置为 10MB）
|
||
- **中文字体支持**: 中文字体渲染需要特定的 font-face 样式注入，以确保在不同环境中正确显示
|
||
- **安全性**: 为防止请求伪造和 XSS 攻击，添加了安全头、内容类型验证和DOMPurify HTML清理
|
||
- **API认证**: 生产环境必须配置API密钥，开发环境可通过DISABLE_API_AUTH=true临时禁用认证
|
||
- **字体依赖**: 依赖外部字体CDN（阿里云图标字体），需要确保网络连接正常
|
||
- **端口配置**: 默认端口3000，可通过PORT环境变量自定义
|
||
|
||
## 外部依赖
|
||
- **云服务**:
|
||
- 腾讯云对象存储（COS）- 通过 cos-nodejs-sdk-v5 访问
|
||
- 阿里云对象存储服务（OSS）- 通过 ali-oss 访问
|
||
- **浏览器引擎**: Chrome/Chromium 浏览器用于 Puppeteer 渲染
|
||
- **字体服务**: 阿里云图标字体CDN（at.alicdn.com）用于中文字体支持
|
||
- **包管理**: NPM registry 用于包管理，使用pnpm作为包管理器
|
||
- **配置管理**: 环境变量用于服务配置（端口、存储凭据、API密钥等）
|
||
- **文档生成**: Swagger UI 用于 API 文档展示，访问路径 /api-docs
|
||
- **Docker**: 支持通过 Docker 进行容器化部署
|
||
- **运行时依赖**: Node.js v20+ 运行环境
|
||
|
||
## API 接口概览
|
||
|
||
### 核心端点
|
||
- **GET /status**: 健康检查接口，返回服务运行状态
|
||
- **GET /api-docs**: Swagger API 文档界面
|
||
- **POST /api/v1/poster**: 生成海报图片接口
|
||
- **POST /api/v1/pdf**: 生成PDF文档接口
|
||
|
||
### 认证方式
|
||
- **Bearer Token**: `Authorization: Bearer <api-key>`
|
||
- **API Key Header**: `X-API-Key: <api-key>`
|
||
- **Query Parameter**: `?api_key=<api-key>`
|
||
|
||
### 响应格式
|
||
```json
|
||
{
|
||
"success": boolean,
|
||
"data": object|null,
|
||
"message": string,
|
||
"code": number
|
||
}
|
||
```
|
||
|
||
## 部署架构
|
||
|
||
### 推荐部署环境
|
||
- **开发环境**: 本地Node.js运行，使用本地存储
|
||
- **测试环境**: Docker容器化部署，模拟生产配置
|
||
- **生产环境**: 云服务器部署，使用COS/OSS云存储
|
||
|
||
### 容器化支持
|
||
- 支持Docker多阶段构建
|
||
- 包含Chrome/Chromium浏览器镜像
|
||
- 环境变量配置外部化
|
||
- 健康检查和优雅关闭
|
||
|
||
### 监控和日志
|
||
- 应用级日志输出到stdout
|
||
- 支持结构化日志格式
|
||
- 错误追踪和性能监控
|
||
- 资源使用情况监控
|
||
|
||
## 性能指标
|
||
|
||
### 关键性能指标
|
||
- **响应时间**: 海报生成通常3-10秒，PDF生成5-15秒
|
||
- **并发处理**: 受浏览器页面池大小限制（默认2个页面）
|
||
- **内存使用**: 每个Chrome实例约100-200MB内存
|
||
- **存储吞吐**: 依赖云存储服务商的网络性能
|
||
|
||
### 优化建议
|
||
- 根据服务器规格调整浏览器页面池大小
|
||
- 使用CDN加速字体和静态资源加载
|
||
- 定期清理临时文件和浏览器缓存
|
||
- 监控内存使用并设置合理的重启策略
|
||
|
||
## 安全考虑
|
||
|
||
### 已实现的安全措施
|
||
- API密钥认证机制
|
||
- DOMPurify HTML内容清理
|
||
- 请求大小限制（10MB）
|
||
- 安全HTTP头部配置
|
||
- 输入参数验证和清理
|
||
|
||
### 安全最佳实践
|
||
- 定期轮换API密钥
|
||
- 使用HTTPS传输
|
||
- 限制API调用频率
|
||
- 监控异常请求模式
|
||
- 定期更新依赖包版本
|