planetscale-postgres-safety-review

Postgres 安全审查

目的

为 PlanetScale Postgres 数据库推荐最佳实践。重点关注可用性保护、应用隔离、恢复、安全自动化和可观测性。不要应用任何更改。

分支和架构工作流

PlanetScale Postgres 分支不使用 Vitess 风格的部署请求。架构更改会直接应用到各个分支，生产环境的架构更改应通过应用的常规迁移工作流管理，并包含分支验证步骤。

检查：

• 是否存在开发或测试分支。
• 分支是否为空，或是否从备份恢复而来。
• 迁移是否在发布到生产环境前通过分支进行测试。
• 应用迁移是否可逆，或是否有记录在案的回滚策略。
• 生产环境的 DDL 是否经过人工审查。

建议：

• 创建或使用非生产分支测试迁移。
• 针对该分支运行迁移验证和应用测试。
• 将在生产环境应用迁移视为需要人工明确批准的部署步骤。
• 使用 PITR/备份恢复分支进行故障恢复，而不是将其用作自动回滚机制。

未经批准，不要创建分支、运行迁移或恢复备份。

角色和最小权限

检查应用是否使用默认角色连接。若是，将其标记为安全缺口。

建议：

• 应用服务器应使用用户自定义的应用角色，而非默认角色。
• 按服务、环境和访问模式拆分角色。
• 为分析、仪表板、报告以及不需要写入权限的 Agent 使用只读角色。
• 为自动化使用短期有效或用途受限的角色。
• 如果 Terraform 管理 PlanetScale Postgres 角色，对于密码不应存储在 Terraform 状态中的角色，优先使用 planetscale_postgres_redacted_branch_role；通过 API 或控制面板重置密码， 并将其存储在团队的密钥管理器中。
• 记录如何在不中断应用运行的情况下轮换凭据。

未经批准，不要创建、重置、删除或轮换角色。

pg_strict

检查应用角色是否启用了 pg_strict。

建议在工作负载能够承受阻止不带 WHERE 的危险 UPDATE 或 DELETE 操作时，为生产应用角色启用 pg_strict。

建议的推出步骤：

1. 在可能的情况下，启用警告模式或在非生产环境中进行评估。
2. 修复可能被阻止的查询。
3. 为应用角色启用严格阻止模式。
4. 记录获批的一次性覆盖流程。

未经批准，不要启用 pg_strict，因为在建立新连接后，它可能会阻止应用查询。

Query Insights 和 pginsights

检查：

• 慢查询。
• 读取行数较高的查询。
• CPU 使用率较高的查询模式（在 Insights API 上使用 sort=cpuTime 或 sort=percentCpuTime）。
• 高频查询。
• 出错的查询。
• 活跃异常。
• 查询标签。
• 是否启用了字面量/原始查询收集。

原始查询收集由 pginsights.raw_queries 集群参数控制，可在控制面板的 Extensions 标签页中按分支配置。数据库 API 对象也包含 insights_raw_queries 字段；两者不一致时，以集群参数作为实际生效的收集状态。仅报告实际生效的状态——切勿将这两个界面描述为相互矛盾或不一致。

建议：

• 将原始查询收集视为一项能力，详见 ../planetscale-query-insights-and-tags/SKILL.md：当模式级数据无法定位异常调用时，原始查询收集是可用于定位的机制。如果客户的数据处理要求对此有限制，可以选择在限定范围内启用（例如事故处理时段、明确的保留期限），也可以保持收集关闭；请记录选择该方案的原因。
• 使用标签进行归因，使用原始查询收集深入分析具体调用；两者互为补充。
• 使用部署 SHA 和路由/作业标签，将回归问题与应用部署关联起来。

查询标签

评估 SQL 注释是否包含结构化的 SQLCommenter 标签。

建议使用同时支持 Insights 和 Traffic Control 的标签：

• application
• service
• route，使用规范化的路由模板，而不是具体 URL
• 适用时使用 controller 和 action
• 后台工作线程使用 job 或 queue
• 对于导出或报告等高开销功能，使用 feature
• environment
• release_sha
• 仅当基数有上限时使用 tenant_tier
• 对于 Agent、脚本、BI 工具、集成和 MCP，使用 source

避免使用高基数或敏感标签：

• 用户 ID
• 请求 ID
• 电子邮件
• 会话 ID
• 租户 ID，除非其范围有明确限制且已获认可
• 包含标识符的原始 URL 路径
• 访问令牌、密钥或 API 密钥

数据库流量控制

对于 Postgres，如果数据库存在以下任一情况，建议使用 Traffic Control：

• 面向公众或由客户触发的高开销功能。
• 导出、报告、分析或临时搜索与 OLTP 数据库共用资源。
• 可能挤占交互式流量的后台作业。
• 查询量难以预测的第三方集成。
• 由 Agent 生成的查询。
• 已知偶尔会失控的查询指纹。
• 需要限制数据库资源用量的租户或路由类别。

默认建议：

• 先以 warn 模式启动预算。
• 尽可能使用查询标签。
• 对已知问题查询使用特定指纹规则。
• 观察警告并确认没有阻断关键流量后，再启用 enforce 模式。
• 制定紧急禁用流程。

未经批准，不要创建预算或强制执行规则。

备份和 PITR

检查：

• 自动备份计划。
• 保留期限。
• WAL/PITR 是否可用。
• 是否存在阻止删除的手动备份。
• 恢复演练历史。
• 恢复运行手册。

建议：

• 确认默认备份满足客户的 RPO/RTO。
• 如果客户的恢复窗口超过默认值，则延长保留期限或增加备份计划。
• 如果 Terraform 是客户的事实来源，应在 Terraform 中管理备份策略，以便在审查其他基础设施代码时一并审查 保留期限和计划的变更。
• 在新分支上进行恢复演练。
• 记录恢复后应用程序切换的具体流程。

未经批准，不要执行恢复或创建紧急备份。紧急备份可能影响性能，应视为运维操作。

连接、连接池和网络安全

检查：

• 应用使用的是直连端口 5432，还是 PgBouncer 端口 6432。
• 连接池大小是否与运行时环境和部署模式匹配。
• 无服务器或边缘环境是否可能导致连接风暴。
• 通过 pscale branch connections top 查看实时连接/会话压力；诊断活动事件时，包括阻塞连接和事务中空闲的会话。
• 是否已配置私有连接。
• 是否已配置 IP 限制。
• 是否仍存在意外开放的公共访问。

建议：

• 如果事务池化的限制可以接受，则高频变动的应用连接应使用 PgBouncer。
• 对于依赖会话且 PgBouncer 事务模式无法支持的功能，应使用直连。
• 对于私有网络需求，使用 AWS PrivateLink 或 GCP Private Service Connect。
• 使用 IP 限制来减少公共暴露。
• 明确说明：私有连接不会自动阻止公共访问；若要实现仅限私有访问，还需要 IP 限制或等效控制措施。

未经批准，不要更改网络限制。网络变更可能导致应用程序连接中断。

扩展

检查与安全性和可观测性相关的已启用和可用扩展：

• pginsights
• pg_strict
• pg_stat_statements
• auto_explain
• pg_squeeze
• pg_cron
• pg_partman_bgw
• pg_hint_plan
• 如果与时序功能相关，则包括 TimescaleDB

只有在用例明确时才推荐扩展。PlanetScale Postgres 提供 auto_explain，配置 auto_explain.log_min_duration 等参数后，可记录慢查询的执行计划；如果捕获慢查询计划能显著改善诊断，且日志量可以接受，则推荐使用。当 Terraform 是客户的事实来源时，可在其中管理 Postgres 分支参数和受支持的扩展，但参数或扩展变更仍需经过与控制面板变更相同的审批和重启影响审查。某些扩展的启用方式需要更改控制面板设置并重启数据库；未经批准不得启用。

Postgres Webhook 建议

评估并推荐以下 Webhook：

• branch.anomaly
• branch.out_of_memory
• branch.primary_promoted
• branch.ready
• branch.start_maintenance
• cluster.storage
• database.access_request
• 如果可用，则包括 branch.schema_recommendation
• 用于验证设置的 webhook.test

推荐的自动化行为：

• 告警：异常、内存不足、主实例提升、存储、维护。
• Agent 接收：异常、架构建议。
• 人工审批：任何生成的 Traffic Control、架构、角色或网络变更。

输出

返回：

• 当前 Postgres 安全状况。
• 风险最高的可用性缺口。
• 推荐的 Traffic Control 计划。
• 推荐的角色和 pg_strict 计划。
• 推荐的备份/PITR 计划。
• 推荐的网络状况计划。
• 推荐的查询标记计划。
• 需要审批的拟议变更。

结尾写上：

“No Postgres changes have been applied.”