SnapOtter生产部署指南:Docker Compose三容器栈+NVIDIA GPU加速完全教程

SnapOtter生产部署指南:Docker Compose三容器栈+NVIDIA GPU加速完全教程

【免费下载链接】SnapOtterOpen-source, self-hosted file-processing tool. Convert, compress, OCR, transcribe & run local AI across image, video, audio, PDF & documents, via UI, REST API & pipelines. Your files never leave your network.项目地址: https://gitcode.com/gh_mirrors/st/SnapOtter

SnapOtter 生产部署的核心，就是用Docker Compose 三容器栈（应用 + PostgreSQL 17 + Redis 8）搭建一套私有文件处理服务器，再叠加NVIDIA GPU 加速让 AI 抠图、超分、语音转写飞快。本文面向新手，带你从 0 到 1 完成生产级部署：改对密码、配好限制项、启用 CUDA，你的文件全程不出内网。

一、为什么生产环境要用"三容器栈"

SnapOtter 是开源、自托管的文件处理平台：200+ 个工具覆盖图片、视频、音频、PDF 和文档，支持 Web UI、REST API 与流水线（Pipeline）。

它其实有两种运行形态：

生产环境选三容器栈的三个理由：

• 可独立重启与备份：数据库和缓存各自挂卷，坏了不互相牵连；
• 资源隔离：应用、Postgres、Redis 各有内存/CPU 上限，互不抢资源；
• 安全加固开箱即用：官方 docker/docker-compose.yml 已内置cap_drop: ALL、最小权限数据库账号、健康检查、日志轮转等加固配置，不用自己折腾。

二、部署前准备清单

从源码或镜像两种起点都可以：直接使用官方镜像，或克隆仓库构建：

git clone https://gitcode.com/gh_mirrors/st/SnapOtter cd SnapOtter

三、Docker Compose 三容器栈一键部署步骤

第 1 步：确认 Compose 文件

仓库里已经备好了生产用的编排文件，核心结构一目了然（三个服务：SnapOtter、postgres、redis）：

• 生产 Compose 文件：docker/docker-compose.yml
• 构建定义：docker/Dockerfile

第 2 步：启动三容器栈

docker compose -f docker/docker-compose.yml up -d

首次启动会自动完成数据库迁移、创建最小权限应用账号、播种管理员账号，无需手写任何 SQL。

第 3 步：登录并强制改密

打开http://服务器IP:1349，默认账号密码均为admin，首次登录会被强制要求修改密码——这是生产安全的第一步，务必改掉。

第 4 步：验证健康状态

每个容器都内置了健康检查，用一条命令确认三个容器全部healthy：

docker compose -f docker/docker-compose.yml ps

应用健康检查会请求/api/v1/health接口，全部通过即代表生产栈部署成功。

四、关键生产环境变量配置（必改清单）

环境变量示例集中维护在 .env.example，部署时建议至少处理以下几项：

💡 小技巧：官方镜像还支持"只读数据库账号"模式——设置DATABASE_MIGRATION_URL后，应用日常运行使用的账号只有数据读写权限，迁移时临时提权，升级现有安装也不用手动 SQL（详见 DOCKERHUB.md）。

五、NVIDIA GPU 加速：三步启用 CUDA

有 NVIDIA 显卡的主机，可以让AI 抠图（背景移除）、AI 超分放大、语音转写走 CUDA 推理，速度数量级提升。注意：OCR 有意保持 CPU 运行时，两种主机行为一致。

第 1 步：宿主机安装 NVIDIA Container Toolkit

确保显卡驱动正常（nvidia-smi能出卡信息），然后按 NVIDIA 官方文档安装 container toolkit（支持 Ubuntu/Debian 等主流发行版）。

第 2 步：用 GPU 版 Compose 文件启动

仓库已备好 GPU 编排文件 docker/docker-compose-gpu.yml，与 CPU 版的差异只有三处：

• 内存上限从 6g 提到8g（AI 推理更吃内存）；
• shm_size: 2gb（PyTorch CUDA 共享内存需要）；
• 通过deploy.resources.reservations.devices向容器注入全部 GPU。

切换命令只多一个-f参数：

docker compose -f docker/docker-compose-gpu.yml up -d

第 3 步：验证 GPU 是否生效

官方提供的验证命令：

docker logs SnapOtter 2>&1 | grep GPU

日志中出现 CUDA 设备信息即成功。镜像会在运行时自动检测 CUDA，检测不到则安全回退 CPU，不会崩——所以 GPU 装错了也只是变慢，不是变坏。

六、日常运维：升级、备份与常见问题

🔄 升级版本

docker compose -f docker/docker-compose.yml pull docker compose -f docker/docker-compose.yml up -d

数据库迁移会在启动时自动执行，历史数据保留在SnapOtter-pgdata卷中。

💾 备份

备份四个卷即可全量恢复：SnapOtter-data（AI 模型与用户文件，最重要）、SnapOtter-workspace、SnapOtter-pgdata、SnapOtter-redisdata。docker volume list可查看全部。

🛠 常见问题速查

总结

📌 本文的部署路径可以浓缩为一句话：docker compose up -d起三容器栈 → 改强密码与限制项 → 有卡就换 GPU Compose 文件。SnapOtter 的官方编排文件已经替你完成了数据库加固、健康检查、日志轮转等大量细节，你只需要把"必改清单"里的密码和限制项填对，就能得到一套文件永不离网的私有文件处理平台。

<输出文章结束> </输出文章>

Wait, I need to remove the closing tag issue. Let me provide the clean article.

<输出文章>

SnapOtter生产部署指南:Docker Compose三容器栈+NVIDIA GPU加速完全教程

SnapOtter 生产部署的核心，就是用Docker Compose 三容器栈（应用 + PostgreSQL 17 + Redis 8）搭建一套私有文件处理服务器，再叠加NVIDIA GPU 加速让 AI 抠图、超分、语音转写飞快。本文面向新手，带你从 0 到 1 完成生产级部署：改对密码、配好限制项、启用 CUDA，你的文件全程不出内网。

一、为什么生产环境要用"三容器栈"

SnapOtter 是开源、自托管的文件处理平台：200+ 个工具覆盖图片、视频、音频、PDF 和文档，支持 Web UI、REST API 与流水线（Pipeline）。

它其实有两种运行形态：

生产环境选三容器栈的三个理由：

• 可独立重启与备份：数据库和缓存各自挂卷，坏了不互相牵连；
• 资源隔离：应用、Postgres、Redis 各有内存/CPU 上限，互不抢资源；
• 安全加固开箱即用：官方 docker/docker-compose.yml 已内置cap_drop: ALL、最小权限数据库账号、健康检查、日志轮转等加固配置，不用自己折腾。

二、部署前准备清单

也可以克隆仓库从源码构建：

git clone https://gitcode.com/gh_mirrors/st/SnapOtter cd SnapOtter

三、Docker Compose 三容器栈一键部署步骤

第 1 步：确认 Compose 文件

仓库里已经备好了生产用的编排文件，核心结构一目了然（三个服务：SnapOtter、postgres、redis）：

• 生产 Compose 文件：docker/docker-compose.yml
• 构建定义：docker/Dockerfile

第 2 步：启动三容器栈

docker compose -f docker/docker-compose.yml up -d

首次启动会自动完成数据库迁移、创建最小权限应用账号、播种管理员账号，无需手写任何 SQL。

第 3 步：登录并强制改密

打开http://服务器IP:1349，默认账号密码均为admin，首次登录会被强制要求修改密码——这是生产安全的第一步，务必改掉。

第 4 步：验证健康状态

每个容器都内置了健康检查，用一条命令确认三个容器全部healthy：

docker compose -f docker/docker-compose.yml ps

应用健康检查会请求/api/v1/health接口，全部通过即代表生产栈部署成功。

四、关键生产环境变量配置（必改清单）

环境变量示例集中维护在 .env.example，部署时建议至少处理以下几项：

💡 小技巧：设置DATABASE_MIGRATION_URL后可启用"只读账号模式"——应用日常运行账号只有数据读写权限，迁移时临时提权，升级现有安装也不用手动 SQL（详见 DOCKERHUB.md）。

五、NVIDIA GPU 加速：三步启用 CUDA

有 NVIDIA 显卡的主机，可以让AI 抠图（背景移除）、AI 超分放大、语音转写走 CUDA 推理，速度数量级提升。注意：OCR 有意保持 CPU 运行时，两种主机行为一致。

第 1 步：宿主机安装 NVIDIA Container Toolkit

确保显卡驱动正常（nvidia-smi能出卡信息），然后按 NVIDIA 官方文档安装 container toolkit（支持 Ubuntu/Debian 等主流发行版）。

第 2 步：用 GPU 版 Compose 文件启动

仓库已备好 GPU 编排文件 docker/docker-compose-gpu.yml，与 CPU 版的差异只有三处：

• 内存上限从 6g 提到8g（AI 推理更吃内存）；
• shm_size: 2gb（PyTorch CUDA 共享内存需要）；
• 通过deploy.resources.reservations.devices向容器注入全部 GPU。

切换命令只多一个-f参数：

docker compose -f docker/docker-compose-gpu.yml up -d

第 3 步：验证 GPU 是否生效

官方提供的验证命令：

docker logs SnapOtter 2>&1 | grep GPU

日志中出现 CUDA 设备信息即成功。镜像会在运行时自动检测 CUDA，检测不到则安全回退 CPU，不会崩——所以 GPU 没配好也只是变慢，不是变坏。

六、日常运维：升级、备份与常见问题

🔄 升级版本

docker compose -f docker/docker-compose.yml pull docker compose -f docker/docker-compose.yml up -d

数据库迁移会在启动时自动执行，历史数据保留在SnapOtter-pgdata卷中。

💾 备份

备份四个卷即可全量恢复：SnapOtter-data（AI 模型与用户文件，最重要）、SnapOtter-workspace、SnapOtter-pgdata、SnapOtter-redisdata。docker volume list可查看全部。

🛠 常见问题速查

总结

📌 本文的部署路径可以浓缩为一句话：docker compose up -d起三容器栈 → 改强密码与限制项 → 有卡就换 GPU Compose 文件。SnapOtter 的官方编排文件已经替你完成了数据库加固、健康检查、日志轮转等大量细节，你只需要把"必改清单"里的密码和限制项填对，就能得到一套文件永不离网的私有文件处理平台。

【免费下载链接】SnapOtterOpen-source, self-hosted file-processing tool. Convert, compress, OCR, transcribe & run local AI across image, video, audio, PDF & documents, via UI, REST API & pipelines. Your files never leave your network.项目地址: https://gitcode.com/gh_mirrors/st/SnapOtter