freelawproject/doctor

文档转换与缩略图生成微服务 Docker 镜像

1. 镜像概述和主要用途

1.1 概述

本镜像是一个轻量级微服务，专注于文档格式转换和缩略图生成功能。基于 Alpine Linux 构建，集成 LibreOffice 和 ImageMagick 作为核心处理引擎，提供高效、稳定的文档转换与图像处理能力。镜像设计遵循微服务架构原则，支持通过 REST API 接口进行交互，适用于各类需要文件预览、格式统一的应用场景。

1.2 主要用途

• 实现多格式文档（如 PDF、DOCX、PPTX 等）的相互转换
• 生成文档或图片的缩略图（支持自定义尺寸、格式和质量）
• 为内容管理系统、云存储服务、企业文档平台等提供文件预览能力

2. 核心功能和特性

2.1 核心功能

• 多格式文档转换
  支持输入格式：PDF、DOCX、DOC、PPTX、PPT、XLSX、TXT、HTML 等
  支持输出格式：PDF、PNG、JPG、HTML、TXT 等

• 缩略图生成
  自定义尺寸（如 128x128、256x256）、输出格式（PNG/JPG）及图像质量（0-100%）
  支持按比例缩放、裁剪、水印添加等高级处理

• 批量处理能力
  支持目录级批量文档转换和缩略图生成，支持通过 API 提交批量任务

• REST API 接口
  提供标准化 HTTP 接口，支持同步/异步任务提交、任务状态查询、结果获取

• 异步任务处理
  支持任务队列机制，通过 Redis 实现任务分发与状态跟踪，避免长耗时任务阻塞

• 错误处理与日志
  完善的错误码机制（如格式不支持、文件损坏、处理超时），详细日志记录任务生命周期

2.2 关键特性

• 轻量级设计：基于 Alpine Linux，镜像体积 < 500MB，资源占用低
• 高兼容性：支持主流文档格式，通过 LibreOffice 确保 Office 文档转换准确性
• 可扩展性：支持水平扩展（多实例部署），通过共享存储或分布式文件系统实现任务协同
• 资源控制：支持配置 CPU/内存使用上限，避免单个任务占用过多资源
• 跨平台：兼容 x86_64 和 ARM64 架构，支持 Linux/macOS 容器环境

3. 使用场景和适用范围

3.1 典型使用场景

• 内容管理系统（CMS）：为上传的文档（如新闻稿、政策文件）生成 HTML 预览或 PNG 缩略图，提升用户体验
• 云存储服务：为用户上传的 Office 文件、PDF 提供在线预览功能，无需依赖本地软件
• 企业文档管理：统一文档格式（如将 DOCX 批量转换为 PDF 归档），或生成缩略图用于快速检索
• 电子商务平台：为产品说明书、规格文档生成缩略图，支持用户快速预览商品信息
• 教育平台：将课件（PPT、PDF）转换为网页兼容格式（HTML/PNG），适配在线学习场景

3.2 适用范围

• 开发者集成：作为独立微服务集成到现有系统，通过 API 调用实现功能扩展
• 企业内部系统：部署于私有云环境，处理内部文档转换需求，保障数据安全性
• SaaS 服务：作为增值功能提供给租户，支持按需扩展处理能力

4. 详细使用方法和配置说明

4.1 获取镜像

从 Docker Hub 拉取最新版本镜像：

bash
docker pull doc-converter-thumbnailer:latest

如需指定版本，替换 latest 为具体版本号（如 v1.2.0）。

4.2 基本使用（Docker Run）

4.2.1 快速启动（默认配置）

bash
docker run -d \
  --name doc-service \
  -p 8080:8080 \
  -v ./input:/app/input \
  -v ./output:/app/output \
  doc-converter-thumbnailer:latest

• -p 8080:8080：映射 API 服务端口（容器内默认 8080）
• -v ./input:/app/input：挂载本地输入目录（存放待处理文件）
• -v ./output:/app/output：挂载本地输出目录（存放转换结果和缩略图）

4.2.2 自定义配置启动

通过环境变量调整核心参数：

bash
docker run -d \
  --name doc-service \
  -p 8080:8080 \
  -v ./input:/app/input \
  -v ./output:/app/output \
  -v ./logs:/app/logs \
  -e API_PORT=8080 \
  -e THUMBNAIL_SIZE=200x200 \
  -e CONVERSION_TIMEOUT=300 \
  -e LOG_LEVEL=INFO \
  -e REDIS_URL=redis://redis:6379 \
  doc-converter-thumbnailer:latest

4.3 Docker Compose 配置示例

适用于生产环境的完整部署（含 Redis 任务队列）：

yaml
version: '3.8'

services:
  doc-service:
    image: doc-converter-thumbnailer:latest
    container_name: doc-service
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - ./input:/app/input:rw
      - ./output:/app/output:rw
      - ./logs:/app/logs:rw
    environment:
      - API_PORT=8080                   # API服务端口
      - INPUT_DIR=/app/input            # 输入文件目录（需挂载）
      - OUTPUT_DIR=/app/output          # 输出文件目录（需挂载）
      - THUMBNAIL_SIZE=200x200          # 缩略图默认尺寸（宽x高）
      - THUMBNAIL_FORMAT=png            # 缩略图输出格式（png/jpg）
      - CONVERSION_TIMEOUT=300          # 文档转换超时时间（秒）
      - MAX_CONCURRENT_TASKS=5          # 最大并发任务数
      - LOG_LEVEL=INFO                  # 日志级别（DEBUG/INFO/WARN/ERROR）
      - LOG_DIR=/app/logs               # 日志文件目录（需挂载）
      - REDIS_URL=redis://redis:6379    # Redis地址（用于任务队列）
      - REDIS_DB=0                      # Redis数据库编号
    depends_on:
      - redis

  redis:
    image: redis:alpine
    container_name: doc-service-redis
    restart: always
    volumes:
      - redis-data:/data

volumes:
  redis-data:  # 持久化Redis数据

4.4 环境变量说明

4.5 API接口说明

服务提供 RESTful API，支持任务提交、状态查询和结果获取。

4.5.1 提交文档转换任务

• 端点：POST /api/v1/convert
• 描述：提交文档转换或缩略图生成任务
• 请求体：

  json
  {
    "inputPath": "example.docx",  // 输入文件名（需预先上传至INPUT_DIR目录）
    "outputFormat": "pdf",        // 目标转换格式（如pdf/html/png），若为图片格式则生成缩略图
    "thumbnail": true             // 是否同时生成缩略图（仅当outputFormat为图片格式时有效）
  }
  

• 响应：

  json
  {
    "taskId": "task-123456",      // 任务唯一ID
    "status": "pending",          // 任务状态（pending/running/success/failed）
    "message": "任务已提交至队列"
  }
  

4.5.2 查询任务状态

• 端点：GET /api/v1/tasks/{taskId}
• 描述：查询指定任务的执行状态和结果
• 响应：

  json
  {
    "taskId": "task-123456",
    "status": "success",
    "inputPath": "example.docx",
    "outputPath": "example.pdf",  // 输出文件路径（相对于OUTPUT_DIR）
    "thumbnailPath": "example_thumb.png",  // 缩略图路径（若thumbnail=true）
    "duration": 12.3,             // 任务耗时（秒）
    "createdAt": "2024-05-20T10:30:00Z",
    "completedAt": "2024-05-20T10:30:12Z"
  }
  

4.6 持久化存储配置

为避免容器重启后输入文件、输出结果和日志丢失，需通过-v参数挂载宿主机目录：

• 输入文件：挂载./input:/app/input，确保待处理文件可被容器访问
• 输出文件：挂载./output:/app/output，保存转换结果和缩略图
• 日志：挂载./logs:/app/logs，持久化日志文件（建议配合日志轮转工具如logrotate使用）

4.7 日志配置

• 日志输出：默认同时输出到stdout（容器日志）和LOG_DIR目录下的文件（如app-20240520.log）
• 日志轮转：容器内置日志轮转机制，单个日志文件达到100MB时自动切割，保留最近10个文件

5. 部署方案示例

5.1 生产环境 Docker Compose 配置

以下配置适用于生产环境，包含资源限制、健康检查和日志驱动：

yaml
version: '3.8'

services:
  doc-service:
    image: doc-converter-thumbnailer:latest
    container_name: doc-service
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - /data/doc-input:/app/input:rw
      - /data/doc-output:/app/output:rw
      - /var/log/doc-service:/app/logs:rw
    environment:
      - API_PORT=8080
      - INPUT_DIR=/app/input
      - OUTPUT_DIR=/app/output
      - THUMBNAIL_SIZE=256x256
      - MAX_CONCURRENT_TASKS=10
      - LOG_LEVEL=INFO
      - REDIS_URL=redis://redis:6379
    deploy:
      resources:
        limits:
          cpus: '2'          # 限制CPU使用不超过2核
          memory: 2G         # 限制内存使用不超过2GB
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/health"]  # 健康检查端点
      interval: 30s
      timeout: 10s
      retries: 3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"      # 单个日志文件最大10MB
        max-file: "5"        # 保留最近5个日志文件

  redis:
    image: redis:alpine
    container_name: doc-redis
    restart: always
    volumes:
      - redis-data:/data
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

volumes:
  redis-data:

5.2 扩展部署（多实例）

通过增加服务实例数量实现负载均衡，需确保：

1. 所有实例共享INPUT_DIR和OUTPUT_DIR（通过NFS或分布式存储如MinIO实现）
2. 共享同一Redis实例，确保任务队列统一调度
   示例（Docker Swarm模式）：

bash
docker service create \
  --name doc-service \
  --replicas 3 \
  --publish 8080:8080 \
  --mount type=bind,source=/data/doc-input,target=/app/input \
  --mount type=bind,source=/data/doc-output,target=/app/output \
  -e REDIS_URL=redis://redis:6379 \
  doc-converter-thumbnailer:latest

6. 注意事项

• 文件权限：挂载宿主机目录时，确保容器内用户（默认www-data，UID=33）对挂载目录有读写权限，可通过chmod 775 /data/doc-input调整
• 资源需求：转换大型文档（如1000页PDF）可能占用较高CPU/内存，建议根据实际负载调整MAX_CONCURRENT_TASKS和资源限制
• 格式支持：部分特殊格式（如加密PDF、宏文件）可能转换失败，需在业务层进行预处理（如解密、格式校验）
• 安全防护：生产环境建议通过反向代理（如Nginx）暴露API，启用HTTPS并限制访问来源（如IP白名单）