convert-multiple-files在EB Amazon Linux 2环境转换文件失败问题

问题根因 #

convert-multiple-files库内置了打包好的LibreOffice二进制文件（soffice.bin）实现文档转换，在本地Windows、Ubuntu桌面环境因为系统自带全量图形依赖、用户目录权限正常可以直接运行，但是在Amazon Linux 2的最小化服务器环境下，既存在系统依赖缺失，又有运行用户的配置目录写入权限问题，最终触发soffice进程返回退出码77——这个状态码是LibreOffice无头模式下依赖缺失、配置目录不可写、权限不足的通用返回值，不会输出具体错误日志。

解决步骤 #

1. 补全所有缺失的系统依赖 #

之前仅安装libxslt、libSM不足以支撑LibreOffice运行，Amazon Linux 2环境需要安装全量依赖，包含图形渲染库、字体包、打印组件依赖。
在项目根目录创建.ebextensions/01_install_deps.config配置文件，通过EB部署流程自动安装依赖：

commands:
  01_install_soffice_runtime_deps:
    command: |
      amazon-linux-extras install epel -y
      yum install -y libX11 libXext libXrender libSM libxslt libpng libjpeg-turbo freetype fontconfig libcups cairo glib2 wqy-zenhei-fonts dejavu-sans-fonts
      yum clean all
  02_set_temp_perm:
    command: chmod 755 /var/app/current/temp
    ignoreErrors: true

注意：必须安装基础字体包，否则文档内文字、特殊符号渲染失败时会直接触发静默退出，没有任何报错。

2. 修复soffice配置目录写入权限 #

EB环境下Node.js应用默认以webapp普通用户运行，该用户默认HOME目录不存在或无写入权限，soffice启动时会尝试在HOME目录下创建.config/libreoffice临时配置目录，写入失败就会直接返回77退出码。
在调用转换逻辑前，手动指定可写的HOME路径到项目的临时目录即可修复，修改测试代码如下：

const { convertWordFiles } = require("convert-multiple-files");
const path = require("path");

async function test() {
  try {
    // 指定可写的临时目录作为soffice配置存储路径
    process.env.HOME = path.resolve(__dirname, `../../temp`);
    const infoOutput = await convertWordFiles(
      path.resolve(__dirname, `../../temp/test02.docx`),
      "pdf",
      path.resolve(__dirname, `../../temp`)
    );
  } catch (err) {
    console.log(err);
  }
}

test();

3. 高可用替代方案（推荐） #

如果不想排查内置二进制的兼容问题，可以直接使用系统源安装的LibreOffice版本，兼容性远高于库内置的裁剪版二进制：

1. 修改EB依赖安装配置，追加安装libreoffice-headless、libreoffice-writer包：

commands:
  01_install_soffice_runtime_deps:
    command: |
      amazon-linux-extras install epel -y
      yum install -y libreoffice-headless libreoffice-writer libX11 libXext libXrender libSM libxslt libpng libjpeg-turbo freetype fontconfig libcups cairo glib2 wqy-zenhei-fonts dejavu-sans-fonts
      yum clean all
  02_set_temp_perm:
    command: chmod 755 /var/app/current/temp
    ignoreErrors: true

2. 调用convertWordFiles时传入配置项，指定soffice路径为系统安装路径/usr/bin/soffice即可。

避坑说明 #

• LibreOffice无头模式禁止root用户直接运行，不要修改EB默认的webapp运行用户，否则会直接触发进程退出
• 多任务并发转换时，不要共用同一个临时目录，避免LibreOffice锁文件冲突导致转换失败
• 部署后首次启动soffice会有3-5秒的初始化时间，可适当调大转换超时阈值避免首次请求失败

内容的提问来源于stack exchange，提问作者Md.Reyad Hossain