PdfDing 是一款开源的PDF 文档管理与阅读工具，支持标签分类、全文检索、暗色主题等实用功能，非常适合用于搭建个人或小团队的 PDF 资料库。本文将手把手教你通过两种主流方式快速部署 PdfDing：
- 方式一：
docker run（适合快速体验） - 方式二：
docker-compose（推荐用于长期使用）
一、环境准备
在开始部署前，请确保你的系统满足以下条件：
- 操作系统：Linux / macOS / Windows（建议使用 WSL2）
- 已安装Docker ≥ 20.x
- （可选）已安装Docker Compose ≥ 2.x
验证 Docker 是否正常工作：
dockerversion若未安装，请参考 Docker 官方安装指南。
二、方式一：使用docker run快速启动（适合测试）
1️⃣ 启动命令
dockerrun --name pdfding\-p8000:8000\-v sqlite_data:/home/nonroot/pdfding/db\-v media:/home/nonroot/pdfding/media\-eHOST_NAME=127.0.0.1\-eSECRET_KEY=some_secret\-eCSRF_COOKIE_SECURE=FALSE\-eSESSION_COOKIE_SECURE=FALSE\-d\mrmn/pdfding:latest2️⃣ 参数说明
| 参数 | 说明 |
|---|---|
--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:pdfdingimage:mrmn/pdfding:latestports:-"8000:8000"volumes:-sqlite_data:/home/nonroot/pdfding/db-media:/home/nonroot/pdfding/mediaenvironment:# 主题设置-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-stoppedvolumes:sqlite_data:media:💡 建议同时创建
.env文件管理敏感配置（如SECRET_KEY），避免硬编码。
2️⃣ 启动服务
在docker-compose.yml所在目录执行：
dockercompose up -d查看运行状态：
dockercomposeps3️⃣ 访问应用
浏览器打开：
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，请务必：
- 更换
SECRET_KEY：使用openssl rand -hex 32生成强密钥。 - 启用 HTTPS：
- 通过 Nginx + Let’s Encrypt（公网）
- 或使用私有 CA（如 step-ca，适用于内网）
- 设置安全 Cookie：
CSRF_COOKIE_SECURE=TRUE SESSION_COOKIE_SECURE=TRUE - 限制访问 IP（如仅允许公司内网）
- 定期备份
db和media数据卷
六、总结
| 部署方式 | 适用场景 | 推荐指数 |
|---|---|---|
docker run | 临时测试、快速体验 | ⭐⭐ |
docker-compose | 日常使用、团队部署、生产环境 | ⭐⭐⭐⭐⭐ |
PdfDing 轻量、开源、功能聚焦，是构建个人笔记的最佳选择。
