解决方案：CEB 文件 Web 端在线预览方案，Linux部署ceb文件在线预览工具

适用场景 ：需要在 Linux 后端环境中为 Web 应用提供 .ceb 附件在线预览能力

核心思路：后端调用 Docker 化 Windows 转换器，将 CEB 转为 PDF 后由浏览器内嵌预览

---

源码已上传至：https://gitcode.com/air__Heaven/cebpreview

一、问题是什么

CEB 是中文电子公文领域常见的一种封闭版式文件格式，在政府机关和大型企业的历史档案中存量较大。用户在前端点击"查看附件"时，期望的体验与 PDF 无异：无需下载、浏览器内直接打开、滚动流畅。

但 CEB 并非开放标准，主流浏览器无法原生渲染，Linux 服务端也缺乏能直接解码 CEB 的开源工具。唯一可用的转换能力来自厂商提供的一个 Windows 命令行工具。当后端服务运行在 Linux 上时，如何把这个 Windows 专有工具接入 Web 预览流程，就成了必须解决的问题。

简言之，核心问题是：如何在 Linux 后端上稳定、可维护地运行一个 Windows 命令行转换器，并将它包装成 Web 应用可调用的服务？

---

二、方案设计：增加一个 CEB → PDF 转换层

2.1 总体思路

我们不改造前端，也不迁移后端。整体数据流如下：

1. 用户点击 CEB 附件的"预览"按钮；
2. 后端接口判断文件类型为 CEB，先检查 PDF 缓存；
3. 缓存未命中时，调用转换层将 CEB 转为 PDF；
4. 后端将 PDF 流返回给前端，浏览器直接渲染。

对前端和终端用户来说，这只是一次普通的文件预览；对后端来说，只是新增了一个异步转换调用。

2.2 为什么用 Docker + Wine

直接将后端服务迁移到 Windows 的成本过高，而在 Linux 上通过 Wine 运行 Windows 程序是一个更轻量的选择。结合 Docker 后，这一方案具备以下优势：

• 零侵入现有架构：后端只需新增一个 wrapper 脚本路径配置，业务代码无需改动；
• 环境隔离：Wine、运行时库、转换器全部封装在镜像中，不污染宿主机；
• 一次构建，多处运行：镜像可在开发、测试、生产环境之间保持一致；
• 复用现有 PDF 预览链路：转换后的 PDF 直接走已有的文件预览与缓存逻辑。

---

三、架构与数据流

3.1 组件清单

组件	职责
前端浏览器	发起预览请求，渲染返回的 PDF
后端服务	接收请求、命中缓存或触发转换、返回 PDF 流
宿主机 wrapper 脚本	准备临时目录、挂载 Wine prefix、调用 Docker 容器
Docker 镜像	包含 Debian + Wine + 转换器及依赖的运行环境
持久化 Wine prefix	保存 Wine 初始化结果，降低后续调用延迟
PDF 缓存	按源文件指纹缓存转换结果，避免重复转换

3.2 完整请求生命周期

用户点击"预览"
    │
    ▼
后端接口
    │  1. 查找 _previews/<fingerprint>.pdf 缓存
    │  2. 命中则直接返回
    │  3. 未命中则调用 wrapper
    ▼
宿主机 wrapper 脚本
    │  1. 将源文件复制到临时工作目录
    │  2. docker run --rm \
    │       -v $tmp:/work \
    │       -v $prefix:/wineprefix \
    │       ceb2pdf:latest /work/in.ceb /work/out.pdf
    │  3. 将生成的 PDF 移回缓存目录
    ▼
Docker 容器
    │  1. 启动 Xvfb 虚拟显示
    │  2. 通过 Wine 运行 ceb2pdf.exe
    │  3. 输出 /work/out.pdf
    ▼
PDF 返回前端 → 浏览器内嵌预览

3.3 容器内关键内容

/opt/ceb2pdf/                 # 全部为 32 位文件
├── ceb2pdf.exe               # Windows 命令行转换器
├── libeay32.dll              # OpenSSL 1.0.x 32 位 Windows 依赖
├── mfc100.dll                # MSVC 2010 MFC 32 位运行时
└── msvcr100.dll              # MSVC 2010 C 运行时 32 位

/usr/local/bin/entrypoint.sh  # 启动 Xvfb 并调用 Wine

关键前提：上述 DLL 必须是 32 位版本，否则 Wine 在 32 位程序模式下会拒绝加载。这是本方案最重要的打包细节，详见第五章。

---

四、构建与部署

4.1 构建镜像

镜像基于 debian:bookworm-slim，安装 Wine 8.0 和 32 位多架构支持包 wine32:i386，并加入 Xvfb 以满足 Wine 对 X server 的依赖。

构建命令示例：

cd docker/ceb2pdf
docker build --network=host -t ceb2pdf:latest .

--network=host 用于解决部分企业网络环境下 Docker bridge 网络访问受限的问题。若构建环境网络正常，此参数可省略。基础镜像不带 CA 证书时，需将宿主机的 CA bundle 复制进镜像，以便 apt 验证 HTTPS 源。

4.2 验证镜像

docker run --rm -v $PWD:/work ceb2pdf:latest /work/test.ceb /work/out.pdf

首次运行约需 5 秒完成 Wine prefix 初始化。输出文件应为合法的 PDF，例如文件头包含 %PDF-1.4。

4.3 后端配置

将 CEB_TO_PDF_PATH 指向宿主机 wrapper 脚本：

CEB_TO_PDF_PATH=/path/to/ceb2pdf-wrapper.sh

wrapper 的接口与原生命令行程序保持一致：

ceb2pdf-wrapper.sh <input.ceb> <output.pdf>

后端业务代码无需改动，subprocess.run([CEB_TO_PDF_PATH, src, dst]) 的调用链路可直接复用。

4.4 可选环境变量

变量	默认值	说明
CEB2PDF_IMAGE	ceb2pdf:latest	使用的 Docker 镜像 tag
CEB2PDF_WINE_PREFIX	~/.cache/ceb2pdf-wineprefix	Wine prefix 持久化位置，建议挂载到独立数据卷

---

五、最关键的排查经验：32/64 位 DLL 目录被放反了

5.1 表面现象

装好 Wine、拷好文件后，运行时出现如下错误：

err:module:import_dll Loading library MSVCR100.dll ... failed (error c000035a)

文件明明就在同一目录下，Wine 却提示找不到。按常规思路，很容易去检查路径、大小写、Wine 覆盖规则，甚至尝试安装 MSVC 运行库，但这些方向都会浪费时间。

5.2 真正原因

通过检查 PE 文件头中的 Machine 字段，发现转换器自带的两个依赖目录 32/ 和 64/ 存在命名与实际架构相反的问题：

文件	32/ 目录实际架构	64/ 目录实际架构
ceb2pdf.exe	i386	i386
libeay32.dll	i386	i386
msvcr100.dll	AMD64	i386
mfc100.dll	AMD64	i386

ceb2pdf.exe 是 32 位程序，Wine 会按 32 位模式加载依赖。当它从 32/ 目录读取到 64 位的 msvcr100.dll 和 mfc100.dll 时，会拒绝加载，并抛出误导性的 STATUS_DLL_NOT_FOUND 错误。

5.3 验证方法

for f in msvcr100.dll mfc100.dll libeay32.dll ceb2pdf.exe; do
    pe_off=$(od -An -tu4 -j 60 -N 4 "$f" | tr -d " ")
    machine=$(od -An -tx2 -j $((pe_off + 4)) -N 2 "$f" | tr -d " ")
    case "$machine" in
        014c) echo "$f: i386";;
        8664) echo "$f: AMD64";;
        *)    echo "$f: unknown ($machine)";;
    esac
done

正确结果应全部为 i386：

msvcr100.dll: i386
mfc100.dll:   i386
libeay32.dll: i386
ceb2pdf.exe: i386

5.4 修复方式

部署到 Linux 镜像时，从 64/ 目录拷贝 msvcr100.dll 和 mfc100.dll，不要按目录名机械复制。

---

六、性能参考

测试样本：一份约 5MB 的 CEB 文件，转换后输出约 700 页 PDF。

场景	延迟
冷启动（首次调用，Wine 初始化 prefix）	约 5 秒
热启动（prefix 已持久化）	约 0.8 秒
镜像大小	约 1.0 GB

加上按文件指纹缓存 PDF 后，同一文件第二次预览直接命中缓存，无需再次启动容器，用户感知接近即时打开。

---

七、运维注意事项

7.1 并发

当前方案每次请求都会 docker run --rm 启动一个独立容器，容器之间互不干扰。但持久化的 Wine prefix 是共享的，多个容器同时写入同一个 prefix 可能产生冲突。

• 低频预览场景：基本无影响；
• 高频预览场景 ：可在后端增加互斥锁；长期可改为常驻容器 + docker exec 模式。

7.2 磁盘

Wine prefix 约占几百 MB，建议放在独立分区或数据卷上，避免撑爆根分区。

7.3 权限

后端用户需要能执行 docker 命令（加入 docker 组），并能访问 Docker socket。生产环境不要直接用 root 运行后端服务。

7.4 网络

转换过程本身不依赖外网，属于纯本地操作。镜像拉取仅发生在部署阶段。

7.5 日志与调试

• 正常运行时建议设置 WINEDEBUG=-all，屏蔽 Wine 冗长日志；
• 排查失败时可临时开启 WINEDEBUG=warn+all；
• Wine 控制台输出中文可能出现编码异常，一般不影响 PDF 生成正确性。

---

八、常见问题排查

现象	可能原因	检查/修复
后端提示找不到转换器	wrapper 路径错误或无可执行权限	检查 CEB_TO_PDF_PATH 指向的路径和权限
Wine 报 STATUS_DLL_NOT_FOUND / c000035a	DLL 位宽错误	用第五章脚本验证 PE 头，从 64/ 目录拷贝 32 位 DLL
容器启动后很快退出且未生成 PDF	Wine prefix 未正确挂载，每次冷启动超时	检查 wrapper 是否挂载了持久化 prefix 目录
docker: command not found	后端用户未加入 docker 组	usermod -aG docker <backend-user> 后重新登录
无法连接 Docker daemon	docker.sock 权限不足	检查 /var/run/docker.sock 属主和用户组
构建镜像时 apt 失败	网络受限或 CA 证书缺失	切到 HTTPS 源并复制宿主机 CA bundle

---

九、适用场景与扩展性

本方案特别适合以下场景：

• 业务系统沉淀了大量 CEB 历史附件；
• 前端已具备 PDF 内嵌预览能力；
• 后端运行在 Linux 环境，不便为单一格式迁移到 Windows；
• 希望以最小改动接入，避免改造现有文件服务。

如果面临的是其他封闭格式，只要存在 Windows 命令行转换器，整体思路------Docker + Wine + 容器化封装 + 结果缓存------同样可以参考。

---

十、总结

这套方案的核心价值在于用较低成本解决了 CEB 在 Web 端的预览问题：

1. 把 Windows 专有转换器封装为 Docker 服务，让 Linux 后端可以无感调用；
2. 通过 Wine prefix 持久化和 PDF 缓存，把转换开销隐藏起来，用户获得接近 PDF 的预览体验；
3. 通过 PE 头检查避开 32/64 位 DLL 放反的打包问题，避免在错误方向上浪费时间。

最终效果是：用户点击"预览"，浏览器内即可流畅查看文档；开发和运维团队无需为 CEB 单独维护一套 Windows 环境。

源码已上传至：https://gitcode.com/air__Heaven/cebpreview