Docker新手必看：5分钟搞定Stirling-PDF的安装与配置（附常见问题解决）

从零到一：用Docker优雅部署你的私有PDF处理中心

最近在折腾个人知识库，发现处理PDF的需求真是无处不在——合并几个扫描件、给合同加水印、提取文档里的文字。市面上的在线工具要么限制大小，要么担心隐私泄露。直到我发现了Stirling-PDF这个开源项目，它几乎囊括了所有你能想到的PDF操作功能，而且最棒的是，你可以用Docker把它轻松部署在自己的服务器上，完全掌控自己的数据。

对于刚接触Docker的朋友来说，这听起来可能有点技术门槛，但别担心。我花了几天时间反复测试，把整个部署过程梳理得明明白白，还总结了不少实战中容易踩的坑。这篇文章就是为你准备的——无论你是想搭建个人工具库的开发者，还是小团队需要内部文档处理方案，跟着我的步骤走，半小时内你就能拥有一个功能强大、完全私有的PDF处理中心。

1. 环境准备：不仅仅是安装Docker那么简单

很多人以为环境准备就是执行几条安装命令，其实远不止如此。一个稳定的部署环境需要考虑系统兼容性、资源分配和后续维护的便利性。我建议你在开始前花十分钟做好这些准备，能避免后面80%的麻烦。

1.1 选择适合你的操作系统

Stirling-PDF对主流Linux发行版支持都很好，但不同系统在Docker安装和权限管理上有些细微差别。

Ubuntu/Debian系列是我最推荐的选择，社区资源丰富，遇到问题容易找到解决方案。如果你用的是CentOS/RHEL系列，需要注意SELinux可能会对卷挂载造成影响，不过我们有办法处理。至于Windows用户，虽然Docker Desktop也能运行，但在生产环境我建议还是用Linux服务器更稳定。

注意：如果你在云服务器上部署，建议选择Ubuntu 20.04 LTS或22.04 LTS版本，长期支持意味着安全更新更有保障。

1.2 Docker安装的“正确姿势”

网上有很多一键安装脚本，但我建议你理解每一步在做什么。以Ubuntu为例，标准的安装流程应该是这样的：

# 更新包索引
sudo apt update

# 安装必要的依赖包
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 设置稳定版仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker引擎
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

安装完成后，验证一下是否成功：

# 检查Docker版本
docker --version

# 运行测试容器
sudo docker run hello-world

看到“Hello from Docker!”的输出，说明基础环境已经就绪。但别急，还有关键一步——把当前用户加入docker组，这样以后就不用每次都加sudo了：

sudo usermod -aG docker $USER

执行完这条命令后，你需要完全退出当前终端会话再重新登录，这个改动才会生效。很多人忽略了这一步，导致后面操作各种权限问题。

1.3 规划你的存储目录

这是很多新手会忽略的环节。Stirling-PDF运行时会产生几种类型的数据：

我建议在home目录下创建清晰的目录结构：

mkdir -p ~/stirling-pdf/{config,logs,data,ocr}

这样不仅管理方便，以后迁移或备份时也一目了然。如果你打算长期使用，甚至可以考虑把数据目录挂载到单独的硬盘分区，避免系统盘被撑满。

2. 两种部署方式：单命令与编排的抉择

Stirling-PDF官方提供了多种部署方式，但最实用的就是两种：直接使用docker run命令，或者用docker-compose编排。选择哪种取决于你的使用场景和技术偏好。

2.1 快速体验：docker run命令部署

如果你只是想快速试用，或者对Docker Compose不熟悉，这个方式最直接。但别小看它，合理的参数配置同样重要。

先拉取镜像——这里有个细节需要注意：

# 拉取标准版镜像（平衡了功能与体积）