mormahr/pdf-service

WeasyPrint in Docker

无状态HTTP API，用于将HTML转换为PDF

!codecov.io !Docker Image Version !Docker Pulls !Docker Image Size

一个Docker化的HTTP服务，使用WeasyPrint从HTML生成PDF文件。主要用例是从开发者控制的模板（如发票）生成文档，并非通用网页转PDF工具。服务期望输入的HTML和其他资源是安全的，不对任意输入进行必要的加固或沙箱处理。请参考本文档的安全部分。

使用

运行Docker镜像mormahr/pdf-service，并向8080端口的/generate端点POST HTML内容。

有关支持的功能和使用方法详情，请参阅API部分。生产环境最佳实践请参见部署部分（特别是安全部分）。

sh
docker run --rm -d --name pdf -p 8080:8080 mormahr/pdf-service

curl \
  -X POST \
  -H "Content-Type: text/html" \
  --data '<p>Hello World!</p>' \
  http://localhost:8080/generate \
  > hello_world.pdf

docker stop pdf

API

无资源支持的基础"简单"API

向/generate发送POST请求，请求体为要渲染的HTML文件。响应将是PDF文件。

sh
curl \
  -X POST \
  -H "Content-Type: text/html" \
  --data '<p>Hello World!</p>' \
  https://pdf.example.com/generate \
  > hello_world.pdf

多部分API

向/generate发送Content-Type为multipart/form-data的POST请求。将HTML输入作为index.html提供，并添加任何所需资源。HTML中引用资源时，可使用绝对URL（如/image.png）或相对URL（如image.png）。相对URL会解析为/。multipart/form-data的name属性请省略前导斜杠。

sh
curl \
  -F index.html=@index.html \
  -F image.png=@image.png \
  -F sub-path/image.png=@sub-path/image.png \
  https://pdf.example.com/generate \
  > hello_world.pdf

html
<!-- index.html -->
<p>带图片：</p>
<img src="/image.png" />
<img src="/sub-path/image.png" />

部署

版本控制

Docker镜像标记为mormahr/pdf-service。

我们尽可能遵循semver，包括检测到视觉变化时的版本更新。因此，我们也标记发布版本，如:1.1.0。支持使用主要版本（:1）或次要版本（:1.1）标签，这些标签会指向最新的次要或补丁版本。

当前开发版本的镜像会持续推送到:edge标签。强烈建议使用发布版本而非:edge。

许可

服务代码采用MIT许可。底层PDF生成库WeasyPrint采用BSD许可。预构建容器镜像包含多种许可，包括GPLv2和GPLv3代码。

目前，由于视觉集成测试中使用poppler，镜像还包含AGPLv3代码。poppler不参与PDF生成，仅包含在集成测试套件中。未来计划从生产镜像中移除测试依赖。

参考一篇关于容器中GPL许可的文章，我认为只要不修改镜像，在闭源环境中使用此容器镜像不应引起问题。如果修改镜像，应进一步了解许可要求，不过添加字体通常无问题。据我理解，此处不会触发affero条款，因为用户根本不与poppler交互。

本部分是我对许可要求的理解，不构成***建议。

安全

不建议允许不受信任的HTML输入。请使用可信HTML模板并 sanitize 用户输入。

目前禁止获取外部资源。可通过多部分API添加内部资源。

如果实例公开暴露，建议使用反向代理终止TLS连接并要求认证。可使用HTTP基本认证，然后通过环境变量将pdf-service URL传递给客户端软件，例如：https://API_USER:API_TOKEN@pdf.example.com/generate，其中API_USER和API_TOKEN是在反向代理中设置的凭据。

环境变量

• WORKER_COUNT（默认：4）设置执行pdf_service的gunicorn服务器的工作池大小。
• HOST 如果容器未设置主机名，可通过环境变量传递以在Sentry中标识服务。
• SENTRY_DSN 启用Sentry集成，并使用此DSN提交数据。
• SENTRY_TRACES_SAMPLE_RATE（0.0...1.0）如果启用Sentry集成，控制跟踪采样率。默认1.0。设为0.0可禁用跟踪。
• SENTRY_ENVIRONMENT 设置发送到Sentry的环境。默认development。
• SENTRY_RELEASE 设置发送到Sentry的版本。我们将其设为当前git SHA，通常无需覆盖。
• SENTRY_TAG_* 为所有事务设置特定值的标签。例如，要将标签test设为abc，设置环境变量SENTRY_TAG_TEST=abc。

健康检查

服务提供/health端点，服务运行时会返回200状态码。此端点也配置为Docker HEALTHCHECK。

开发

设置开发环境

• 设置python虚拟环境
• pip install -r requirements.txt（或：pip install -e '.[dev]'）
• 安装docker和docker-compose以运行测试。测试在docker中运行，确保渲染输出不受平台影响。

运行

• 使用python -m pdf_service运行开发服务器
• 使用./test或./test-watch运行测试
  • 测试在docker中执行，确保渲染结果与容器化版本一致。镜像包含外部依赖，但代码和测试文件会从项目源挂载。如需重建开发镜像，在命令末尾添加--build，这会指示docker-compose重建镜像。

使用参考图片的视觉测试

test-data包含参考输入*.html和对应输出*.png。测试套件会渲染html文件并与参考图片比较，确保无意外变更。

要更新test-data或添加新测试用例，运行./update-test-data。