使用 Docker / Docker Compose 部署 PdfDing —— 个人 PDF笔记

PdfDing 是一款开源的 PDF 文档管理与阅读工具 ，支持标签分类、全文检索、暗色主题等实用功能，非常适合用于搭建个人或小团队的 PDF 资料库。本文将手把手教你通过 两种主流方式 快速部署 PdfDing：

• 方式一：docker run（适合快速体验）
• 方式二：docker-compose（推荐用于长期使用）

---

一、环境准备

在开始部署前，请确保你的系统满足以下条件：

• 操作系统：Linux / macOS / Windows（建议使用 WSL2）
• 已安装 Docker ≥ 20.x
• （可选）已安装 Docker Compose ≥ 2.x

验证 Docker 是否正常工作：

docker version

若未安装，请参考 Docker 官方安装指南。

---

二、方式一：使用 docker run 快速启动（适合测试）

1️⃣ 启动命令

docker run --name pdfding \
  -p 8000:8000 \
  -v sqlite_data:/home/nonroot/pdfding/db \
  -v media:/home/nonroot/pdfding/media \
  -e HOST_NAME=127.0.0.1 \
  -e SECRET_KEY=some_secret \
  -e CSRF_COOKIE_SECURE=FALSE \
  -e SESSION_COOKIE_SECURE=FALSE \
  -d \
  mrmn/pdfding:latest

2️⃣ 参数说明

参数	说明
--name pdfding	容器名称，便于管理
-p 8000:8000	将容器的 8000 端口映射到宿主机
-v sqlite_data:/.../db	持久化 SQLite 数据库（避免重启丢失数据）
-v media:/.../media	持久化上传的 PDF 文件
HOST_NAME	设置访问地址（如 your-domain.com 或 192.168.1.100）
SECRET_KEY	Django 应用密钥（生产环境务必更换为强随机字符串）
CSRF_COOKIE_SECURE / SESSION_COOKIE_SECURE	是否仅在 HTTPS 下传输 Cookie（开发可设为 FALSE，生产应为 TRUE）

3️⃣ 访问服务

打开浏览器，访问：

http://127.0.0.1:8000

即可看到 PdfDing 的界面，开始上传和管理你的 PDF 文档！

---

三、方式二：使用 Docker Compose 部署（推荐 ✅）

Docker Compose 提供更清晰的配置结构，便于版本控制、备份和升级，强烈推荐用于日常使用或团队部署。

1️⃣ 创建 docker-compose.yml

version: "3.8"

services:
  pdfding:
    container_name: pdfding
    image: mrmn/pdfding:latest
    ports:
      - "8000:8000"
    volumes:
      - sqlite_data:/home/nonroot/pdfding/db
      - media:/home/nonroot/pdfding/media
    environment:
      # 主题设置
      - DEFAULT_THEME=${DEFAULT_THEME:-dark}
      - DEFAULT_THEME_COLOR=${DEFAULT_THEME_COLOR:-blue}

      # 安全与配置
      - SECRET_KEY=${SECRET_KEY:-change_me_to_a_strong_random_string}
      - HOST_NAME=${HOST_NAME:-127.0.0.1}

      # 生产环境建议启用 HTTPS 后设为 TRUE
      - CSRF_COOKIE_SECURE=${CSRF_COOKIE_SECURE:-FALSE}
      - SESSION_COOKIE_SECURE=${SESSION_COOKIE_SECURE:-FALSE}

    restart: unless-stopped

volumes:
  sqlite_data:
  media:

💡 建议同时创建 .env 文件管理敏感配置（如 SECRET_KEY），避免硬编码。

2️⃣ 启动服务

在 docker-compose.yml 所在目录执行：

docker compose up -d

查看运行状态：

docker compose ps

3️⃣ 访问应用

浏览器打开：

http://127.0.0.1:8000

现在你拥有了一个功能完整的 PDF 管理平台！

---

四、常用运维命令

操作	命令
查看实时日志	docker logs -f pdfding
停止服务	docker compose down
更新到最新版	docker pull mrmn/pdfding:latest && docker compose up -d
备份数据	备份 sqlite_data 和 media 卷（或挂载到宿主机路径）

---

五、生产环境安全建议（重要！）

如果你计划在内网或公网长期使用 PdfDing，请务必：

1. 更换 SECRET_KEY ：使用 openssl rand -hex 32 生成强密钥。

2. 启用 HTTPS ：

   • 通过 Nginx + Let's Encrypt（公网）
   • 或使用私有 CA（如 step-ca，适用于内网）

3. 设置安全 Cookie ：

   CSRF_COOKIE_SECURE=TRUE
   SESSION_COOKIE_SECURE=TRUE

4. 限制访问 IP（如仅允许公司内网）

5. 定期备份 db 和 media 数据卷

---

六、总结

部署方式	适用场景	推荐指数
docker run	临时测试、快速体验	⭐⭐
docker-compose	日常使用、团队部署、生产环境	⭐⭐⭐⭐⭐

PdfDing 轻量、开源、功能聚焦，是构建个人笔记的最佳选择。