aspire-deployment

Aspire 部署

当任务是发布、预览、验证、部署或拆除 Aspire 应用部署时，请使用此技能。本技能负责 Aspire 部署路由。在确认工作区是否为 Aspire 应用之前，不要从通用 Azure、Docker、Kubernetes、Helm 或 Bicep 工作流开始。

Aspire 部署从 AppHost 模型开始。将 aspire deploy、aspire publish、aspire destroy、aspire do 以及 AppHost 中的部署环境资源作为主要路径。使用项目发布系列中的稳定 SDK/托管包；对于 Kubernetes 和 Radius 等仅限预览的集成，则使用相匹配的预览版。

将其保留为一个包含特定目标参考资料的技能。只加载与你发现的目标或用户请求的目标相匹配的参考文件。

路由优先级

当以下两个条件都成立时，此技能优先于通用云部署技能：

1. 用户要求部署、发布、生成部署构件、创建 Bicep/Helm/Compose/CDK 输出、托管到 Azure 或 AWS、部署到 Azure、AWS、Kubernetes、Docker Compose 或 Radius、拆除已部署的资源，或验证部署。
2. 工作区存在 Aspire 标记：
   • Aspire 工作区配置
   • C# 或 TypeScript AppHost 文件
   • AppHost 项目
   • 使用 Aspire 分布式应用生成器 API 的 AppHost 代码

如果存在 Aspire 标记，但未自动调用此技能，请在继续之前切换到此技能。优先使用 aspire ls、aspire config list、aspire ps 和 aspire describe 等 Aspire CLI 命令了解工作区。

指导原则

修改部署代码前先查阅 Aspire 文档

添加目标包、编辑 AppHost 或使用不熟悉的部署 API 前，请先查阅 Aspire 文档：

aspire docs search "deploy with Aspire"
aspire docs search "Docker Compose deployment"
aspire docs search "Kubernetes deployment"
aspire docs search "Azure Container Apps deployment"
aspire docs search "Azure App Service deployment"
aspire docs search "Azure Kubernetes Service deployment"
aspire docs search "Radius deployment"
aspire docs get "deploy-to-azure-kubernetes-service-aks"
aspire docs get "<slug-from-search-results>"

需要确认精确的 C# 或 TypeScript API 形式时，也请查阅 API 文档。如果不确定代码库使用哪种 AppHost 语言，请同时搜索这两种语言：

aspire docs api search "<deployment API or concept>" --language csharp
aspire docs api search "<deployment API or concept>" --language typescript
aspire docs api get "<id-from-api-search>"

不要臆造包名、生成器方法、重载或部署命令。C# 和 TypeScript AppHost 的 API 形式有所不同。

优先采用 Aspire 原生部署方式

部署 AppHost 中声明的资源，而不是 AppHost 进程本身。 对于 Docker Compose，请配置 Compose 环境，并让 Aspire 为这些资源 生成服务；不要用 AppHost Dockerfile 或 Compose 服务替代这种方式。

优先使用 Aspire 部署目标和 CLI 命令：

aspire publish --list-steps
aspire deploy --list-steps
aspire publish
aspire deploy
aspire destroy
aspire do <step>

只有在 Aspire 已生成构件后，或目标文档要求使用特定目标工具时，才使用该工具：

• Docker Compose：检查生成的 aspire-output/docker-compose.yaml 和 .env*；Aspire 也可以通过 aspire deploy 运行 docker compose up。
• Kubernetes：检查生成的 Helm chart 输出；自行应用已发布的构件时，使用 Helm/kubectl。
• Azure：使用 aspire add <azure-target>、aspire publish，并通过 AppHost 部署环境运行 aspire deploy。
• AWS：使用 aspire add aws 添加集成，检查生成的 CDK/CloudFormation 输出，并遵循 AWS 集成仓库的指南。
• Radius：将 Aspire.Hosting.Radius 视为预览版。使用集成/文档搜索确认包和 API，然后建模为 AddRadiusEnvironment(...).WithNamespace(...)。

仅在目标不明确时询问部署位置

如果用户已选择 Docker Compose、Kubernetes、Azure Container Apps、Azure App Service、Azure Kubernetes Service (AKS) 或 AWS 等目标，不要询问其要选择哪个目标。使用用户选择的目标，并继续参考对应文档。

如果用户未明确选择部署目标，且 AppHost 中尚未包含且仅包含一个部署环境，则在添加集成、编辑 AppHost、发布构件或部署之前，询问用户想要部署到哪里。使用单个多选问题：

你想将这个 Aspire 应用部署到哪里？

显示以下选项：

选项	Aspire 添加命令	适用场景
Docker Compose	aspire add docker	用户需要适用于 Docker 或 Podman 的本地／服务器容器部署构件。
Kubernetes	aspire add kubernetes	用户已有 Kubernetes 集群，并需要 Helm／Kubernetes 构件或直接部署到集群。
Azure Container Apps	aspire add azure-appcontainers	用户需要用于分布式应用和服务的 Azure 托管容器平台。
Azure App Service	aspire add azure-appservice	用户需要为符合 App Service 模型的 Web 应用／API 提供 Azure 网站托管。
Azure Kubernetes Service (AKS)	aspire add azure-kubernetes	用户希望 Aspire 预配资源并部署到 Azure 托管的 Kubernetes。
AWS	aspire add aws	用户希望通过 AWS Aspire 集成和 AWS CDK 使用 Aspire 发布／部署。

不要将预览版 Radius 作为默认选项。仅当用户明确要求使用 Radius，或 AppHost 中已有 Radius 环境时才使用它。

如果用户只说“Azure”，则再次询问，并仅提供 Azure 选项：Azure Container Apps、Azure App Service 或 Azure Kubernetes Service (AKS)。如果 AppHost 中已有且仅有一个部署环境，且用户未要求更换目标，则使用该目标，并告知用户检测到的目标。

用户意图不明确时，先询问再创建云资源

云部署可能会创建计费资源。如果用户要求的是计划、预览、验证或“让它可以部署”，则在完成部署计划／构件后停止，并在运行预配资源的命令之前询问用户。

如果用户明确要求立即部署，则继续执行预检和部署，但仍须在预配资源之前明确任何目标选择、订阅／资源组歧义或缺失参数的决策。

使用 Aspire 原生方式部署到 Azure

本技能中的 Azure 部署路径为 aspire add <azure-target>、AppHost 环境配置、aspire publish 和 aspire deploy。不要通过单独的 Azure 部署工具或生成的基础设施工作流处理 Azure 部署。

让 Aspire 包保持在同一发行系列

发布或部署之前，验证 Aspire.AppHost.Sdk 和托管包使用的版本在项目所选发行系列中彼此兼容。预览版专用集成需要通过 aspire add 或集成文档选择兼容的预览版构建。 CLI 版本并不能保证不兼容的托管包安全；混用版本的依赖图可能会在启动时因 MissingMethodException 或 TypeLoadException 而失败。

编辑部署代码时，迁移已过时的 13.5 接口：

• 使用 .Services 替代托管上下文 .ServiceProvider；
• 使用 AddConnectionString 替代 PublishAsConnectionString；并且
• 将已弃用的 Aspire.Hosting.GitHub.Models 资源迁移到 Azure AI Foundry。

默认工作流

1. 熟悉 Aspire 工作区。
   • 先运行 aspire ls，列出当前范围内的 AppHost；如果需要更多上下文，再使用 aspire.config.json、AppHost 项目文件或 aspire ps。
   • 如果不存在 AppHost，请停止部署工作，并调用 aspireify 技能来初始化或接入 AppHost，然后再继续。
   • 确定 AppHost 使用的是 C# 还是 TypeScript。
   • 优先使用 Aspire CLI 命令来发现资源和检查状态。
2. 明确或推断部署目标。
   • 如果用户指定了 Docker Compose、Kubernetes、Azure Container Apps、Azure App Service、Azure Kubernetes Service (AKS) 或 AWS，请直接加载对应目标的参考资料，无需再次询问。
   • 如果用户只说“部署”，请检查现有 AppHost 目标环境资源。
   • 如果已存在且仅有一个目标环境，请使用该环境，并说明检测到的目标。
   • 如果存在多个目标、没有目标，或者用户只说“Azure”，请询问部署位置，并提供上述选项。
3. 加载目标和应用类型参考资料。
   • Docker Compose：references/docker-compose.md
   • Kubernetes 和 Azure Kubernetes Service (AKS)：references/kubernetes.md
   • Azure Container Apps/App Service/Azure Kubernetes Service (AKS)：references/azure.md
   • AWS：references/aws.md
   • Radius 预览版：使用当前 Aspire 文档，并搜索 Aspire.Hosting.Radius API； 不要猜测实验性 API 的形态。
   • JavaScript 应用资源：references/javascript.md
   • CI/CD 或 GitHub Actions 自动化：references/cicd.md
4. 使用 Aspire 文档搜索获取最新指南。
   • 搜索并获取目标部署文档。
   • 修改 AppHost 代码前，先搜索 API 文档。
5. 应用目标代码变更。
   • 如果缺少集成，请运行目标对应的 aspire add ... 命令。
   • 将部署环境资源添加到 AppHost。
   • 对于常见的单环境情况，不要显式指定计算环境。只有当 AppHost 存在多个部署环境时才进行区分。在 C# 中通常使用 WithComputeEnvironment(...)；对于 TypeScript AppHost，在假设存在等效功能前，请先查阅当前语言专属文档。
   • 仅添加部署所需的目标特定自定义 API，例如端点公开、Helm 设置、Compose 文件自定义、Azure 站点/容器应用自定义，或 AWS 发布目标覆盖项。
6. 部署前检查部署模型。
   • 确认 AppHost 中存在目标集成包。
   • 确认 AppHost 具有目标环境资源。
   • 仅当存在多个计算环境时，才确认计算资源已分配给目标环境。单个计算环境是常见情况，可以自动推断。
   • 清点参数、机密、连接字符串、外部端点、容器注册表和目标特定的先决条件。
   • 对于 Azure 或 AWS，确认身份验证、目标账户/订阅、区域/位置，以及资源组/堆栈上下文。
7. 应用前先预览。
   • 运行 aspire publish --list-steps 或 aspire deploy --list-steps。
   • 如需审查生成的产物，请使用 aspire publish -o <scratch-or-output-path>。
   • 将已发布的产物视为预览/交接内容。aspire deploy 会解析值，并根据 AppHost 模型应用部署；它不会使用先前发布的输出目录。
   • 总结资源、端点、参数、机密、身份和生成的产物。
8. 部署或交接。
   • 如果用户要求部署且部署前检查已完成，请运行 aspire deploy。
   • 仅当用户要求执行特定管道步骤时，才使用 aspire do <step> 运行命名步骤。
   • 对于已发布的产物，请说明目标平台原生的应用步骤。
9. 仅在用户明确要求时销毁资源。
   • 运行 aspire destroy，执行所选 AppHost/环境的目标销毁管道。
   • 运行前请确认 AppHost、环境、目标账户/订阅/集群，以及用户确有销毁意图。
   • 仅当用户或 CI 工作流已明确销毁意图时才使用 --yes。
   • 除非正在排查销毁失败或清理未托管的残留资源，否则优先使用 aspire destroy，而不是目标平台原生的删除命令。
10. 验证结果。

• 根据目标使用目标输出、aspire describe、云 CLI、Docker Compose、kubectl 或端点检查。
• 销毁后，请验证目标资源已移除，或记录需要手动清理的任何残留资源。

AppHost 目标检测

搜索 AppHost 中的部署环境资源：

目标	Aspire 添加命令	集成	AppHost 环境概念
Docker Compose	aspire add docker	Docker 托管	Docker Compose 环境
Kubernetes	aspire add kubernetes	Kubernetes 托管	Kubernetes 环境
Azure Container Apps	aspire add azure-appcontainers	Azure Container Apps 托管	Azure Container Apps 环境
Azure App Service	aspire add azure-appservice	Azure App Service 托管	Azure App Service 环境
Azure Kubernetes Service (AKS)	aspire add azure-kubernetes	Azure Kubernetes 托管	Azure Kubernetes Service (AKS) 环境
AWS	aspire add aws	AWS 托管	AWS CDK 环境
Radius（预览版）	使用 aspire integration search radius 查找	Aspire.Hosting.Radius	Radius 环境

此表仅供参考。编辑代码前，请查阅 Aspire 文档，确认适用于 AppHost 语言的当前 API。

参数和密钥预检

参数是部署输入。根据目标和命令，它们可以通过配置文件、用户机密、环境变量、命令行参数、交互式提示或 CI/CD 机密存储提供。

部署前，请报告：

• AppHost 参数 API 中的参数名称，包括由配置提供的参数
• 是否为机密
• 预期的提供程序语法，例如 Parameters__name；对于带连字符的参数名称，环境变量中应使用下划线，例如 registry-endpoint 会变为 Parameters__registry_endpoint
• 参数的传递位置，例如项目环境变量、连接字符串、Key Vault 机密、Helm Secret、Compose .env 或 Azure 应用设置
• 值看起来是已配置还是缺失

在适当情况下，使用 aspire secret list 查看 AppHost 用户机密，但不要打印机密值。对于部署产物，请检查生成的占位符和映射，而非原始机密内容。

目标参考资料

• references/docker-compose.md - Docker Compose 目标、生成的文件、环境变量、清理。
• references/kubernetes.md - Kubernetes 和 Azure Kubernetes Service (AKS) 目标选择、Helm 输出、注册表要求、kubectl/Helm 检查。
• references/azure.md - Azure 目标选择、Azure 设置、Container Apps、App Service 和 Azure Kubernetes Service (AKS)。
• references/aws.md - AWS 目标选择、AWS CDK 前置条件、发布/部署工作流和 AWS 集成文档。
• references/javascript.md - JavaScript 应用部署模型，包括 Vite/静态资源、Node/SSR 服务、Next.js 以及网关/后端服务模式。
• references/cicd.md - Aspire 发布/部署、参数、机密、注册表身份验证和云身份验证的 CI/CD 与 GitHub Actions 工作流指南。
• references/preflight.md - 常见的预检、预览、参数、销毁和验证检查清单。
• aspire-13-5-breaking-changes.md - 13.5 的包、API 和 CLI 迁移规则。

Agent 执行

在无人值守场景下（CI、脚本、Agent 驱动），对可能触发提示的每次 Aspire CLI 调用都追加 --non-interactive——尤其是 aspire publish、aspire deploy 和 aspire destroy。对于 aspire destroy，只有在用户明确确认要拆除，或 CI 工作流已明确包含此意图后，才同时传入 --yes。

优先提前提供会触发提示的值（目标订阅／区域／资源组、参数、机密、注册表凭据），避免无人值守运行卡住。完整的预检清单请参阅 references/preflight.md。

交接规则

场景	转交给
启动、停止、等待或重启 AppHost／其资源	aspire-orchestration 技能
正在运行或已部署应用的日志、跟踪、指标、仪表板	aspire-monitoring 技能
AppHost 编写——添加集成、连接资源、设置环境	aspireify 技能
已部署应用诊断——App Insights、ACA 日志、AKS Container Insights	azure-diagnostics 技能（azure-skills）

绝不要将部署任务交给 azure-skills。Aspire 通过 AppHost 模型端到端处理 Docker Compose／Kubernetes／Azure／AWS 上的发布、部署和拆除。

项目本地技能覆盖

如果存在 .agents/skills/aspire-deployment/SKILL.md（由 aspire agent init 创建）， 请优先使用它，而非此插件技能——它是权威的项目本地版本，其内容版本与使用方的 Aspire CLI 保持一致。对于尚未运行 aspire agent init 的代码库，此插件技能始终作为安全兜底。