planetscale-vitess-safety-review

Vitess 安全性审查

目的

为 PlanetScale Vitess 数据库推荐最佳实践。重点关注生产安全性、可部署性、可观测性，以及对 Agent 安全的自动化。不要应用任何更改。

需要评估的主要安全功能

安全迁移

检查生产和预发布分支是否启用了安全迁移。

在以下情况下，建议启用安全迁移：

• 分支承载生产流量。
• 团队会在部署请求之外运行 DDL。
• 没有受保护分支工作流。
• 预计应用架构会频繁演进。

说明其中的权衡：安全迁移会拒绝在受保护分支上直接执行 DDL，并强制通过部署请求进行架构更改。这是一项功能，但可能影响依赖直接在生产环境执行 DDL 的团队。应将启用安全迁移视为需要审批的行为变更。

部署请求

检查：

• 是否使用部署请求进行架构更改。
• 是否要求管理员审批。
• 是否审查部署请求中的数据丢失、冲突、lint 错误、外键问题、字符集问题和分片影响。
• 团队是否使用带门控的部署来控制切换。
• 是否使用“立即部署”，以及团队是否了解这会移除带门控部署和回退的操作模式。
• 切换是否经常因长时间运行的事务而延迟。
• 是否通过 Webhook 订阅部署请求事件。

建议：

• 生产环境的架构更改必须使用部署请求。
• 如果有多名管理员，则对生产部署请求启用管理员审批。
• 在只有一名管理员的组织中，管理员审批无法阻止以该管理员身份运行的 Agent 自行审批： 发起部署请求的管理员也可以审批该请求。如果目的是阻止 Agent 自行审批，请为 Agent 分配单独的用户，或使用不具备部署请求审批权限的服务令牌。
• 除非已知迁移可以安全地立即完成，且回滚方案可接受，否则优先采用常规安全部署，而非立即部署。
• 如果切换时机很重要，请使用带门控的部署。
• 将“立即强制切换”视为由操作员控制的延迟切换操作：它会强制停止正在运行的事务，以完成架构切换。建议在使用前审查阻塞工作负载和事件背景；只有在已了解并接受频繁的切换阻塞时，才建议采用数据库级别的激进切换默认设置。

架构回退

检查团队是否了解回退时限，以及事件响应手册是否包含相关说明。

建议记录：

• 如何识别有问题的架构迁移。
• 如何在支持的时限内回退。
• 谁有权执行回退。
• 哪个应用部署应与架构回退一并回滚。

分支策略

建议采用以下分支拓扑：

• main 或等效的生产分支，启用安全迁移。
• 从生产分支创建的 staging 分支，启用安全迁移。
• 从预发布分支创建的短期开发分支。
• 在适当情况下，通过部署请求先将更改从开发分支部署到预发布分支，再从预发布分支部署到生产分支。

未经批准，不要创建分支。

Query Insights

检查 Insights 中的以下内容：

• 慢查询。
• 读取行数过多的查询。
• 报错的查询。
• 索引使用情况不佳的查询。
• 对于分片数据库，查询模式是否使用相关 vindex，以及索引或路由更改后 vindex 的使用情况如何变化。
• 异常的查询量。
• 缺少 SQL 注释标签的情况。
• 存在内置元数据或 SQLCommenter 标签时的标签明细：在控制面板中使用 tag:key:value 进行筛选，以及通过 insights/tags 和 insights/tags/summaries API 端点进行程序化细分。
• 部署关联数据。

建议启用或改进应用查询标签，以便 Insights 将查询归因到应用、路由、控制器、操作、作业、部署 SHA 和功能。

异常

查看活跃和近期异常。

建议：

• 将 branch.anomaly Webhook 订阅到团队的告警或自动化系统。
• 将异常负载路由到会创建 Issue 或 Agent 任务的分诊工作流。
• 将异常与部署请求、应用部署和查询标签关联起来。
• 不要根据异常事件自动应用架构或代码变更；只能生成提案或 PR。

架构建议

查看待处理的架构建议。

对于每项建议，记录：

• 类型：添加索引、移除冗余索引、主键耗尽、未使用的表、旧版字符集/排序规则，或其他。
• 受影响的表和键空间。
• 支持该建议的查询遥测数据。
• DDL。
• 预期收益。
• 风险。
• 测试计划。

建议的实施路径：

• 将建议转换为应用迁移或 PlanetScale 分支架构变更。
• 创建部署请求。
• 审查生成的 DDL 和分片影响。
• 在分支上进行基准测试或验证。
• 使用安全迁移进行部署。
• 部署后监控 Insights 和异常状态。

不要直接应用建议。

备份与恢复

检查备份状况和恢复运行手册。

建议：

• 确认存在自动备份。
• 定期进行非生产环境恢复演练。
• 记录恢复目标、RPO/RTO 预期和应用切换计划。
• 对于分片数据库，记录分片感知的恢复预期。

分片与键空间安全

如果数据库采用分片，请检查：

• 键空间和分片。
• Vschema。
• 跨分片查询模式。
• 架构部署请求是否显示各分片的影响。
• 查询是否使用适合分片的访问路径。

仅将适合 Agent 的分片审查作为提案。切勿自动重新分片、更改 vschema 或更改路由。

Vitess 的 Webhook 建议

评估并建议订阅以下 Webhook：

• branch.anomaly
• branch.primary_promoted
• branch.ready
• branch.sleeping
• cluster.storage
• keyspace.storage
• deploy_request.opened
• deploy_request.queued
• deploy_request.in_progress
• deploy_request.pending_cutover
• deploy_request.schema_applied
• deploy_request.errored
• deploy_request.reverted
• deploy_request.closed
• 如果客户数据库的 Webhook API 支持，订阅 branch.schema_recommendation

建议的目标：

• 将异常、主节点提升、存储和部署错误发送到告警系统。
• 将部署请求生命周期通知发送到 Slack 或内部通知系统。
• 将架构建议和异常发送到 Agent 接收队列，默认仅输出 PR。

输出

返回：

• 当前 Vitess 安全状况。
• 缺失的安全功能。
• 建议的工作流。
• 建议的 Webhook 订阅。
• 架构建议分诊表。
• 部署安全方面的差距。
• 需要审批的变更提案。

最后写上：

“No Vitess changes have been applied.”