新的 API 密钥和非对称认证

你可以配置自托管的 Supabase，同时使用 可发布和私密的 API 密钥 以及传统的 API 密钥（ANON_KEY 和 SERVICE_ROLE_KEY HS256 签名的 JWT）。

🌐 You can configure self-hosted Supabase to use the publishable and secret API keys alongside the legacy API keys (ANON_KEY and SERVICE_ROLE_KEY HS256-signed JWTs).

在你开始之前 #

🌐 Before you begin

• 完成 Docker 设置指南，确保在你的 .env 文件中设置了 JWT_SECRET、ANON_KEY 和 SERVICE_ROLE_KEY。快速开始（Linux） 会自动处理这些；手动操作则运行 generate-keys.sh。
• 如果你正在从传统的自托管 Supabase 环境升级，记得查看 更新日志 并 添加/更新 以下文件：
  • .env.example（将新部分合并到你的 .env 文件中）
  • docker-compose.yml
  • utils/add-new-auth-keys.sh
  • utils/rotate-new-api-keys.sh
  • volumes/api/envoy/*

添加新密钥 #

🌐 Adding the new keys

在你的项目目录里，你有 docker-compose.yml：

🌐 From your project directory where you have docker-compose.yml:

1
sh utils/add-new-auth-keys.sh --update-env

这会生成新的配置环境变量并将它们写入 .env。省略 --update-env 可以以交互方式查看并确认更改。

🌐 This generates new configuration environment variables and writes them to .env. Omit --update-env to review and confirm the changes interactively.

此外，为了让新的身份验证正常工作，脚本会自动取消注释以下配置：

🌐 In addition, the following configuration is uncommented automatically by the script for the new authentication to work correctly:

1
auth:
2
  environment:
3
    # JSON array of signing JWKs (EC private + legacy symmetric)
4
    GOTRUE_JWT_KEYS: ${JWT_KEYS:-[]}
5
6
rest:
7
  environment:
8
    # PostgREST accepts a plain-text symmetric secret, a single JWK, or a JWKS.
9
    PGRST_JWT_SECRET: ${JWT_JWKS:-${JWT_SECRET}}
10
11
realtime:
12
  environment:
13
    # JWKS for token verification (EC public + legacy symmetric)
14
    API_JWT_JWKS: ${JWT_JWKS:-{"keys":[]}}
15
16
storage:
17
  environment:
18
    # JWKS for token verification (EC public + legacy symmetric)
19
    JWT_JWKS: ${JWT_JWKS:-{"keys":[]}}
20
21
functions:
22
  environment:
23
    # JWKS for token verification (EC public + legacy symmetric).
24
    SUPABASE_JWKS: ${JWT_JWKS:-{"keys":[]}}

重启所有服务：

🌐 Restart all services:

1
sh run.sh recreate

新的 API 密钥格式 #

🌐 New API keys format

这些密钥使用与 Supabase 平台上的 API 密钥 相同的格式：

🌐 These keys use the same format as API keys on the Supabase platform:

1
sb_publishable_<22-char-random>_<8-char-checksum>
2
sb_secret_<22-char-random>_<8-char-checksum>

正在检查设置 #

🌐 Verifying the setup

使用新的密钥测试：

🌐 Test with the new secret key:

1
curl http://<your-domain>/rest/v1/ \
2
-H "apikey: your-supabase-secret-key"

你应该会收到来自 PostgREST 的有效响应。然后确认旧版服务角色密钥仍然可用：

🌐 You should receive a valid response from PostgREST. Then verify that the legacy service role key still works:

1
curl http://<your-domain>/rest/v1/ \
2
-H "apikey: your-service-role-key"

两者都应该可以，并返回相同的结果。

🌐 Both should work and return the same result.

你也可以验证公共 JWKS 端点：

🌐 You can also verify the public JWKS endpoint:

1
curl http://<your-domain>/auth/v1/.well-known/jwks.json

这应该返回 EC 公钥（对称密钥被排除在外）。第三方服务可以使用这个接口获取公钥，并在不需要私钥的情况下验证非对称用户会话的 JWT。

🌐 This should return the EC public key (the symmetric key is excluded). Third-party services can use this endpoint to obtain the public key and verify asymmetric user session JWTs without needing the private key.

环境变量配置 #

🌐 Environment variables configuration

在 .env.example 中，新变量默认是空值。当为空时，API 网关和所有服务会以仅传统模式运行：sb_publishable 和 sb_secret 的 API 密钥未配置。

🌐 New variables default to empty values in .env.example. When empty, the API gateway and all services operate in legacy-only mode: sb_publishable and sb_secret API keys are not configured.

与 Supabase 平台的不同 #

🌐 Differences from the Supabase platform

• 每个角色一个密钥。 自托管的 Supabase 支持单个 sb_publishable 和单个 sb_secret。该平台允许每个项目创建多个 sb_ 密钥。
• 不进行校验和验证。 不透明密钥使用与平台相同的格式（sb_publishable_<random>_<checksum>），但是 API 网关不会验证校验和。API 网关会将密钥作为不透明字符串进行匹配。

向后兼容 #

🌐 Backward compatibility

新的认证配置完全向后兼容：

🌐 The new authentication configuration is fully backward compatible:

• **API网关同时接受两种密钥类型。**你可以逐步迁移客户端——有些使用老的API密钥，有些使用新的。
• JWKS 包含对称密钥。 JWT_JWKS 同时包含 EC 公钥（用于验证新的 ES256 令牌）以及旧的 JWT_SECRET 作为对称 JWK（用于验证旧的 HS256 令牌）。接收到 JWT_JWKS 的服务可以验证这两种类型的令牌。
• 不需要更改数据库。 非对称密钥系统完全在 API 网关和服务配置层运行。

轮换新的 API 密钥 #

🌐 Rotating the new API keys

如果你的新 API 密钥被泄露，或者你想定期更换它们，你可以在不动非对称密钥对的情况下重新生成 sb_publishable 和 sb_secret：

🌐 If your new API keys are compromised or you want to rotate them periodically, you can regenerate sb_publishable and sb_secret without touching the asymmetric key pair:

1
sh utils/rotate-new-api-keys.sh --update-env

更换密钥后，重启服务并用新密钥更新你的客户端应用：

🌐 After rotating, restart services and update your client applications with the new keys:

1
sh run.sh recreate

正在重新生成非对称密钥对 #

🌐 Regenerating asymmetric key pair

如果 EC 私钥被泄露或你需要重新生成所有东西：

🌐 If the EC private key is compromised or you need to regenerate everything:

1
sh utils/add-new-auth-keys.sh --update-env

这会生成一个新的 EC P-256 密钥对、新的 JWKS、新的非对称 JWT，以及新的 sb_ API 密钥。更新 .env 并重启服务后：

🌐 This generates a new EC P-256 key pair, new JWKS, new asymmetric JWTs, and new sb_ API keys. After updating .env and restarting services:

• 新用户会话令牌将使用新的EC密钥进行签名。
• 使用旧 EC 密钥签署的现有用户会话令牌将验证失败。用户需要重新登录。
• 用旧的对称密钥（JWT_SECRET）签署的现有用户会话令牌仍然可以使用，因为 JWT_SECRET 没有改变，并且仍然包括在新的 JWKS 中。

它是怎么运作的 #

🌐 How it works

通过 supabase-js 的请求，每个服务都会包含两个头信息，Edge Functions 除外：

🌐 Requests via supabase-js include two headers for every service except Edge Functions:

• apikey - API 密钥（sb_ 或旧版 JWT）
• Authorization - 未认证时，客户端 SDK 会把 API 密钥复制到这里（Bearer sb_publishable_xxx 或 Bearer eyJ...）。认证后，这里会包含由 Auth 生成的用户会话 JWT。

对于 实时 WebSocket 连接，API 密钥作为 ?apikey= 查询参数发送在升级 URL 中，而不是使用 apikey 头。

🌐 For Realtime WebSocket connections, the API key is sent as a ?apikey= query parameter in the upgrade URL instead of an apikey header.

存储 和 边缘函数 也可以接受没有 API 密钥的请求。这些服务会自己处理身份验证。

有关 API 网关如何路由和验证请求的详细信息，请参阅 Envoy API 网关指南。

🌐 For details on how the API gateway routes and authenticates requests, see the Envoy API Gateway guide.

额外资源 #

🌐 Additional resources

• API 密钥 - Supabase 平台上的 API 密钥如何工作
• 认证架构 - 认证服务如何处理身份验证和令牌签发
• JWT 签名密钥 - 关于管理 Supabase Auth 用于创建和验证 JSON Web 令牌的密钥的最佳实践
• JSON Web Token (JWT) - 如何在 Supabase 中最佳使用 JSON Web Token
• 使用 Docker 自托管 - 初始设置指南，包括旧密钥生成

在 GitHub 上：

🌐 On GitHub:

• 即将对 Supabase API 密钥进行的更改（讨论 #29260）
• Supabase 认证：非对称密钥支持（讨论 #29289）
• 自托管 Supabase：Envoy 成为默认 API 网关（讨论 #48048）