Stirling-PDF 保姆级部署教程：
Stirling-PDF（仓库 Stirling-Tools/Stirling-PDF）
一、项目介绍与适用场景
适用场景包括：个人服务器自托管、团队内部工具搭建、学习开源项目架构、以及替代商业 SaaS 方案。
二、核心功能逐条拆解
- Parallel file processing and downloads
- Custom download options
- Custom 'Pipelines' to run multiple features in an automated queue
- API for integration with external scripts
- Optional Login and Authentication support (see here for documentation)
- Enterprise features like SSO (see here for documentation)
- Database Backup and Import (see here for documentation)
- *PDF Multi Tool*: Access merge, rotate, rearrange, split and delete actions from a single dashboard
三、全套官方链接
| 类型 | 链接 |
|---|---|
| GitHub 仓库 | https://github.com/Stirling-Tools/Stirling-PDF |
| 官方 README | https://github.com/Stirling-Tools/Stirling-PDF/blob/main/README.md |
| 官方主页 | https://Stirling-Tools.github.io/Stirling-PDF |
| License | 见仓库 LICENSE 文件 |
四、硬件与环境前置要求
根据官方 README 及项目类型，部署前需准备：
- 操作系统：Linux（推荐 Ubuntu 22.04+/Debian 12）、macOS 或 Windows
- 运行时：根据项目需要，可能涉及 Python 3.9+、Node.js 18+、Go 1.21+ 或 Docker
- 内存：最低 1GB 内存，推荐 2GB 以上
- 磁盘：项目本身约 100MB 至 1GB，数据目录按需扩展
- 网络：需能访问 GitHub 和对应镜像源
五、多平台部署步骤
5.1 源码部署
第 1 步：克隆仓库。
git clone [https://github.com/Stirling-Tools/Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF).git
cd Stirling-PDF
第 2 步：安装依赖。
# 根据项目类型选择对应包管理器安装
# Python 项目: pip install -r requirements.txt
# Node 项目: npm install
# Go 项目: go build ./...
第 3 步：配置环境。 复制示例配置文件并修改：
cp .env.example .env
# 编辑 .env 填入必要参数
5.2 Docker 部署
官方支持 Docker Compose 部署的项目可使用：
docker compose up -d
如官方未提供 Docker 配置，请以源码部署为准。
六、配置文件全部参数解释
主要配置项（从 README 提炼）：
| 参数 | 说明 | 默认值 |
|---|---|---|
| 端口 | 服务监听端口 | 8080 |
| 数据目录 | 数据存储路径 | ./data |
| 日志级别 | debug/info/warn/error | info |
| 数据库连接 | 如使用外部数据库 | 内置 |
七、启动、后台常驻与开机自启
前台启动（调试用）：
# 按项目实际命令启动
后台常驻（systemd 方式）：
sudo tee /etc/systemd/system/stirling-pdf.service <
八、功能实操教程
第 1 步：确认服务运行状态。
systemctl status stirling-pdf
# 或访问 http://localhost:8080
第 2 步：首次登录管理后台，使用默认账号密码登录后立即修改密码。
第 3 步：根据需要在设置页中调整参数，包括端口、数据目录、备份策略等。
第 4 步：将域名解析到服务器 IP，并配置反向代理（如 Nginx/Caddy）以启用 HTTPS。
九、全套报错故障排查
报错：端口被占用
- 原因：默认端口 8080 已被其他程序占用
- 解决：修改配置文件中的端口，或停止占用端口的服务
报错：权限不足无法写入数据目录
- 原因：运行用户对数据目录没有写权限
- 解决：chown -R www-data:www-data /opt/stirling-pdf/data
报错：Docker 镜像拉取失败
- 原因：网络无法访问 Docker Hub
- 解决：配置国内镜像加速器，或使用代理
报错：配置文件格式错误
- 原因：YAML/JSON 语法错误
- 解决：使用 python -c "import yaml; yaml.safe_load(open('config.yaml'))" 验证
十、升级、回滚与卸载
升级：
git pull origin main
# 重新安装依赖并重启
回滚：
git log --oneline # 查看历史提交
git checkout # 回退到指定版本
卸载：
systemctl stop stirling-pdf
systemctl disable stirling-pdf
rm -rf /opt/stirling-pdf
十一、商用许可与合规风险提示
本项目开源协议以仓库 LICENSE 文件为准。使用前请仔细阅读：
- 确认所选 License 允许的商用范围
- 如涉及用户数据，需做好隐私保护
- 如处理敏感信息，建议启用访问控制和审计日志
参考链接：
- GitHub 仓库
- 官方 README
- 官方文档站
十二、补充说明
Stirling-PDF 作为开源项目，社区贡献活跃。建议关注官方 GitHub 的 Releases 页面获取版本更新。部署过程中如遇问题，可在 Issues 区搜索同类问题，或在 Discussions 板块提问。
日常使用中，建议定期备份数据目录，关注安全更新。对于生产环境，建议配置监控告警和日志轮转，确保服务稳定运行。
更多使用技巧和最佳实践，请参考官方文档和社区教程。