using-medusa-cloud

管理 Medusa Cloud 资源

面向 AI Agent 的操作指南，介绍如何通过 mcloud CLI 管理 Medusa Cloud 基础设施。涵盖设置、部署、调试、环境和变量。

限制

• 解析 CLI 输出时务必传入 --json。 纯文本输出面向人类，且可能在不发出通知的情况下发生变化。
• 修改前确认上下文。 进行任何状态更改前，运行 mcloud whoami --json。
• 先读取，再写入。 执行任何 delete、redeploy 或 trigger-build 前，先运行 get 或 list。
• 破坏性操作使用 --yes。 在非交互模式下，delete 命令（包括 variables delete）必须传入 --yes。
• 变量更改需要部署才能生效。 variables set/delete 不会重新构建或重新部署：运行时更改使用 redeploy，构建更改使用 trigger-build。
• 不能删除生产环境。 按设计，mcloud environments delete 在生产环境上会报错。
• 除非用户明确要求，否则绝不传入 --reveal。 密钥值会出现在终端滚屏内容和日志中。
• --json 和 --follow 不兼容。 使用 --json 进行程序化日志采集时，请通过 --from/--to 指定有界时间范围。

关键：按需加载参考文件

根据操作内容加载以下参考文件：

• 设置 CLI？ → 必须先加载 setup.md
• 调试失败的部署？ → 必须先加载 debugging-deployments.md
• 管理环境或变量？ → 必须先加载 environments-and-variables.md

最低要求： 执行多步骤工作流前，至少加载一个参考文件。

快速参考

身份验证检查

修改状态前务必确认身份验证和作用域：

mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'

退出代码为 0 = 已通过身份验证且作用域正确。非零 = 停止并询问用户。

设置一次上下文

mcloud use \
  --organization org_123 \
  --project proj_123 \
  --environment production

关键： 不带标志运行 mcloud use 会进入交互模式，在 CI/Docker/管道输入中会失败。务必传入标志。

部署状态路由

根据 backend_status（或 storefront_status）进行路由：

状态	含义	要检查的日志
build-failed	构建步骤失败	mcloud deployments build-logs <id>
deployment-failed	构建后运行时崩溃	mcloud logs --deployment <id>
timed-out	超出时间限制	两者：先检查 build-logs，再检查运行时日志

重新部署决策

命令	使用时机
mcloud environments redeploy <env>	修复涉及环境侧问题（变量更改、基础设施）——重新运行现有构建
mcloud environments trigger-build <env>	修复涉及跟踪分支上的源代码——启动新构建

常见问题

• 仅限 TTY 的命令。 mcloud login、mcloud use（不带标志）以及不带 --yes 的 delete 都需要 TTY。在 CI、Docker 或管道输入中会失败。
• MCLOUD_TOKEN 优先级。 设置后会忽略基于文件的凭据，并拒绝 mcloud login。取消设置即可切换账户。
• 个人访问密钥与组织访问密钥。 个人密钥需要 --organization；组织密钥已预设作用域。
• organizations list 需要个人身份验证。 使用组织访问密钥运行此命令会返回 401。
• 构建 ID 与部署 ID。 depl_* = 部署 ID；其他值均为构建 ID（会解析为最新部署）。mcloud logs --deployment 接受两者；其他命令仅接受构建 ID。
• mcloud local build 没有 --json。 它会以纯文本流式输出，并通过退出代码报告成功（0 = 成功）。需要 Docker，且必须在项目的 Git 仓库内运行。可用于在本地复现 build-failed 故障——参见 debugging-deployments.md。

参考文件

setup.md                       - CLI installation, authentication, context setup
debugging-deployments.md       - Build/deployment failure recipes and log analysis
environments-and-variables.md  - Environment lifecycle and variable management