从平台复制存储对象

Copy storage objects from a managed Supabase project to a self-hosted instance using rclone.

本指南将带你了解如何使用 rclone 通过 S3 到 S3 复制，将存储对象从托管的 Supabase 平台项目复制到自建实例。

🌐 This guide walks you through copying storage objects from a managed Supabase platform project to a self-hosted instance using rclone with S3-to-S3 copy.

直接复制文件（例如，下载文件并放到 volumes/storage/）是行不通的。自托管存储使用的内部文件结构和你从平台下载的文件结构不同。使用 S3 协议传输对象，这样存储才会创建正确的元数据记录。

🌐 Direct file copy (e.g., downloading files and placing them into volumes/storage/) does not work. Self-hosted Storage uses an internal file structure that differs from what you get when downloading files from the platform. Use the S3 protocol to transfer objects so that Storage creates the correct metadata records.

在你开始之前 #

🌐 Before you begin

你需要：

🌐 You need:

一个可以正常运行的自托管 Supabase 实例，并启用了 S3 协议端点 - 参见配置 S3 存储
你的平台项目的 S3 凭证——从 S3 配置页面生成
在你自托管的实例上创建匹配的存储桶
在运行复制的机器上安装了rclone

步骤1：获取平台S3凭证 #

🌐 Step 1: Get platform S3 credentials

在你管理的 Supabase 项目仪表板里，进入存储 > S3 配置 > 访问密钥。生成一个新的访问密钥对并复制：

🌐 In your managed Supabase project dashboard, go to Storage > S3 Configuration > Access keys. Generate a new access key pair and copy:

端点: https://<project-ref>.supabase.co/storage/v1/s3
地区：你项目所在的地区（例如，us-east-1）
访问密钥ID 和 秘密访问密钥

为了更好地处理大文件，使用直接存储主机名：https://<project-ref>.storage.supabase.co/storage/v1/s3

步骤2：在自托管上创建存储桶 #

🌐 Step 2: Create buckets on self-hosted

在你把对象复制进去之前，目标地点的桶必须先存在。你可以通过仪表板的界面创建它们，或者用SQL 编辑器创建。

🌐 Buckets must exist on the destination before you can copy objects into them. You can create them through the dashboard UI, or with the SQL Editor.

如果你已经按照恢复指南将平台数据库恢复到自托管，你的存储桶定义已经存在了。你可以跳过这一步。

🌐 If you already restored your platform database to self-hosted using the restore guide, your bucket definitions are already present. You can skip this step.

要列出你的平台桶，连接到你的平台数据库并运行：

🌐 To list your platform buckets, connect to your platform database and run:

1
select id, name, public from storage.buckets order by name;

然后在你自建的实例上创建匹配的桶。连接到你自建的数据库并运行：

🌐 Then create matching buckets on your self-hosted instance. Connect to your self-hosted database and run:

1
insert into storage.buckets (id, name, public)
2
values
3
  ('your-storage-bucket', 'your-storage-bucket', false)
4
on conflict (id) do nothing;

对每个桶重复操作，将 public 设置为 true 或 false，视情况而定。

🌐 Repeat for each bucket, setting public to true or false as appropriate.

步骤 3：配置 rclone #

🌐 Step 3: Configure rclone

创建或编辑你的 rclone 配置文件（~/.config/rclone/rclone.conf）:

🌐 Create or edit your rclone configuration file (~/.config/rclone/rclone.conf):

1
[platform]
2
type = s3
3
provider = Other
4
access_key_id = your-platform-access-key-id
5
secret_access_key = your-platform-secret-access-key
6
endpoint = https://your-project-ref.supabase.co/storage/v1/s3
7
region = your-project-region
8
9
[self-hosted]
10
type = s3
11
provider = Other
12
access_key_id = your-self-hosted-access-key-id
13
secret_access_key = your-self-hosted-secret-access-key
14
endpoint = http://your-domain:8000/storage/v1/s3
15
region = your-self-hosted-region

将凭据替换为你实际的值。对于自托管，请使用你在配置 S3 存储中设置的 REGION、S3_PROTOCOL_ACCESS_KEY_ID 和 S3_PROTOCOL_ACCESS_KEY_SECRET。

🌐 Replace the credentials with your actual values. For self-hosted, use the REGION, S3_PROTOCOL_ACCESS_KEY_ID and S3_PROTOCOL_ACCESS_KEY_SECRET you configured in Configure S3 Storage.

检查两个遥控器是否都能连接：

🌐 Verify both remotes connect:

1
rclone lsd platform:
2
rclone lsd self-hosted:

这两个命令都应该列出你的存储桶。

🌐 Both commands should list your buckets.

步骤4：复制对象 #

🌐 Step 4: Copy objects

复制一个桶：

🌐 Copy a single bucket:

1
rclone copy platform:your-storage-bucket self-hosted:your-storage-bucket --progress

复制所有桶:

🌐 To copy all buckets:

1
for bucket in $(rclone lsf platform: | tr -d '/'); do
2
  echo "Copying bucket: $bucket"
3
  rclone copy "platform:$bucket" "self-hosted:$bucket" --progress
4
done

对于大型迁移，可以考虑添加 --transfers 4 来增加并行度，或者添加 --checkers 8 来加快比较阶段的速度。有关所有选项，请参阅标志文档。

🌐 For large migrations, consider adding --transfers 4 to increase parallelism, or --checkers 8 to speed up the comparison phase. See the flags documentation for all options.

验证 #

🌐 Verify

比较源和目标的对象数量：

🌐 Compare object counts between source and destination:

1
rclone size platform:your-storage-bucket && \
2
rclone size self-hosted:your-storage-bucket

在你自托管的实例上打开 Studio，并浏览存储桶以确认文件可访问。

🌐 Open Studio on your self-hosted instance and browse the storage buckets to confirm files are accessible.

故障排除 #

🌐 Troubleshooting

签名错误 #

🌐 Signature errors

如果你在连接到任意远程时看到 SignatureDoesNotMatch：

🌐 If you see SignatureDoesNotMatch when connecting to either remote:

平台：在你项目的存储设置中重新生成 S3 访问密钥。确保端点 URL 包含 /storage/v1/s3。
自托管：确认 .env 文件中的 REGION、S3_PROTOCOL_ACCESS_KEY_ID 和 S3_PROTOCOL_ACCESS_KEY_SECRET 是否与你的 rclone 配置匹配。

未找到桶 #

🌐 Bucket not found

如果 rclone 报告自托管端的存储桶不存在，先创建它——参见步骤 2。S3 协议在复制时不会自动创建存储桶。

🌐 If rclone reports that a bucket doesn't exist on the self-hosted side, create it first - see Step 2. The S3 protocol does not auto-create buckets on copy.

大文件超时 #

🌐 Timeouts on large files

对于非常大的文件，请增加 rclone 的超时时间：

🌐 For very large files, increase rclone's timeout:

1
rclone copy platform:your-storage-bucket self-hosted:your-storage-bucket --timeout 30m

平台上的空列表 #

🌐 Empty listing on platform

如果 rclone lsd platform: 没有返回任何内容，请确认端点 URL 以 /storage/v1/s3 结尾，并且 S3 访问密钥没有过期。如有需要，可以从仪表板重新生成。

🌐 If rclone lsd platform: returns nothing, verify the endpoint URL ends with /storage/v1/s3 and that the S3 access keys have not expired. Regenerate them from the dashboard if needed.