运维文档

# Puppeteer打印部署手册

# 背景

标准产品的CAP4报表等功能由于涉及很多后台算力，在进行报表打印时，均采用后端无头浏览器打印技术。

标准产品默认的后台打印使用PhantomJS技术，这种技术在信创环境支持较弱，同时随着PhantomJS不再维护，其功能在非信创环境下的兼容性也越来越差。

当项目上遇到无法使用默认的PhantomJS打印时，则需要考虑替代方案，目前市面推荐的是采用"Node+Puppeteer+Chromium"替代（后文均简称Puppeteer）。

Puppeteer: 是 Google Chrome 的 Headless 版本的一个工具，它提供了一个高级的 API 来控制 Chrome。与 PhantomJS 相比，Puppeteer 提供了更为强大的功能，并且是 Chrome 团队官方支持的项目。

哪些需要更换Puppeteer方案？

  1. 麒麟信创系统下，使用CAP4表单打印功能时（如报表打印、报表转发、CAP4表单转新闻公告空白或失败），提示"执行截图服务失败"。

  2. 客开使用htmltopdf接口，后台打印生成PDF进行归档操作失败，查看日志均体现在PhantomJS不可用。

  3. 移动端进行打印时，显示不全，上报BUG后研发建议更换为Puppeteer模式。

# 系统内置三种打印引擎模式

V11 版本起，系统内置了三种打印引擎模式，无需再修改配置文件，统一在系统管理界面进行切换：

模式 说明 适用场景
传统方式 使用内置的 PhantomJS / WK 截图组件 常规环境、无需信创支持
本地Puppeteer 使用OA服务器本地部署的 PrintEngine（已内置到安装包） V11 标准环境开箱即用
远程Puppeteer服务 使用远程独立容器中的 Puppeteer 服务 信创环境、非标准CPU/操作系统

切换方式：

  1. 使用系统管理员账号登录OA

  2. 进入 系统管理员 → 系统设置 → 系统参数设置

  3. 找到 【功能选项】打印引擎模式，按需选择：

    • 传统方式：默认模式，无需额外配置

    • 本地Puppeteer：V11 安装包已内置 PrintEngine，选中即可使用，无需额外配置

    • 远程Puppeteer服务：选中后需配置以下两个参数：

      参数 说明 示例
      远程服务地址 Puppeteer 容器服务的访问地址 http://10.1.131.195:16395
      A8回调地址 远程 Puppeteer 服务回调访问 OA 的地址（容器部署或反向代理场景必须配置） http://宿主机IP:8080

  4. 点击底部 确定 保存，配置即时生效，无需重启服务。

A8回调地址说明：远程 Puppeteer 容器需要回调访问 OA 系统以获取用户会话信息（Cookie）。当 OA 部署在容器内或通过反向代理时，容器无法自动获取 OA 的真实地址，此时需手动填写 OA 的访问地址（如 http://宿主机IP:8080）。如果不配置，系统将自动获取本机地址。

# 部署：

# 方式1：标准内置部署（本地Puppeteer）

V11 版本时，Puppeteer 已内置到标准安装包中，且在标准安装过程中会把相关内容部署到 ApacheJetspeed 同级目录，名称为 PrintEngine。

部署步骤：

  1. 正常安装 V11 标准版本（安装包已内置 PrintEngine）
  2. 登录 OA，进入 系统管理员 → 系统设置 → 系统参数设置
  3. 在 【功能选项】 中找到 打印引擎模式，选择 本地Puppeteer
  4. 点击 确定 保存

默认即可使用，无需额外操作。

# 方式2：容器化部署（远程Puppeteer服务）

适用于非常规 CPU 架构（如龙芯 loongarch）或非常规操作系统的场景。

提示：部署完成后，需要在 OA 界面中切换打印引擎模式并配置远程服务地址，详见本文档"三、OA配置修改"章节。

# 一、镜像信息

项目 值
AMD64镜像 puppeteer-service-amd64.tgz (opens new window)
ARM64镜像 puppeteer-service-arm64.tgz (opens new window)
服务端口 16395
内存建议 4GB
磁盘空间 2GB+

# 二、部署步骤

# 2.1 下载镜像

从华为云OBS下载对应架构的镜像包：

# AMD64 架构
wget https://puppeteer-chromium.obs.cn-north-4.myhuaweicloud.com/amd64/puppeteer-service-amd64.tgz

# ARM64 架构（信创环境）
wget https://puppeteer-chromium.obs.cn-north-4.myhuaweicloud.com/arm64/puppeteer-service-arm64.tgz

# 2.2 解压并导入镜像

# 解压镜像
tar -zxvf puppeteer-service-amd64.tgz   # AMD64
tar -zxvf puppeteer-service-arm64.tgz   # ARM64

# 导入镜像
docker load -i puppeteer-service-amd64.tar   # AMD64
docker load -i puppeteer-service-arm64.tar   # ARM64

# 查看导入的镜像
docker images | grep puppeteer-service

# 2.3 启动容器

docker run -d \
  --name puppeteer-service \
  --restart unless-stopped \
  --memory="4g" \
  --memory-swap="6g" \
  --cpus="4.0" \
  --cpu-quota=-1 \
  --shm-size="2g" \
  --ulimit nofile=65536:65536 \
  --ulimit nproc=65536:65536 \
  -p 16395:16395 \
  -e TZ=Asia/Shanghai \
  -e NODE_ENV=production \
  -e SAVE_SCREENSHOTS=true \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/screenshots:/app/screenshots \
  -v /usr/share/fonts:/usr/share/fonts:ro \
  -v /dev/shm:/dev/shm \
  --cap-add=SYS_ADMIN \
  --security-opt seccomp=unconfined \
  --tmpfs /tmp:rw,noexec,nosuid,size=2g \
  --tmpfs /run:rw,noexec,nosuid,size=256m \
  puppeteer-service:latest

# 2.4 刷新字体缓存

# 刷新字体
docker exec puppeteer-service fc-cache -f

# 查看已安装字体
docker exec puppeteer-service fc-list

# 2.5 验证服务

# 检查容器状态
docker ps -a | grep puppeteer

# 检查服务健康状态
curl -s -X GET http://<服务器IP>:16395/health

# 查看容器日志
docker logs -f --tail 50 puppeteer-service

# 三、OA 配置修改

# V11 版本（界面配置）

配置入口参考：

打印引擎模式入口

V11 版本不再修改配置文件，统一通过系统管理界面进行配置。

切换本地Puppeteer模式：

  1. 使用系统管理员账号登录 OA
  2. 进入 系统管理员 → 系统设置 → 系统参数设置
  3. 找到 【功能选项】打印引擎模式
  4. 选择 本地Puppeteer，点击 确定

切换远程Puppeteer服务模式：

  1. 进入 系统管理员 → 系统设置 → 系统参数设置

  2. 找到 【功能选项】打印引擎模式

  3. 选择 远程Puppeteer服务

  4. 配置以下两个参数：

    参数 填写说明 示例
    远程服务地址 Puppeteer 容器的访问地址，端口默认为 16395 http://10.1.131.195:16395
    A8回调地址 远程服务回调 OA 的地址。容器部署或反向代理场景必须配置 http://宿主机IP:8080

远程参数配置示例：

远程参数配置

  1. 点击 确定 保存

参数说明：

  • 远程服务地址：填写 Puppeteer 容器所在服务器的 IP 和端口，确保 OA 服务器能够访问该地址。
  • A8回调地址：当 Puppeteer 容器需要访问 OA 系统以获取用户会话信息时使用的地址。
    • 如果 OA 直接部署在物理机/虚拟机上，可不填写，系统自动使用本机地址。
    • 如果 OA 部署在容器内（如 Docker）或通过反向代理（如 Nginx）访问，则需要填写 OA 的外部可访问地址。

注意：界面配置保存后即时生效，无需重启 OA 服务。

# V10.0 SP1 及以下版本（配置文件方式）

旧版本需要通过修改配置文件启用 Puppeteer。

编辑 base/conf/systemCtp.properties 配置文件，按示例增加配置：

puppeteerPrint.printServer = true
# 将下列IP地址替换为puppeteer容器所在宿主机IP（容器端口默认16395）
puppeteerPrint.remoteUrl = http://10.1.131.118:16395
puppeteerPrint.switch = true

配置修改后需重启OA服务。

# 四、打印测试

  1. 配置完成后，登录系统
  2. 使用 CAP4 表单打印功能进行测试
  3. 检查报表打印、报表转发等功能是否正常

快速验证方法：

  • 在 OA 中打开任意一个 CAP4 表单，点击打印，观察是否正常生成 PDF
  • 检查系统日志（logs/cap4/ 目录），确认打印调用链路正常
  • 如果使用远程Puppeteer模式，可通过浏览器访问 http://远程服务IP:16395/health 验证服务状态

# 五、镜像导出（用于离线部署）

如需在其他服务器部署，可将镜像导出为tar包：

# AMD64
docker save puppeteer-service:latest | gzip > puppeteer-service-amd64.tgz

# ARM64
docker save puppeteer-service:latest | gzip > puppeteer-service-arm64.tgz

# 六、常见问题

# Q1: 打印内容显示异常（缺少文字）

字体未正确加载，执行字体刷新：

docker exec puppeteer-service fc-cache -f
docker restart puppeteer-service

# Q2: 容器启动失败

检查内存和权限配置，确保足够的系统资源。建议内存不低于 4GB。

# Q3: 连接超时

确认防火墙已开放 16395 端口：

firewall-cmd --add-port=16395/tcp --permanent
firewall-cmd --reload

# Q4: 切换打印引擎模式后打印无变化

  • 确认界面配置已点击 确定 保存
  • 远程Puppeteer模式需确认 远程服务地址 和 A8回调地址 均已正确填写
  • 检查远程服务是否正常运行：curl http://远程服务IP:16395/health

# Q5: 远程Puppeteer服务调用失败

  • 确认 OA 服务器能够访问远程服务地址（网络连通性）
  • 确认 A8回调地址配置正确（容器或反向代理场景必须配置）
  • 查看容器日志：docker logs -f --tail 50 puppeteer-service

# Q6: V11 版本是否还需要同步修改配置文件？

不需要。V11 版本打印引擎配置已迁移至系统管理界面，通过 系统管理员 → 系统设置 → 系统参数设置 → 打印引擎模式 进行切换，配置即时生效，无需改文件、无需重启服务。

# 附录：部署检查清单

部署前可按以下清单逐项确认：

  • [ ] 确认 OA 版本（V10/V11）
  • [ ] 确认服务器 CPU 架构和操作系统
  • [ ] 根据环境选择部署方式（本地内置 / 容器化）
  • [ ] 容器化部署时，确认已下载对应架构的镜像
  • [ ] 按部署步骤启动服务
  • [ ] 验证服务健康状态（curl http://服务IP:16395/health）
  • [ ] 登录 OA 界面，切换打印引擎模式
  • [ ] 远程模式需填写远程服务地址和 A8 回调地址
  • [ ] 执行打印测试
编撰人：wangyxyf、pengbin、zhoulongbo、het

快速跳转

← (2025)Puppeteer打印部署手册 →