Readur是一个用 Rust + TypeScript 编写的自托管 OCR（文字识别）平台，从 2.5.4 版本开始支持S3 对象存储：你可以把文档文件从本地磁盘迁移到MinIO、AWS S3、Wasabi、Backblaze B2等任意 S3 兼容服务，获得几乎无限的存储空间、更高的可靠性，以及更省心的备份能力。本指南带你用最少的配置，完成Readur 连接 S3 存储的全过程。

为什么要把 Readur 文档存到 S3

本地磁盘存文档有三个绕不开的问题：容量有上限、坏盘风险高、扩容很麻烦。换成 S3 对象存储后：

而且切换存储对使用体验零影响——前端界面、上传、OCR 流程完全不变：

上传的文档经过 OCR 识别后，可以直接在库视图中查看识别出的文本：

准备工作：拿到存储服务的四件套

无论用云厂商还是自建 MinIO，你都需要准备以下信息：

1. 一个存储桶（Bucket），例如readur-documents
2. Access Key ID / Secret Access Key（建议使用只授予该桶权限的最小权限账号）
3. Region（云厂商必填；MinIO 默认填us-east-1即可）
4. Endpoint URL（仅 MinIO、Wasabi 等兼容服务需要，AWS 官方留空）

权限方面，Readur 只需要对象读写与列桶权限（s3:PutObject、s3:GetObject、s3:DeleteObject、s3:ListBucket及分片上传相关权限），完整策略示例见 docs/s3-storage-guide.md。

💡 小贴士：Readur 的s3特性在 Cargo.toml 的默认特性里已经开启（default = ["ocr", "s3"]），使用官方发布镜像或默认构建即可直接使用，无需额外编译参数。

最快配置方法：5 个环境变量接通 S3

在 Readur 的.env配置文件中加入以下内容并重启服务：

# 启用 S3 存储后端 S3_ENABLED=true S3_BUCKET_NAME=readur-documents S3_ACCESS_KEY_ID=your-access-key-id S3_SECRET_ACCESS_KEY=your-secret-access-key S3_REGION=us-east-1

仅连接AWS S3时，以上 5 项就够了。连接S3 兼容服务则多给一个 endpoint：

# S3 兼容服务（MinIO / Wasabi / B2 等） S3_ENDPOINT_URL=https://minio.company.com:9000

配置完成后，新上传的文档会自动写入 S3 桶，数据库中的file_path也会记录为s3://...路径。相关实现可参考 src/services/s3_service.rs 与存储工厂 src/storage/factory.rs。

各服务 Endpoint 速查

设置自定义 endpoint 后，Readur 默认使用 path-style 寻址；如果你的服务要求虚拟主机寻址，可设置S3_FORCE_PATH_STYLE=false。

配置生效后的文档详情页会展示来源、标签与 OCR 置信度等信息：

本地文件搬家：migrate_to_s3 一键迁移工具

已经用本地存储跑了一段时间？Readur 自带企业级迁移工具migrate_to_s3（源码见 src/bin/migrate_to_s3.rs），支持dry-run 预演、断点续传、失败回滚、按用户迁移。推荐分四步走：

第 1 步：备份数据库（永远先做这一步）

pg_dump readur > readur_backup.sql

第 2 步：先 dry-run 预演，不实际改动任何数据，仅预览待迁移的文档数量与预计流量：

cargo run --bin migrate_to_s3 --features s3 -- --dry-run

第 3 步：正式迁移，建议开启回滚：

cargo run --bin migrate_to_s3 --features s3 -- \ --enable-rollback \ --limit 100 # 可先小批量试跑，去掉该参数即全量迁移

迁移过程会自动处理缩略图与 OCR 处理后的图片，并逐个更新数据库中的文件路径。若中途中断，可以用--resume-from <document-id>从断点继续；想先迁某个用户的文件，加--user-id <uuid>即可。完整参数与回滚细节见 docs/administration/storage-migration.md。

第 4 步：验证，确认文档路径都已切换：

SELECT COUNT(*) FILTER (WHERE file_path LIKE 's3://%') AS s3_documents, COUNT(*) FILTER (WHERE file_path NOT LIKE 's3://%' ) AS local_documents FROM documents;

S3 桶里长什么样：结构化目录

Readur 不会把文件平铺在桶根目录，而是按用户 → 年 → 月组织路径，天然友好于生命周期管理与按用户清理：

readur-documents/ ├── documents/{user_id}/2026/10/{document_id}.pdf ├── thumbnails/{user_id}/{document_id}_thumb.jpg └── processed_images/{user_id}/{document_id}_processed.png

这种结构让"90 天前的文档转归档存储"这类生命周期策略非常容易编写。

性能优化与常见问题排查

大文件自动分片：超过 100MB 的文件会自动走 S3 分片上传（单片 16MB），失败时按指数退避自动重试最多 3 次，无需手动干预。

区域选择：把桶建在离 Readur 服务器最近的 region，上传/下载延迟会明显下降；全球访问多的场景可开启 Transfer Acceleration。

遇到连不上、权限被拒这类问题时，按下表逐项排查：

更多诊断命令与日志开关见 docs/s3-troubleshooting.md（开启RUST_LOG=readur=debug,aws_sdk_s3=debug可查看详细 S3 调用日志）。

安全与备份最佳实践（3 条就够）

1. 加密：为桶开启 SSE-S3 / SSE-KMS 服务端加密，传输层务必走 HTTPS；
2. 最小权限：给 Readur 单独建账号，只授予目标桶的读写权限，定期轮换密钥；
3. 版本 + 生命周期：开启桶版本控制可防误删，配合生命周期策略把旧文档归档到 Glacier 等冷存储，长期成本可降一个数量级。

总结

只需 5 个环境变量，Readur 就能把文档存储从本地磁盘升级到 S3 对象存储：云 S3 填好密钥即用，自建 MinIO 多一个 endpoint；存量数据用migrate_to_s3工具先预演、后迁移、可回滚。配合结构化目录与生命周期策略，你的自托管 OCR 平台从此不再受本地硬盘限制。

延伸阅读：

• 完整 S3 配置说明：docs/s3-storage-guide.md
• 存储后端对比（Local / S3 / WebDAV）：docs/self-hosting/storage.md
• 故障排查手册：docs/s3-troubleshooting.md
• 迁移工具详解：docs/administration/storage-migration.md