一、PDF3MD介绍

1.1 PDF3MD简介

PDF3MD 是一款基于 Web 的文档转换工具，采用 React 前端与 Python Flask 后端架构，专注于将 PDF 文件高效、准确地转换为结构清晰的 Markdown 和 Microsoft Word（DOCX）格式，并提供实时进度反馈与友好的用户交互体验。

1.2 PDF3MD主要特点

• PDF 转 Markdown：将 PDF 文档智能转换为结构清晰、可读性强的 Markdown 格式。
• Markdown 转 DOCX：利用 Pandoc 将 Markdown 内容高保真地导出为 Word（.docx）文件。
• 多文件上传：支持同时上传并批量处理多个 PDF 文件，提升转换效率。
• 拖拽上传界面：提供拖放或传统选择两种方式，简化文件上传操作。
• 实时进度跟踪：在转换过程中为每个文件提供详细的实时状态更新。
• 文件信息展示：清晰显示原始文件名、大小、页数及转换时间等元数据。
• 现代响应式 UI：界面简洁直观，适配桌面与移动设备，确保跨平台良好体验。

二、本次实践规划

2.1 本地环境规划

本次实践为个人测试环境，操作系统版本为 Ubuntu 24.04.2 LTS。

2.2 本次实践介绍

1.本次实践部署环境为个人测试环境，生产环境请谨慎；
2.在Docker环境下部署PDF转Markdown工具PDF3MD。

三、本地环境检查

3.1 检查Docker服务状态

检查Docker服务是否正常运行，确保Docker正常运行。

root@jeven:~# systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: enabled)
     Active: active (running) since Tue 2025-12-02 00:51:31 CST; 1min 11s ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 75393 (dockerd)
      Tasks: 32
     Memory: 34.1M (peak: 34.8M)
        CPU: 1.248s
     CGroup: /system.slice/docker.service

3.2 检查Docker版本

检查Docker版本

root@jeven:~# docker -v
Docker version 28.5.0, build 887030f

3.3 检查docker compose 版本

检查Docker compose版本，确保2.0以上版本。

root@jeven:~# docker compose version
Docker Compose version v2.39.4

四、拉取PDF3MD镜像

下载PDF3MD镜像，执行以下命令：

docker pull registry.cn-hangzhou.aliyuncs.com/jeson/pdf3md-backend:latest

docker pull  registry.cn-hangzhou.aliyuncs.com/jeson/pdf3md-frontend:latest

五、部署PDF3MD服务

5.1 创建部署目录

• 创建部署目录

mkdir -p /data/pdf3md/data && cd /data/pdf3md

• 目录权限设置：

chmod -R 777 /data/pdf3md

5.2 docker compose方式部署

新建及编辑docker-compose.yaml文件，宿主机映射端口可自行设置，注意防止端口冲突。

vim docker-compose.yaml

services:
  backend:
    image: registry.cn-hangzhou.aliyuncs.com/jeson/pdf3md-backend:latest 
    container_name: pdf3md-backend
    restart: unless-stopped
    ports:
      - "6201:6201"
    volumes:
      - ./data:/app/temp
    environment:
      - PYTHONUNBUFFERED=1
      - FLASK_ENV=production
      - TZ=Asia/Shanghai
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6201/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  frontend:
    image: registry.cn-hangzhou.aliyuncs.com/jeson/pdf3md-frontend:latest 
    container_name: pdf3md-frontend
    restart: unless-stopped
    ports:
      - "9960:3000"
    environment: {}
    depends_on:
      - backend
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

5.3 创建PDF3MD容器

执行以下命令，创建PDF3MD容器。

docker compose up -d

5.4 查看PDF3MD容器状态

检查PDF3MD容器运行状态，确保PDF3MD容器正常启动。

root@jeven:/data/pdf3md# docker compose ps
NAME              IMAGE                                                            COMMAND                   SERVICE    CREATED          STATUS                            PORTS
pdf3md-backend    registry.cn-hangzhou.aliyuncs.com/jeson/pdf3md-backend:latest    "python app.py"           backend    39 seconds ago   Up 38 seconds (health: starting)   0.0.0.0:6201->6201/tcp, [::]:6201->6201/tcp
pdf3md-frontend   registry.cn-hangzhou.aliyuncs.com/jeson/pdf3md-frontend:latest   "docker-entrypoint.s…"   frontend   39 seconds ago   Up 38 seconds (healthy)            0.0.0.0:9960->3000/tcp, [::]:9960->3000/tcp

5.5 检查PDF3MD容器日志

检查容器运行日志，确保PDF3MD服务正常运行。

docker compose logs

六、访问PDF3MD服务

6.1 访问PDF3MD首页

浏览器地址： http://<个人的服务器IP>:9960，访问PDF3MD初始页。如果无法访问，请确保宿主机的防火墙已关闭或已放行相关端口，对于云服务器还需配置相应的安全组规则。

6.2 文档转化

将测试PDF文档转化为Markdown格式文档，效果如下：

七、总结

本次实践通过 Docker 成功部署了 PDF3MD，验证了其作为一款轻量级 PDF 转 Markdown/DOCX 工具的便捷性与实用性。借助 Docker Compose，前后端服务快速启动，无需手动配置复杂依赖，极大简化了部署流程。PDF3MD 提供的拖拽上传、多文件处理和实时进度反馈功能，显著提升了文档转换效率和用户体验。