了解 API 密钥

Supabase 让你可以通过 API 密钥对哪些应用组件可以访问你的项目进行精细控制。

🌐 Supabase gives you fine-grained control over which application components are allowed to access your project through API keys.

API 密钥提供了数据访问的第一层身份验证。身份验证就在此基础上构建。这个图表展示了它们的区别：

🌐 API keys provide the first layer of authentication for data access. Auth then builds upon that. This chart covers the differences:

概览 #

🌐 Overview

API 密钥用于验证应用组件，从而让它能够访问 Supabase 服务。应用组件可以是网页、移动应用或服务器。API 密钥 不会 区分用户，只会区分应用。

🌐 An API key authenticates an application component to give it access to Supabase services. An application component might be a web page, a mobile app, or a server. The API key does not distinguish between users, only between applications.

在 Supabase 中，你可以使用 4 种类型的 API 密钥：

🌐 There are 4 types of API keys that you can use with Supabase:

可发布的密钥 #

🌐 Publishable keys

可发布的密钥用于识别你应用的公共部分。公共部分运行在无法保护任何秘密的环境中。这些包括：

🌐 Publishable keys identify the public components of your application. Public components run in environments where it is impossible to secure any secrets. These include:

• 网页，密钥被打包在源代码里。
• 移动端或桌面应用，其中密钥被打包在已编译的包或可执行文件中。
• 命令行接口、脚本、工具或其他预先构建的可执行文件。
• 其他公开可用的 API，可以在没有额外授权的情况下返回密钥。

这些环境总是被认为是公开的，因为任何人都可以从源代码或构建产物中获取密钥。

🌐 These environments are always considered public because anyone can retrieve the key from the source code or build artifacts.

与 Supabase Auth 的互动 #

🌐 Interaction with Supabase Auth

使用可发布的密钥并不意味着你的用户是匿名的。你可以用可发布的密钥验证你的应用，而你的用户则通过个人 JWT（通过 Supabase Auth）进行身份验证：

🌐 Using a publishable key does not mean that your user is anonymous. You can authenticate your application with the publishable key, while your user is authenticated (via Supabase Auth) with their personal JWT:

安全注意事项 #

🌐 Security considerations

可发布的密钥并不是为了防止以下情况，因为从公共组件中总是可以获取密钥：

🌐 Publishable keys are not intended to protect from the following, since key retrieval is always possible from a public component:

• 静态或动态代码分析以及逆向工程尝试。
• 在浏览器中使用网络检查器。
• 跨站请求伪造、跨站脚本攻击、网络钓鱼攻击。
• 中间人攻击

使用可发布密钥时，你的项目数据的访问会通过 Postgres 内置的 anon 和 authenticated 角色进行保护。为了确保完全保护，请确认：

🌐 When using a publishable key, access to your project's data is guarded by Postgres via the built-in anon and authenticated roles. For full protection make sure:

• 你已经在所有表上启用了行级安全。
• 你会定期检查分行级别安全策略，对 anon 和 authenticated 角色授予的权限进行审查。
• 在不了解你正在做的更改的情况下，你不要修改角色的属性。

你们项目的安全顾问会不断检查内置 Postgres 角色的常见安全问题。确保在忽略任何发现之前仔细查看每一项内容。

🌐 Your project's Security Advisor constantly checks for common security problems with the built-in Postgres roles. Make sure you carefully review each finding before dismissing it.

哪些秘密钥匙可以访问 #

🌐 What secret keys allow access to

与可发布密钥不同，秘密密钥允许对你的项目数据进行更高级的访问。它只应在安全的、开发者控制的应用组件中使用，例如：

🌐 Unlike publishable keys, secret keys allow elevated access to your project's data. It is meant to be used only in secure, developer-controlled components of your application, such as:

• 自己实现事先授权的服务器，比如 Edge Functions、微服务、传统或专用的网络服务器。
• 周期性任务、队列处理器、主题订阅者。
• 管理和后台工具，仅限事先授权检查。
• 数据处理流程，比如用于分析、报表、备份或数据库同步。

密钥可以通过内置的 service_role Postgres 角色授权访问你项目的数据。按照设计，这个角色对你项目的数据拥有完全访问权限。它还使用 BYPASSRLS 属性，会跳过你设置的所有行级安全策略。

🌐 Secret keys authorize access to your project's data via the built-in service_role Postgres role. By design, this role has full access to your project's data. It also uses the BYPASSRLS attribute, skipping any and all Row Level Security policies you attach.

这个密钥是对旧的基于 JWT 的 service_role 密钥的改进，我们建议在可能的情况下使用它。它增加了更多的检查以防止误用，具体包括：

🌐 The secret key is an improvement over the old JWT-based service_role key, and we recommend using it where possible. It adds more checks to prevent misuse, specifically:

• 你不能在浏览器里使用密钥（匹配 User-Agent 头），而且它总会返回 HTTP 401 未授权。
• 如果你不使用它们，就不需要任何密钥。

处理密钥的最佳做法 #

🌐 Best practices for handling secret keys

下面是一些关于如何安全使用密钥的初步指南：

🌐 Below are some starting guidelines on how to securely work with secret keys:

• 总是只在你完全拥有或控制的电脑上使用密钥。
• 使用安全且加密的发送工具与他人共享 API 密钥（通常由好的密码管理器提供），但最好还是使用仪表板中的 设置 > API 密钥 部分。
• 最好在存储到文件或环境变量时加密它们。
• 不要把它加到源代码管理里，特别是 CI 脚本和工具。最好用工具自带的秘密管理功能。
• 最好为你应用的每个后端组件使用单独的密钥，这样如果某个组件被发现有漏洞或者密钥泄露，你只需要更换它，而不必更换所有的密钥。
• 即使在浏览器中使用时，秘密密钥总是会返回 HTTP 401 未授权错误，这并不意味着攻击者不会使用其他工具来利用它。立即删除！
• 如果你必须在日志中包含它们，就只记录前几个随机字符（但不要超过6个）。
• 如果你想记录或存储使用了哪个有效的 API 密钥，就把它存成 SHA256 哈希。

如果秘密密钥或 service_role#

🌐 What to do if a secret key or service_role has been leaked or compromised?

如果这种情况已经发生，或者你怀疑发生了，不要着急。先确保你已经完全考虑了情况，并且已经解决了引起怀疑或漏洞的根本原因。可以考虑使用 OWASP 风险评估方法 作为一种简单的方式来确定事件的严重性，并规划下一步的行动。

🌐 Don't rush if this has happened, or you are suspecting it has. Make sure you have fully considered the situation and have remediated the root cause of the suspicion or vulnerability first. Consider using the OWASP Risk Rating Methodology as an easy way to identify the severity of the incident and to plan your next steps.

要轮换一个秘密密钥（sb_secret_...），请在仪表板的 设置 > API 密钥 部分创建一个新的秘密 API 密钥，然后用它替换被泄露的密钥。一旦所有组件都使用了新密钥，就删除被泄露的密钥。

🌐 To rotate a secret key (sb_secret_...), use the Settings > API Keys section of the Dashboard to create a new secret API key, then replace it with the compromised key. Once all components are using the new key, delete the compromised one.

删除密钥是不可逆的，一旦删除将永久丢失。

如果你还在使用基于 JWT 的 service_role 密钥，那就用一个新的密钥替换掉 service_role。按照上面的指南操作，就像你在更换现有密钥一样。

🌐 If you are still using the JWT-based service_role key, replace the service_role key with a new secret key instead. Follow the guide from above as if you are rotating an existing secret key.

已知的限制和兼容性差异 #

🌐 Known limitations and compatibility differences

由于可发布和私密密钥不再基于 JWT，所以你可能需要考虑一些已知的限制和兼容性差异：

🌐 As the publishable and secret keys are no longer JWT-based, there are some known limitations and compatibility differences that you may need to plan for:

• 你不能在 Authorization: Bearer ... 头中发送可发布或私密密钥，除非其值正好等于 apikey 头。这种情况下，你的请求会被转发到你项目的数据库，但会被拒绝，因为该值不是 JWT。
• Edge Functions 只支持通过 anon 和 service_role 基于 JWT 的 API 密钥进行 JWT 验证。使用可发布和密钥时，你需要使用 --no-verify-jwt 选项。Supabase 平台在以这种方式使用 Edge Functions 时不会验证 apikey 头。你需要在 Edge Function 代码内部实现自己的 apikey 头授权逻辑。
• 公共实时连接的时长限制为 24 小时，除非通过 Supabase Auth 或支持的第三方认证提供商升级连接并进行用户级认证后才能继续维护。