docs(guide): add a low-resource deployment guide in 21 languages (#548)

New guide/low-resource page: what runs well on 2 GB machines, a Raspberry Pi / old laptop Compose walkthrough with tuned caps, the env-var knobs that matter on small hardware, and what to skip. Linked from getting-started, the deployment hardware section, and the sidebar. Translated into all 20 non-English locales via the i18n batch pipeline; parity check and VitePress build pass. Admin merge: docs-only PR, the path-filtered required integration contexts never report (#420 precedent). Closes #497
2026-08-03 07:46:42 +02:00 · 2026-07-17 00:40:48 +08:00
parent 1f4878ac4d
commit fe85dd2b98
104 changed files with 2323 additions and 80 deletions
@@ -1,7 +1,7 @@
 ---
 description: "使用 Docker 将 SnapOtter 部署到生产环境。涵盖硬件要求、GPU 配置，以及 Nginx、Traefik 和 Cloudflare 的反向代理配置。"
 i18n_output_hash: 63267650bd5f
-i18n_source_hash: e0d8d5f6fc87
+i18n_source_hash: 98172965118b
 i18n_provenance: human
 ---

@@ -218,6 +218,8 @@ docker logs SnapOtter 2>&1 | head -20

 这些数字来自一系列系统上的基准测试，从配备 NVIDIA RTX 4070 的现代 amd64 工作站到 Raspberry Pi，在每台设备上运行整个工具目录，并扫描 Docker 资源限制以找出真实的下限。

+运行在这些层级的低端（Pi、旧笔记本电脑、2 GB 的 VPS）？[低资源环境部署](/zh-CN/guide/low-resource)把这些数字变成一份带有调优上限的具体分步指南。
+
 ### 快速参考 {#quick-reference}

 | 层级 | 使用场景 | CPU | 内存 | GPU | 存储 |
@@ -1,7 +1,7 @@
 ---
 description: "用一条 Docker 命令安装 SnapOtter。包含 Docker Compose 配置、从源码构建，以及完整的功能概览。"
 i18n_output_hash: 3da9d8045239
-i18n_source_hash: 24724b5595b2
+i18n_source_hash: 68bf7f60b68d
 i18n_provenance: human
 ---

@@ -19,6 +19,8 @@ docker run -d --name SnapOtter -p 1349:1349 -v SnapOtter-data:/data snapotter/sn

 这个单容器运行它所需的一切：在未设置 `DATABASE_URL` 时，它会在回环接口上启动自己的 PostgreSQL 和 Redis（嵌入式模式），并将所有数据保存在 `SnapOtter-data` 卷中。这是试用 SnapOtter 或在家庭实验室中自托管的最快方式。生产环境请运行下面的 [Docker Compose](#docker-compose) 栈，它会将 PostgreSQL 和 Redis 分别放在各自的容器中。嵌入式模式以 root 运行（默认），一旦你设置了 `DATABASE_URL` 便会自动关闭。

+要安装在 Raspberry Pi、旧笔记本电脑或小型 VPS 上？参阅[低资源环境部署](/zh-CN/guide/low-resource)，那里有调优后的分步指南，以及对受限硬件该有的预期。
+
 首次登录时会要求你更改密码。

 ::: tip 匿名产品分析
@@ -0,0 +1,103 @@
+---
+i18n_source_hash: f5de74aee1b9
+i18n_provenance: machine
+i18n_output_hash: 6c82cfe39a38
+---
+# 低资源环境部署 {#low-resource-setups}
+
+SnapOtter 在小型硬件上运行良好：Raspberry Pi 4 或 5、一台旧笔记本电脑，或一台 2 GB 的 VPS。本页是针对这些机器的实用指南：该有什么预期、一套可直接复制粘贴且带有合理上限的配置，以及哪些功能应该跳过。这些数字背后的完整基准测试数据见[硬件要求](/zh-CN/guide/deployment#hardware-requirements)。
+
+先说两条硬性限制：
+
+- **仅支持 64 位。**镜像只为 `linux/amd64` 和 `linux/arm64` 构建。不支持 32 位 ARM（`armv7`/`armhf`），因此第一代 Pi 和 Pi Zero 系列不在此列。
+- **内存下限 2 GB。**512 MB 无法启动整个栈，1 GB 在多文件批量处理时会失败。2 GB 加 2 核是能舒适运行的最小配置。
+
+## 小型硬件上哪些功能运行良好 {#what-runs-well}
+
+所有非 AI 工具都能在 2 GB / 2 核的机器上运行：整个"图像"和"文件"板块、PDF 工具，以及流复制类的视频和音频操作（裁剪、静音、更换容器）。大多数在一秒内完成。
+
+有两类负载是例外：
+
+- **视频重编码**（在不同编解码器之间转换）受 CPU 限制。一段在高速桌面 CPU 上约 40 秒完成的 1080p 视频，在 Pi 级 CPU 上可能需要几分钟。流复制操作依然是即时的。
+- **AI 工具**需要内存（推荐 4 GB）和磁盘（较大的 AI 包每个 4-5 GB），其中重型工具（放大、照片修复、背景移除）在 Pi 级 CPU 上并不实用。人脸检测和 OCR 这类轻量 AI 在内存足够时可以使用。
+
+这两类负载在你用到之前既不会安装也不会运行：未安装任何 AI 包时，应用空闲内存占用约 360 MB，而 AI 包只有在管理员启用时才会下载。
+
+## Raspberry Pi / 旧笔记本电脑实操指南 {#walkthrough}
+
+这就是[快速上手](/zh-CN/guide/getting-started)中的标准 Compose 安装，外加资源限制和保守的上限。它假设使用 64 位操作系统（在 Pi 上：Raspberry Pi OS 64 位或 Ubuntu Server arm64）。
+
+```yaml
+services:
+  snapotter:
+    image: snapotter/snapotter:latest
+    ports:
+      - "1349:1349"
+    volumes:
+      - ./snapotter-data:/data
+    environment:
+      - DATABASE_URL=postgres://snapotter:snapotter@db:5432/snapotter
+      - REDIS_URL=redis://redis:6379
+      # Small-box profile: see the table below for what each cap does.
+      - CONCURRENT_JOBS=1
+      - MAX_WORKER_THREADS=2
+      - MAX_BATCH_SIZE=5
+      - MAX_UPLOAD_SIZE_MB=100
+      - MAX_MEGAPIXELS=50
+      - MAX_VIDEO_DURATION_S=300
+    deploy:
+      resources:
+        limits:
+          cpus: "2"
+          memory: 2G
+    depends_on:
+      - db
+      - redis
+    restart: unless-stopped
+
+  db:
+    image: postgres:17-alpine
+    environment:
+      - POSTGRES_USER=snapotter
+      - POSTGRES_PASSWORD=snapotter
+      - POSTGRES_DB=snapotter
+    volumes:
+      - ./postgres-data:/var/lib/postgresql/data
+    restart: unless-stopped
+
+  redis:
+    image: redis:8-alpine
+    command: redis-server --maxmemory 256mb --maxmemory-policy noeviction
+    restart: unless-stopped
+```
+
+针对 Pi 级机器的注意事项：
+
+- **数据卷和 Postgres 优先使用 USB SSD 而不是 SD 卡。**任务工作区会产生真实的磁盘 IO，而 SD 卡既慢又容易磨损。
+- **一体化单容器在这里同样适用**（未设置 `DATABASE_URL`/`REDIS_URL` 时使用嵌入式 Postgres 和 Redis），在内存受限的主机上应通过 `REDIS_MAXMEMORY` 调低其嵌入式 Redis 的内存上限（见[配置](/zh-CN/guide/configuration)）。Compose 提供更细的按服务控制，这也是本指南采用它的原因。
+- **在 2 GB 设备上添加 swap。**它能避免偶发的内存尖峰（一个大 PDF、一个你忘了设上限的批量任务）以内存不足被杀进程收场。zram 是对 SD 卡更友好的选择。
+- arm64 镜像仅支持 CPU；ARM 板卡上没有 CUDA。
+
+## 调优参数 {#tuning-knobs}
+
+所有上限都是环境变量，完整文档见[配置](/zh-CN/guide/configuration)。`0` 表示不限制或自动。在小型硬件上重要的有这些：
+
+| 变量 | 小型机器建议值 | 它保护什么 |
+|---|---|---|
+| `CONCURRENT_JOBS` | `1` | 并行运行的任务数。自动检测使用 CPU 核心数减一，在大机器上没问题，但在内存吃紧的 2 核机器上过于激进。 |
+| `MAX_WORKER_THREADS` | `2` | 图像处理线程池。 |
+| `MAX_BATCH_SIZE` | `5` | 批量处理是 1-2 GB 机器最先耗尽内存的地方。 |
+| `MAX_UPLOAD_SIZE_MB` | `100` | 防止单个巨大文件占满整个工作区。 |
+| `MAX_MEGAPIXELS` | `50` | 解码一张 100+ MP 的图像无论文件大小都要消耗内存。 |
+| `MAX_VIDEO_DURATION_S` | `300` | 长时间转码会把小 CPU 独占几分钟到几小时。 |
+| `PROCESSING_TIMEOUT_S` | `600` | 硬性上限，确保失控的任务最终会释放机器。 |
+
+这些上限约束的是服务器接受什么，所以应按你的实际用途来设置，而不是越小越好。如果你从不处理视频，设一个 `MAX_VIDEO_DURATION_S` 上限毫无代价；如果你每天扫描文档，就不要限制 `MAX_PDF_PAGES`。
+
+## 应该跳过什么 {#what-to-skip}
+
+- **重型 AI 包。**放大、照片修复和背景移除需要 GPU 或高速多核 CPU，而且每个包要占 4-5 GB 磁盘。在小型机器上，干脆不要安装它们；缺少对应包的工具会显示安装提示，而不会运行。
+- **把视频重编码当作日常负载。**偶尔转码没有问题（只是慢）；持续的转码队列需要的是 CPU 核心，而不是一台 Pi。
+- **总的来说，用不到的工具。**管理员可以在 Settings 中关闭单个工具，这会把它们从 UI 中移除并停止注册其 API 路由。这本身并不省内存，但能避免一台共享的小型实例被拿去跑硬件唯一扛不住的那种负载。
+
+如果以后把实例迁移到更强的硬件上，去掉这些上限（改回 `0`），同一个数据卷可以直接沿用。
@@ -1,7 +1,7 @@
 ---
 description: "SnapOtter 的安全加固指南。涵盖容器安全、网络隔离、Docker 密钥、Kubernetes 部署和合规产物。"
 i18n_source_hash: 986f7658430c
-i18n_provenance: machine
+i18n_provenance: human
 i18n_output_hash: 05d4a7e4d409
 ---