Docker 环境部署指南

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

目录

• Docker 环境部署指南
  • 目录
  • 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. 构建和运行

1. 部署方式选择

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

推荐使用方式一：将依赖安装封装到自定义基础镜像中，业务项目的 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 基础镜像维护建议

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 组件

Chromium 依赖

字体

镜像大小参考

5. 环境变量配置

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 镜像，需提前准备：

1. 基础镜像：docker save mcr.microsoft.com/dotnet/aspnet:8.0 -o aspnet8.tar
2. SDK 镜像：docker save mcr.microsoft.com/dotnet/sdk:8.0 -o sdk8.tar
3. 在离线环境导入：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