convex-deploy-guard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deployment target guard

部署目标防护机制

Deployments are not interchangeable, and most incidents start with a command aimed at the wrong one. Every Convex project has several (personal dev, preview, prod — often across multiple projects on one machine). This guard is the standing discipline: identify, announce, then act — and treat prod as consent-gated, per action, per session.

部署环境不可随意混用，大多数事故都始于针对错误环境执行命令。每个Convex项目都有多个环境（个人开发环境、预览环境、生产环境——通常一台机器上会涉及多个项目）。本防护机制是一项固定规范：先识别、再告知、最后执行——并且针对生产环境的每一项操作、每一次会话，都需要获取明确的授权。

Workflow

工作流程

IDENTIFY before you act: read
```
CONVEX_DEPLOYMENT
```
in .env.local,
```
convex.json
```
, and whether
```
CONVEX_DEPLOY_KEY
```
is set; or call the official Convex MCP
```
status
```
tool. Classify the target: local-anonymous | dev | preview | prod. If two sources disagree, resolve before proceeding.
ANNOUNCE in one line before any deployment-affecting command:
```
target: dev (joyful-capybara-123, personal dev)
```
. Never run the command in the same breath as discovering the target — announce first.
PROD needs a FRESH explicit yes: before
```
npx convex deploy
```
(when it resolves to prod),
```
npx convex run --prod
```
,
```
env set
```
on prod, snapshot
```
import
```
/
```
export
```
on prod, or starting the MCP with prod access — state exactly what will change on which deployment and get an explicit yes in THIS session. A yes given earlier, or for a different target, does not carry.
MCP safety defaults: start the official MCP scoped non-prod (
```
--deployment dev
```
). The two prod flags are DIFFERENT risk levels — keep them split: a read-only prod audit (advisor/insights reading data/logs/insights) passes ONLY
```
--cautiously-allow-production-pii
```
(read tools);
```
--dangerously-enable-production-deployments
```
(which enables MUTATING prod tools) stays OFF unless the user explicitly asked to CHANGE prod this session. Never pair them by default — 'look at prod' must not silently grant 'mutate prod'.
READ-ONLY session mode: when the user says 'read-only' / 'don't change anything', honor it absolutely for the rest of the session — no deploy, no env set/remove, no mutations via
```
run
```
, no imports; start the MCP with
```
--disable-tools run,envSet,envRemove
```
.
Wrong-deployment diagnosis: when a deploy 'didn't change anything', do NOT re-deploy harder. Re-run step 1 — the deploy almost certainly landed on a different deployment than the one being observed.
Ambiguity = stop: if you cannot determine which deployment a command will hit, find out (status tool; compare
```
npx convex env list
```
fingerprints) — never guess.

行动前先识别：读取.env.local中的
```
CONVEX_DEPLOYMENT
```
、
```
convex.json
```
，以及是否设置了
```
CONVEX_DEPLOY_KEY
```
；或者调用官方Convex MCP的
```
status
```
工具。对目标环境进行分类：本地匿名环境 | 开发环境 | 预览环境 | 生产环境。如果两个来源的信息不一致，需先解决冲突再继续。
执行影响部署的命令前先以一行内容告知：格式如
```
target: dev (joyful-capybara-123, personal dev)
```
。绝对不能在发现目标环境的同时立即执行命令——必须先告知。
生产环境需获取新的明确同意：当
```
npx convex deploy
```
指向生产环境、执行
```
npx convex run --prod
```
、在生产环境执行
```
env set
```
、在生产环境执行快照
```
import
```
/
```
export
```
，或启动具有生产环境访问权限的MCP时——需明确说明将在哪个部署环境进行哪些变更，并获取本次会话内的明确同意。之前给出的同意，或针对其他目标环境的同意均无效。
MCP安全默认设置：启动官方MCP时默认限定为非生产环境（
```
--deployment dev
```
）。两个生产环境标志的风险等级不同——需分开使用：仅用于生产环境审计的只读模式（查看数据/日志/洞察的顾问/洞察工具）仅需传递
```
--cautiously-allow-production-pii
```
（只读工具）；
```
--dangerously-enable-production-deployments
```
（启用生产环境变更工具）默认保持关闭，除非用户在本次会话中明确要求修改生产环境。默认情况下绝不能同时启用这两个标志——“查看生产环境”绝不能默认授予“修改生产环境”的权限。
会话只读模式：当用户要求“只读”/“不要进行任何修改”时，在本次会话剩余时间内必须严格遵守——禁止部署、禁止设置/移除环境变量、禁止通过
```
run
```
执行变更操作、禁止导入数据；启动MCP时需添加
```
--disable-tools run,envSet,envRemove
```
参数。
错误部署诊断：当部署操作“没有产生任何变化”时，请勿反复尝试重新部署。重新执行步骤1——这种情况几乎可以肯定是部署到了与你正在观察的环境不同的环境中。
存在歧义则停止：如果无法确定命令将作用于哪个部署环境，需先查明（使用status工具；对比
```
npx convex env list
```
的指纹信息）——绝不能猜测。

Rules

规则

Classify and announce the target BEFORE every deployment-affecting command — identification and action are two separate steps.
Prod consent is per-action, per-target, per-session: state what changes where, get a fresh explicit yes.
Keep the two prod MCP flags split by risk: --cautiously-allow-production-pii (read-only) for an audit; --dangerously-enable-production-deployments (mutating) only when the user explicitly asks to change prod. Both are user-spoken-only; default every MCP start to a non-prod deployment selector.
Read-only mode, once requested, is absolute for the session — including 'harmless' mutations.
A deploy that seemed to do nothing means the WRONG deployment changed — diagnose the target, don't re-run.
This guard composes: ship, env, migrate, and seed run it as their step 0; it is not itself a deploy tool.

在执行每一项影响部署的命令前，必须先分类并告知目标环境——识别和执行是两个独立的步骤。
生产环境的授权需针对每一项操作、每一个目标环境、每一次会话：明确说明变更内容和目标环境，获取新的明确同意。
将两个MCP生产环境标志按风险等级分开使用：
```
--cautiously-allow-production-pii
```
（只读）用于审计；仅当用户明确要求修改生产环境时才启用
```
--dangerously-enable-production-deployments
```
（变更操作）。这两个标志都必须由用户主动指定；启动MCP时默认选择非生产环境。
一旦用户要求启用只读模式，在本次会话中必须严格执行——包括“无害”的变更操作。
如果部署操作看似没有产生任何效果，说明错误的环境被修改了——需诊断目标环境，而非重新执行命令。
本防护机制可与其他工具组合使用：部署、环境配置、迁移和数据初始化工具都会将其作为第0步执行；它本身并非部署工具。