如何使用

开始前准备

• Windows 或 macOS 上的 Docker Desktop，或 Linux 上的 Docker Engine 和 Docker Compose plugin。
• 可从 Docker Hub 拉取 compdfkit/pdf-generation:1.1.0 镜像。

获取项目

克隆仓库并进入项目目录：

git clone https://github.com/ComPDFKit/compdf-generation.git
cd compdf-generation

配置并启动

项目会在 .env.example 中提供试用 License。部署前复制该文件重命名为.env即可使用试用 License；使用试用 License 生成的 PDF 会带有水印。

正式生产使用时，请将 COMPDF_LICENSE_KEY 替换为正式 License，以移除试用水印。可联系销售获取正式 License。请根据操作系统选择对应命令复制环境变量文件：

# Windows PowerShell
Copy-Item .env.example .env

# macOS 或 Linux
cp .env.example .env

启动服务：

docker compose up -d --build
docker compose ps

当 compdf-app 状态变为 healthy 后，打开 http://localhost:8090。部署到远程 Linux 服务器时，请在能访问该服务器 8090 端口的浏览器中打开该地址。

环境变量

启动服务前，可在 .env 中配置以下变量：

变量	默认值	说明
COMPDF_LICENSE_KEY	必填	具有 PDF Generation 或 HTML 转 PDF 权限的 ComPDF License Key。.env.example 中提供的试用 Key 生成的 PDF 会带有水印。
COMPDF_IMAGE_PLATFORM	linux/amd64	compdf-app 镜像使用的平台。仅当镜像支持部署主机所需的平台时才修改该值。
NODE_IMAGE	node:22-bookworm-slim	用于构建 Web 和 API 服务 Docker 多阶段镜像的 Node.js 镜像。
APP_PORT	8090	映射到宿主机的 ComPDF Generation Web 界面和 API 端口。8090 被占用时可改为其他可用端口。
COMPDF_TIMEOUT_MS	120000	Web/API 服务等待 ComPDF 引擎响应的最长时间，单位为毫秒。处理大型或复杂模板耗时较长时，可适当调大此值。
TEMPLATE_STORAGE_DIR	./data/templates	宿主机上用于持久化 HTML 模板、JSON 数据源和元数据的目录。部署需要固定数据位置时可使用绝对路径。

验证部署

docker compose ps
docker compose logs --tail=100 compdf-generation compdf-app

两个服务均需处于运行状态，且 compdf-app 必须为 healthy 后才能生成 PDF。需要从其他设备访问服务时，请在服务器防火墙或安全组中放行 APP_PORT（默认 8090）的入站 TCP 流量。

创建并生成模板

1. 在模板列表中新建模板，或导入 .html、.htm、.zip、.dito 文件创建模板。
2. 打开模板编辑器，编写 HTML 内容。
3. 按需添加 JSON 数据，并保存模板。
4. 在编辑器中生成 PDF，浏览器会下载结果文件。

模板存储在 TEMPLATE_STORAGE_DIR 中，默认路径为 ./data/templates。重建应用容器不会删除这些数据。