volcengine-deploy

Volcengine 部署技能

在用户选择 ECS / VKE / veFaaS 和资源管理方式（cli 或 iac）后，将本地项目目录或远程 Git URL 部署到 Volcengine。保持部署执行务实：仅在用户选择 Terraform/IaC 或已有 IaC 工作流时使用 volcengine-iac；否则使用 ve CLI 和 .volcengine/created-resources.json。

---

0. 前置条件

Volcengine 身份验证由你调用的执行技能（volcengine-cli、volcengine-iac 或 volcengine-vefaas）检查。接受该技能所需的 AK/SK 环境变量，或在该技能支持时使用已配置的 CLI 配置文件；不要在此重复其严格的环境要求。

用户选择路径后检查工具：

模式	所需工具
ECS	ve、git、jq、curl；仅当用户开放 22 端口时需要 ssh；仅在使用 Docker 或 compose 打包时需要 docker/docker compose
VKE	ve、docker、kubectl、git、jq、curl
veFaaS	切换到/调用 volcengine-vefaas 技能，该技能会检查 vefaas、Node.js、身份验证、框架检测和部署命令

对于 ECS 工件传输和 TOS 存储桶，tosutil 是可选的。不要将其列为 volcengine-deploy 的硬性前置条件；如果未安装，在允许时使用 SSH/scp，或请用户提供现有工件 URL。

如果用户尚未选择模式，请内联运行 volcengine-prepare，或询问以下选项：

1. Deployment mode: ECS / VKE / veFaaS (recorded as `ecs` / `vke` / `vefaas`)
2. Resource strategy: new isolated project deploy-<repo>, or reuse existing resources
3. Resource management: CLI resource ledger / Terraform IaC (recorded as `cli` / `iac`)

持久化本地状态位于仓库根目录的 .volcengine/ 下：

.volcengine/
  deployment-plan.md       # human-readable approval gate
  deploy-choice.json
  created-resources.json   # CLI fast path only
  iac-outputs.json
  terraform/               # IaC-managed resources

---

步骤

此表为导航概览。详细规则见 Details 中指定的章节或参考文件。

#	操作	详情
1	解析目标 — 解析本地路径或 Git URL；记录 repo_name、repo_dir 和 git_sha。	阶段 0
2	加载或选择路径 — 加载 .volcengine/deploy-choice.json；如果缺失，使用 volcengine-prepare 技能，或询问 mode、资源策略和资源管理方式。	阶段 0
3	创建计划 — 使用用户的原始语言创建/更新 .volcengine/deployment-plan.md。	references/deployment-plan-template.md
4	展示资源 — 列出所有要创建或复用的资源，例如 VPC、ECS、VKE、RDS、Redis、CR、EIP 或依赖项。	references/deployment-plan-template.md
5	验证关卡 — 在配置资源前，要求 status: validated、填写完整的 Validation Proof，以及 approval: granted 和非空的 approval_evidence。	references/deployment-plan-template.md
6	分派资源管理 — Terraform/IaC 使用 volcengine-iac 技能；否则使用 ve CLI 和 .volcengine/created-resources.json。	资源管理分派
7	配置资源 — 创建或复用资源；将每项由 CLI 创建的资源追加到 .volcengine/created-resources.json。	资源台账
8	接入运行时配置 — 解析配置和密钥；绝不打印密钥。	环境与依赖接入
9	执行部署 — 运行所选场景：ecs、vke，或使用 volcengine-vefaas 技能部署 vefaas。	分支参考
10	验证成功 — 尽可能检查公共端点、运行状况、日志和一项核心行为。	分支参考
11	处理失败 — 按逆序打印 CLI 清理命令；未经确认，绝不删除复用的资源。	资源台账
12	报告结果 — 打印 URL、运行状况、验收情况、日志、资源记录、清理路径和警告。	部署摘要

---

1. Stage 0 — 确定仓库和选择

input="${1:-.}"
if [[ "$input" =~ ^(https?|git@) ]]; then
  repo_name=$(basename "$input" .git)
  work_dir="/tmp/volcengine-deploy/$repo_name"
  mkdir -p "$work_dir"
  if [ -d "$work_dir/src/.git" ]; then
    git -C "$work_dir/src" pull --ff-only
  else
    git clone --depth 1 "$input" "$work_dir/src"
  fi
  repo_dir="$work_dir/src"
else
  repo_dir=$(cd "${input:-.}" && pwd)
  repo_name=$(basename "$repo_dir")
  work_dir="$repo_dir/.volcengine"
  mkdir -p "$work_dir"
fi
git_sha=$(cd "$repo_dir" && git rev-parse --short HEAD 2>/dev/null || echo "$(date +%s)")

本地目录会原地部署，不会克隆。对于 Git URL，先进行浅克隆；如果克隆反复失败，则尝试归档文件／子目录路径，或停止并明确提示“此项目不适合快速远程构建”。不得声称 README／静态镜像就是已部署的应用程序。

如果 .volcengine/deploy-choice.json 存在，则加载该文件。该文件由 volcengine-prepare 生成，并由其确保选择项的 schema 保持权威；volcengine-deploy 只使用选定的仓库、区域、模式、端口、依赖项、数据库选择、资源策略、项目和 infra_management。

如果缺少 .volcengine/deploy-choice.json，则运行 volcengine-prepare，或仅询问创建该文件所需的缺失决策。不要在此技能中维护第二套完整的选择项 schema。

加载或创建选择文件后，创建或更新 .volcengine/deployment-plan.md；先阅读 references/deployment-plan-template.md。计划正文必须使用用户的原始语言，列出预期资源，并要求 status: validated、approval: granted 和非空的 approval_evidence 均满足后，才可配置资源。

如果 approval 为 pending，创建资源前请使用与用户相同的语言进行确认：

Deploying <repo_name> via <mode> in <region>.
Resource plan:
- <create|reuse> <resource type>: <name>, <purpose/exposure/cleanup>
Proceed? [y/N]

---

2. 资源清单

资源清单仅用于 CLI 创建的资源。IaC 创建的资源由 Terraform 状态跟踪，并导出到 .volcengine/iac-outputs.json。

volcengine-deploy 创建的每项资源都必须在创建后立即追加到 .volcengine/created-resources.json。这是清理和故障恢复的强制要求。

清单条目：

{
  "type": "eip",
  "id": "eip-xxxx",
  "name": "deploy-myapp-eip",
  "region": "cn-beijing",
  "project": "deploy-myapp",
  "reused": false,
  "created_at": "2026-05-29T00:00:00Z",
  "delete_command": "ve vpc ReleaseEipAddress --AllocationId eip-xxxx"
}

规则：

• 新资源：设为 reused=false，并包含准确的删除命令。
• 复用的资源：设为 reused=true，不得将其纳入破坏性清理。
• 如果 EIP 随 ECS 实例一并创建并随该实例释放，则将其标记为 dependent=true / cleanup_optional=true，或不将其作为独立的清单条目。不得仅因实例已释放 EIP 而导致清理失败。
• 发生故障时，按清单顺序的逆序打印清理命令。目前没有一键清理工具；用户必须手动审核并运行清单中的 delete_command 值。未经用户确认，不得静默删除。
• 新建资源时，优先创建或使用名为 deploy-<repo> 的独立火山引擎项目，但在将该项目名称传给资源创建操作之前，须确认项目已存在或可以创建。如果无法创建项目，则使用 default，并通过名称和标签隔离资源。

---

3. 资源管理分发

部署计划审批关卡

创建云资源需要付费，且无法轻易撤销，因此计划的 frontmatter 会记录两个独立事实：

• status：draft | validated — 验证检查是否通过。
• approval：pending | granted — 用户是否授权创建资源。
• approval_evidence：引用用户授权用语；此项为空时，approval: granted 无效。

只有同时满足以下所有条件，才能创建、修改或复用资源：status: validated，Validation Proof 部分已填写实际检查，且没有未通过的必需检查，approval: granted，并且 approval_evidence 非空。否则应停止并先完成审批关卡。

规则：

• approval_evidence 必须引用用户授权执行的原话——“just deploy it”、“open the resources for me”、“go ahead”。“use ecs”这样的配置选择属于选项选择，而非费用授权，不得作为证据。
• 没有真实授权用语时，绝不能将 approval: granted 设为已授权；如果缺少必需决策或密钥，或者某项检查并未实际运行，也绝不能将 status: validated 设为已验证——应将未运行的检查记录为 deferred，并说明原因，而不是伪造 pass。
• 如果用户授权自主部署（“deploy it for me”、“资源也帮我开好”、“go ahead and deploy”），则展示一次资源计划，使用该原话将 approval 设为 granted，随后继续执行，不要在创建每项资源之前打断用户。只有用语明确授权部署或创建资源，而非仅选择模式时，才将其视为授权。
• 如果计划的核心内容发生变化——mode、region、infra_management 或资源计划——则将 status 重置为 draft，将 approval 重置为 pending，将 approval_evidence 重置为 ""，重新展示资源计划，并再次征求授权。

在配置资源之前，根据 .volcengine/deploy-choice.json 中的 infra_management 进行分派。volcengine-prepare 负责提供 cli 与 iac 的建议并记录用户选择；此技能只使用该选择。

infra_management	操作
iac	使用 volcengine-iac（见下文 使用 IaC 时）。
cli	使用 ve CLI 和资源台账（见下文 使用 CLI 时）。

如果缺少 infra_management 或其值无效，请勿在此处推断默认值。返回 volcengine-prepare，或请用户选择 cli 或 iac，然后更新 .volcengine/deploy-choice.json 并刷新 .volcengine/deployment-plan.md。

使用 IaC 时：

1. 使用 .volcengine/deploy-choice.json 调用或切换到 volcengine-iac。
2. 在该技能下运行 Terraform 生成、验证、计划和明确的应用确认。
3. 使用 .volcengine/iac-outputs.json 中的 VPC/子网/安全组/集群/CR/数据库/缓存输出。
4. 在此继续部署打包和运行时步骤：构建/拉取镜像、运行 Cloud Assistant、应用 Kubernetes 清单、运行迁移并验证运行状况。

使用 CLI 时：

1. 直接使用 ve 创建资源。
2. 创建的每项资源都要立即追加到 .volcengine/created-resources.json。
3. 失败时打印按创建顺序逆序排列的清理命令。

---

4. 环境与依赖配置

在启动 ECS 服务或应用 Kubernetes 清单之前，先解析运行时配置：

1. 读取 .env.example、.env.sample、框架配置，以及通过 IaC/CLI 配置获得的依赖项输出。
2. 将非敏感值放入配置，将敏感值放入密钥。连接字符串、密码、令牌、AK/SK 和会话令牌都应视为密钥。
3. 向用户询问缺失的必需值。不要向用户回显密钥值，不要将其写入日志，并将生成的本地文件权限设为 0600。
4. 对于 ECS systemd，在启动服务前写入 /opt/<repo>/.env；单元模板通过 EnvironmentFile=-/opt/<repo>/.env 读取该文件。
5. 对于 VKE，根据解析出的值生成 ConfigMap 和 Secret 清单。应用的 Secret 中绝不能保留 <connection-string> 占位符。

托管依赖配置必须在健康检查之前完成：

• RDS 数据库（database_product=rds，引擎为 mysql / postgresql / sqlserver）：创建或复用实例、数据库和应用账户；使用私有端点；构建 DATABASE_URL；将 ECS/VKE 子网 CIDR 或安全组来源添加到数据库允许列表；当 migration_paths 非空时，显式运行迁移。
• AIDAP 数据库（database_product=aidap，引擎为 supabase / postgresql）：调用 volcengine-db-supabase 创建或复用工作区、分支、应用 DB 账户/数据库，并在应用健康检查之前返回数据库/AIDAP 环境变量值。
• Redis：创建或复用实例以及应用账户/密码；使用私有端点；构建 REDIS_URL；将 ECS/VKE 子网 CIDR 或安全组来源添加到 Redis 允许列表。
• 如果用户拒绝为已检测到的依赖使用托管服务，应说明持久化/扩展方面的取舍，并通过相同的环境变量/Secret 路径配置用户选择的替代方案。

---

5. 分支调度

case "$deploy_mode" in
  ecs)  proceed_ecs ;;
  vke)  proceed_vke ;;
  vefaas) run_vefaas_skill ;;
  *)    echo "Unknown deploy mode: $deploy_mode"; exit 2 ;;
esac

---

6. ECS 分支

ECS 是默认的轻量级 VM 部署路径。公共服务必须分配 EIP，以便用户在部署后访问服务。

根据仓库结构选择打包方式：有 compose 文件 -> 在 ECS 上使用 compose；有 Dockerfile -> 在 ECS 上使用 Docker；有明确的二进制文件或单进程 -> 使用二进制文件 + systemd；否则，提出一个聚焦于启动命令的问题。

在主上下文中严格遵守以下边界：

• 当 infra_management=iac 时使用 IaC 输出；否则使用 CLI 记录路径，并立即记录每个通过 CLI 创建的资源。
• 不要硬编码实例类型或 OS 镜像。查询可用选项，并避免使用会匹配到 GPU、WebUI、市场或无关镜像的模糊匹配。
• 如果未明确批准开放 SSH 22 端口，就保持其关闭并使用 Cloud Assistant。如果已批准 SSH，则尽可能将其限制为当前出站 IP。
• Volcengine RunCommand 为异步操作。将命令视为成功之前，先轮询调用结果。
• 生成的一次性 ECS 密码不得打印，也不得写入记录/状态。
• 尽可能验证监听端口、本地健康检查/根路径、公共端点、日志，以及一项核心应用行为。

有关 ECS 打包、上传、Cloud Assistant、Docker 镜像源、架构、健康检查门槛和清理工作流的详细信息，请参阅 references/ecs-deploy-steps.md。

---

7. veFaaS 分支

此处不要重复 veFaaS 部署详情。如果用户选择 veFaaS，请切换到/调用 volcengine-vefaas 技能，并提供以下信息：

• 仓库路径
• 应用名称
• 地域
• 已知时的框架/端口
• 环境变量说明
• prepare 阶段的任何警告

告知用户，volcengine-vefaas 技能将运行 vefaas inspect、验证登录状态、创建/关联应用、按需配置环境变量、部署并打印域名。

如果 volcengine-vefaas 技能失败，则返回此主部署流程。概述失败情况，然后让用户选择：

• 修复 veFaaS 问题并重试，
• 切换到 ECS，
• 切换到 VKE。

---

8. VKE 分支

建议使用 volcengine-iac 配置 VKE 资源，因为集群、节点池、CR、LB 和托管依赖项都能从计划、差异对比和销毁安全性中受益。若用户了解权衡后选择 CLI、需要临时验证、明确偏好 CLI，或将 IaC 作为后备方案，则使用 ve CLI 和资源台账。

选择 VKE 后，检查 docker、kubectl、ve，以及使用 IaC 时所需的 terraform/jq。根据节点架构构建镜像；除非集群数据证明应使用其他架构，否则默认使用 linux/amd64；部署前检查已推送镜像的平台。

按顺序执行以下流程骨架——这些操作必须依次串联执行；在较早步骤收敛前运行后续步骤，是 VKE 最常见的故障原因：

1. 配置或复用 VKE 和 CR（使用 IaC 输出或 CLI 快速路径）。
2. 等待集群状态变为 Running，然后获取 kubeconfig（通过 IaC 输出或 CreateKubeconfig）。
3. 验证插件：确认存在 core-dns；拉取私有 CR 镜像时，优先使用 cr-credential-controller。
4. 根据节点架构构建镜像。
5. 向 CR 进行身份验证、推送镜像，并检查已推送镜像的平台。
6. 解析环境变量/Secret 值和依赖项输出。
7. 根据解析后的值生成清单。
8. 存在迁移路径时，使用 Kubernetes Job 运行迁移。
9. 应用清单，然后等待工作负载完成滚动更新以及 LoadBalancer/EIP 就绪。
10. 验证公网端点和一项核心应用行为。

在主上下文中严格遵守以下边界：

• 有可用的 IaC 输出时，使用其中的 VPC/子网/安全组/VKE/CR 信息；否则，通过 CLI 快速路径创建或复用资源，并记录资源。
• 集群状态变为 Running 前调用 CreateKubeconfig 会返回 OperationDenied——先轮询至 Running。
• 在依赖集群内 DNS 前，确认 core-dns 已就绪。
• 拉取私有 Volcengine CR 镜像时，优先使用 cr-credential-controller，不要将镜像仓库密码存入应用清单。
• 使用 GetAuthorizationToken 获取 Result.Username，并在 docker login 时重新读取；绝不要编造备用用户名。
• 应用工作负载前解析 ConfigMap/Secret 值；应用的 Secret 清单中绝不能保留占位符。
• 存在迁移路径时，使用 Kubernetes Job 运行迁移。
• 等待滚动更新和 LoadBalancer/EIP 就绪，然后验证公网端点。

对于托管依赖项，实际可行时优先使用 Volcengine 托管服务；否则，明确说明计划会在 VKE 内部署有状态容器。

阅读 references/vke-deploy-steps.md，了解完整的 VKE 流程（集群等待、kubeconfig、插件检查、CR 身份验证和推送、滚动更新、端点验证）；清单模板见 references/k8s-manifests.md，镜像构建模板见 references/dockerfile-templates.md。

---

9. 部署摘要

打印一张访问卡片：

volcengine-deploy — <repo_name> (<git_sha>)

Mode:        <ecs|vke|vefaas>
Region:      <region>
Project:     <deploy-project or reused resources>
URL:         <public endpoint>
Health:      <checked URL/status>
Acceptance:  <core app behavior checked, or reason only transport health was possible>
Resources:   .volcengine/created-resources.json
IaC:         <.volcengine/terraform + .volcengine/iac-outputs.json | n/a>
Logs:        <journalctl / docker logs / kubectl logs / vefaas logs command>
Cleanup:     <reverse-order cleanup commands or ledger path>
Notes:       <credentials/env/migration warnings>

除非用户提出要求，否则不要添加自定义域名、HTTPS、仪表板或费用卡片；这些属于 day-2 任务。

---

10. 参考详情

按需使用以下参考资料：

• 配置资源前务必阅读：部署计划模板、门槛和资源计划，见 references/deployment-plan-template.md
• ECS 构建、systemd 和上传详情：references/ecs-deploy-steps.md
• VKE 部署流程（集群/kubeconfig/插件/CR/滚动更新）：references/vke-deploy-steps.md
• veFaaS 部署交接详情：references/faas-deploy-steps.md
• Dockerfile 模板：references/dockerfile-templates.md
• Kubernetes 清单：references/k8s-manifests.md
• 运行时依赖项：references/supported-dependencies.md

---

11. 常见故障模式

我们有意保留常见注意事项作为参考，以便主要技能保持灵活：

• ECS 实例／镜像／Cloud Assistant／SSH／Docker 镜像问题：references/ecs-deploy-steps.md
• 容器架构和 Dockerfile 常见问题：references/dockerfile-templates.md
• VKE 流水线的步骤顺序（kubeconfig／addons／CR 身份验证／rollout）：references/vke-deploy-steps.md
• Kubernetes 就绪状态、LoadBalancer、探针和清单问题：references/k8s-manifests.md
• 托管依赖项的接入和迁移：references/supported-dependencies.md
• veFaaS CLI／身份验证／框架配置：references/faas-deploy-steps.md 和 volcengine-vefaas
• 部署期间的权限／角色／STS 错误：启用 volcengine-troubleshooting 技能，并使用其账号权限诊断能力定位根本原因，指导用户完成修复