私有化 PDF 生成

ComPDF Generation 是一项可私有化部署的 HTML 模板管理和 PDF 生成服务。它提供 Web 界面和 HTTP API，用于管理 HTML 模板、可选 JSON 数据源，以及通过 ComPDF PDF Generation 引擎生成 PDF。

当你需要将模板和文档生成流程保留在自己的环境中时，可以使用 ComPDF Generation。

功能

• 用于创建、编辑、搜索、下载和删除模板的浏览器界面。
• 支持为模板配置可选 JSON 数据源。
• 用于程序化生成 PDF 的模板转 PDF HTTP API。
• 基于 Docker Compose 的部署方式和持久化模板存储。

架构

────────────────────────────────────
    Browser / API Client                         
    http://localhost:${APP_PORT}                      
────────────────────────────────────
        │ HTML / CSS / JS
        │ HTTP /api/*
        ▼
────────────────────────────────────
    compdf-generation container                         
    Vue 3 static files + Express API                    
    port 8090                                  
────────────────────────────────────
- Express 提供前端静态资源，并将 SPA 路由回退到 index.html              
- /api/templates/* 管理模板 HTML、JSON 数据源和元数据                   
- /api/v1/process/pdf/generation/template-to-pdf 代理 PDF 生成请求     
- 统一处理上传、超时、错误响应、下载文件名和 traceId                  
────────────────────────────────────
      │ HTTP                                       
      │ compdf-internal                  
      ▼                                                
────────────────────────────────────
 compdf-app container                
 ComPDF PDF Generation engine      
 port 7001                 
────────────────────────────────────

请求链路

1. 浏览器从 compdf-generation 加载构建后的 Vue 单页应用，并通过同源 /api 调用 Express，生产环境无需单独部署静态文件服务器。
2. 模板管理请求由 Express 直接读写 /data/templates；该目录绑定到宿主机的 TEMPLATE_STORAGE_DIR，容器重建后数据仍然保留。
3. PDF 生成请求由 Express 转发到 http://compdf-app:7001/v1/sync/generation/template-to-pdf。Express 负责整理 multipart 请求、透传 PDF 响应，并统一生成错误信息和 traceId。
4. compdf-generation 会等待 compdf-app 健康检查通过后启动；两个服务通过私有桥接网络 compdf-internal 通信。

部署与本地开发

• 生产镜像使用多阶段 Docker 构建：分别编译 Vue 前端和 Express 后端，仅将前端 dist、后端 dist 及生产依赖复制到最终的非 root Node.js 容器。1.1.0 优化了底层镜像，移除不必要的数据库依赖并减小镜像体积。
• Docker Compose 将 APP_PORT（默认 8090）映射到 Web/API 容器；同时将引擎的 7001 端口发布到宿主机，供本地后端开发和连通性检查使用。
• 本地开发时，Vite 运行在独立进程并将 /api 代理到 http://localhost:8090；Express 默认通过 http://localhost:7001 访问 Docker 中的 ComPDF 引擎。

关键框架与第三方组件

层级	框架或组件	用途
前端	Vue 3、Vue Router、Vue I18n	单页界面、路由和六语言国际化。
前端构建	Vite、TypeScript、Less	开发服务器、类型检查和样式构建。
前端 UI	TDesign Vue Next、tdesign-icons-vue-next	页面组件与图标。
模板编辑	WangEditor（@wangeditor/editor-for-vue）	HTML 富文本模板编辑。
HTTP 客户端	Axios	调用同域 /api 接口并处理文件下载。
后端	Node.js 22、Express、TypeScript	提供 HTTP API、静态文件和 ComPDF 代理。
上传与归档	Multer、Archiver	处理 multipart 文件上传与模板 ZIP 下载。
PDF 生成	compdfkit/pdf-generation:1.1.0	执行 HTML / 模板到 PDF 的同步生成。
部署	Docker Compose、Docker 多阶段构建	编排 ComPDF 引擎与 Web/API 容器。
数据持久化	宿主机文件系统	持久化模板 HTML、JSON 和元数据。

下一步

• 按照如何使用部署服务。
• 通过模板转 PDF API生成文档。