mcpField
D
deploying-laravel-cloud

deploying-laravel-cloud

github.com/laravel云与 DevOps731364 次安装2 周前更新
代码仓库

关于 deploying-laravel-cloud

面向 Laravel Cloud CLI 的操作技能，用于管理部署和云资源，涵盖命令发现、非交互操作、部署监控及资源流程。

主要功能

  1. 01云资源的 CRUD 流程
  2. 02部署与 ship 操作流程
  3. 03环境变量与密钥管理
  4. 04远程 PHP 和 Shell 命令
  5. 05账单与用量查询

适用场景

  1. 01首次部署或部署现有应用
  2. 02配置数据库、缓存和存储
  3. 03将加密密钥关联到环境
  4. 04在 Cloud 环境中运行命令

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/laravel/agent-skills --skill deploying-laravel-cloud

安装后在 Claude Code 中输入/deploying-laravel-cloud确认已加载。

附带文件reference/checklists.md

详细介绍

使用 Laravel Cloud CLI 部署

设置

composer global require laravel/cloud-cli
cloud auth -n

cloud auth 会打开浏览器。如果无法使用浏览器，请在环境中设置 LARAVEL_CLOUD_TOKEN——它会覆盖已保存的令牌，且不会将任何内容写入磁盘。若要改为保存令牌：cloud auth:token --add --token=<token> -n，或通过管道传入：echo "$TOKEN" | cloud auth:token --add -n。

命令

命令遵循 CRUD 模式：resource:list、resource:get、resource:create、resource:update、resource:delete。

可用资源：application、environment、instance、database-cluster、database、cache、bucket、domain、websocket-cluster、background-process、secret、command、deployment。

部分资源还有其他命令（例如 domain:verify、database:open、instance:sizes、cache:types）。通过 cloud -h 查找这些命令。

切勿将命令签名硬编码。始终运行 cloud <command> -h，以便在运行时查找选项。

CLI 标志

每条命令都要添加 -n——以防 CLI 卡住。 切勿使用 -q 或 --silent——它们会隐藏所有输出。

各操作对应的标志组合：

  • 读取（:list、:get）→ --json -n
  • 创建（:create）→ --json -n
  • 更新（:update）→ --json -n --force
  • 删除（:delete）→ -n --force（不使用 --json）
  • 环境变量 → -n --force
  • 部署/发布 → -n，并显式传入所有选项（不使用 --json）

部署工作流

确定任务并遵循对应路径：

首次部署？→ cloud ship -n（通过 cloud ship -h 查找选项）

已有应用？→

cloud deploy {app_name} {environment} -n --open
cloud deploy:monitor -n

环境变量？→ cloud environment:variables -n --force

机密？→ echo "$VALUE" | cloud secret:create --name=NAME --json -n，然后运行 cloud environment-secret:attach

配置基础设施？→ cloud <resource>:create --json -n

单体仓库（应用位于子目录中）？→ 为 cloud ship 或 cloud application:create 添加 --root-directory=<subdir>

自定义域名？→ cloud domain:create --json -n，然后运行 cloud domain:verify -n

多步操作请参阅 reference/checklists.md。

不确定用户需要什么？→ 运行任何操作前先询问用户。

命令失败时

  1. 阅读错误输出
  2. 使用 :list --json -n 或 :get --json -n 检查资源状态
  3. 认证错误？→ cloud auth -n
  4. 修复问题，然后重新运行命令
  5. 如果修复一次后仍重复出现相同错误，请停止并询问用户

每次部署后都要运行 cloud deploy:monitor -n。如果失败，请先向用户说明出错原因，再尝试修复。

子 Agent 委派

将高输出量操作委派给子 Agent（使用 Task 工具），以缩小主上下文窗口。返回的只有摘要——冗长输出会留在子 Agent 的上下文中。

将以下操作委派给子 Agent：

  • cloud deploy:monitor -n——部署日志可能非常长
  • cloud deployment:get --json -n——获取完整部署详情
  • cloud <resource>:list --json -n——列出大量资源会生成很大的 JSON
  • 通过 WebFetch 从 https://cloud.laravel.com/docs/llms.txt 获取文档

保留在主上下文中：

  • :create、:delete、:update 等简短命令——输出很少
  • cloud deploy -n——你需要立即获取部署 ID
  • 需要立即使用其结果执行下一步的任何命令

规则

严格遵循以下步骤：

  • 标志选择——始终使用上述已记录的组合
  • 部署顺序——先部署，再监控，绝不跳过监控
  • 破坏性命令——始终先向用户确认，展示命令并等待批准
  • 错误循环——诊断问题，修复一次；如果再次失败，则询问用户

酌情判断：

  • 实例规格、区域、集群类型——如果用户未指定，请询问
  • 要配置哪些资源——根据用户描述决定
  • 配置顺序——没有严格要求
  • 如何呈现输出——根据上下文选择总结、展示原始内容或提取字段

Secrets

在组织内共享并附加到环境的加密值。CLI 会在本地加密值，因此明文不会传到 API。

cloud secret:list --json -n
echo "$VALUE" | cloud secret:create --name=STRIPE_KEY --json -n
cloud environment-secret:attach {environment} {secretId} -n
cloud environment-secret:list {environment} --json -n

通过管道传入值。--value= 也可用，但明文会留在 shell 历史记录和进程列表中。

secret:update、secret:delete 和 environment-secret:attach 接受的是 secret ID，而不是名称——名称并不唯一。使用 cloud secret:list --json -n 查看 ID。

没有 secret:get，也无法仅从单个环境中分离 secret。secret:delete 会将其删除，并从所有环境中分离。

Secrets 需要 PHP 扩展 sodium。其他命令都不需要。

远程访问

Tinker（>= v0.2.0）

直接在 Cloud 环境中运行 PHP 代码：

cloud tinker {environment} --code='Your PHP code here' --timeout=60 -n
  • --code — 要执行的 PHP 代码（非交互模式下必需）
  • --timeout — 等待输出的最长秒数（默认值：60）

代码必须使用 echo、dump 或类似方式显式输出结果——单独的表达式不会产生输出。

始终传入 --code 和 -n，以避免交互式提示。

远程命令

在 Cloud 环境中运行 shell 命令：

cloud command:run {environment} --cmd='your command here' -n
  • --cmd — 要运行的命令（非交互模式下必需）
  • --no-monitor — 跳过实时输出流
  • --copy-output — 将输出复制到剪贴板

查看过去执行的命令：

  • cloud command:list {environment} --json -n — 列出命令历史记录
  • cloud command:get {commandId} --json -n — 获取特定命令的详情和输出

如果输出可能很长，请将 command:run 委托给子 Agent。

账单与用量

查看当前组织的账单和用量：

cloud usage --json -n
  • --period=current|previous|1|2|3 — 账单周期（默认值为 current；1/2/3 表示往前推 N 个周期，最多 3 个）。其他值会报错。
  • --environment=<id> — 将用量筛选为单个环境
  • --detailed — 包含按应用、资源和附加组件细分的数据
  • --json — 机器可读的输出（始终与 -n 配合使用）

常见查询：

  • 当前支出：cloud usage --json -n | jq '.currentSpendCents'
  • 上个月的账单：cloud usage --period=previous --json -n
  • 单个环境的完整细分数据：cloud usage --environment=<id> --detailed --json -n

所有金额都以美分为单位。所有层级的键均采用 camelCase 格式（例如，currentSpendCents、bandwidth.allowanceBytes、databases[].totalCents、applications[].totalCostCents）。

请将 --detailed --json 委托给子 Agent——此负载包含每个数据库、缓存、存储桶、WebSocket 和应用，可能会很大。

配置

  1. 环境变量：LARAVEL_CLOUD_TOKEN — API 令牌，优先于任何已保存的令牌（空值视为未设置）
  2. 全局：~/.config/cloud/config.json — 身份验证令牌和偏好设置
  3. 仓库本地：.cloud/config.json — 应用和环境默认值（由 cloud repo:config {application} -n 设置）
  4. CLI 参数会覆盖这两个配置文件

将应用传给 repo:config——否则命令必须询问；在 -n 模式下，如果组织有多个应用，则会失败。部署命令不需要这些默认值；直接将应用和环境传给它们即可。

多个组织意味着会存储多个 API 令牌。每个命令都会从 .cloud/config.json 读取 organization_id，以选择令牌；如果未设置，则命令会失败。使用 cloud repo:config {application} --organization=<id|name|slug> -n 进行设置。

LARAVEL_CLOUD_TOKEN 只能保存一个令牌，因此会自行选择组织。使用 --organization 指定其他组织会导致失败，而不会回退到令牌所属的组织。

文档

Laravel Cloud 文档：https://cloud.laravel.com/docs/llms.txt

当用户询问某项功能的工作方式或需要了解 Laravel Cloud 功能时，请使用 WebFetch 获取上述 URL 中的文档，并据此提供准确的回答。

遇到问题时

评论

支持 Markdown