更新你自托管的部署

一个辅助脚本（update.sh）会在你现有的部署基础上拉取自托管 Supabase 配置的更新版本。它使用三向合并，所以你的秘密信息、覆盖设置和本地修改都会保留，同时会显示合并冲突。

🌐 A supplemental script (update.sh) pulls a newer version of the self-hosted Supabase configuration on top of your existing deployment. It uses a three-way merge, so your secrets, overrides, and local edits survive, while merge conflicts are surfaced.

这是保持自托管部署与上游版本同步的支持方式。每次运行都是增量的并且有步骤限制：它会保留你的 .env 和数据，备份配置，并在应用任何更改前停下来提示破坏性变更。新安装会自动进行版本跟踪。它不是一种从任意状态一键升级的方式——要更新一个较老且未跟踪的部署，需要手动操作（见下文）。

🌐 It is the supported way to keep a self-hosted deployment current with upstream releases. Each run is incremental and gated: it preserves your .env and data, backs up your configuration, and stops to flag breaking changes before applying anything. New installs are version-tracked automatically. It is not a one-click upgrade from an arbitrary state - catching up an older, untracked deployment requires manual intervention (read below).

如果你对 git 操作熟悉，并且保留了仓库的克隆，你也可以使用 git 自己的工具来合并上游的更改，而不是用 update.sh —— 这是同样三方合并的一个更动手的版本。

🌐 If you are comfortable with git and keep a clone of the repository, you can also bring upstream changes in with git's own tools instead of update.sh - a more hands-on version of the same three-way merge.

它是怎么运作的 #

🌐 How it works

update.sh 比较了每个供应商文件的三个版本：

• 基础 - 你当前部署所在的版本，记录在 .supabase-version 中（由 setup.sh 编写，每次成功更新后会推进到新版本）
• new - 你正在更新到的版本（默认是最新的 self-hosted/v* 标签）
• 你的——你部署目录里的文件

它会将基础版本和新版本之间的更改应用到你的文件上。如果你从未编辑过某个文件，它会干净地更新。你编辑过的文件，只要版本发布没有修改同样的行，你的修改就会保留下来。只有当两者都修改了同一行时，才会出现需要解决的冲突。

🌐 It applies the changes between base and new to your files. Where you never edited a file, it updates cleanly. Where you edited a file but the release did not touch the same lines, your edit is kept. Only when both changed the same lines do you have a conflict to resolve.

你的秘密和数据永远不会被合并。你在 .env 文件中设置的值会被保留，来自 .env.example 的新密钥会被添加。.gitignore 中列出的路径保持不变。

🌐 Your secrets and data are never merged. The values in the .env file you set are kept and the new keys from .env.example are appended. Paths listed in .gitignore are left untouched.

在你开始之前 #

🌐 Before you start

• 从你的部署目录运行（docker-compose.yml 和 .env 所在的地方）。
• update.sh 在主机上需要 git 和 jq。
• 使用 setup.sh 创建的部署会在 .supabase-version 中记录它们的版本，而 update.sh 会在每次成功更新后推进它。如果该文件丢失，请参阅 设置已记录的版本。

如果你的部署早于 update.sh——从 v0.7.1 开始，它会自带自托管配置——先把它下载到你的部署目录里。你只需要做一次；之后的更新会帮你保持脚本最新。

🌐 If your deployment predates update.sh - it ships with the self-hosted configuration from v0.7.1 onward - download it into your deployment directory first. You only need to do this once; later updates keep the script current for you.

1
curl -fsSL https://raw.githubusercontent.com/supabase/supabase/master/docker/update.sh -o update.sh

如何更新 #

🌐 How to update

预览可能会改变的内容，不会影响任何东西：

🌐 Preview what would change, without affecting anything:

1
sh update.sh --dry-run

一个有意义的预览需要一个已录制的基础版本。在没有 .supabase-version（也没有 --from）的部署上，--dry-run 会回退到和普通运行一样的有限仅报告输出。它只能列出全新的文件，而不能显示会发生什么变化或冲突。

🌐 A meaningful preview needs a recorded base version. --dry-run on a deployment with no .supabase-version (and no --from) falls back to the same limited report-only output as a plain run. It can only list brand-new files, not what would change or conflict.

应用更新——它针对最新的 self-hosted/v* 版本：

🌐 Apply the update - it targets the latest self-hosted/v* release:

1
sh update.sh

检查一下 update.sh 的输出——特别是任何冲突、新的 .env 键以及重大更改通知。

🌐 Review the output from update.sh - especially any conflicts, new .env keys, and breaking-change notices.

然后拉取新镜像并重新创建容器：

🌐 Then pull the new images and recreate the containers:

1
sh run.sh pull
2
sh run.sh recreate

它改变了什么 #

🌐 What it changes

更新于：

🌐 Updated:

• docker-compose.yml，覆盖模板，volumes/*，脚本，.env.example
• volumes/functions/main/index.ts

不包括：

🌐 Excluded:

• 当前 .env 配置
• .gitignore 中的路径：数据目录、片段、你的边缘函数

重大变更 #

🌐 Breaking changes

有些版本发布在应用其文件之前需要手动操作——例如，Postgres 的一次重大升级。update.sh 会从发布清单中读取这些信息，并在更改任何文件之前打印出所需步骤并要求你确认。如果你还没准备好，可以拒绝提示——此时还没有任何修改。

🌐 Some releases need a manual step before their files can be applied - for example, a Postgres major upgrade. update.sh reads these from the release manifest and, before changing any files, prints the required steps and asks you to confirm. If you are not ready, decline the prompt - nothing has been modified yet.

完成列出的步骤，然后重新运行 sh update.sh。

🌐 Complete the listed steps, then re-run sh update.sh.

解决冲突 #

🌐 Resolving conflicts

如果摘要列出了冲突，update.sh 会在这些文件中写入标准合并标记，并以状态 2 退出。打开每个文件，选择正确的内容，然后删除 <<<<<<<、======= 和 >>>>>>> 标记：

🌐 If the summary lists conflicts, update.sh writes standard merge markers into those files and exits with status 2. Open each file, pick the correct content, and remove the <<<<<<<, =======, and >>>>>>> markers:

1
<<<<<<< yours (docker-compose.yml)
2
      image: supabase/studio:your-pinned-tag
3
=======
4
      image: supabase/studio:new-tag
5
>>>>>>> new (self-hosted/v0.7.0)

继续编辑那些你想保留自己修改的文件。如果一个文件有很多冲突，而且你的修改不值得保留——用目标版本的文件覆盖它通常更简单。例如：

🌐 Keep editing the files where you want to preserve your own changes. When a file contains many conflicts and you have no edits worth keeping - overwriting it with the file from the target release is often easier. For example:

1
curl -fsSL https://raw.githubusercontent.com/supabase/supabase/self-hosted/v0.7.0/docker/run.sh > run.sh

或者，如果你在 ./supabase 保留了一个克隆：

🌐 Alternatively, if you kept a clone in ./supabase:

1
git -C ./supabase show self-hosted/v0.7.0:docker/run.sh > run.sh

然后启动堆栈：

🌐 Then start the stack:

1
sh run.sh pull
2
sh run.sh recreate

冲突意味着你编辑了一个 自托管 Supabase 配置 文件，而发布版本也修改了同样的行。

🌐 A conflict means you edited a self-hosted Supabase configuration file and the release changed the same lines.

虽然还有冲突，update.sh 不会推进 .supabase-version——它只会在干净运行时记录新版本。在你解决标记后，重新运行 sh update.sh 来最终确定版本标记。

🌐 While conflicts remain, update.sh does not advance .supabase-version - it records the new release only on a clean run. After you resolve the markers, re-run sh update.sh to finalize the version stamp.

更新到特定版本 #

🌐 Update to a specific release

1
sh update.sh --to self-hosted/v0.7.0

查看更新日志了解可用的版本。

🌐 Check the changelog for available releases.

设置录制版本 #

🌐 Setting a recorded version

没有 .supabase-version，update.sh 无法安全合并，只能以有限的报告模式运行。只有完全新的文件和 .env 密钥才能被列出。不过，因为完整比较需要一个基础，所以无法检测哪些已有文件会发生变化或有冲突。先记录一次你的文件来源版本，然后再重新运行。

🌐 Without .supabase-version, update.sh cannot merge safely and runs in a limited report mode. Only files and .env keys that are entirely new to you can be listed. However, because the full comparison needs a base, it is not possible to detect which existing files would change or have conflicts. Record the version your files came from once, then re-run.

尽量使用你的 ./docker 文件来源的确切提交。这会带来最干净的合并，并且只有在你编辑了发布也改过的文件时才会出现冲突。使用完整的 40 位提交 SHA：update.sh 从 GitHub 获取基础。

🌐 Prefer the exact commit your ./docker files came from. It gives the cleanest merge and conflicts only where you edited a file that the release also changed. Use the full 40-character commit SHA: update.sh fetches the base from GitHub.

要找到它，先克隆仓库，找到日期与你的文件匹配的提交，然后将其展开为完整的 SHA:

🌐 To find it, clone the repository, find the commit whose date matches your files, and expand it to a full SHA:

1
git clone --filter=blob:none https://github.com/supabase/supabase
2
cd supabase
3
4
# Browse docker/ history, newest first, as "date short-hash subject":
5
git log --date=short --format='%ad %h %s' -- docker
6
7
# Expand the short hash you picked into the full SHA update.sh needs:
8
git rev-parse <short-hash>

在部署目录中记录它（或者用 --from 传一次）:

🌐 In the deployment directory, record it (or pass it once with --from):

1
printf 'ref=<full-40-char-sha>\n' > .supabase-version

正确的提交并不总是你第一次部署那天的提交。如果你之后刷新过任何文件，选择最接近你最新 docker/ 文件的提交。比你文件还旧的基准会把所有更新的内容都变成冲突（参考 从一个旧的、未跟踪的安装开始）。

🌐 The right commit is not always the one from the day you first deployed. If you have refreshed any files since, choose the commit closest to your newest docker/ files. A base older than your files turns everything newer into a conflict (refer to Coming from an old, untracked install).

如果找不到提交，就使用最接近的发布标签——在 docker-compose.yml / .env 中对比镜像标签和 versions.md。这只是一个大概的参考，所以根据你的文件偏离程度，可能会出现冲突：

🌐 If you cannot find the commit, use the closest release tag instead - compare the image tags in docker-compose.yml / .env against versions.md. This is an approximation, so expect conflicts proportional to how far your files have drifted:

1
printf 'ref=self-hosted/v0.7.0\n' > .supabase-version

来自一个旧的、未跟踪的安装 #

🌐 Coming from an old, untracked install

长期运行的部署通常是随着时间从几个上游点组合而成的，而不是固定在某个提交上。例如，一个月前复制的新 docker-compose.yml，或者后来手动添加的 run.sh。三方合并（这个工具或者 git 本身）假设有一个共同的祖级，所以没有哪个基准能匹配所有文件，而且比你选择的基准更新的文件会显示为冲突。冲突的数量大致与部署的时间长度成正比。这很正常，这第一次的补齐只是一次性的成本：成功后，版本就被记录下来了，以后的每次更新都会是干净、受控的合并。

🌐 Long-running deployments are usually assembled from several upstream points over time, rather than frozen at one commit. For instance, a newer docker-compose.yml copied in a month ago, or run.sh added manually later. A three-way merge (this tool, or git itself) assumes a single common ancestor, so no base will match every file, and files newer than your chosen base show up as conflicts. Expect conflicts roughly proportional to the deployment's age. This is normal, and this first catch-up is a one-time cost: after it succeeds, the version is recorded and every future update is a clean, gated merge.

1. 运行 sh update.sh 一次。如果没有记录的版本，它会保持在仅报告模式，列出新文件和 .env 密钥而不做任何更改。
2. 记录你的基准（在 设置已记录版本 中了解更多）——就是最接近你最新文件的提交，或者最近的发布标签。
3. 预览。运行 sh update.sh --dry-run 并检查冲突数量。如果冲突多，尝试使用更新的基线——基线太旧会把从那之后添加的每个文件都变成冲突。
4. 单独备份你的数据库——update.sh 只备份配置。
5. 应用更新，然后解决冲突。大多数冲突都会出现在你原本不打算管理的“供应商文件”中——run.sh、setup.sh、tests/*，即覆盖模板。对于这些文件，直接复制新版本即可。需要手动编辑的冲突通常出现在你刻意修改过的 compose 配置中。你的 .env 从来不会有冲突——update.sh 会添加新键，你可以单独查看。这个工具会展示所有问题供你处理。详情请参考 解决冲突。
6. 处理 Postgres。Postgres 17 在 v0.6.0 中成为默认版本。如果你仍然在用 Postgres 15，不要直接升级到 17——请按照 升级到 Postgres 17 操作，或者使用 docker-compose.pg15.yml 覆盖来固定 Postgres 15。查看 更新日志 了解你跨版本时的破坏性变更。
7. 先运行 sh run.sh pull，然后运行 sh run.sh recreate。

从备份恢复 #

🌐 Restore from backup

每次更新前，配置备份都会写入 backups/pre-update-*.tgz。如果出了问题，可以从那个存档里提取或对比。

🌐 Configuration backups are written to backups/pre-update-*.tgz before each update. If something goes wrong, extract or compare against that archive.

命令行选项 #

🌐 Command-line options