Qovery Engine 实战：用 Rust 统一多云部署，简化云原生应用交付

1. 从零到一：理解 Qovery Engine 的核心价值

如果你和我一样，在云原生和 DevOps 这条路上摸爬滚打了好些年，那你一定对“部署”这件事又爱又恨。爱的是，容器化、Kubernetes、IaC（基础设施即代码）这些技术栈确实让我们的应用交付能力上了好几个台阶；恨的是，为了把这些技术栈串联起来，让一个应用从代码仓库真正跑在云端，我们往往需要和 AWS、Terraform、Helm、Kubectl 等一大堆工具打交道，配置复杂，学习曲线陡峭，一个环节出错就可能前功尽弃。我最初接触 Qovery Engine，就是被它“在几分钟内将应用部署到任何云”的口号所吸引。经过一段时间的深度使用和源码研究，我发现它远不止是一个部署工具，而是一个设计精巧的“抽象层引擎”，它试图用 Rust 语言的高效与安全，封装掉云原生部署中所有繁琐的“管道工程”。

简单来说，Qovery Engine 是一个用 Rust 编写的开源库。它的核心目标不是替代 Kubernetes 或 Terraform，而是站在它们的肩膀上，提供一个更高层次的、统一的抽象。你可以把它想象成一个“万能适配器”或者“智能编排中枢”。你告诉它：“我想把这个 GitHub 上的 Node.js 应用，用 1 核 2G 的配置，部署到我的 AWS 账户里，并自动配置好 HTTPS。” 剩下的工作，比如在 AWS 上创建 EKS 集群、配置 VPC 网络、在 ECR 创建镜像仓库、用 Helm 部署应用、用 Cloudflare 配置 DNS 解析，Qovery Engine 会帮你全部搞定。它通过内部协调 Terraform 来管理基础设施（如 K8s 集群），协调 Helm 来部署应用，协调 Kubectl 来操作集群，而所有这些都是通过一个统一的、可编程的 Rust API 来完成的。

这解决了什么痛点呢？首先，它极大地降低了多云部署的复杂度。团队不再需要为 AWS、GCP、Azure 分别维护一套部署脚本和知识体系。其次，它实现了部署流程的代码化和版本化。你的整个基础设施和应用部署定义，都可以作为 Rust 代码（或通过其 CLI/Web 界面生成的配置）纳入版本控制。最后，也是我认为最重要的一点，它将最佳实践内化到了引擎中。比如，默认创建的是托管的 Kubernetes 服务（如 EKS、GKE），默认配置了合理的网络策略和自动扩缩容，这避免了许多因为初期配置不当而导致的安全隐患和性能瓶颈。

注意：虽然 Qovery Engine 旨在简化，但它本身并不是一个无服务器平台。它仍然要求你对容器、Kubernetes 基本概念和所使用的云服务商（如 AWS IAM）有基础了解。它的简化，体现在“编排”和“集成”层面，而非完全隐藏底层细节。

2. 架构深度解析：引擎如何统一多云部署

要真正用好 Qovery Engine，不能只停留在“黑盒”调用，理解其内部架构和工作原理至关重要。这能帮助你在出问题时快速定位，也能让你更灵活地定制部署流程。

2.1 核心设计哲学：抽象层与插件化

Qovery Engine 的架构核心是“抽象”与“插件化”。它定义了一套清晰的内部接口（Trait），将部署过程中涉及的各种实体和操作标准化。

1. 基础设施抽象：它将不同的云服务商（AWS、GCP、Azure）抽象为统一的CloudProvider接口。无论底层是调用 AWS SDK 还是 Google Cloud Client Library，上层业务代码看到的都是“创建集群”、“获取存储桶”等统一方法。
2. 部署单元抽象：它将应用（Application）、数据库（Database）、环境（Environment）等概念进行建模。一个“环境”对应一个命名空间（Namespace），里面可以包含多个应用和数据库实例。
3. 流程插件化：这是其强大扩展性的来源。构建平台（CI）、容器仓库、DNS 服务、监控服务都被设计为插件。例如，构建应用镜像时，你可以选择使用 Qovery 内置的 CI，也可以插件式地接入 GitHub Actions 或 GitLab CI。这种设计意味着你可以像搭积木一样，组合出最适合自己技术栈的部署流水线。

其工作流程可以概括为下图所示的几个阶段（注：此处以文字描述替代图表）：

• 解析阶段：引擎读取你的应用配置（Dockerfile 路径、资源需求、环境变量等）和基础设施配置（目标云厂商、区域等）。
• 协调阶段：这是引擎的“大脑”。它根据配置，按正确顺序决定需要调用哪些插件和执行哪些操作。例如，它会先确保目标 Kubernetes 集群存在（调用 Terraform），然后构建并推送镜像（调用 Docker/CI 插件），最后部署应用到集群（调用 Helm）。
• 执行与监控阶段：引擎驱动具体的二进制工具（Terraform, Helm, Kubectl）或调用插件 API 来执行实际任务，并持续监控执行状态，处理回滚等异常情况。

2.2 关键技术栈选型的背后逻辑

为什么是 Rust + Terraform + Helm + Kubectl 这个组合？这体现了 Qovery 团队务实的技术选型观。

• Rust (引擎核心)：官方 FAQ 提到了“高效、性能、安全”。在实际使用中，我的体会是，Rust 的“零成本抽象”和强类型系统，对于构建一个需要高可靠性和长期维护的基础设施引擎至关重要。内存安全特性避免了部署脚本中常见的内存错误，而优秀的并发处理能力（async/await）让引擎可以高效地协调多个异步任务（如并行创建多个云资源）。此外，编译成单一二进制文件，分发和依赖管理极其简单。
• Terraform (基础设施管理)：这是业界的实际标准。用 Terraform 管理云资源（VPC, EKS, 数据库实例）意味着基础设施状态是可声明、可版本化、可复现的。Qovery Engine 没有重复造轮子，而是选择生成并执行 Terraform 代码，这既利用了成熟的生态，也使得熟悉 Terraform 的工程师可以轻松理解和调试 Qovery 创建的资源。
• Helm (应用部署)：同样，Helm 是 Kubernetes 生态中事实上的包管理标准。使用 Helm Chart 来部署应用，意味着你可以利用海量的社区 Chart，也可以将自己的应用打包成标准的、参数化的 Chart，部署的灵活性和可复用性大大增强。
• Kubectl (集群操作)：作为与 Kubernetes API 交互的最直接工具，用于一些 Helm 覆盖不到的细粒度操作或状态检查，是必要的补充。

这个技术栈的选择，本质上是在“创新”和“稳定”之间找到了一个平衡点。引擎核心用 Rust 追求极致控制和性能，而外围的“脏活累活”则交给久经考验的社区工具。作为使用者，你获得的是一个既前沿又稳固的基石。

3. 实战演练：亲手部署一个应用到 AWS

理论说得再多，不如动手一试。我们以一个最简单的 Node.js 应用为例，完整走一遍使用 Qovery Engine Rust 库将其部署到 AWS 的流程。假设你已经有一个 AWS 账户，并配置好了具有足够权限的 IAM 用户 Access Key 和 Secret Key。

3.1 环境准备与项目初始化

首先，你需要一个 Rust 开发环境。如果你还没有安装，可以通过rustup工具轻松安装。

# 安装 Rust (如果未安装) curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env # 创建一个新的 Rust 二进制项目 cargo new qovery-deploy-demo cd qovery-deploy-demo

接下来，编辑Cargo.toml文件，添加 Qovery Engine 作为依赖。由于引擎正在快速迭代，我们直接从其 GitHub 主分支拉取。

[package] name = "qovery-deploy-demo" version = "0.1.0" edition = "2021" [dependencies] qovery-engine = { git = "https://github.com/Qovery/engine", branch = "main" } tokio = { version = "1", features = ["full"] } # Qovery Engine 使用异步，需要异步运行时 anyhow = "1.0" # 用于简单的错误处理

提示：直接依赖 Git 主分支在快速原型阶段是可行的，但对于生产环境，强烈建议锁定到某个具体的发布版本（Tag），以保证部署行为的确定性。你可以查看项目的 Release 页面或使用特定的 commit hash。

3.2 编写部署代码：从创建集群到部署应用

现在，我们在src/main.rs中编写核心部署逻辑。代码将分为两大步：第一步，初始化 AWS 基础设施（EKS 集群和 ECR 仓库）；第二步，部署我们的应用。

首先，我们需要构建引擎运行所需的上下文（Context）和各种初始化组件。为了清晰，我将代码拆解并加上详细注释。

use anyhow::Result; use qovery_engine::{ cloud_provider::aws::AWS, container_registry::ecr::ECR, dns_provider::cloudflare::Cloudflare, engine::{CloudProvider, ContainerRegistry, DnsProvider, Engine, GetSession}, infrastructure::kubernetes::Kind as KubernetesKind, io_models::context::Context, logger, models::{ application::Application, cloud_provider::{CloudProvider as CloudProviderTrait, Kind as CloudProviderKind}, container_registry::Kind as ContainerRegistryKind, dns_provider::Kind as DnsProviderKind, environment::Environment, types::{Action, EnvironmentAction}, }, transaction::{TransactionResult, TransactionType}, }; use std::sync::Arc; use url::Url; #[tokio::main] async fn main() -> Result<()> { // 1. 初始化日志，便于调试 let logger = logger::Logger::new("info".to_string(), "my-deployment".to_string()); logger.info("开始 Qovery Engine 部署流程"); // 2. 构建上下文 (Context) // Context 包含了这次部署的元信息，如项目ID、环境名称、执行ID等。 let context = Context { id: "my-project-id".to_string(), name: "My Demo Project".to_string(), organization_id: "my-org".to_string(), organization_long_id: uuid::Uuid::new_v4(), project_id: "my-project".to_string(), project_long_id: uuid::Uuid::new_v4(), environment_id: "prod".to_string(), environment_long_id: uuid::Uuid::new_v4(), execution_id: uuid::Uuid::new_v4(), cluster_id: "my-eks-cluster".to_string(), cluster_long_id: uuid::Uuid::new_v4(), user_id: "engine-user".to_string(), user_email: "dev@example.com".to_string(), cloud_provider: CloudProviderKind::Aws, kubernetes: KubernetesKind::Eks, logger: Arc::new(logger), ..Default::default() // 使用其他字段的默认值 }; // 3. 初始化各个插件/提供商 // 注意：以下所有密钥、ID等信息应从环境变量或安全配置管理服务中读取，切勿硬编码！ let aws_provider = AWS::new( context.clone(), "my-aws-resource-id".to_string(), "us-east-1".to_string(), // AWS 区域 "your-aws-access-key-id".to_string(), // 替换为你的 Access Key "your-aws-secret-access-key".to_string(), // 替换为你的 Secret Key None, // 可选：角色ARN ); let ecr_registry = ECR::new( context.clone(), "my-ecr-id".to_string(), ContainerRegistryKind::Ecr, "us-east-1".to_string(), "your-aws-access-key-id".to_string(), "your-aws-secret-access-key".to_string(), ); // 假设我们使用 Cloudflare 管理 DNS let cloudflare_dns = Cloudflare::new( context.clone(), "my-cloudflare-id".to_string(), DnsProviderKind::Cloudflare, "your-cloudflare-api-token".to_string(), // 替换为你的 API Token "example.com".to_string(), // 你的域名 None, ); // 4. 创建引擎实例 // 这里我们使用本地 Docker 作为构建平台。对于生产环境，可以考虑集成到云 CI。 let local_docker = qovery_engine::build_platform::docker::Docker::new(context.clone()); let engine = Engine::new( context, local_docker, ecr_registry, aws_provider, cloudflare_dns, ); // 5. 获取会话 (Session) // Session 是与特定目标环境（云账户+集群）建立的一个有状态连接。 let session = match engine.session().await { Ok(s) => { println!("✅ 引擎会话创建成功"); s } Err(e) => { eprintln!("❌ 创建会话失败: {:?}", e); std::process::exit(1); } }; // 6. 开始一个事务 (Transaction) // 事务确保一系列操作要么全部成功，要么在失败时回滚。 let mut tx = session.transaction(); println!("🔄 开始基础设施创建事务..."); // 6.1 定义我们要创建的 EKS 集群配置 let eks_config = qovery_engine::models::aws::EksCluster { id: "my-eks".to_string(), name: "my-eks-cluster".to_string(), region: "us-east-1".to_string(), version: "1.28".to_string(), // 指定 K8s 版本 node_groups: vec![qovery_engine::models::aws::NodeGroup { name: "ng-1".to_string(), instance_type: "t3.medium".to_string(), desired_capacity: 2, min_capacity: 1, max_capacity: 3, disk_size_gb: 20, }], ..Default::default() }; // 请求创建集群 tx.create_kubernetes(&eks_config); // 提交事务，引擎将开始实际创建资源 match tx.commit().await { TransactionResult::Ok => println!("🎉 EKS 集群创建成功！"), TransactionResult::Rollback(err) => { eprintln!("⚠️ 创建失败但已回滚: {:?}", err); std::process::exit(1); } TransactionResult::UnrecoverableError(commit_err, rollback_err) => { eprintln!("💥 严重错误！创建失败且回滚也失败: {:?}, {:?}", commit_err, rollback_err); std::process::exit(1); } }; // 7. 基础设施就绪后，部署应用 deploy_application(session).await?; Ok(()) } async fn deploy_application(session: impl GetSession) -> Result<()> { println!("\n🚀 开始部署应用程序..."); // 1. 定义要部署的环境 let mut environment = Environment { id: "prod-env".to_string(), name: "Production".to_string(), project_id: "my-project".to_string(), organization_id: "my-org".to_string(), cloud_provider: CloudProviderKind::Aws, kubernetes: KubernetesKind::Eks, ..Default::default() }; // 2. 定义要部署的应用程序 let app = Application { id: "node-simple-app".to_string(), name: "node-simple-example".to_string(), action: Action::Create, // 执行创建操作 git_url: "https://github.com/Qovery/node-simple-example.git".to_string(), git_credentials: None, // 公有仓库，无需凭证 branch: "main".to_string(), commit_id: None, // 不指定特定提交，则部署分支的最新提交 dockerfile_path: "Dockerfile".to_string(), // Dockerfile 在仓库根目录 private_port: Some(3000), // 应用内部监听端口 total_cpus: "0.5".to_string(), // 申请 0.5 个 CPU 核心 cpu_burst: "1.0".to_string(), // 突发限制 total_ram_in_mib: 512, // 申请 512 MiB 内存 min_instances: 1, max_instances: 2, storage: vec![], // 无持久化存储 environment_variables: vec![ ("NODE_ENV".to_string(), "production".to_string()), ("LOG_LEVEL".to_string(), "info".to_string()), ], // 设置环境变量 }; // 3. 将应用添加到环境中 environment.applications.push(app); // 4. 开启一个新事务来部署环境 let mut tx = session.transaction(); tx.deploy_environment(&EnvironmentAction::Environment(environment)); // 5. 提交部署事务 match tx.commit().await { TransactionResult::Ok => println!("🎉 应用程序部署成功！"), TransactionResult::Rollback(err) => { eprintln!("⚠️ 部署失败但已回滚: {:?}", err); std::process::exit(1); } TransactionResult::UnrecoverableError(commit_err, rollback_err) => { eprintln!("💥 严重错误！部署失败且回滚也失败: {:?}, {:?}", commit_err, rollback_err); std::process::exit(1); } }; Ok(()) }

这段代码是一个完整的示例。运行cargo run之前，请务必：

1. 将your-aws-access-key-id和your-aws-secret-access-key替换为你有足够权限的 AWS IAM 用户密钥。
2. 如果你使用 Cloudflare，替换your-cloudflare-api-token和example.com。
3. 确保你的 AWS 账户在us-east-1区域有创建 EKS 集群的配额和权限。

重要安全提示：永远不要将云服务商的 Access Key/Secret Key 或 API Token 硬编码在源代码中！上述代码仅为演示。在生产环境中，应使用环境变量（如AWS_ACCESS_KEY_ID）、IAM 角色（对于在 AWS 内部运行的代码）或专业的密钥管理服务（如 AWS Secrets Manager, HashiCorp Vault）来安全地管理这些凭证。你可以在初始化AWS或Cloudflare对象时，从std::env::var读取环境变量。

3.3 代码执行与结果验证

当你运行cargo run后，Qovery Engine 会开始工作。这个过程可能需要 10 到 20 分钟，因为创建 EKS 集群本身就需要时间。引擎会在终端输出详细的日志，你可以看到它正在执行哪些 Terraform 步骤、构建 Docker 镜像、推送镜像到 ECR、以及执行 Helm 安装。

部署成功后，如何访问你的应用呢？Qovery Engine 在部署应用时，默认会创建一个 KubernetesLoadBalancer类型的 Service。你需要：

1. 使用 AWS CLI 或控制台，查看你的 EKS 集群。
2. 使用kubectl连接到该集群（Qovery 创建的集群，其 kubeconfig 通常会自动配置或可通过引擎 API 获取）。
3. 运行kubectl get svc -n <environment-namespace>命令，找到你的应用对应的 Service，其EXTERNAL-IP列就是 AWS 为你分配的负载均衡器地址。
4. 在浏览器中访问http://<EXTERNAL-IP>:3000，你应该能看到示例 Node.js 应用的页面。

如果你配置了 Cloudflare DNS 插件，并且提供了域名，引擎还会自动为你创建 DNS 记录，将子域名指向这个负载均衡器，并可能协助配置 HTTPS 证书（通过 Let‘s Encrypt 等），实现通过域名直接访问。

4. 进阶配置与插件生态运用

基础部署跑通后，我们来看看如何利用 Qovery Engine 的插件化特性，打造更贴合企业需求的部署流水线。

4.1 集成外部 CI/CD：以 GitHub Actions 为例

虽然 Qovery Engine 内置了构建能力，但很多团队已有成熟的 CI/CD 流程。这时，你可以将其作为一个“部署器”集成进去。以下是一个 GitHub Actions 工作流的示例，它在代码推送后，使用 Qovery Engine CLI（一个封装了引擎功能的命令行工具）来触发部署。

# .github/workflows/deploy.yml name: Deploy to AWS via Qovery Engine on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v3 - name: Setup Rust uses: actions-rs/toolchain@v1 with: toolchain: stable - name: Install Qovery CLI run: | curl -sSL https://get.qovery.com | bash echo "$HOME/.qovery/bin" >> $GITHUB_PATH - name: Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v2 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} aws-region: us-east-1 - name: Deploy using Qovery CLI run: | # 假设你有一个预定义的部署配置文件 (qovery.yaml) qovery deploy --config qovery.yaml --environment production env: QOVERY_API_TOKEN: ${{ secrets.QOVERY_API_TOKEN }} # 如果需要认证

在这个流程中，GitHub Actions 负责代码检查、测试和构建镜像（如果你在 Actions 中构建），而 Qovery Engine（通过 CLI）专门负责将构建好的镜像部署到多云基础设施上。这种关注点分离的架构非常清晰。

4.2 配置自定义监控与日志

部署只是开始，可观测性同样关键。Qovery Engine 支持集成 Datadog、New Relic 等监控服务。配置通常是在环境或应用级别添加特定的环境变量或注解（Annotation）。

例如，要为你的应用启用 Datadog APM（应用性能监控），你可以在定义Application时，在environment_variables或一个专门的annotations字段中添加 Datadog 所需的配置：

let app = Application { // ... 其他字段同上 environment_variables: vec![ // ... 其他环境变量 ("DD_AGENT_HOST".to_string(), "datadog-agent.datadog.svc.cluster.local".to_string()), ("DD_ENV".to_string(), "production".to_string()), ("DD_SERVICE".to_string(), "node-simple-example".to_string()), ("DD_VERSION".to_string(), env!("CARGO_PKG_VERSION").to_string()), // 注入版本号 ], // 假设引擎支持通过 annotations 注入 sidecar 或配置 // annotations: Some(vec![ // ("ad.datadoghq.com/<container-name>.logs".to_string(), r#"[{"source": "node", "service": "webapp"}]"#.to_string()), // ]), ..Default::default() };

同时，你需要在你的 Kubernetes 集群中提前部署 Datadog Agent。这可以通过在 Qovery 环境配置中声明一个“Addon”或通过 Helm Chart 依赖来实现。Qovery Engine 的灵活之处在于，你可以通过编写自定义的 Helmvalues.yaml或 Terraform 模块，将这些第三方服务的安装也纳入引擎的管理范围，实现“一键部署应用及其完整的可观测性栈”。

4.3 管理多环境与配置差异化

真实的项目通常有开发、预发布、生产等多个环境。Qovery Engine 通过Environment模型来支持这一点。你可以为不同环境创建不同的Context和配置。

一个常见的模式是，使用相同的应用代码，但通过不同的环境变量和资源规格来区分环境。你可以编写一个函数来生成环境配置：

fn create_environment(env_name: &str, context: Context) -> Environment { let (node_instance_type, min_instances, max_instances) = match env_name { "production" => ("m5.large", 3, 10), "staging" => ("t3.medium", 2, 4), _ => ("t3.small", 1, 2), // development }; Environment { id: format!("{}-env", env_name), name: env_name.to_string(), cloud_provider: CloudProviderKind::Aws, kubernetes: KubernetesKind::Eks, // 这里可以传入不同的集群配置，或者使用同一个集群的不同命名空间 // 对于生产环境，强烈建议使用独立的、资源更充足的集群。 kubernetes_cluster: match env_name { "production" => "prod-eks-cluster".to_string(), _ => "shared-eks-cluster".to_string(), }, applications: vec![create_application(env_name)], // 应用配置也因环境而异 ..Default::default() } } fn create_application(env_name: &str) -> Application { let (cpus, memory_mib) = match env_name { "production" => ("1.0", 1024), "staging" => ("0.5", 512), _ => ("0.25", 256), }; Application { id: format!("myapp-{}", env_name), name: "myapp".to_string(), action: Action::Create, git_url: "https://github.com/your-org/your-repo.git".to_string(), branch: "main".to_string(), total_cpus: cpus.to_string(), total_ram_in_mib: memory_mib, min_instances: 1, max_instances: match env_name { "production" => 5, _ => 2, }, environment_variables: vec![ ("ENVIRONMENT".to_string(), env_name.to_string()), ("API_ENDPOINT".to_string(), match env_name { "production" => "https://api.prod.example.com".to_string(), "staging" => "https://api.staging.example.com".to_string(), _ => "https://api.dev.example.com".to_string(), }), ], ..Default::default() } }

通过编程方式管理多环境配置，可以实现部署流程的标准化和自动化，减少人为错误。

5. 避坑指南与疑难杂症排查

在实际使用中，我踩过不少坑，也总结了一些排查问题的经验。这里分享几个最常见的问题和解决思路。

5.1 权限不足导致的部署失败

这是新手最容易遇到的问题。Qovery Engine 需要相当广泛的权限来操作云资源。

• 症状：事务提交失败，Terraform 或 AWS SDK 报错，提示AccessDenied,UnauthorizedOperation或Forbidden。
• 根因：你提供的 AWS IAM 凭证所属的用户或角色，没有执行特定操作（如创建 EKS 集群、创建 IAM 角色、操作 EC2）的权限。
• 解决方案：
  1. 最小权限原则：不要直接使用 AdministratorAccess。为 Qovery Engine 创建一个专用的 IAM 策略。你可以参考 Qovery 官方文档中关于 AWS IAM 配置的部分，通常会提供一个详细的策略 JSON 示例，涵盖了创建和管理 EKS、ECR、VPC、IAM 等资源所需的所有权限。
  2. 仔细阅读错误信息：错误信息通常会明确指出是哪个 API 操作被拒绝（例如eks:CreateCluster）。根据这个信息去补充 IAM 策略。
  3. 使用 CloudTrail：在 AWS 控制台启用 CloudTrail，它可以记录所有的 API 调用，帮助你精确查看是哪个调用失败了，以及失败的原因。

5.2 网络配置与子网冲突

在已有 VPC 的环境中部署，或者跨可用区部署时，容易遇到网络问题。

• 症状：EKS 集群创建成功，但节点组（NodeGroup）创建失败；或应用 Pod 一直处于Pending状态，事件显示InsufficientSubnetCapacity或类似错误。
• 根因：Terraform 脚本尝试在指定的 VPC 和子网中创建资源，但子网 IP 地址耗尽，或子网标签不符合 EKS 要求（例如，子网需要明确打上kubernetes.io/cluster/<cluster-name>: shared的标签供 EKS 识别）。
• 解决方案：
  1. 规划 CIDR：提前规划好 VPC 和子网的 CIDR 块，确保有足够的 IP 地址。对于生产环境，建议为 EKS 集群使用独立的、足够大的子网。
  2. 检查子网标签：如果你指定了已有的 VPC/子网，确保这些子网已经按照 AWS EKS 的要求打上了正确的标签。
  3. 让 Qovery 管理网络：最简单的方法是，在配置中不指定 VPC 和子网 ID，让 Qovery Engine 自动创建和管理一套新的、符合规范的网络资源。这虽然增加了资源，但避免了兼容性问题。

5.3 镜像构建与推送失败

应用部署卡在“构建”或“推送”阶段。

• 症状：部署日志显示 Docker build 失败，或无法推送到 ECR 仓库。
• 根因：
  • Dockerfile 错误：代码仓库中的 Dockerfile 存在语法错误，或依赖的基础镜像不存在/无法拉取。
  • 网络问题：构建环境（如 GitHub Actions Runner）无法访问 Docker Hub 或你的私有镜像仓库。
  • ECR 权限问题：IAM 用户没有对 ECR 仓库进行PushImage的权限。
• 解决方案：
  1. 本地验证：在本地使用docker build -t test .和docker run test命令，确保 Dockerfile 本身是正确的。
  2. 检查网络：如果使用自托管 Runner 或公司内网，确保其有访问外部网络的权限。对于私有仓库，需要正确配置认证。
  3. 检查 ECR 权限：确保 IAM 策略包含ecr:GetAuthorizationToken,ecr:BatchCheckLayerAvailability,ecr:GetDownloadUrlForLayer,ecr:GetRepositoryPolicy,ecr:DescribeRepositories,ecr:ListImages,ecr:DescribeImages,ecr:BatchGetImage,ecr:InitiateLayerUpload,ecr:UploadLayerPart,ecr:CompleteLayerUpload,ecr:PutImage等操作权限。

5.4 应用部署后无法访问

集群和应用都显示运行中，但通过 LoadBalancer 的 IP 或域名无法访问。

• 症状：kubectl get pods显示 Pod 是Running状态，kubectl get svc显示EXTERNAL-IP已分配，但curl或浏览器访问超时或返回错误。
• 根因：
  • 安全组规则：AWS 为 LoadBalancer 自动创建的安全组，入站规则可能没有开放你的应用端口（如 3000）。
  • 应用未监听正确端口：Pod 内的应用没有监听你在Application配置中指定的private_port（如 3000），或者监听的是127.0.0.1而非0.0.0.0。
  • Ingress 或 Service 配置：如果你配置了自定义的 Ingress，可能存在路由规则错误。
• 排查步骤：
  1. 检查安全组：在 AWS EC2 控制台，找到 LoadBalancer 使用的安全组，检查入站规则是否允许来自0.0.0.0/0（或你的 IP）到应用端口的流量。
  2. 检查 Pod 日志：kubectl logs <pod-name> -n <namespace>查看应用是否有启动错误。
  3. 进入 Pod 调试：kubectl exec -it <pod-name> -n <namespace> -- sh，然后在容器内执行curl localhost:3000，确认应用在容器内是否可访问。
  4. 检查 Service：kubectl describe svc <service-name> -n <namespace>，确认Selector是否与 Pod 的标签匹配，以及Port和TargetPort配置是否正确。

5.5 引擎事务回滚与状态管理

Qovery Engine 的事务机制是一把双刃剑。它保证了原子性，但在复杂场景下，回滚可能不彻底。

• 经验之谈：
  • 监控事务状态：务必在你的部署脚本中处理TransactionResult::Rollback和TransactionResult::UnrecoverableError的情况，并记录详细的错误信息。回滚失败通常意味着有资源残留，需要手动清理。
  • 理解回滚粒度：引擎的回滚通常是针对“本次事务中创建的资源”。如果一个资源（比如一个 VPC）在之前的事务中创建，并在本次事务中被引用，那么本次事务失败通常不会删除那个 VPC。你需要理解 Terraform 的状态管理。
  • 定期清理：对于开发或测试环境，建议定期（例如每天）运行一个清理任务，使用引擎 API 或直接调用 Terraform 销毁命令，来清理所有资源，避免产生不必要的费用和资源碎片。

使用 Qovery Engine 是一个逐步深入的过程。从最简单的单应用部署开始，逐步尝试集成 CI/CD、配置监控、管理多环境。遇到问题时，多查看引擎输出的详细日志，并结合云服务商控制台（如 AWS Management Console）和kubectl命令进行联合排查。它的设计理念是“约定大于配置”，在大多数情况下遵循其默认的最佳实践就能获得很好的效果，但当你有特殊需求时，其底层基于 Terraform 和 Helm 的开放性又给了你足够的定制空间。