# V11发版-Puppeteer打印部署手册

# 前言

本文作为在线 Wiki 部署手册，仅适用于 V11 标准版本。V11 已包含 Puppeteer 打印标准化代码，不需要下载安装低版本 A8 代码补丁。

V10.0SP1 及以下客户请使用同目录《V10.0SP1及以下版本Puppeteer打印补丁操作手册》。

# 一、打印引擎模式

系统管理员进入：

系统管理 -> 系统设置 -> 系统参数设置 -> 功能选项 -> 打印引擎模式

后台可选择三种模式：

模式	使用场景	必要条件
传统方式	临时回退或兼容原打印链路	不使用 PrintEngine 和远程容器
本地 Puppeteer	A8 服务器本机执行打印	安装匹配系统的 PrintEngine
远程 Puppeteer 服务	独立 Linux 容器执行打印	部署容器并配置服务地址和 A8 callback 地址

生产环境应明确选择模式，不建议长期依赖自动判断。

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

V11版本安装包已内置 PrintEngine ，无需手动下载。

缺少字体时，把字体文件放到：

&lt;A8安装根目录>/PrintEngine/fonts

Linux 刷新字体缓存：

fc-cache -fv <A8安装根目录>/PrintEngine/fonts

重启 OA 后使用实际公文、表单和报表验证字体。

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

# 3.1 镜像信息

架构	文件名	SHA256	镜像tag
AMD64	`puppeteer-service-amd64.tgz`	`9444c17fef28fd5e5c65d28cd69fcf425380f6d8bf9c61c3d4638323c264af41`	`puppeteer-service:V11-20260403`
ARM64	`puppeteer-service-arm64.tgz`	`9ed16df8fc6a1f6edf821332a40dc3973afee30b37d336487b56ab378dcb95cf`	`puppeteer-service:V11-20260403`

本次发布镜像不使用历史私有仓库标签。容器镜像从下述固定 OBS 地址下载；如果发布方覆盖了同名对象，必须同步更新本文 SHA256 并重新完成公网下载验证。

# 3.2 部署命令

# 查看宿主机架构

uname -m

# AMD64导入镜像

# 下载容器镜像
wget -O puppeteer-service-amd64.tgz https://puppeteer-chromium.obs.cn-north-4.myhuaweicloud.com/amd64/puppeteer-service-amd64.tgz

# 校验镜像
echo "9444c17fef28fd5e5c65d28cd69fcf425380f6d8bf9c61c3d4638323c264af41  puppeteer-service-amd64.tgz" | sha256sum -c -

# 导入镜像
docker load -i puppeteer-service-amd64.tgz

# ARM64导入镜像

wget -O puppeteer-service-arm64.tgz https://puppeteer-chromium.obs.cn-north-4.myhuaweicloud.com/arm64/puppeteer-service-arm64.tgz

# 校验镜像
echo "9ed16df8fc6a1f6edf821332a40dc3973afee30b37d336487b56ab378dcb95cf  puppeteer-service-arm64.tgz" | sha256sum -c -

# 导入镜像
docker load -i puppeteer-service-arm64.tgz

# 启动容器

# 创建puppeteer目录
mkdir /data/Seeyon/Puppeteer-Service -p

# 启动容器
cd /data/Seeyon/Puppeteer-Service
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 $(pwd)/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:V11-20260403

需要补充字体时，将字体放入 /data/Seeyon/Puppeteer-Service/fonts

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

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

# 3.3 验证和常用运维命令

查看容器状态：

docker ps --filter name=puppeteer-service

健康检查：

curl -fsS http://127.0.0.1:16395/health

查看日志：

docker logs --tail 200 puppeteer-service

验证容器能够访问 A8 callback 地址：

docker exec puppeteer-service sh -c "wget -S --spider '<A8回调地址>' 2>&1 | head"

容器内没有 wget 时，使用现场允许的网络诊断工具验证。

# 四、后台配置说明

后台入口示意：

远程配置示意：

远程模式必须填写：

参数	填写要求	示例
远程服务地址	A8 能访问的容器服务地址	`http://<容器宿主机IP>:16395`
A8 callback 地址	容器能访问的真实 OA 地址	`https://oa.example.com` 或 `http://<OA内网IP>:8080`

外部 HTTPS 与内部 HTTP 端口不一致时，必须明确填写 A8 callback 地址，不依赖自动推导。

# 五、打印测试

至少验证以下标准场景：

普通页面截图或 PDF。
CAP4 表单打印 PDF。
CAP4 表单截图 PNG。
报表打印。
公文 PDF 打印。
表单转新闻或公告。
中文、英文、繁体和客户特殊字体。
HTTPS、反向代理或非标准端口环境。

详细测试矩阵见同目录《测试点与影响点.md》。

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

AMD64：

docker save puppeteer-service:V11-20260403 | gzip > puppeteer-service-amd64.tgz

ARM64：

docker save puppeteer-service:V11-20260403 | gzip > puppeteer-service-arm64.tgz

导出后重新计算 SHA256，不得继续沿用本交付包中的校验值。

# 七、常见问题

# Q1：打印缺字或字体不一致

本地模式把字体加入 PrintEngine/fonts；容器模式挂载字体目录或重建镜像，然后重启并重新验证。

# Q2：远程容器启动失败

检查 CPU 架构、16395 端口占用、Docker 日志和共享内存参数。

# Q3：连接超时或空白页

从容器侧验证 A8 callback 地址、协议、端口、DNS、证书和防火墙。外部 HTTPS 转内部 HTTP 时不要依赖端口自动推导。

# Q4：后台切换后未生效

重新进入系统参数设置确认保存结果，必要时重新登录后台并重启 OA 服务。

# Q5：可以使用旧 Windows 手工安装方式或旧容器吗

不可以。本次正式方案只支持本文列出的 PrintEngine OBS 运行包和新容器镜像。

# 八、部署检查清单

检查项	结果
已确认使用 V11 标准版本
已选择本地或远程模式
已校验运行包 SHA256
本地模式 PrintEngine 目录结构正确
远程模式镜像架构和标签正确
A8 callback 地址从容器侧可访问
标准打印场景验证通过
已准备回滚方案

编撰人：wangyxyf

← 电科金仓R6 Mysql模式项目化适配手册 V10.0SP1及更早版本Puppeteer打印补丁操作手册 →