dc940d2598
- 新增海报生成接口，支持从网页URL或HTML内容生成海报图像 - 新增PDF生成接口，支持从网页URL或HTML内容生成PDF文档 - 添加Swagger API文档注释，完善接口描述和参数说明 - 实现HTML内容参数支持，允许直接传入HTML结构生成海报/PDF - 添加输入验证和标准化响应格式 - 引入DOMPurify库对HTML内容进行安全过滤 - 更新环境变量配置，支持API密钥认证和CORS设置 - 优化上传逻辑，统一返回标准响应结构 - 添加构建脚本支持Docker镜像打包和推送
186 lines
3.9 KiB
Markdown
186 lines
3.9 KiB
Markdown
# ERPTurbo Poster
|
||
|
||
基于 Puppeteer 的海报生成服务，支持多种云存储后端。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.
|
||
├── lib
|
||
│ ├── browser.js # 浏览器管理模块
|
||
│ ├── storage.js # 存储服务模块
|
||
│ ├── params.js # 参数处理模块
|
||
│ ├── utils.js # 工具类模块
|
||
│ ├── routes.js # 路由处理模块
|
||
│ └── constants.js # 常量定义模块
|
||
├── .env # 环境变量配置文件
|
||
├── server.mjs # 主应用入口
|
||
└── package.json # 项目依赖配置
|
||
```
|
||
|
||
## 环境变量配置
|
||
|
||
项目使用 `.env` 文件配置环境变量，请根据需要修改 `.env` 文件中的配置项：
|
||
|
||
```env
|
||
# 存储配置
|
||
STORAGE_TYPE=local # 可选值: cos(腾讯云), oss(阿里云), local(本地存储)
|
||
|
||
# COS 配置 (腾讯云对象存储)
|
||
COS_SECRET_ID=
|
||
COS_SECRET_KEY=
|
||
COS_BUCKET=
|
||
COS_REGION=
|
||
COS_DOMAIN=
|
||
|
||
# OSS 配置 (阿里云对象存储)
|
||
OSS_REGION=oss-cn-hangzhou
|
||
OSS_ACCESS_KEY_ID=
|
||
OSS_ACCESS_KEY_SECRET=
|
||
OSS_BUCKET=
|
||
|
||
# 本地存储配置
|
||
LOCAL_DOMAIN=http://localhost:3000
|
||
|
||
# 上传路径配置
|
||
UPLOAD_PATH=uploads/posters
|
||
|
||
# API 认证配置
|
||
# 多个API密钥用逗号分隔，例如: abc123,def456,ghi789
|
||
ALLOWED_API_KEYS=
|
||
|
||
# 认证开关 (用于临时禁用认证，默认为 false)
|
||
DISABLE_API_AUTH=false
|
||
```
|
||
|
||
## 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
## 启动服务
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
## 接口说明
|
||
|
||
### 1. 健康检查接口
|
||
|
||
- URL: `/status`
|
||
- Method: GET
|
||
- Description: 检查服务运行状态
|
||
|
||
### 2. 海报生成接口
|
||
|
||
- URL: `/api/v1/poster`
|
||
- Method: POST
|
||
- Description: 生成海报并上传到云存储
|
||
- Authentication: 需要有效的API密钥
|
||
- Request Body:
|
||
```json
|
||
{
|
||
"webpage": "需要截图的网页URL",
|
||
"device": "设备缩放因子",
|
||
"width": "截图宽度",
|
||
"height": "截图高度",
|
||
"type": "图片类型(png/jpeg)",
|
||
"encoding": "编码方式(binary/base64)"
|
||
}
|
||
```
|
||
- Authentication: 此接口需要有效的API密钥，可通过以下方式提供：
|
||
- HTTP Header `X-API-Key: <your-api-key>`
|
||
- HTTP Header `Authorization: Bearer <your-api-key>`
|
||
- URL Query Parameter `?api_key=<your-api-key>`
|
||
- Response Format:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"name": "海报文件名",
|
||
"path": "海报文件访问URL"
|
||
},
|
||
"message": "Poster generated successfully",
|
||
"code": 200
|
||
}
|
||
```
|
||
|
||
### 3. PDF下载接口
|
||
|
||
- URL: `/api/v1/pdf`
|
||
- Method: POST
|
||
- Description: 将网页保存为PDF并上传到云存储
|
||
- Authentication: 需要有效的API密钥
|
||
- Request Body:
|
||
```json
|
||
{
|
||
"webpage": "需要生成PDF的网页URL",
|
||
"device": "设备缩放因子",
|
||
"width": "页面宽度",
|
||
"height": "页面高度",
|
||
"encoding": "编码方式(binary/base64)"
|
||
}
|
||
```
|
||
- Authentication: 此接口需要有效的API密钥，可通过以下方式提供：
|
||
- HTTP Header `X-API-Key: <your-api-key>`
|
||
- HTTP Header `Authorization: Bearer <your-api-key>`
|
||
- URL Query Parameter `?api_key=<your-api-key>`
|
||
- Response Format:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"name": "PDF文件名",
|
||
"path": "PDF文件访问URL"
|
||
},
|
||
"message": "PDF generated successfully",
|
||
"code": 200
|
||
}
|
||
```
|
||
|
||
## 模块说明
|
||
|
||
### browser.js
|
||
|
||
浏览器管理模块，负责:
|
||
- 浏览器实例的创建和销毁
|
||
- 页面资源的管理和复用
|
||
- 浏览器连接的维护
|
||
|
||
### storage.js
|
||
|
||
存储服务模块，支持:
|
||
- 腾讯云COS对象存储
|
||
- 阿里云OSS对象存储
|
||
- 本地存储
|
||
- 统一的上传接口
|
||
- 自动根据配置选择存储类型
|
||
|
||
### params.js
|
||
|
||
参数处理模块，负责:
|
||
- 处理截图参数
|
||
- 处理上传参数
|
||
|
||
### utils.js
|
||
|
||
工具类模块，包含:
|
||
- 随机字符串生成函数
|
||
|
||
### routes.js
|
||
|
||
路由处理模块，负责:
|
||
- 处理健康检查接口
|
||
- 处理海报生成接口
|
||
- 处理PDF下载接口
|
||
|
||
### constants.js
|
||
|
||
常量定义模块，包含:
|
||
- 默认配置常量
|
||
- 样式定义常量
|
||
- HTTP状态码常量
|
||
- 字符串常量
|