eve-troubleshooting

Eve 故障排查

优先使用 CLI 进行诊断。不要假设可以访问集群。

快速排查清单

eve system health
eve auth status
eve job list --phase active

常见问题及修复方法

身份验证失败或“未通过身份验证”

eve auth logout
eve auth login
eve auth status

如果缺少 SSH 密钥，请让管理员为其注册，或按照 CLI 提示从 GitHub 获取。

缺少密钥 / 插值错误

eve secrets list --project proj_xxx
eve secrets set MISSING_KEY "value" --project proj_xxx

确认本地插值所需的 .eve/dev-secrets.yaml 存在。

部署任务失败

eve job follow <job-id>
eve job diagnose <job-id>
eve job result <job-id>
eve env diagnose <project> <env>     # structured DeployFailure + cluster snapshot

检查是否存在镜像仓库身份验证错误、缺少密钥或健康检查失败。

eve env diagnose 会显示带类型的 last_deploy_failure（kind、service、pod、namespace、message）以及实时 K8s 状态。首先查看失败的 kind——CLI 不再将真实原因简化为单纯的 HTTP request failed。对比 diagnose 中的 manifest_hash 与最新同步记录，找出已应用版本的偏差。

Sentinel Slack 警报

平台 Sentinel 发来的 Slack 提醒表示某个环境状态降级。不要仅凭警报文本采取行动——从中提取项目和环境，然后用 eve env diagnose <project> <env> 重新确认。如果环境状态显示正常，则说明警报是已自行恢复的暂时性问题；否则，请按上述标准部署失败排查流程处理。

未收到魔法链接或邀请邮件

预检通常会发现 SES 配置错误，但如果收件人坚称邮件从未送达：

eve admin email bounces list --recipient [email protected] --limit 20
eve admin email bounces list --event-type Bounce
eve admin email bounces list --event-type Complaint

email_delivery_events 表是事实依据——Bounce / Complaint / Reject 记录可以解释 SES 静默丢弃邮件的原因。如果完全没有记录，说明邮件发送从未发生；请重新检查项目的 x-eve.branding 回复地址 / 支持邮箱，以及 x-eve.auth 策略。

首次点击魔法链接时提示“已使用”

邮件安全扫描器（Defender SafeLinks、Mimecast、Proofpoint、Barracuda、IronPort）会预取 URL 并消耗一次性 OTP。平台现在会将每个操作链接包装在 SSO 中间页后，要求用户明确点击，因此预取不会再消耗令牌。如果用户仍然遇到“已使用”提示：

• 链接包装已过期（TTL 为 1h）——请用户重新申请魔法链接。
• 用户确实点击了两次——第二次点击会命中已消耗的链接包装。
• 遥测数据：对于受保护的邮箱，magic_link_wraps 中 get_count > 1 的记录是预期情况；只有 consumed_at 才重要。

魔法链接或邀请跳转到通用 SSO 页面

重定向允许列表拒绝了应用的自定义域名来源，因此 SSO 回退到了集群落地页。确认项目的 x-eve.auth.allowed_redirect_origins（或其已注册的 custom_domains 行）包含应用来源——仅限来源，即 scheme://host[:port]；除本地环境外，必须使用 https。然后重新同步：

eve project sync
eve project auth-context <project_id>     # shows the resolved allowlist

同步时会拒绝路径、查询参数、片段和用户信息，因此如果清单中意外包含 https://app.example.com/callback，问题会在此处显现。

自定义域名应用上的 /session 401 错误

浏览器会在跨站请求中剥离 SameSite=Lax Cookie，因此自定义域名应用访问 sso.<cluster> 时将看不到 eve_sso_rt，并收到 401。SSO 代理现在会在 EVE_SSO_SECURE_COOKIES=true 时设置 SameSite=None; Secure。在代理日志中确认：

[eve-sso] Secure cookies: true (SameSite=none)

在浏览器开发者工具中，.<EVE_DEFAULT_DOMAIN> 上的 eve_sso_rt Cookie 必须显示 SameSite=None; Secure; HttpOnly。如果显示 Lax，说明代理运行在本地 HTTP 模式——请设置 EVE_SSO_SECURE_COOKIES=true 并重新部署。本地 k3d 上的 *.lvh.me 会有意保留 Lax（同一父站点）。

升级后域名注册清单被拒绝

自 2026-05-12 起，不再接受 v1 结构（domains: [string] 加上块级 target_org）——清单同步首次发现时就会拒绝。请迁移到 v2：

x-eve:
  auth:
    org_access:
      domain_signup:
        enabled: true
        domains:
          - { domain: acme.com, target_org: org_acme, role: member }
          - { domain: partner.example, target_org: org_partner }

每条规则都必须声明自己的 target_org，并且每个 target_org 都必须已出现在项目的 allowed_orgs 中。免费邮箱域名（free-mail.example、outlook.com 等）会触发一致性警告，而非拒绝——声明这些域名几乎总是错误的。完整的 v2 结构请参见 references/manifest.md 和 docs/system/auth.md#domain-based-signup。

工作流步骤令牌“资源被拒绝”

工作流步骤作业现在会携带一个 token_scope 声明，该声明根据工作流级和步骤级 scope 块生成（并与 API 提供的任何 scope 取交集）。如果某个步骤在组织文件系统路径、环境数据库表或 Cloud FS 挂载上遇到 denied，问题很可能出在 scope：

eve job show <job-id> --json | jq '.token_scope'

将该声明与清单中的工作流/步骤 scope 进行比较。步骤 scope 与工作流 scope 取交集——只能收窄，不能扩大。如果步骤需要访问工作流禁止的路径，请扩大工作流的 scope（或将其移除）。请求提供的 scope 需要 jobs:harness_override 权限；目前还没有 --scope-* CLI 标志。

自定义域名问题

eve domain verify <hostname>     # DNS check + cert state + next steps
eve domain status <hostname>     # which env owns it
eve domain list --env <env>      # everything bound to this env

常见原因：

• DNS 尚未解析：verify 会打印预期目标，并显示 dns_result.verified: false——请先修复 CNAME/A 记录，再重新运行 deploy。
• 证书仍在等待中：cert-manager 的 HTTP-01 挑战正在进行；一分钟后重新运行 verify。
• 优先绑定冲突：另一个环境已认领该主机名。使用 eve domain transfer <host> --to <env> 并重新部署，或通过 environments.<env>.overrides 按环境限定域名。

推送到 Registry 时失败并显示 UNAUTHORIZED

如果构建作业在推送时失败，并显示 UNAUTHORIZED: authentication required：

1. 确认已设置密钥：eve secrets list --project proj_xxx
2. 如果使用自定义 BYO Registry，请确认凭据映射到 registry.host
3. 确认清单中的 imagePull 元数据正确
4. 在 Dockerfile 中添加 OCI 源标签：LABEL org.opencontainers.image.source="https://github.com/ORG/REPO"

某些 Registry 需要与仓库关联的软件包元数据，或工作区级别的身份验证配置一致。

构建失败

症状

• 流水线在构建步骤失败
• eve build diagnose 显示运行状态 = failed

排查

eve build list --project <id>          # Find recent builds
eve build diagnose <build_id>          # Full state dump
eve build logs <build_id>              # Raw build output

常见原因

Registry 身份验证：

• 如果使用自定义 Registry 模式，请确认已设置 REGISTRY_USERNAME 和 REGISTRY_PASSWORD 密钥（或提供商对应的 Registry 凭据）。使用托管 Registry（registry: "eve"）时，通常无需执行此步骤。
• 确保凭据可以访问已配置的 Registry 账户和命名空间
• 检查：eve secrets list --project <id>

Dockerfile 问题：

• 服务必须在清单中设置 build.context，指向包含 Dockerfile 的目录
• Dockerfile 路径默认为 <context>/Dockerfile
• 多阶段构建可使用 BuildKit；使用 Kaniko 时可能失败

工作区/克隆错误：

• 构建需要工作区处于正确的 git SHA
• 检查 eve build diagnose 中的工作区准备错误

镜像推送失败：

• OCI 标签有助于将软件包关联到仓库：在 Dockerfile 中添加 LABEL org.opencontainers.image.source="https://github.com/OWNER/REPO"
• 使用 BYO/自定义 Registry 时，确保 Registry 主机和身份验证信息与清单中的 registry.host 一致

作业卡住或被阻塞

eve job show <job-id>
eve job dep list <job-id>

如果合适，请解决依赖项，或使用 eve job update 更新阶段。

现在，过期尝试恢复功能涵盖所有受派者和优雅的 Agent 运行时关闭；Agent 运行时 Pod 退出也不再会导致尝试陷入停滞。如果作业在近期重启后仍像是卡住了，请先等待恢复循环运行一轮，再手动介入——它通常会自行重新认领。

聊天路由不匹配

现在，聊天路由匹配在正则表达式端不区分大小写。如果路由仍未触发，问题很可能出在模式本身，而非大小写。请重新检查聊天配置中的 match 正则表达式，然后重新同步清单。

Agent 运行时组织发现

Agent 运行时会在启动时自动发现组织；你不再需要 org_default 配置项。如果新部署无法看到某个组织的作业，请检查该组织是否至少已注册一个项目和一个 Agent，然后查看 Agent 运行时日志——不要再去寻找缺失的 org_default。

部署后无法访问应用

• 确认部署作业已成功（eve job result）。
• 验证入口主机模式：{service}.{orgSlug}-{projectSlug}-{env}.{domain}。
• 确保服务端口与 x-eve.ingress.port 匹配。

升级处理

如果 CLI 输出不足，请收集：

• eve system health
• eve job diagnose <job-id>
• 清单差异（近期更改）

然后移交给平台运维人员。