Debian/Ubuntu 离线环境准备指南

本文档介绍如何在 无网络连接 的 Debian/Ubuntu 服务器上准备 Aegis.DocumentConverter 所需的运行环境依赖。

适用场景：对网络安全要求严格的内网环境

目录

• 1. 系统要求
• 2. 依赖项清单
• 3. 离线包准备（有网络机器）
• 4. 离线安装（目标机器）
• 5. 验证安装
• 6. 常见问题

1. 系统要求

操作系统

适用于基于 apt/dpkg 包管理的 Linux 发行版：

⚠️ 版本要求：LibreOffice 必须 7.0+，Python 必须 3.8+。旧版系统需要手动升级或使用 Docker 部署。

硬件要求

2. 依赖项清单

2.1 UnoServer 引擎依赖（Word 转 PDF）

2.2 PuppeteerSharp 引擎依赖（HTML 转 PDF）

2.3 字体依赖（两个引擎共享）

2.4 Python 包

3. 离线包准备（有网络机器）

💡 建议：为避免依赖兼容性问题，建议准备离线包的机器与目标机器使用相同或相近的发行版版本，且 CPU 架构必须一致（如 x86_64 或 arm64）

3.1 创建工作目录

mkdir -p ~/offline-packages/{debs,python}
cd ~/offline-packages

3.2 下载系统依赖包（apt 包）

💡 chromium 包名说明：Ubuntu 使用 chromium-browser，Debian 使用 chromium。请根据实际系统选择。

方法 A：使用 apt download（推荐）

cd ~/offline-packages/debs

# 定义要安装的包（Ubuntu 使用 chromium-browser，Debian 使用 chromium）
PACKAGES="libreoffice python3 python3-pip python3-uno \
  chromium-browser \
  fonts-liberation fonts-noto-cjk fonts-wqy-zenhei libfreetype6 fontconfig \
  libnss3 libnspr4 ca-certificates libglib2.0-0 libgbm1 libdrm2 libxcb1 \
  libxkbcommon0 libpango-1.0-0 libcairo2 libx11-6 libxcomposite1 libxdamage1 \
  libxext6 libxfixes3 libxrandr2 libxrender1"

# 下载包及其所有依赖
sudo apt update
apt download $(apt-cache depends --recurse --no-recommends --no-suggests \
  --no-conflicts --no-breaks --no-replaces --no-enhances \
  $PACKAGES 2>/dev/null | grep "^\w" | sort -u)

# 统计下载数量
echo "已下载 $(ls -1 *.deb 2>/dev/null | wc -l) 个 .deb 包"

方法 B：使用 apt-offline

# 安装 apt-offline
sudo apt-get install -y apt-offline

# 定义要安装的包
PACKAGES="libreoffice python3 python3-pip python3-uno \
  chromium-browser \
  fonts-liberation fonts-noto-cjk fonts-wqy-zenhei libfreetype6 fontconfig \
  libnss3 libnspr4 ca-certificates libglib2.0-0 libgbm1 libdrm2 libxcb1 \
  libxkbcommon0 libpango-1.0-0 libcairo2 libx11-6 libxcomposite1 libxdamage1 \
  libxext6 libxfixes3 libxrandr2 libxrender1"

# 生成签名文件
apt-offline set --install-packages $PACKAGES offline.sig

# 下载所有包到 bundle
apt-offline get offline.sig --bundle debs/offline-bundle.zip

3.3 下载 Python 包

cd ~/offline-packages/python

# 下载 unoserver 及其依赖
pip3 download unoserver

echo "已下载 $(ls -1 *.whl *.tar.gz 2>/dev/null | wc -l) 个 Python 包"

3.4 Ubuntu 20.04 特殊处理（LibreOffice 版本过低）

Ubuntu 20.04 默认仓库的 LibreOffice 为 6.4.x，不满足 7.0+ 要求。需要从 LibreOffice 官方 PPA 或官网下载：

# 方案 A：使用 LibreOffice PPA（需要在线环境准备）
sudo add-apt-repository ppa:libreoffice/ppa
sudo apt update
# 然后重新执行 3.2 的下载命令

# 方案 B：下载官方 deb 包
cd ~/offline-packages
mkdir -p libreoffice && cd libreoffice
wget https://mirrors.cloud.tencent.com/libreoffice/libreoffice/stable/7.6.7/deb/x86_64/LibreOffice_7.6.7_Linux_x86-64_deb.tar.gz
echo "LibreOffice 7.6.7 已下载"

💡 如果目标机器是 Ubuntu 22.04+ 或 Debian 11+，可跳过此步骤。

3.5 打包所有离线文件

cd ~/offline-packages

# 创建最终离线包
# Ubuntu 22.04+ / Debian 11+
tar -czvf aegis-converter-deps-$(date +%Y%m%d).tar.gz debs/ python/

# Ubuntu 20.04（需包含 libreoffice 目录）
# tar -czvf aegis-converter-deps-$(date +%Y%m%d).tar.gz debs/ python/ libreoffice/

echo "离线包已创建："
ls -lh aegis-converter-deps-*.tar.gz

3.6 传输文件

将 aegis-converter-deps-YYYYMMDD.tar.gz 传输到离线目标机器。

4. 离线安装（目标机器）

4.1 解压离线包

# 创建工作目录
sudo mkdir -p /opt/aegis-deps
cd /opt/aegis-deps

# 解压离线包
tar -xzvf /path/to/aegis-converter-deps-YYYYMMDD.tar.gz

4.2 安装系统依赖

方法 A：使用 dpkg（推荐）

cd /opt/aegis-deps/debs
sudo dpkg -i *.deb

# 如果提示依赖错误，尝试多次执行以修复依赖顺序问题
sudo dpkg -i *.deb
sudo dpkg --configure -a

方法 B：使用 apt-offline（如果使用该方式准备）

cd /opt/aegis-deps/debs
sudo apt-offline install offline-bundle.zip

# apt-offline 已处理依赖关系，如仍有问题可运行：
sudo dpkg --configure -a

4.3 Ubuntu 20.04 安装 LibreOffice 7.x

如果使用了官方 deb 包（方案 B），需单独安装：

# 先卸载旧版本
sudo apt remove -y libreoffice* --allow-remove-essential 2>/dev/null || true

# 安装 LibreOffice 7.x
cd /opt/aegis-deps/libreoffice
tar -xzf LibreOffice_7.6.7_Linux_x86-64_deb.tar.gz
cd LibreOffice_7.6.7.2_Linux_x86-64_deb/DEBS
sudo dpkg -i *.deb

4.4 安装 Python 包

cd /opt/aegis-deps/python
sudo pip3 install --no-index --find-links=. unoserver

4.5 刷新字体缓存

sudo fc-cache -f -v

5. 验证安装

5.1 验证 LibreOffice

soffice --version
# 应显示：LibreOffice 7.x.x.x ...
# 如果显示 6.x 或更低，版本不满足要求，需升级或使用 Docker

5.2 验证 Python 和 UNO

python3 --version
# 应显示：Python 3.8.x 或更高版本

python3 -c "import uno; print('UNO 桥接库加载成功')"

5.3 验证 unoserver

python3 -m unoserver.server --help
# 应显示 unoserver 帮助信息

5.4 验证 Chromium

chromium --version
# 或
chromium-browser --version
# 应显示：Chromium xxx.x.xxxx.xxx

5.5 验证字体

# 检查中文字体
fc-list :lang=zh | head -5
# 应显示 Noto CJK 或 WenQuanYi 字体

6. 常见问题

Q1: 安装 .deb 包时提示依赖错误

# 在离线环境不能使用 apt-get install -f（需要网络）
# 应使用 dpkg 多次安装或强制安装

# 方法1：多次运行 dpkg 直到所有依赖安装完成
cd /opt/aegis-deps/debs
sudo dpkg -i *.deb
sudo dpkg --configure -a
sudo dpkg -i *.deb   # 再次运行

# 方法2：强制安装（不推荐，可能导致功能异常）
sudo dpkg -i --force-depends *.deb

Q2: Chromium 启动失败 "No usable sandbox"

# 配置 sandbox 权限
sudo chown root:root /usr/lib/chromium/chrome-sandbox
sudo chmod 4755 /usr/lib/chromium/chrome-sandbox

Q3: LibreOffice 启动失败 "no suitable windowing system found"

# 确保使用 headless 模式，不设置 DISPLAY 环境变量
unset DISPLAY

Q4: 字体显示为方块或乱码

# 重新刷新字体缓存
sudo fc-cache -f -v

# 检查中文字体是否安装
fc-list :lang=zh

Q5: Python 找不到 uno 模块

# 从离线包重新安装 python3-uno
cd /opt/aegis-deps/debs
sudo dpkg -i --force-reinstall python3-uno*.deb

附录：离线包文件清单

aegis-converter-deps/
├── debs/                           # 系统依赖包
│   ├── offline-bundle.zip          # apt-offline 打包（方法 B）
│   └── *.deb                       # 或单独的 deb 文件（方法 A）
├── python/                         # Python 包
│   └── *.whl                       # unoserver 及依赖
└── libreoffice/                    # LibreOffice 7.x（Ubuntu 20.04 需要）
    └── LibreOffice_7.6.7_Linux_x86-64_deb.tar.gz

更新日志