1. Stirling-PDF可视化网页工具箱，合并、拆分、压缩、OCR、加密、图片转PDF、Word转PDF，普通人直接网页操作，适合论坛用户自助处理PDF
2. Gotenberg无界面，纯HTTP接口，HTML/网页/Office转PDF，程序后端调用（Xiuno二次开发对接）
3. wkhtmltopdf老牌HTML转PDF，占用资源最低，适合简单报表生成，无复杂功能

 
系统兼容：Ubuntu20.04/22.04、Debian11/12、CentOS Stream、RockyLinux
前置统一依赖：Docker（推荐容器部署，规避依赖冲突）
 
前置章节：一键安装Docker & Docker Compose
 
bash
  
apt update && apt install curl -y
curl -fsSL https://get.docker.com | sh
systemctl start docker
systemctl enable docker

验证

docker -v
docker compose version
 
 
CentOS/Rocky：
 
bash
  
yum install curl -y
curl -fsSL https://get.docker.com | sh
systemctl start docker && systemctl enable docker
 
第一部分：Stirling-PDF 全能网页PDF工具箱（完整版）
 

1. 创建部署目录

 
bash
  
mkdir -p /data/stirling-pdf
cd /data/stirling-pdf
vim docker-compose.yml
 
 

2. 完整生产配置（支持中文OCR、登录权限、时区、大文件上传）

 
yaml
  
version: '3.9'
services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "127.0.0.1:8380:8080" # 只监听本地，禁止直接公网暴露，必须Nginx反代
    environment:
      TZ: Asia/Shanghai
      LANGS: zh_CN
      # 安全开关 true=开启登录认证，false=公开访问
      DOCKER_ENABLE_SECURITY: "true"
      SECURITY_ENABLELOGIN: "true"
      # 最大文件上传限制
      SYSTEM_MAXFILESIZE: 200M
      SYSTEM_CONNECTIONTIMEOUTMINUTES: 30
    volumes:
      - ./configs:/configs
      - ./logs:/logs
      - ./tessdata:/usr/share/tesseract-ocr/5/tessdata
    healthcheck:
      test: ["CMD-SHELL", "curl -s http://127.0.0.1:8080/api/v1/info/status > /dev/null"]
      interval: 30s
      timeout: 10s
      retries: 3
 
 
初始账号： admin  密码： stirling ，登录立刻修改！

3. 启动服务

 
bash
  
docker compose up -d

查看日志

docker logs -f stirling-pdf
 

4. 中文OCR字库（识别扫描PDF必备）

 
bash
  

进入容器

docker exec -it stirling-pdf bash
apt update && apt install tesseract-ocr-chi-sim fonts-wqy-zenhei -y
exit
docker restart stirling-pdf
 

5. Nginx反向代理（HTTPS完整版，直接复制）

 
新建配置  /etc/nginx/sites-available/pdf.你的域名.com.conf 
 
nginx
  
server {
    listen 80;
    server_name pdf.xxx.com;
    return 301 https://$host$request_uri;
}
server {
    listen 443 ssl;
    server_name pdf.xxx.com;
    # SSL证书（certbot自动生成）
    ssl_certificate /etc/letsencrypt/live/pdf.xxx.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pdf.xxx.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    # 大文件上传
    client_max_body_size 200M;
    proxy_read_timeout 3600s;
    location / {
        proxy_pass http://127.0.0.1:8380;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
 
 
生效命令：
 
bash
  
ln -s /etc/nginx/sites-available/pdf.xxx.com.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
 

6. 防火墙放行

 
bash
  
ufw allow 80/tcp
ufw allow 443/tcp
 

7. 常用运维命令

 
bash
  

重启

docker compose restart

停止

docker compose down

更新镜像

docker compose pull && docker compose up -d
 

8. 常见坑

1. 中文方块乱码：缺少文泉驿字体，执行上面字体安装命令
2. 上传大文件报错：Nginx  client_max_body_size  和环境变量同步修改
3. 公网直接打不开：不要直接暴露8380端口，严格使用Nginx反向代理
4. 临时文件堆积：容器内自动清理，长期运行无需额外操作

 
第二部分：Gotenberg API 转换服务（程序调用｜Xiuno开发对接）
 
无前端页面，只提供HTTP接口，适合网站代码自动生成PDF（网页转PDF、Word转PDF）
 
1. docker-compose.yml
 
yaml
  
version: '3.8'
services:
  gotenberg:
    image: gotenberg/gotenberg:8
    container_name: gotenberg
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      TZ: Asia/Shanghai
      CHROMIUM_MAX_CONCURRENCY: 4 # 并发数量，不要超过6
      GOTENBERG_LOG_LEVEL: info
 
 
bash
  
mkdir -p /data/gotenberg && cd /data/gotenberg
vim docker-compose.yml
docker compose up -d
 

2. 基础API测试（网页转PDF）

 
bash
  
curl --request POST http://127.0.0.1:3000/forms/chromium/convert/url \
--form url=https://baidu.com \
-o test.pdf
 
执行后当前目录生成  test.pdf 
 

3. Nginx反向代理（可选）

 
nginx
  
location /pdf-api/ {
    proxy_pass http://127.0.0.1:3000/;
    proxy_set_header Host $host;
}
 

4. 优缺点

 
 优点：接口标准化、适合PHP/程序调用、渲染JS网页
缺点：没有网页操作面板，普通用户无法手动处理PDF
 
第三部分：wkhtmltopdf 轻量命令行HTML转PDF
 
不推荐容器，直接宿主机安装，资源占用最低
 
Ubuntu/Debian
 
bash
  
apt update
apt install wkhtmltopdf fonts-wqy-zenhei xvfb -y
 
 
CentOS
 
bash
  
yum install wkhtmltopdf wqy-zenhei-fonts xvfb -y
基础测试命令
 
bash

普通网页

wkhtmltopdf https://baidu.com test.pdf

无图形服务器必须加xvfb-run

xvfb-run wkhtmltopdf https://baidu.com test.pdf
 
常用参数
 
bash
  
--margin-top 15    # 上边距
--javascript-delay 2000 # 等待JS加载2秒
-s A4 # A4纸张
 

 
缺陷重点说明
 

1. 新版网页、Vue/React SPA渲染经常失效
2. 对现代CSS支持差
3. 只适合简单静态页面，不推荐新项目使用
4. 禁止容器端口直接0.0.0.0公网暴露，全部监听127.0.0.1，由Nginx反向代理
5. Stirling-PDF正式环境务必开启登录账号，不要裸奔公开
6. 不要开放匿名上传给外网，防止恶意上传超大文件打满硬盘
7. 定期更新镜像  docker compose pull 
8. 云服务器安全组只放行80/443，自定义内部端口全部封锁