环境准备指南

本文档介绍如何为 Aegis.DocumentConverter 准备运行环境，包括在线和离线两种场景。

功能与依赖对照表

⚠️ 版本要求：LibreOffice 必须 7.0 或更高版本，Python 必须 3.8 或更高版本。CentOS 7 等旧系统的默认仓库版本可能不满足要求。

在线环境配置

在线环境配置非常简单，程序会自动下载 Chromium 并自动安装 unoserver（Python 包）。

Windows

只需安装 LibreOffice：

1. 下载：https://www.libreoffice.org/download/download-libreoffice/
2. 运行安装程序，使用默认路径安装即可

💡 Chromium 会在首次使用时自动下载（内部优先使用国内源）

Debian / Ubuntu

# 安装所有依赖（一条命令）
sudo apt update && sudo apt install -y \
    libreoffice \
    python3 \
    python3-pip \
    fonts-wqy-zenhei \
    fonts-noto-cjk

💡 Chromium 无需安装：程序会自动下载。如需使用系统 Chromium（减少磁盘占用），可选择安装：sudo apt install -y chromium

RHEL 8+ / Rocky Linux 8+ / AlmaLinux 8+

⚠️ 注意：RHEL 8 系列默认仓库中的 LibreOffice 版本为 6.4.x，不满足 7.0+ 要求，需要使用 Flatpak 安装新版本。

# 1. 启用必要的仓库
sudo dnf install -y epel-release
sudo dnf config-manager --set-enabled powertools  # Rocky 8 / AlmaLinux 8
# 或 sudo dnf config-manager --set-enabled crb    # Rocky 9+ / AlmaLinux 9+

# 2. 安装 Python 3.9（通过模块）
sudo dnf module install -y python39
sudo alternatives --set python3 /usr/bin/python3.9

# 3. 安装 LibreOffice 7.x（通过 Flatpak）
sudo dnf install -y flatpak
sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
sudo flatpak install -y flathub org.libreoffice.LibreOffice

# 创建 soffice 符号链接（使程序能够找到）
sudo ln -sf /var/lib/flatpak/exports/bin/org.libreoffice.LibreOffice /usr/local/bin/soffice
sudo ln -sf /var/lib/flatpak/exports/bin/org.libreoffice.LibreOffice /usr/local/bin/libreoffice

# 4. 安装中文字体
sudo dnf install -y google-noto-sans-cjk-fonts google-noto-serif-cjk-fonts

或者使用 LibreOffice 官方 RPM 包：

# 下载并安装 LibreOffice 7.x
cd /tmp
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
tar -xzf LibreOffice_7.6.7_Linux_x86-64_rpm.tar.gz
cd LibreOffice_7.6.7.2_Linux_x86-64_rpm/RPMS
sudo dnf localinstall -y *.rpm

💡 Chromium 无需安装：程序会自动下载。如需使用系统 Chromium，可选择安装：sudo dnf install -y chromium

CentOS 7

CentOS 7 默认仓库版本较旧，需手动安装新版本：

# 1. 安装 Python 3.8（通过 SCL 仓库）
sudo yum install -y centos-release-scl
sudo yum install -y rh-python38 rh-python38-python-pip

# 启用 Python 3.8（添加到 ~/.bashrc 使其永久生效）
echo 'source /opt/rh/rh-python38/enable' >> ~/.bashrc
source ~/.bashrc

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

# 2. 卸载旧版 LibreOffice（如已安装）
sudo yum remove -y libreoffice*

# 3. 安装 LibreOffice 7.x（从腾讯镜像下载）
cd /tmp
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
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 -y *.rpm

# 4. 安装中文字体
sudo yum install -y wqy-zenhei-fonts

💡 如果无法访问腾讯镜像，可从 LibreOffice 官网 下载

⚠️ 注意：CentOS 7 已于 2024 年 6 月 30 日停止官方支持，不再有安全更新。如条件允许，可考虑使用 Docker 部署以获得更一致的运行环境。

验证安装

# 检查 LibreOffice（需要 7.0 或更高版本）
soffice --version

# 检查 Python（需要 3.8 或更高版本）
python3 --version

💡 Chromium 由程序自动管理，无需验证系统安装。

离线环境配置

离线环境需要提前下载安装包并手动安装。由于步骤较为复杂，请参考对应平台的详细文档：

离线环境概要

需要准备的安装包：

⚠️ 离线环境下程序无法自动下载 Chromium，必须预先安装 Chrome/Chromium。

Docker 环境

Docker 容器化部署需要在 Dockerfile 中预装所有依赖。

详细配置请参考 Docker 环境部署指南，包含：

• 完整的多阶段构建 Dockerfile 示例
• 依赖包说明
• 环境变量配置
• 构建和运行命令

💡 程序检测到 Docker 环境时会跳过依赖检查，假定 Dockerfile 已预装所有组件。

常见问题

Q: 程序启动时报错找不到 Chromium？

在线环境：检查网络连接，程序会自动下载。
离线环境：需要手动安装 Chrome 或 Chromium。

Q: Word 转 PDF 报错找不到 LibreOffice？

LibreOffice 需要手动安装，程序只负责检测，不会自动安装。

Q: Linux 下 Chromium 自动下载后仍报错？

需要安装 Chromium 的系统依赖：

# Debian/Ubuntu
sudo apt install -y libxss1 libnss3 libatk1.0-0 libatk-bridge2.0-0 \
    libdrm2 libxcomposite1 libxdamage1 libxrandr2 libgbm1 \
    libasound2 libpango-1.0-0 libcairo2 libcups2

# RHEL 8+ / Rocky Linux / AlmaLinux
sudo dnf install -y nss nspr atk at-spi2-atk libdrm libxcomposite \
    libxdamage libxrandr mesa-libgbm alsa-lib pango cairo cups-libs libXScrnSaver

# CentOS 7
sudo yum install -y nss nspr atk at-spi2-atk libdrm libxcomposite \
    libxdamage libxrandr mesa-libgbm alsa-lib pango cairo cups-libs libXScrnSaver

💡 或者直接安装 chromium 包（会自动安装所有依赖）

Q: 中文文档转换后是乱码？

安装中文字体：

# Debian/Ubuntu
sudo apt install -y fonts-wqy-zenhei fonts-noto-cjk

# RHEL 8+ / Rocky Linux / AlmaLinux
sudo dnf install -y google-noto-sans-cjk-fonts google-noto-serif-cjk-fonts

# CentOS 7
sudo yum install -y wqy-zenhei-fonts