mcpField
D
deploying-to-cloud

deploying-to-cloud

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

关于 deploying-to-cloud

面向 Laravel Cloud 部署与运维的技能，供管理 Laravel Cloud 环境的开发者使用。它通过 Cloud CLI 指引应用发布、资源配置、密钥管理和部署故障排查，并强调按需查阅当前文档。

主要功能

  1. 01使用 Cloud CLI 管理应用与环境
  2. 02执行部署并监控发布状态
  3. 03配置数据库、缓存与对象存储
  4. 04管理组织密钥及环境关联
  5. 05处理域名、队列与调度设置

适用场景

  1. 01首次发布 Laravel Cloud 应用
  2. 02更新环境变量或关联资源后重新部署
  3. 03配置私有与公开对象存储
  4. 04检查部署日志并定位失败步骤

安装

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

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

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

附带文件reference/checklists.md

详细介绍

使用 Laravel Cloud 部署

如需了解详细且最新的功能行为，请参阅 Laravel Cloud 文档。进行 Cloud 操作时，请使用 Cloud CLI，不要猜测仪表板或 API 的操作流程。请在项目中安装 CLI，默认通过 ./vendor/bin/cloud 调用；仅在备用情况下使用全局安装的 cloud 命令。为简洁起见，下文的命令均写作 cloud；除非使用全局安装，否则请改用 ./vendor/bin/cloud 执行。

应用设置

  • Laravel Cloud 支持从 GitHub、GitLab 或 Bitbucket 部署。新建 Laravel 应用需要 PHP 8.2 或更高版本、Laravel 9 或更高版本、已连接的 Git 提供商，以及部署区域。
  • Cloud 会为应用创建环境。请分别使用生产、暂存和预览环境；每个环境都有自己的计算资源、附加资源和部署设置。
  • 尽可能让应用计算资源和附加资源位于同一区域。
  • Cloud 使用所选的 PHP 版本构建 Docker 镜像，运行配置的构建和部署命令，并在部署成功后以零停机时间切换流量。默认启用推送即部署，也支持手动部署和部署钩子。

构建和部署

  • 典型的 Laravel 构建命令是 composer install --no-dev && npm run build。
  • 请在构建期间运行优化和缓存构建命令，而不要在部署期间运行。典型的部署命令是 php artisan migrate --force。
  • 构建和部署命令的超时时间为 15 分钟。部署命令会在版本正式上线前立即运行，其造成的文件系统更改不会保留。
  • 请勿将 php artisan queue:restart、php artisan horizon:terminate、php artisan optimize:clear 或 php artisan storage:link 添加到部署命令中。Cloud 会处理工作进程重启和进程管理；部署期间的文件系统更改不会持久保留。
  • 更改环境设置、附加资源或已关联的密钥后，请重新部署环境，使更改生效。

配置和资源

  • 附加的数据库、缓存和对象存储会自动注入连接变量。自定义环境变量的优先级高于注入的值。
  • 使用 Secrets Manager 存储在组织级别加密、供多个环境共享的值。密钥创建后无法读取；创建、更新、关联、取消关联或删除密钥后，请重新部署受影响的环境。
  • 环境文件系统是临时的，且副本之间不共享。请使用数据库或 Laravel Valkey 持久化缓存和会话，并使用 Laravel Cloud Object Storage 持久化文件。请勿依赖本地文件在部署后继续保留。
对象存储与文件可见性
  • Laravel Cloud Object Storage 基于 Cloudflare R2。R2 在存储桶级别应用可见性；一个存储桶不能同时包含私有对象和公开对象。
  • 对于私有文件，始终使用不带参数的 Storage::disk()，例如 Storage::disk()->put(...)，以便 Laravel 使用环境的默认磁盘。对于私有／默认存储，不要传入磁盘名称。将私有 Cloud 存储桶设为环境的默认磁盘。
  • 对于公开文件，使用命名的公开磁盘：Storage::disk('public')->put(...)。关联第二个配置为公开的 Cloud 存储桶，并为其指定 public 磁盘名称。
  • 同时使用私有文件和公开文件的应用，因此需要在环境中关联两个 Cloud Object Storage 存储桶：一个私有默认存储桶和一个名为 public 的公开存储桶。
  • 不要为 Cloud Object Storage 设置单个文件或 Flysystem 的 visibility: 'public' 配置。R2 不支持单个对象的 ACL 标头，并且会拒绝此类请求；创建存储桶时选择存储桶的可见性。
  • 私有存储桶无法通过互联网访问，但 Laravel 可以使用 Storage::temporaryUrl(...) 生成临时公开 URL。公开存储桶会通过 Cloud 提供的公开 URL 暴露其中的所有对象。
  • 使用 Cloud Object Storage 前，请先安装 S3 Flysystem 适配器：composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies。

队列与调度

  • 托管队列是推荐的队列选项。它们会配置专用工作进程，并根据队列中的工作量自动扩缩。
  • 托管队列需要受支持的较新 Laravel 版本和 aws/aws-sdk-php；更改依赖项前，请查阅当前的 Cloud 文档。
  • 在 App 或 Worker 集群上启用调度器，使其每分钟运行一次 php artisan schedule:run。当一个环境有多个副本时，对于必须仅运行一次的任务，请使用 Laravel 的 onOneServer。
  • 只有 Flex 计算规格可以缩容至零。缩容至零的环境会因 Laravel 计划任务和队列作业而唤醒，但达到休眠超时时，长时间运行的作业可能会被中断。对于不能中断的工作负载，请使用托管队列。

域名与存储

  • 每个环境在首次成功部署后都会获得一个 laravel.cloud 域名。配置所需的 DNS 记录后，Cloud 会自动验证自定义域名并配置 SSL。
  • 请勿使用临时文件系统来存储持久上传文件、生成的文件、缓存或会话数据。请改用相应的 Cloud 资源。

Cloud CLI

设置
composer require --dev laravel/cloud-cli
./vendor/bin/cloud auth -n

如果没有可用的项目本地安装，请使用 composer global require laravel/cloud-cli 全局安装 CLI，并将其作为 cloud 调用。

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、database:types、<resource>:metrics）。可通过 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 -h，然后运行 cloud ship -n 并传入所有必需的值。

  • 已有应用：

    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

  • Monorepo（应用位于子目录中）：向 cloud ship 或 cloud application:create 添加 --root-directory=<subdir>。

  • 自定义域名：cloud domain:create --json -n，然后运行 cloud domain:verify -n。

  • 边缘缓存：cloud environment:purge-edge-cache {environment} -n 会清除所有内容；传入 --path=/blog/post、--prefix=/blog/ 或 --tag=<cache-tag> 之一可以缩小清除范围。标签需要专用边缘网络。

  • Laravel Cloud 域名：cloud environment:vanity-domain {environment} --name=<subdomain> --deploy -n --force。只传入域名的第一部分。新域名会在下次部署时生效；--deploy 会启动并监控此次部署。每 30 分钟只能更改一次，因此请先与用户确认。

  • 仓库默认设置：cloud repo:config {application} -n 会设置仓库本地的应用和组织默认值。如果用户有多个组织，请传入 --organization=<id|name|slug>。

有关多步骤操作，请参阅 reference/checklists.md。

  • 如果不清楚用户的需求，请先询问，再运行任何命令。
命令失败时
  1. 阅读错误输出。
  2. 使用 :list --json -n 或 :get --json -n 检查资源状态。
  3. 如果是身份验证错误，运行 cloud auth -n。
  4. 修复问题并重新运行命令。
  5. 如果修复一次后仍出现相同错误，请停止操作并询问用户，不要重复执行。

每次部署后都要运行 cloud deploy:monitor -n。如果失败，请运行 cloud deployment:logs {deploymentId} --json -n，找到 "status": "failed" 的构建或部署步骤，并阅读其 output。在尝试修复前，先向用户说明出了什么问题。

子 Agent 委派

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

将以下操作委派给子 Agent：

  • cloud deploy:monitor -n — 部署日志可能非常长
  • cloud deployment:get --json -n — 完整的部署详情
  • cloud deployment:logs --json -n — 每个步骤的完整构建或部署输出
  • cloud <resource>:list --json -n — 列出大量资源会产生很大的 JSON
  • cloud <resource>:metrics --json -n — 会包含每个数据点；使用 --fields 缩小范围（例如 --fields=period,cpuUsage.average）
  • cloud command:run — 输出可能很长时
  • cloud usage --detailed --json -n — 负载包含每个数据库、缓存、存储桶、WebSocket 和应用的详情
  • 通过 WebFetch 从 https://cloud.laravel.com/docs/llms.txt 获取文档

在主上下文中执行：

  • 简短命令，如 :create、:delete、:update — 输出较少
  • cloud deploy -n — 需要立即获取部署 ID
  • 需要立即将结果用于下一步的任何命令
规则

请遵循以下规则：

  • 标志选择 — 始终使用上述文档中列出的组合
  • 部署顺序 — 先部署，再监控，绝不跳过监控
  • 破坏性命令 — 始终先向用户确认，展示命令并等待批准。这包括删除应用、环境、数据库、缓存、存储桶、域名或密钥，以及分离 Resend。
  • 错误处理循环 — 诊断问题并修复一次；如果再次失败，询问用户

以下事项请自行判断：

  • 实例规格、区域、集群类型 — 如果用户未指定，请询问
  • 要配置哪些资源 — 根据用户的描述决定
  • 配置资源的顺序 — 无需遵循固定顺序
  • 如何呈现输出 — 根据上下文选择摘要、原始输出或提取字段
密钥

密钥是组织内共享并关联到环境的加密值。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:detach {environment} {secretId} --force -n
cloud environment-secret:list {environment} --json -n

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

secret:update、secret:delete、environment-secret:attach 和 environment-secret:detach 接受的是密钥 ID，而不是名称，因为名称并不唯一。使用 cloud secret:list --json -n 获取 ID。

没有 secret:get 命令。environment-secret:detach 会从一个环境中移除密钥，但保留该密钥；secret:delete 会删除密钥，并将其从所有环境中分离。

密钥需要 PHP 扩展 sodium。其他命令均不需要。

创建、更新、关联、分离或删除密钥后，请重新部署受影响的环境。

电子邮件（Resend）

Resend 会发送环境的电子邮件。连接 Resend 帐户和验证发件域名需在控制面板中完成；CLI 无法执行这两项操作。如果 resend:attach 提示没有已验证的发件域名，请将错误消息中的集成设置链接提供给用户。

cloud resend:domains --status=verified --json -n
cloud resend:attach {environment} --from-address=hello@{verifiedDomain} --from-name="My App" --json -n
cloud resend:update {environment} --from-address=team@{verifiedDomain} --json -n
cloud resend:keys {environment} --json -n
cloud resend:detach {environment} --force -n
  • 发件人地址必须使用已验证的发件域名。--from-name 默认为应用名称。
  • resend:attach 会创建新的发件密钥。若要与另一个环境共享密钥，请使用 --reuse-key-id 并传入从 resend:keys 获取的 ID。
  • 关联时，Cloud 会设置 RESEND_API_KEY、MAIL_MAILER、MAIL_FROM_ADDRESS 和 MAIL_FROM_NAME，并替换环境中已有的值。
  • 应用需要 resend/resend-php。使用 -n 时，如果缺少此依赖，resend:attach 只会发出警告；请在项目中运行 composer require resend/resend-php。
  • 如果没有其他环境在使用该发件密钥，分离时会将其删除。
  • 关联、更新或分离 Resend 后，请重新部署环境。
远程访问
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 — 获取特定命令的详情和输出
账单和用量

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

cloud usage --json -n
  • --period=current|previous|1|2|3 — 账单周期（默认值：current；1、2 和 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）。

配置
  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 中的文档，并据此提供准确的答复。

遇到问题时

验证

  1. 在更改或部署任何内容之前，确认目标应用和环境。
  2. 部署前检查已暂存的环境更改和所需资源。
  3. 使用 cloud deploy:monitor -n 持续监控每次部署，直到完成。
  4. 对于生产环境更改，验证应用 URL、日志、队列、计划任务以及相关资源的运行状况。

评论

支持 Markdown