## 简介 supabase_vault 是一个 PostgreSQL 扩展插件，用于在数据库内部安全地存储和管理敏感字符串（例如 API Key、访问令牌等）。插件通过将加密后的密文持久化保存到 `vault.secrets` 表中，并在查询时通过 `vault.decrypted_secrets` 视图按需即时解密返回明文，从而实现： * **静态数据加密**：磁盘文件、备份及复制流中仅存储密文； * **受控运行时访问**：仅在被授权的查询中动态解密并返回明文； * **最小暴露面**：业务方无需直接接触加密实现细节即可安全使用敏感信息。 ## 前提条件在使用 supabase_vault 插件前，需要先将其加入 PostgreSQL 配置参数 `shared_preload_libraries` 中。更新该参数后，必须重启 PostgreSQL 实例配置方可生效。 ## 创建与删除插件 ### 创建插件 ```SQL CREATE EXTENSION supabase_vault; ``` ### 删除插件 ```SQL DROP EXTENSION supabase_vault; ``` ## 基础使用 ### **创建 Secret** 使用 `vault.create_secret()` 函数创建新的密钥。该函数会将密文写入 `vault.secrets` 表，并返回新建密钥的通用唯一标识符（UUID）。 ```SQL SELECT vault.create_secret('secret'); create_secret -------------------------------------- 0957e0d7-081e-400e-833f-922526e14df2 (1 row) ``` 创建时可附加可选的唯一名称和描述信息，便于后续识别与管理。 ```SQL SELECT vault.create_secret( 'sk_live_abcdefghijklmnopqrstuvwxyz', 'stripe_production_key', '用于生产环境的 Stripe API Key' ); create_secret -------------------------------------- 5ced3759-473d-48e0-b109-4f1d13124dd3 (1 row) ``` 其中： * 第一个参数为实际要保存的敏感字符串； * 第二个参数为密钥的唯一名称（`name`）； * 第三个参数为便于理解用途的描述信息（`description`）。 ### 查询 Secret 解密访问密钥时，可通过 `vault.decrypted_secrets` 视图查询。该视图在查询阶段对密文进行即时解密，并通过 `decrypted_secret` 列返回明文： ```SQL -- 根据名称查询特定的 secret SELECT id, name, decrypted_secret,created_at FROM vault.decrypted_secrets WHERE name = 'stripe_production_key'; id | name | decrypted_secret | created_at --------------------------------------+-----------------------+------------------------------------+------------------------------- 5ced3759-473d-48e0-b109-4f1d13124dd3 | stripe_production_key | sk_live_abcdefghijklmnopqrstuvwxyz | 2025-12-24 01:12:40.382076+08 (1 row) ``` 在上述查询中： * `decrypted_secret` 列返回密钥明文； * `vault.secrets` 表中的 `secret` 列始终以密文形式存储，不会在视图中直接暴露。建议在应用层对 `vault.decrypted_secrets` 的访问进行严格的权限控制，仅授予确实需要读取明文密钥的角色或服务账号。 ### 更新 Secret 使用 `vault.update_secret(secret_id, new_secret, new_name, new_description)` 函数更新现有密钥。 ```SQL SELECT vault.update_secret( '5ced3759-473d-48e0-b109-4f1d13124dd3', new_secret := 'sk_live_new_updated_secret_key', new_name := 'stripe_prod_key_rotated', new_description := '已轮替的 Stripe 生产环境 API Key' ); ``` 参数说明： * `secret_id`：待更新密钥的 UUID； * `new_secret`：新的密钥值； * `new_name`：新的名称； * `new_description`：新的描述信息。除 `secret_id` 外，其余参数均为可选，仅在提供时才会更新对应字段。未显式传入的字段将保持不变。更新完成后，可通过查询 `vault.decrypted_secrets` 视图验证变更是否生效。 ```SQL SELECT name, description, decrypted_secret FROM vault.decrypted_secrets WHERE id = '5ced3759-473d-48e0-b109-4f1d13124dd3'; name | description | decrypted_secret -------------------------+----------------------------------+-------------------------------- stripe_prod_key_rotated | 已轮替的 Stripe 生产环境 API Key | sk_live_new_updated_secret_key (1 row) ``` ### 删除 Secret supabase_vault 未提供专用的删除函数。如需删除不再使用的密钥，可对 `vault.secrets` 表执行标准 `DELETE` 操作。 ```SQL DELETE FROM vault.secrets WHERE id = '5ced3759-473d-48e0-b109-4f1d13124dd3'; ``` :::warning * 删除操作**不可逆**。一旦从 vault.secrets 表中移除，对应的加密信息将永久丢失、无法恢复。 * 删除前应确认该密钥不再被任何应用、服务或定时任务引用，以避免引发生产故障； * 建议结合审计记录或变更流程，对密钥删除操作进行必要的审批与留痕。 :::

AI 原生 BaaS 平台 Supabase 版