deploying-applications

部署应用

从 Kubernetes 到无服务器和边缘函数的生产部署模式。弥合从应用组装到生产基础设施的差距。

目的

此技能提供清晰的指导，帮助你：

• 选择合适的部署策略（Kubernetes、无服务器、容器、边缘）
• 使用 Pulumi 或 OpenTofu 实现基础设施即代码
• 使用 ArgoCD 或 Flux 设置 GitOps 自动化
• 选择无服务器数据库（Neon、Turso、PlanetScale）
• 部署边缘函数（Cloudflare Workers、Deno Deploy）

何时使用此技能

在以下情况使用此技能：

• 将应用部署到生产基础设施
• 设置 CI/CD 流水线和 GitOps 工作流
• 在 Kubernetes、无服务器或边缘部署之间进行选择
• 实现基础设施即代码（Pulumi、OpenTofu、SST）
• 从手动部署迁移到自动化基础设施
• 与 assembling-components 集成，以实现完整的部署流程

部署策略决策树

WORKLOAD TYPE?

├── COMPLEX MICROSERVICES (10+ services)
│   └─ Kubernetes + ArgoCD/Flux (GitOps)
│       ├─ Helm 4.0 for packaging
│       ├─ Service mesh: Linkerd (5-10% overhead) or Istio (25-35%)
│       └─ See references/kubernetes-patterns.md

├── VARIABLE TRAFFIC / COST-SENSITIVE
│   └─ Serverless
│       ├─ Database: Neon/Turso (scale-to-zero)
│       ├─ Compute: Vercel, AWS Lambda, Cloud Functions
│       ├─ Edge: Cloudflare Workers (<5ms cold start)
│       └─ See references/serverless-dbs.md and references/edge-functions.md

├── CONSISTENT LOAD / PREDICTABLE TRAFFIC
│   └─ Containers (ECS, Cloud Run, Fly.io)
│       ├─ ECS Fargate: AWS-native, serverless containers
│       ├─ Cloud Run: GCP, scale-to-zero containers
│       └─ Fly.io: Global edge, multi-region

├── GLOBAL LOW-LATENCY (<50ms)
│   └─ Edge Functions + Edge Database
│       ├─ Cloudflare Workers + D1 (SQLite)
│       ├─ Deno Deploy + Turso (libSQL)
│       └─ See references/edge-functions.md

└── RAPID PROTOTYPING / STARTUP MVP
    └─ Managed Platform as a Service
        ├─ Vercel (Next.js, zero-config)
        ├─ Railway (any framework)
        └─ Render (auto-deploy from Git)

IaC CHOICE?

├─ TypeScript-first → Pulumi (Apache 2.0, multi-cloud)
├─ HCL-based → OpenTofu (CNCF, Terraform-compatible)
└─ Serverless TypeScript → SST v3 (built on Pulumi)

核心概念

基础设施即代码（IaC）

使用代码定义基础设施，而非手动配置。

主要方案：Pulumi（TypeScript）

• Context7 ID：/pulumi/docs（信任度：94.6/100，9,525 个代码片段）
• 以 TypeScript 为先（与 React/Next.js 使用相同语言）
• 支持多云（AWS、GCP、Azure、Cloudflare）
• 模式和示例请参阅 references/pulumi-guide.md

替代方案：OpenTofu（HCL）

• CNCF 项目，兼容 Terraform
• MPL-2.0 许可证（开放治理）
• 可直接替换 Terraform
• 迁移指南请参阅 references/opentofu-guide.md

无服务器方案：SST v3（TypeScript）

• 基于 Pulumi 构建
• 针对 AWS Lambda、API Gateway 进行了优化
• 支持 Lambda 实时开发

GitOps 部署

以 Git 为事实来源的声明式基础设施。

ArgoCD（推荐用于平台团队）：

• 功能丰富的 Web UI
• 内置 RBAC 和多租户支持
• 自动修复部署状态
• 请参阅 references/gitops-argocd.md

Flux（推荐用于 DevOps 自动化）：

• 原生支持 Kubernetes
• 以 CLI 为主
• 架构更简单
• 请参阅 references/gitops-argocd.md

服务网格

用于微服务通信、安全和可观测性的可选层。

适用服务网格的情况：

• 多团队微服务（安全边界）
• 零信任网络（需要 mTLS）
• 高级流量管理（金丝雀发布、蓝绿部署）

不适用的情况：

• 简单的单体应用或 2-3 个服务（开销不值得）
• 无服务器架构（不兼容）

Linkerd（侧重性能）：

• 5-10% 的开销
• 基于 Rust
• 简单且有明确主张

Istio（功能丰富）：

• 25-35% 的开销
• C++（Envoy）
• 高级路由和可观测性

服务网格模式请参阅 references/kubernetes-patterns.md。

快速入门工作流

工作流 1：将 Next.js 部署到 Vercel（零配置）

# Install Vercel CLI
npm i -g vercel

# Link project
vercel link

# Deploy to production
vercel --prod

完整示例请参阅 examples/nextjs-vercel/。

工作流 2：使用 ArgoCD 部署到 Kubernetes

1. 创建 Helm chart
2. 将 chart 推送到 Git 仓库
3. 创建 ArgoCD Application
4. ArgoCD 自动同步

完整的 GitOps 设置请参阅 examples/k8s-argocd/。

工作流 3：使用 Pulumi 部署无服务器应用

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

// Create Lambda function
const lambda = new aws.lambda.Function("api", {
    runtime: "nodejs20.x",
    handler: "index.handler",
    role: role.arn,
    code: new pulumi.asset.FileArchive("./dist"),
});

export const apiUrl = lambda.invokeArn;

模式请参阅 examples/pulumi-aws/ 和 references/pulumi-guide.md。

工作流 4：将边缘函数部署到 Cloudflare Workers

import { Hono } from 'hono'

const app = new Hono()

app.get('/api/hello', (c) => {
  return c.json({ message: 'Hello from edge!' })
})

export default app

使用 Wrangler 部署：

wrangler deploy

请参阅 examples/cloudflare-workers-hono/ 和 references/edge-functions.md。

与 assembling-components 集成

使用 assembling-components 构建应用后，此技能可提供部署模式：

前端（Next.js/Vite）→ 部署：

1. 查看部署决策树
2. 选择平台：Vercel（Next.js）、Cloudflare Pages（静态）或自定义方案（Pulumi）
3. 设置环境变量
4. 使用所选方法部署

后端（FastAPI/Axum）→ 部署：

1. 将应用容器化（Dockerfile）
2. 选择平台：ECS Fargate、Cloud Run 或 Kubernetes
3. 设置 IaC（Pulumi 或 OpenTofu）
4. 使用 GitOps（ArgoCD/Flux）或 CI/CD 部署

请参阅 references/pulumi-guide.md，了解集成示例。

参考文件

Kubernetes 部署

• references/kubernetes-patterns.md - Helm 4.0、服务网格、自动扩缩容
• references/gitops-argocd.md - ArgoCD/Flux GitOps 工作流

无服务器与边缘计算

• references/serverless-dbs.md - Neon、Turso、PlanetScale（缩至零）
• references/edge-functions.md - Cloudflare Workers、Deno Deploy（冷启动时间 <5ms）

基础设施即代码

• references/pulumi-guide.md - Pulumi TypeScript 模式、组件模型
• references/opentofu-guide.md - OpenTofu/Terraform 迁移

实用脚本

scripts/ 中的脚本无需加载到上下文即可执行（不消耗令牌）。

生成 Kubernetes 清单：

python scripts/generate_k8s_manifests.py --app-name my-app --replicas 3

验证部署配置：

python scripts/validate_deployment.py --config deployment.yaml

完整用法文档请参阅脚本文件。

示例

examples/ 中提供完整、可运行的示例：

• pulumi-aws/ - 使用 Pulumi 部署 ECS Fargate
• k8s-argocd/ - Kubernetes + ArgoCD GitOps
• sst-serverless/ - SST v3 无服务器 TypeScript

每个示例均包含：

• README.md，其中包含设置说明
• 完整源代码
• 环境变量配置
• 部署命令

库推荐

基础设施即代码（2025）

首选：Pulumi

• Context7：/pulumi/docs（可信度：94.6，9,525 个代码片段）
• 以 TypeScript 为先，支持多云
• Apache 2.0 许可证

替代方案：OpenTofu

• CNCF 项目，MPL-2.0
• 兼容 Terraform
• HCL 语法

无服务器：SST v3

• 基于 Pulumi 构建
• 针对 AWS Lambda 优化
• 原生支持 TypeScript

无服务器数据库

Neon PostgreSQL：

• 数据库分支（类似 Git）
• 计算资源可缩至零
• 完全兼容 PostgreSQL

Turso SQLite：

• 边缘部署（200 多个位置）
• 亚毫秒级读取
• libSQL（SQLite 分支）

PlanetScale MySQL：

• 非阻塞式架构变更
• 由 Vitess 驱动
• 按行计价

有关比较和集成，请参阅 references/serverless-dbs.md。

边缘函数

Cloudflare Workers：

• 冷启动时间 <5ms（V8 隔离区）
• 200 多个边缘位置
• 每个请求 128MB 内存

Deno Deploy：

• 原生支持 TypeScript
• Web 标准 API
• 全球边缘网络（<50ms）

Hono 框架：

• 可在所有边缘运行时上运行
• 包大小为 14KB
• 以 TypeScript 为先

有关模式，请参阅 references/edge-functions.md。

最佳实践

安全

• 使用密钥管理（AWS Secrets Manager、Vault）
• 为服务间通信启用 mTLS
• 实施最小权限 IAM 角色
• 扫描容器映像中的漏洞

成本优化

• 对流量变化较大的场景使用无服务器数据库（缩至零）
• 在 Kubernetes 中启用水平 Pod 自动扩缩容（HPA）
• 为计算资源合理配置容量（CPU/内存）
• 对非关键工作负载使用竞价实例

性能

• 在靠近用户的位置部署（全球应用使用边缘函数）
• 使用 CDN 提供静态资源（CloudFront、Cloudflare）
• 实施缓存策略（Redis、CloudFront）
• 监控无服务器应用的冷启动时间

可靠性

• 实施健康检查（Kubernetes 存活/就绪探针）
• 设置自动扩缩容（HPA、Lambda 并发）
• 为关键服务采用多区域部署
• 实施熔断器和重试机制

故障排除

部署失败

Kubernetes Pod 启动失败：

1. 检查 Pod 日志：kubectl logs <pod-name>
2. 描述 Pod：kubectl describe pod <pod-name>
3. 验证资源限制和请求
4. 检查镜像拉取错误（imagePullSecrets）

无服务器冷启动过慢：

1. 减小打包体积（摇树优化、代码拆分）
2. 使用预置并发（AWS Lambda）
3. 考虑使用边缘函数（Cloudflare Workers）
4. 优化初始化代码

GitOps 同步错误（ArgoCD/Flux）：

1. 验证 Git 仓库访问权限
2. 检查清单是否有效（kubectl apply --dry-run）
3. 检查同步策略（prune、selfHeal）
4. 检查 ArgoCD/Flux 日志

性能问题

服务网格开销过高：

1. 考虑切换到 Linkerd（5-10%，而 Istio 为 25-35%）
2. 禁用不必要的功能
3. 评估是否需要服务网格

数据库连接池耗尽：

1. 增大连接池
2. 使用无服务器数据库（Neon 按需缩容至零）
3. 实现连接池（PgBouncer）

详细的故障排查指南请参阅 references/ 文件。

迁移模式

从手动管理迁移到 IaC

1. 清点现有基础设施
2. 从非关键环境开始（开发、预发布）
3. 使用 Pulumi/OpenTofu 将基础设施转化为代码
4. 在生产环境部署前先在预发布环境测试
5. 逐步迁移（每次迁移一项服务）

从 Terraform 迁移到 OpenTofu

# Install OpenTofu
brew install opentofu

# Migrate state
terraform state pull > terraform.tfstate.backup
tofu init -migrate-state
tofu plan
tofu apply

完整的迁移指南请参阅 references/opentofu-guide.md。

从 EC2 迁移到容器

1. 将应用容器化（创建 Dockerfile）
2. 在本地测试（Docker Compose）
3. 部署到预发布环境（ECS/Cloud Run/Kubernetes）
4. 监控性能和成本
5. 切换生产流量（蓝绿部署）

从容器迁移到无服务器

1. 找出无状态服务
2. 重构为适合无服务器的模式
3. 使用无服务器数据库（Neon/Turso）
4. 部署到 Lambda/Cloud Functions
5. 监控冷启动和成本

后续步骤

部署应用后：

• 设置可观测性（指标、日志、链路追踪）
• 实现 CI/CD 流水线（GitHub Actions、GitLab CI）
• 配置自动扩缩容和资源限制
• 设置灾难恢复和备份
• 编写事件响应运行手册

其他资源

• Pulumi 文档：https://www.pulumi.com/docs/
• OpenTofu 文档：https://opentofu.org/docs/
• ArgoCD 文档：https://argo-cd.readthedocs.io/
• Cloudflare Workers 文档：https://developers.cloudflare.com/workers/
• Neon 文档：https://neon.tech/docs/