版本：2.2.0

Docker 环境部署指南

本文档介绍如何在 Docker 容器中部署 Aegis.DocumentConverter。

1. 部署方式选择

由于文档转换需要安装大量系统依赖（Chromium、LibreOffice、字体等），我们提供两种部署方式：

方式	适用场景	优点	缺点
自定义基础镜像	多项目共享、团队协作	Dockerfile 简洁、构建快、易维护	需额外维护基础镜像
单文件 Dockerfile	单一项目、快速验证	自包含、无外部依赖	Dockerfile 冗长、每次构建慢

推荐使用方式一：将依赖安装封装到自定义基础镜像中，业务项目的 Dockerfile 只需引用即可。

2. 方式一：构建自定义基础镜像（推荐）

2.1 创建基础镜像 Dockerfile

创建 Dockerfile.base 文件：

# Dockerfile.base - 文档转换基础镜像
FROM mcr.microsoft.com/dotnet/aspnet:8.0

USER root

# 配置国内镜像源（可选，加速下载）
RUN rm -f /etc/apt/sources.list.d/debian.sources && \
    printf '%s\n' \
    "deb http://mirrors.aliyun.com/debian/ bookworm main contrib non-free non-free-firmware" \
    "deb http://mirrors.aliyun.com/debian/ bookworm-updates main contrib non-free non-free-firmware" \
    "deb http://mirrors.aliyun.com/debian-security bookworm-security main contrib non-free non-free-firmware" \
    > /etc/apt/sources.list

# 安装所有运行时依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    # LibreOffice（Word → PDF）
    libreoffice-core \
    libreoffice-writer \
    python3 \
    python3-pip \
    python3-uno \
    # Chromium（HTML → PDF）
    chromium \
    # 中文字体
    fonts-liberation \
    fonts-noto-cjk \
    fonts-wqy-zenhei \
    fontconfig \
    # Chromium 运行时依赖
    libnss3 \
    libnspr4 \
    ca-certificates \
    libglib2.0-0 \
    libgbm1 \
    libdrm2 \
    libxcb1 \
    libxkbcommon0 \
    libpango-1.0-0 \
    libcairo2 \
    libx11-6 \
    libxcomposite1 \
    libxdamage1 \
    libxext6 \
    libxfixes3 \
    libxrandr2 \
    libxrender1 \
    && fc-cache -f -v \
    && rm -rf /var/lib/apt/lists/*

# 安装 unoserver
RUN pip3 install --no-cache-dir \
    -i https://pypi.tuna.tsinghua.edu.cn/simple \
    unoserver \
    --break-system-packages

# 创建应用用户和目录
ENV APP_UID=1000
RUN mkdir -p /app /tmp/libreoffice /home/appuser/.cache /home/appuser/.config && \
    chown -R $APP_UID:$APP_UID /app /tmp/libreoffice /home/appuser

# 设置环境变量
ENV HOME=/home/appuser \
    PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
    PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

2.2 构建并推送基础镜像

# 构建基础镜像
docker build -f Dockerfile.base -t your-registry/dotnet-converter-base:8.0 .

# 推送到私有仓库（可选）
docker push your-registry/dotnet-converter-base:8.0

2.3 业务项目 Dockerfile

业务项目的 Dockerfile 变得非常简洁：

# ==================== 构建阶段 ====================
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish "YourApp.csproj" -c Release -o /app/publish

# ==================== 运行阶段 ====================
FROM your-registry/dotnet-converter-base:8.0 AS final
WORKDIR /app

USER $APP_UID

ENV ASPNETCORE_URLS=http://+:8080 \
    DOTNET_RUNNING_IN_CONTAINER=true

COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApp.dll"]

2.4 基础镜像维护建议

场景	建议
版本管理	使用语义化版本号，如 `dotnet-converter-base:8.0.1`
更新策略	定期更新安全补丁，重新构建基础镜像
多环境	可构建不同配置的基础镜像（如带/不带中文字体）

3. 方式二：单文件完整 Dockerfile

如果不想维护单独的基础镜像，可以使用单文件多阶段构建：

# ==================== 运行时基础镜像 ====================
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime-with-deps

USER root

# 配置国内镜像源（可选，加速下载）
RUN rm -f /etc/apt/sources.list.d/debian.sources && \
    printf '%s\n' \
    "deb http://mirrors.aliyun.com/debian/ bookworm main contrib non-free non-free-firmware" \
    "deb http://mirrors.aliyun.com/debian/ bookworm-updates main contrib non-free non-free-firmware" \
    "deb http://mirrors.aliyun.com/debian-security bookworm-security main contrib non-free non-free-firmware" \
    > /etc/apt/sources.list

# 安装运行时依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    # LibreOffice（Word → PDF）
    libreoffice-core \
    libreoffice-writer \
    python3 \
    python3-pip \
    python3-uno \
    # Chromium（HTML → PDF）
    chromium \
    # 中文字体
    fonts-liberation \
    fonts-noto-cjk \
    fonts-wqy-zenhei \
    fontconfig \
    # Chromium 运行时依赖
    libnss3 \
    libnspr4 \
    ca-certificates \
    libglib2.0-0 \
    libgbm1 \
    libdrm2 \
    libxcb1 \
    libxkbcommon0 \
    libpango-1.0-0 \
    libcairo2 \
    libx11-6 \
    libxcomposite1 \
    libxdamage1 \
    libxext6 \
    libxfixes3 \
    libxrandr2 \
    libxrender1 \
    && fc-cache -f -v \
    && rm -rf /var/lib/apt/lists/*

# 安装 unoserver（使用国内镜像）
RUN pip3 install --no-cache-dir \
    -i https://pypi.tuna.tsinghua.edu.cn/simple \
    unoserver \
    --break-system-packages

# ==================== 构建阶段 ====================
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish "YourApp.csproj" -c Release -o /app/publish

# ==================== 最终镜像 ====================
FROM runtime-with-deps AS final
WORKDIR /app

# 创建非特权用户
ENV APP_UID=1000
RUN mkdir -p /app/logs /tmp/libreoffice /home/appuser/.cache /home/appuser/.config && \
    chown -R $APP_UID:$APP_UID /app /tmp/libreoffice /home/appuser

USER $APP_UID

# 环境变量配置
ENV ASPNETCORE_URLS=http://+:8080 \
    DOTNET_RUNNING_IN_CONTAINER=true \
    HOME=/home/appuser \
    PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
    PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApp.dll"]

4. 依赖说明

LibreOffice 组件

包名	大小	说明
`libreoffice-core`	~100 MB	核心库，必需
`libreoffice-writer`	~15 MB	Word 文档处理，必需
`libreoffice-calc`	~10 MB	Excel 处理，可选
`libreoffice-impress`	~8 MB	PPT 处理，可选
`python3-uno`	~5 MB	Python-UNO 桥接，必需

Chromium 依赖

包名	说明
`chromium`	浏览器本体
`libnss3`	网络安全服务库（HTTPS）
`libgbm1`	图形缓冲管理
`libpango-1.0-0`	文本渲染引擎
`libcairo2`	2D 图形库

字体

包名	大小	说明
`fonts-noto-cjk`	~120 MB	中日韩字体，推荐
`fonts-wqy-zenhei`	~8 MB	文泉驿正黑
`fonts-liberation`	~2 MB	Liberation 字体（类 Times/Arial）

镜像大小参考

配置	镜像大小
基础 .NET 8.0 运行时	~320 MB
完整功能（含所有依赖）	~2.6 GB

5. 环境变量配置

变量	值	说明
`PUPPETEER_SKIP_CHROMIUM_DOWNLOAD`	`true`	跳过 Chromium 自动下载
`PUPPETEER_EXECUTABLE_PATH`	`/usr/bin/chromium`	指定 Chromium 路径
`HOME`	`/home/appuser`	用户主目录
`XDG_CACHE_HOME`	`/home/appuser/.cache`	缓存目录

6. 注意事项

6.1 程序自动跳过依赖检查

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

6.2 非特权用户

生产环境建议使用非 root 用户运行：

ENV APP_UID=1000
USER $APP_UID

6.3 目录权限

确保以下目录对应用用户可写：

RUN mkdir -p /app/logs /tmp/libreoffice /home/appuser/.cache && \
    chown -R $APP_UID:$APP_UID /app /tmp/libreoffice /home/appuser

6.4 离线构建

如需离线构建 Docker 镜像，需提前准备：

基础镜像：docker save mcr.microsoft.com/dotnet/aspnet:8.0 -o aspnet8.tar
SDK 镜像：docker save mcr.microsoft.com/dotnet/sdk:8.0 -o sdk8.tar
在离线环境导入：docker load -i aspnet8.tar

7. 构建和运行

# 构建镜像
docker build -t myapp:latest .

# 运行容器
docker run -d -p 8080:8080 --name myapp myapp:latest

# 查看日志
docker logs -f myapp

# 查看状态
docker stats myapp

目录​

1. 部署方式选择​

2. 方式一：构建自定义基础镜像（推荐）​

2.1 创建基础镜像 Dockerfile​

2.2 构建并推送基础镜像​

2.3 业务项目 Dockerfile​

2.4 基础镜像维护建议​

3. 方式二：单文件完整 Dockerfile​

4. 依赖说明​

LibreOffice 组件​

Chromium 依赖​

字体​

镜像大小参考​

5. 环境变量配置​

6. 注意事项​

6.1 程序自动跳过依赖检查​

6.2 非特权用户​

6.3 目录权限​

6.4 离线构建​

7. 构建和运行​

目录