RHEL/CentOS 离线环境准备指南

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

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

目录

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

1. 系统要求

操作系统

适用于基于 yum/dnf 包管理的 Linux 发行版：

• RHEL 及其衍生版（CentOS、Rocky Linux、AlmaLinux、Oracle Linux 等）

硬件要求

2. 依赖项清单

2.1 UnoServer 引擎依赖（Word 转 PDF）

⚠️ CentOS 7 注意：默认仓库的 LibreOffice (5.x) 和 Python (3.6) 版本过低，需手动安装新版本。详见下文。

2.2 PuppeteerSharp 引擎依赖（HTML 转 PDF）

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

2.4 Python 包

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

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

3.1 启用 EPEL 仓库

Chromium 等包需要 EPEL 仓库：

# RHEL 8/9, Rocky Linux, AlmaLinux
sudo dnf install epel-release

# CentOS 7
sudo yum install epel-release

3.2 创建工作目录

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

3.3 下载系统依赖包（rpm 包）

方法 A：使用 dnf download（RHEL 8+）

cd ~/offline-packages/rpms

# 定义要安装的包
PACKAGES="libreoffice-core libreoffice-writer libreoffice-pyuno \
  python3 python3-pip \
  chromium \
  liberation-fonts google-noto-cjk-fonts wqy-zenhei-fonts freetype fontconfig \
  nss nspr ca-certificates glib2 mesa-libgbm libdrm libxcb libxkbcommon \
  pango cairo libX11 libXcomposite libXdamage libXext libXfixes libXrandr libXrender \
  atk at-spi2-atk cups-libs libXScrnSaver alsa-lib"

# 下载包及其所有依赖
sudo dnf download --resolve --destdir=. $PACKAGES

# 统计下载数量
echo "已下载 $(ls -1 *.rpm | wc -l) 个 .rpm 包"

方法 B：使用 repotrack（CentOS 7）

⚠️ 重要：CentOS 7 默认仓库的 LibreOffice (5.x) 和 Python (3.6) 版本过低，不要下载这些包。需要单独处理。

cd ~/offline-packages/rpms

# 安装 yum-utils
sudo yum install -y yum-utils

# 仅下载 Chromium 及系统依赖（不含 LibreOffice 和 Python）
PACKAGES="chromium \
  liberation-fonts wqy-zenhei-fonts freetype fontconfig \
  nss nspr ca-certificates glib2 mesa-libgbm libdrm libxcb libxkbcommon \
  pango cairo libX11 libXcomposite libXdamage libXext libXfixes libXrandr libXrender \
  atk at-spi2-atk cups-libs libXScrnSaver alsa-lib"

repotrack $PACKAGES
echo "已下载 $(ls -1 *.rpm | wc -l) 个 .rpm 包"

CentOS 7 还需单独下载：

# 1. 下载 Python 3.8（从 vault 归档源，见 3.4 节）

# 2. 下载 LibreOffice 7.x（从腾讯镜像）
cd ~/offline-packages
mkdir -p libreoffice && cd libreoffice
wget https://mirrors.cloud.tencent.com/libreoffice/libreoffice/stable/7.6.7/rpm/x86_64/LibreOffice_7.6.7_Linux_x86-64_rpm.tar.gz
echo "LibreOffice 7.6.7 已下载"

3.4 下载 Python 包

⚠️ CentOS 7 用户注意：系统默认 Python 3.6 版本过低，需先安装 Python 3.8+ 再下载 Python 包。

RHEL 8+ / Rocky Linux / AlmaLinux

cd ~/offline-packages/python

# 下载 unoserver 及其依赖
pip3 download unoserver

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

CentOS 7（需先安装 Python 3.8）

由于 CentOS 7 已停止维护，SCL 仓库可能不可用。有以下几种方案：

方案 A：配置 vault 归档源安装 SCL

# 1. 创建 SCL vault 仓库配置
sudo tee /etc/yum.repos.d/centos-scl-vault.repo << 'EOF'
[centos-sclo-rh]
name=CentOS-7 - SCLo rh
baseurl=https://vault.centos.org/centos/7/sclo/x86_64/rh/
gpgcheck=0
enabled=1
EOF

# 2. 安装 Python 3.8
sudo yum install -y rh-python38 rh-python38-python-pip
source /opt/rh/rh-python38/enable

# 3. 验证版本
python3 --version  # 应显示 Python 3.8.x

# 4. 下载 unoserver
cd ~/offline-packages/python
pip3 download unoserver

# 5. 下载 Python 3.8 的 rpm 包供目标机器离线安装
cd ~/offline-packages/rpms
repotrack rh-python38 rh-python38-python-pip

方案 B：从其他机器下载（推荐）

如果您有 RHEL 8+ / Rocky Linux 8+ 机器，可在该机器上下载 Python 包，然后传输到 CentOS 7 目标机器使用。

方案 C：使用 Docker

对于 CentOS 7 环境，推荐使用 Docker 部署，可获得更一致的运行环境。参见 deploy-docker.md

3.5 打包所有离线文件

cd ~/offline-packages

# 创建最终离线包（RHEL 8+ 不含 libreoffice 目录）
tar -czvf aegis-converter-deps-rhel-$(date +%Y%m%d).tar.gz rpms/ python/

# CentOS 7 需包含 libreoffice 目录
# tar -czvf aegis-converter-deps-centos7-$(date +%Y%m%d).tar.gz rpms/ python/ libreoffice/

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

3.6 传输文件

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

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

4.1 解压离线包

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

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

4.2 安装系统依赖

RHEL 8+/Rocky Linux/AlmaLinux

cd /opt/aegis-deps/rpms
sudo dnf localinstall *.rpm -y

CentOS 7

# 1. 安装 Chromium 及系统依赖
cd /opt/aegis-deps/rpms
sudo yum localinstall *.rpm -y

# 2. 安装 LibreOffice 7.x（如果使用了腾讯镜像下载）
cd /opt/aegis-deps/libreoffice
tar -xzf LibreOffice_7.6.7_Linux_x86-64_rpm.tar.gz
cd LibreOffice_7.6.7.2_Linux_x86-64_rpm/RPMS
sudo yum localinstall *.rpm -y

4.3 安装 Python 包

RHEL 8+ / Rocky Linux / AlmaLinux

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

CentOS 7（需先启用 Python 3.8）

# 1. 先安装 Python 3.8 rpm 包
cd /opt/aegis-deps/rpms
sudo yum localinstall rh-python38*.rpm -y

# 2. 启用 Python 3.8 并添加到 bashrc
echo 'source /opt/rh/rh-python38/enable' >> ~/.bashrc
source ~/.bashrc

# 3. 验证版本
python3 --version  # 应显示 Python 3.8.x

# 4. 安装 unoserver
cd /opt/aegis-deps/python
pip3 install --no-index --find-links=. unoserver

4.4 刷新字体缓存

sudo fc-cache -f -v

5. 验证安装

5.1 验证 LibreOffice

soffice --version
# 应显示：LibreOffice 7.x.x.x ...
# 如果显示 5.x 或 6.x，版本过低，需安装 LibreOffice 7.0+

5.2 验证 Python 和 UNO

python3 --version
# 应显示：Python 3.8.x 或更高版本
# CentOS 7 用户如果显示 3.6.x，请确保已执行 source /opt/rh/rh-python38/enable

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

5.3 验证 unoserver

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

5.4 验证 Chromium

# 可执行文件名因发行版而异
chromium-browser --version 2>/dev/null || chromium --version
# 应显示：Chromium xxx.x.xxxx.xxx

5.5 验证字体

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

6. 常见问题

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

# 使用 --skip-broken 跳过有问题的包
sudo dnf localinstall *.rpm -y --skip-broken

# 或使用 rpm 强制安装
sudo rpm -ivh --nodeps *.rpm

Q2: 准备阶段找不到 chromium 包

此问题发生在有网络的准备机器上：

# 确保启用了 EPEL 仓库
sudo dnf install epel-release
sudo dnf makecache

# 某些系统中包名可能是 chromium-browser
dnf search chromium

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

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

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

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

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

Q5: Python 找不到 uno 模块

# 从离线包重新安装 libreoffice-pyuno
cd /opt/aegis-deps/rpms
sudo rpm -ivh --force libreoffice-pyuno*.rpm

Q6: SELinux 阻止 Chromium 运行

# 临时禁用 SELinux（测试用）
sudo setenforce 0

# 或配置 SELinux 策略（生产环境推荐）
sudo setsebool -P httpd_execmem 1

附录：离线包文件清单

aegis-converter-deps-rhel/
├── rpms/                           # 系统依赖包（Chromium、字体等）
│   └── *.rpm                       # rpm 包文件
├── python/                         # Python 包
│   └── *.whl                       # unoserver 及依赖
└── libreoffice/                    # LibreOffice 7.x（CentOS 7 需要）
    └── LibreOffice_7.6.7_Linux_x86-64_rpm.tar.gz

更新日志