本文基于 stirlingtools/stirling-pdf:2.13.1-ultra-lite 镜像Ubuntu 24.04 服务器实测想在浏览器里合并 PDF、加水印、改文字又不想装 Adobe 或一堆桌面软件Stirling PDF是一款开源、可本地托管的 Web PDF 工具箱提供合并、拆分、压缩、水印、文本编辑等 60 工具文件在服务器内存中临时处理任务完成后自动清理适合个人与小团队私有化部署。本文带你完成一次10 分钟级 Stirling PDF Docker 部署从 Docker 环境准备、轩辕镜像加速拉取到一条docker run启动容器、读懂启动日志再到浏览器里上传 PDF、编辑文字、添加水印并下载——全程零基础可跟做。下文基于 Ubuntu 24.04、约 4GB 内存环境实测命令可直接复制执行。国内用户从 Docker Hub 拉取stirlingtools/stirling-pdf可能较慢本文使用 轩辕镜像 加速docker.xuanyuan.run。官方文档见 Stirling PDF Docs源码仓库 Stirling-Tools/Stirling-PDF。一、环境要求项目ultra-lite 建议操作系统Linux本文 Ubuntu 24.04内存≥ 2 GB实测检测到 3845 MBJVM 自动分配约 15%70%CPU双核即可磁盘≥ 5 GB 可用镜像 configs数据端口8080容器内固定监听 8080可映射到其他宿主机端口踩坑提示本文使用ultra-lite精简镜像不含 LibreOffice无法 Word/Excel 转 PDF且OCR 能力受限。若侧栏出现灰色不可用工具属预期行为可换latest或fat镜像。首次启动约30 秒2 分钟期间请不要用CtrlC打断docker logs -f。镜像版本对照按需选择标签标签适用场景2.13.1-ultra-lite低配 VPS、只要基础 PDF 操作本文主镜像2.13.1/latest需要 OCR Office 文档转换2.13.1-fat多语言字体、高质量转换二、安装 Docker若尚未安装 Docker可使用轩辕镜像一键脚本适用于 Linux 及国内云服务器bash(wget-qO- https://xuanyuan.cloud/docker.sh)验证docker--versiondockercompose version更多安装说明见 轩辕镜像使用手册。三、拉取 Stirling PDF 镜像使用轩辕镜像加速域拉取2.13.1-ultra-lite标签dockerpull docker.xuanyuan.run/stirlingtools/stirling-pdf:2.13.1-ultra-lite成功时终端显示Status: Downloaded newer image for docker.xuanyuan.run/stirlingtools/stirling-pdf:2.13.1-ultra-lite官方镜像轩辕镜像加速拉取镜像说明stirlingtools/stirling-pdf:2.13.1-ultra-litedocker pull docker.xuanyuan.run/stirlingtools/stirling-pdf:2.13.1-ultra-litestirlingtools/stirling-pdf四、创建目录并一键启动容器4.1 准备数据目录持久化配置与数据库写在挂载的configs目录重建容器后不会丢失mkdir-p/www/wwwroot/docker_xuanyuan_cloud/stirling-data/configs若提示权限不足可在路径前加sudo或改为$HOME/stirling-data/configs下文路径同步替换。4.2 启动容器实测命令dockerrun-d\--namestirling-pdf\--restartunless-stopped\-p8080:8080\-v/www/wwwroot/docker_xuanyuan_cloud/stirling-data/configs:/configs\docker.xuanyuan.run/stirlingtools/stirling-pdf:2.13.1-ultra-lite各参数说明参数说明--name stirling-pdf容器名称便于docker logs/docker stop--restartunless-stopped服务器重启后容器自动恢复-p 8080:8080宿主机 8080 → 容器 8080若 8080 被占用可改为-p 8090:8080-v .../configs:/configs设置、数据库、生成密钥持久化到宿主机镜像标签2.13.1-ultra-lite精简版体积小、启动快成功时终端返回容器 ID例如462552d6e739492d5d5b3cc948f807dd37163c53c7edac9543d7aed6233970e04.3 查看启动日志dockerlogs-fstirling-pdf看到 Spring Boot 启动 banner 且无持续报错后即可尝试浏览器访问。首次启动会生成settings.yml约 30 秒2 分钟。五、读懂启动日志判断是否部署成功对照实测日志中的关键行快速判断是否正常日志含义Detected container memory: 3845MB容器可见内存JVM 据此自动调参Without additional features in jarultra-lite 精简版无登录/安全扩展模块Xvfb not installed; skipping virtual display setup无虚拟显示正常unoserver/unoconvert not installed; skipping UNO setup无 LibreOfficeOffice 转 PDF 不可用Created settings file from template首次运行已在/configs生成配置Starting SPDFApplication v2.13.1应用版本2.13.1Powered by Spring Boot 4.0.6后端框架就绪中Using default multipart file upload limit: 2000MB单文件上传上限约 2 GB命令行健康检查curl-s-o/dev/null-w%{http_code}\nhttp://127.0.0.1:8080期望返回200或302。同时确认容器在运行dockerps|grepstirling-pdf六、验证部署浏览器首次访问在浏览器中打开将YOUR_SERVER_IP换成服务器局域网或公网 IPhttp://YOUR_SERVER_IP:8080若本机在服务器上操作也可用http://127.0.0.1:8080。云服务器需确保安全组 / 防火墙已放行8080端口。首次进入会出现Stirling V2欢迎引导介绍新布局、管理工具与 PDF 文本编辑等功能图 1部署成功后首次访问的 V2 欢迎页点击「下一步」完成引导左侧可点击「从电脑打开」上传本地 PDF右侧为工具分类合并、压缩、水印、签署等。七、功能实测跟做验证部署成功以下步骤用于确认服务不仅「能打开」还能完成常见 PDF 操作。7.1 打开 PDF 文件点击左侧「从电脑打开」选择任意 PDF本文示例为打印机说明书文件出现在左侧「文件」列表后中间区域进入查看器可翻页、缩放图 2PDF 已加载中间为预览区右侧为推荐工具与文档安全类工具7.2 PDF 文本编辑器V2 新功能在右侧「推荐」中选择「PDF 文本编辑器」ALPHA。首次使用会弹出说明适合简单版式文档复杂表格、多栏排版可能效果有限。图 3文本编辑器说明弹窗建议先阅读适用场景与限制点击「知道了」进入编辑模式可直接选中页面文字并修改图 4在 PDF 页面上直接修改文字右侧可调整字体与分组模式点击「应用更改」保存7.3 添加水印日常高频场景在右侧工具栏选择「添加水印」或在「文档安全」分类中找到文件确认当前 PDF 已选中水印类型/措辞在文字框填入水印内容示例为https://xuanyuan.cloud/按需展开样式、格式调整透明度、角度等点击「添加水印」生成预览图 5水印配置步骤措辞中可填文字或链接预览满意后在「审核」步骤点击「下载」保存带水印的 PDF图 6水印已应用到全文预览点击「下载」保存文件至此拉镜像 → 启容器 → 上传 PDF → 编辑文字 → 加水印下载全流程验证完成。八、可选进阶配置8.1 中文界面若界面为英文重建容器时增加环境变量dockerstop stirling-pdfdockerrmstirling-pdfdockerrun-d\--namestirling-pdf\--restartunless-stopped\-p8080:8080\-v/www/wwwroot/docker_xuanyuan_cloud/stirling-data/configs:/configs\-eLANGSzh_CN\-eSYSTEM_DEFAULTLOCALEzh-CN\docker.xuanyuan.run/stirlingtools/stirling-pdf:2.13.1-ultra-lite8.2 完整数据卷挂载便于备份、日志排查与自动化流水线可一次性创建子目录并挂载mkdir-p/www/wwwroot/docker_xuanyuan_cloud/stirling-data/{configs,logs,pipeline,customFiles,tessdata}对应docker run增加卷-v/www/wwwroot/docker_xuanyuan_cloud/stirling-data/tessdata:/usr/share/tessdata\-v/www/wwwroot/docker_xuanyuan_cloud/stirling-data/configs:/configs\-v/www/wwwroot/docker_xuanyuan_cloud/stirling-data/customFiles:/customFiles\-v/www/wwwroot/docker_xuanyuan_cloud/stirling-data/logs:/logs\-v/www/wwwroot/docker_xuanyuan_cloud/stirling-data/pipeline:/pipeline\挂载路径作用/configs设置、数据库、密钥务必备份/logs应用日志/pipeline自动化流水线配置/customFiles自定义静态资源/usr/share/tessdataOCR 语言包ultra-lite 上 OCR 仍受限docker-compose.yml示例与上述等价便于长期维护services:stirling-pdf:image:docker.xuanyuan.run/stirlingtools/stirling-pdf:2.13.1-ultra-litecontainer_name:stirling-pdfrestart:unless-stoppedports:-8080:8080volumes:-./stirling-data/tessdata:/usr/share/tessdata-./stirling-data/configs:/configs-./stirling-data/customFiles:/customFiles-./stirling-data/logs:/logs-./stirling-data/pipeline:/pipelineenvironment:LANGS:zh_CNSYSTEM_DEFAULTLOCALE:zh-CNcd/www/wwwroot/docker_xuanyuan_clouddockercompose up-ddockercompose logs-f8.3 开启登录可选需换镜像实测日志Without additional features in jar表明ultra-lite 不包含登录模块。默认部署无登录墙若将 8080 暴露到公网存在被滥用的风险。需要用户认证时建议换用标准镜像docker.xuanyuan.run/stirlingtools/stirling-pdf:2.13.1或latest同时设置缺一不可DOCKER_ENABLE_SECURITYtrueSECURITY_ENABLELOGINtrueSECURITY_INITIALLOGIN_USERNAME/SECURITY_INITIALLOGIN_PASSWORD首次管理员账号保留原有/configs卷挂载示例dockerrun-d\--namestirling-pdf\--restartunless-stopped\-p8080:8080\-v/www/wwwroot/docker_xuanyuan_cloud/stirling-data/configs:/configs\-eDOCKER_ENABLE_SECURITYtrue\-eSECURITY_ENABLELOGINtrue\-eSECURITY_INITIALLOGIN_USERNAMEadmin\-eSECURITY_INITIALLOGIN_PASSWORD请改为强密码\docker.xuanyuan.run/stirlingtools/stirling-pdf:2.13.1九、升级镜像配置与数据在configs卷中升级时保留挂载即可dockerpull docker.xuanyuan.run/stirlingtools/stirling-pdf:2.13.1-ultra-litedockerstop stirling-pdfdockerrmstirling-pdf# 再执行第四节 docker run 或 docker compose up -d十、常见问题 FAQQ18080 打不开或浏览器超时依次检查docker ps容器是否为 Updocker logs stirling-pdf是否启动完成本机curl http://127.0.0.1:8080是否返回 200/302云安全组与ufw是否放行 8080。Q2部分工具灰色、无法点击ultra-lite 预期行为。需要 Office 转换或完整 OCR 时换2.13.1/latest或2.13.1-fat镜像。Q3Word / Excel 转 PDF 失败日志unoserver/unoconvert not installed表示无 LibreOffice请换标准版或 fat 镜像。Q4OCR 不可用或没有语言选项ultra-lite 不含完整 Tesseract 栈换latest并挂载tessdata卷后可按需下载语言包。Q5上传大 PDF 失败默认上传上限约 2000MB若仍失败检查网络稳定性与浏览器限制。Q6重建容器后设置丢失确认-v .../configs:/configs已挂载数据在宿主机stirling-data/configs目录。Q7如何改用其他端口将-p 8080:8080改为-p 8090:8080浏览器访问http://YOUR_SERVER_IP:8090。Q8需要合并多个 PDF 怎么做在右侧「推荐」中选择「合并」按界面提示添加多个文件并执行即可ultra-lite 支持。总结本文完成了 Stirling PDF 从 Docker 环境到浏览器功能验证的完整流程使用轩辕镜像加速拉取stirlingtools/stirling-pdf:2.13.1-ultra-lite一条docker run映射 8080 并持久化configs读懂启动日志确认 ultra-lite 的能力边界浏览器访问 V2 界面实测 PDF 文本编辑与添加水印下载延伸阅读Stirling PDF 官方文档Docker 安装指南Stirling-Tools/Stirling-PDFstirlingtools/stirling-pdf 镜像页轩辕镜像使用手册如果你在拉取 Docker 镜像时遇到速度慢、超时等问题可以试试 轩辕镜像 的加速服务镜像页支持一键复制拉取命令。欢迎收藏 stirlingtools/stirling-pdf 镜像页获取最新标签与更新说明。
