mcpField
E
eve-deploy-debugging

eve-deploy-debugging

github.com/incept5云与 DevOps0307 次安装17 周前更新
代码仓库

关于 eve-deploy-debugging

eve-deploy-debugging 是一项面向 Eve CLI 的技能，用于部署应用并诊断环境、任务、构建及系统问题。它为 Eve 平台运维提供部署检查和分步故障排查方法。

主要功能

  1. 01创建并部署环境
  2. 02跟踪流水线和任务进度
  3. 03诊断部署、构建及系统故障
  4. 04检查自定义域名状态和归属
  5. 05检查私有端点连通性

适用场景

  1. 01将应用部署到 staging
  2. 02排查无法启动或卡住的任务
  3. 03查找部署失败原因
  4. 04验证私有端点连接

安装

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

$npx skills add https://github.com/incept5/eve-skillpacks --skill eve-deploy-debugging

安装后在 Claude Code 中输入/eve-deploy-debugging确认已加载。

详细介绍

Eve 部署与调试

按照以下步骤快速部署并诊断应用问题。

环境设置

  • 向管理员获取暂存环境的 API URL。
  • 创建并使用配置文件：
eve profile create staging --api-url https://api.eve.example.com
eve profile use staging

基础设施变更政策

切勿对共享基础设施运行 kubectl apply、helm install 或直接创建任何 Kubernetes 资源。所有基础设施变更都必须通过 Terraform 完成。使用 Eve CLI（eve env、eve env deploy）管理应用部署，平台会处理底层的 k8s 资源。

部署流程（暂存环境）

# Create env if needed
eve env create staging --project proj_xxx --type persistent

# Deploy (requires --ref with 40-char SHA or a ref resolved against --repo-dir)
eve env deploy staging --ref main --repo-dir .

# When environment has a pipeline configured, the above triggers the pipeline.
# Use --direct to bypass pipeline and deploy directly:
eve env deploy staging --ref main --repo-dir . --direct

# Pass inputs to pipeline:
eve env deploy staging --ref main --repo-dir . --inputs '{"key":"value"}'
部署轮询流程

调用 eve env deploy 时：

  1. 直接部署（无流水线）：直接返回 deployment_status。轮询健康检查端点，直到 ready === true。
  2. 流水线部署：返回 pipeline_run_id。轮询 GET /pipelines/{name}/runs/{id}，直到所有步骤完成，然后检查健康状态。

满足以下条件时，部署完成：ready === true 且 active_pipeline_run === null。

观察部署

eve job list --phase active
eve job follow <job-id>              # Real-time SSE streaming
eve job watch <job-id>               # Poll-based status updates
eve job diagnose <job-id>            # Full diagnostic
eve job result <job-id>              # Final result
eve job runner-logs <job-id>         # Raw worker logs
实时调试（三终端方法）
# Terminal 1: Pipeline/job progress
eve job follow <job-id>

# Terminal 2: Environment health
eve env diagnose <project> <env>

# Terminal 3: System-level logs
eve system logs

调试工作流

任务无法启动
  1. 检查依赖项：eve job dep list <job-id>
  2. 检查是否被阻塞：eve job show <job-id> → 查看 blocked_by
  3. 验证环境是否就绪：eve env show <project> <env>
  4. 检查编排器：eve system orchestrator status
任务失败
  1. 获取错误信息：eve job diagnose <job-id>
  2. 检查日志：eve job follow <job-id> 或 eve job runner-logs <job-id>
  3. 如果构建失败：eve build diagnose <build-id>
  4. 如果密钥配置失败：eve secrets list --project <project_id>
任务卡在活动状态
  1. 检查是否正在等待输入：eve job show <job-id> → 查看 effective_phase
  2. 检查线程消息：eve thread messages <thread-id>
  3. 检查运行器 Pod：eve system pods
系统问题
  1. API 健康状态：eve system health
  2. 编排器：eve system orchestrator status
  3. 最近的事件：eve system events
部署失败（结构化诊断）

部署失败时，优先使用结构化输出，而非原始 HTTP 错误：

eve env diagnose <project> <env>

eve env diagnose 会提供类型化的 last_deploy_failure（kind、service、pod、namespace、message）、实时 K8s 状态，以及已部署版本与最新同步版本各自的 manifest_hash。利用这些信息，可以在重新运行前发现已应用版本的偏差。CLI 不再用简单的 HTTP request failed 隐藏错误。

自定义域名

自定义主机名在清单的 x-eve.ingress.domains 下声明，并在首次部署时绑定。操作方法如下：

eve domain list --env <env>          # what is bound where
eve domain verify <hostname>         # DNS check + cert state + next steps
eve domain status <hostname>         # which env owns it today
eve domain transfer <hostname> --to <env>   # move ownership across envs in same project
eve domain unbind <hostname>         # release so the next deploy claims it

所有权按环境划分，且先绑定者优先：首先使用某个主机名部署的环境拥有该主机名；其他引用同一主机名的环境会记录 owned by environment "<A>"，并跳过渲染。使用 transfer 后重新部署（或通过 environments.<env>.overrides 按环境单独配置），即可转移所有权。

平台 Sentinel 告警

平台会持续运行环境 Sentinel，并在环境状态恶化时发送 Slack 告警。收到 Sentinel 提醒后，应先从告警中获取项目和环境，再运行 eve env diagnose <project> <env> 确认当前状态，然后采取行动——告警可能会晚于自动恢复。

每日 Sentinel 摘要可能包含月度成本部分。使用 eve system env-cost --all 查看完整明细；该命令会读取已存储的 环境成本快照，并标注过时或不可用的估算值。请勿 从 Slack 摘要流程直接查询 OpenCost。

常见错误消息

错误原因修复方法
401 Unauthorized令牌已过期eve auth login
git clone failed缺少凭据设置 github_token 或 ssh_key 密钥
service not provisioned环境尚未创建eve env create <env>
image pull backoff镜像仓库身份验证失败如果使用 BYO/自定义镜像仓库，请验证 REGISTRY_USERNAME + REGISTRY_PASSWORD；对于托管应用，请使用 registry: "eve"
healthcheck timeout应用未启动检查应用日志，并验证清单中的端口

构建失败

如果部署流水线在构建步骤失败：

eve build list --project <project_id>
eve build diagnose <build_id>
eve build logs <build_id>
eve secrets list --project <project_id>     # Required for BYO/custom registry: REGISTRY_USERNAME, REGISTRY_PASSWORD

常见的构建失败原因：

  • Registry 身份验证：对于 BYO/自定义 Registry，请验证 REGISTRY_USERNAME 和 REGISTRY_PASSWORD 密钥
  • 未找到 Dockerfile：检查清单中的 build.context 路径
  • 多阶段构建失败：BuildKit 可以正确处理；Kaniko 可能会有问题
  • 工作区错误：构建上下文不可用 — 检查 eve build diagnose

Worker 镜像 Registry

Eve 会将以下变体的 Worker 镜像发布到配置的私有 Registry：

变体内容
baseNode.js、git、标准 CLI 工具
pythonBase + Python 运行时
rustBase + Rust 工具链
javaBase + JDK
kotlinBase + Kotlin 编译器
full所有运行时的组合

版本固定：生产环境中使用 semver 标签（例如 v1.2.3）。开发环境中使用 SHA 标签或 :latest。

平台环境变量

Eve 会自动将以下变量注入每个已部署的服务容器：

变量用途
EVE_API_URL用于服务器间调用的内部集群 URL
EVE_PUBLIC_API_URL面向浏览器应用的公共入口 URL（配置后）
EVE_SSO_URL用于用户身份验证的 SSO Broker URL（配置后）
EVE_PROJECT_ID当前项目 ID
EVE_ORG_ID当前组织 ID
EVE_ENV_NAME当前环境名称

后端调用使用 EVE_API_URL。浏览器/客户端代码使用 EVE_PUBLIC_API_URL。服务可以在清单的 environment 部分中显式定义这些变量，以覆盖其中任意变量。

访问 URL

  • URL 格式：{service}.{orgSlug}-{projectSlug}-{env}.{domain}
  • 本地开发的默认域名：lvh.me
  • 请向管理员询问正确的域名（预发布还是生产环境）。

按环境调试

环境调试方式
本地（k3d）通过入口直接访问服务，使用 eve system logs
Docker Composedocker compose logs <service>，仅用于开发（不用于生产环境）
Kubernetes基于入口访问，必要时使用 kubectl -n eve logs

私有端点（Tailscale）

将私有网络中的服务（家庭实验室 GPU、内部 API、开发机器）连接到 Eve 集群。平台会创建由 Tailscale 出口代理支持的 K8s ExternalName 服务。

# Register a private endpoint
eve endpoint add \
  --name lmstudio \
  --provider tailscale \
  --tailscale-hostname mac-mini.tail12345.ts.net \
  --port 1234 \
  --org org_xxx

# List and inspect
eve endpoint list --org org_xxx
eve endpoint show lmstudio --org org_xxx

# Diagnose connectivity
eve endpoint diagnose lmstudio

# Remove
eve endpoint remove lmstudio --org org_xxx

每个端点都会获得一个稳定的集群内 DNS 名称：http://{orgSlug}-{name}.eve-tunnels.svc.cluster.local:{port}。通过密钥将其接入应用/Agent：

eve secrets set LLM_BASE_URL \
  "http://myorg-lmstudio.eve-tunnels.svc.cluster.local:1234/v1" \
  --scope project

诊断检查：Operator 状态、K8s 服务是否存在、DNS 解析、TCP 连通性以及 HTTP 健康状况。

按需提供 Worker 工具链

默认 Worker 镜像为 base（约 800MB，包含 Node.js、git 和所有 Harness）。工具链（Python、Rust、Java、Kotlin、媒体）会通过 init 容器按需注入，而不是打包进臃肿的镜像。

对部署的影响：如果 Agent 作业需要工具链，Runner Pod 会启动 init 容器，从预先构建的小型镜像中复制工具链二进制文件。首次拉取会额外耗时约 5–10 秒；同一节点上的后续作业会使用缓存的镜像。

工具链问题调试：

# Check if toolchains are declared in agent config
# agents.yaml: toolchains: [python]

# If a toolchain binary is missing at runtime:
# 1. Verify agent config has the toolchain declared
# 2. Check init container logs on the runner pod
# 3. Verify toolchain images are available in the registry

如需使用包含所有工具链的完整镜像：设置 EVE_WORKER_VARIANT=full，或在本地使用 --variant full。

应用取消部署/删除生命周期

移除环境并清理资源：

# Undeploy services from an environment (stops pods, keeps env record)
eve env undeploy <project> <env>

# Delete the environment entirely (removes env record, managed DB, secrets)
eve env delete <project> <env>

如果附加了托管数据库，eve env delete 会将其解除配置。环境范围内的密钥也会被清理。该环境的流水线历史记录会保留在审计日志中。

如需进行应用级清理，请移除项目：

eve project delete <project-id>

这会级联移除环境、密钥、流水线历史记录和构建产物。

工作区清理器

为 Agent 工作区进行生产级磁盘管理：

  • EVE_WORKSPACE_MAX_GB — 工作区总容量预算
  • EVE_WORKSPACE_MIN_FREE_GB — 触发清理的阈值
  • EVE_SESSION_TTL_HOURS — 自动清除过期会话
  • 接近容量预算时按 LRU 策略清除；清理空闲会话时遵循 TTL
  • K8s：完成后删除每次尝试对应的 PVC

托管数据库 TLS

托管 Postgres 现在会向应用提供可信 CA 链。服务代码中不要设置 rejectUnauthorized: false 或 ssl: { rejectUnauthorized: false } ——默认启用经过验证的 TLS。如果客户端在证书验证时出错，请检查服务是否读取 ${managed.<db>.url}，而不是手动编写的 DSN。

稳定出站流量（允许列表源 IP）

当供应商要求使用固定源 IP 时，可在清单中为服务启用平台管理的稳定出站流量：

services:
  poller:
    x-eve:
      networking:
        egress: stable      # default is 'nat'

部署器会使用 hostNetwork: true，将 Pod 调度到稳定出站流量节点组上，使流量通过该节点的 IGW 路径发出。仅在需要时启用（这会绕过 NAT 并限制调度）。完整字段格式请参阅 eve-manifest-authoring。

相关技能

  • 本地开发循环：eve-local-dev-loop
  • 密钥：eve-auth-and-secrets
  • 清单变更：eve-manifest-authoring

评论

支持 Markdown