Eve Troubleshooting 是一套 CLI 优先的排查指引，用于定位 Eve 平台在部署和任务执行中出现的常见失败。使用前提是不假定拥有集群访问权限。
快速分诊清单 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>（结构化 DeployFailure 与集群快照）。检查注册表认证错误、缺失密钥或健康检查失败。eve env diagnose 会给出带类型的 last_deploy_failure（kind、service、pod、namespace、message）以及实时 K8s 状态；先读 failure kind，CLI 不再把真实原因压缩为笼统的 HTTP 请求失败。可将 diagnose 的 manifest_hash 与最新同步对比，发现已应用版本的漂移。
Sentinel Slack 告警 平台 sentinel 的 Slack 告警提示某环境降级。不要仅凭告警文本行动，从中取出项目/环境，用 eve env diagnose <project> <env> 再次确认。若环境显示健康，说明是已自愈的瞬时问题；否则按标准部署失败分诊处理。
魔法链接或邀请邮件缺失 预检通常能发现 SES 配置错误，但若收件人坚称未收到： eve admin email bounces list --recipient user@example.com --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 的 reply-to/support 邮箱与项目的 x-eve.auth 策略。
魔法链接首次点击即提示已被使用 邮件安全扫描器（Defender SafeLinks、Mimecast、Proofpoint、Barracuda、IronPort）会预取 URL 并消耗一次性 OTP。平台现在把每个操作链接包在需显式点击的 SSO 过渡页后，预取不再消耗令牌。若用户仍遇到已使用：一是包装已过期（TTL 1 小时），让其请求新的魔法链接；二是确实点击了两次，第二次命中已消耗的包装。遥测上，受保护邮箱出现 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> # 显示解析后的白名单 路径、查询、片段与用户信息会在同步时被拒绝，因此清单中误写的 https://app.example.com/callback 会在那里暴露。
自定义域应用的 /session 返回 401 浏览器在跨站请求会剥离 SameSite=Lax cookie，因此自定义域应用访问 sso.<cluster> 时看不到 eve_sso_rt 并返回 401。当 EVE_SSO_SECURE_COOKIES=true 时，SSO 代理会设置 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 并重新部署。*.lvh.me 上的本地 k3d 有意保持 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。
工作流步骤令牌资源被拒绝 工作流步骤任务现在带有由工作流级与步骤级 scope 块派生的 token_scope 声明（与任何 API 提供的 scope 取交集）。若步骤在组织文件系统路径、环境数据库表或 Cloud FS 挂载上被拒绝，scope 是嫌疑对象： eve job show <job-id> --json | jq '.token_scope' 将该声明与清单中的 workflow/step scope 对比。步骤 scope 与工作流 scope 取交集，只能收窄不能放宽。若步骤需要工作流禁止的路径，放宽工作流 scope（或去掉它）。请求提供的 scope 需要 jobs:harness_override 权限；目前还没有 --scope-* 这类 CLI 标志。
自定义域问题 eve domain verify <hostname> # DNS 检查 + 证书状态 + 后续步骤 eve domain status <hostname> # 哪个环境拥有它 eve domain list --env <env> # 绑定到此环境的所有域名 常见原因：DNS 未解析，verify 会打印预期目标与 dns_result.verified: false，重新部署前先修 CNAME/A 记录；证书待定，cert-manager 的 HTTP-01 challenge 正在进行，一分钟后重跑 verify；先绑定先得冲突，另一个环境已认领该主机名，使用 eve domain transfer <host> --to <env> 并重新部署，或通过 environments.<env>.overrides 将域名按环境限定。
注册表推送返回 UNAUTHORIZED 若构建任务推送时失败并提示 UNAUTHORIZED: authentication required：确认密钥已设置（eve secrets list --project proj_xxx）；若使用自带 BYO 注册表，确认凭据映射到 registry.host；确认清单中的 imagePull 元数据正确；在 Dockerfile 添加 OCI 来源标签 LABEL org.opencontainers.image.source="https://github.com/ORG/REPO"。某些注册表要求仓库关联的包元数据或工作区级认证对齐。
构建失败 症状：流水线在构建步骤失败；eve build diagnose 显示 run status = failed。 分诊： eve build list --project <id> # 查找最近的构建 eve build diagnose <build_id> # 完整状态转储 eve build logs <build_id> # 原始构建输出 常见原因：注册表认证，若使用自定义注册表模式，确认 REGISTRY_USERNAME 与 REGISTRY_PASSWORD 密钥已设置（或提供方等效的注册表凭据）；使用托管注册表（registry: "eve"）时通常不需要此步骤；确保凭据可访问配置的注册表账户与命名空间；检查 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.host 匹配。
任务卡住或阻塞 eve job show <job-id> eve job dep list <job-id> 解决依赖，或酌情用 eve job update 更新阶段。陈旧尝试恢复现在覆盖所有受理人并支持代理运行时优雅关闭，代理运行时 pod 死亡也不再让尝试搁浅。若在最近重启后任务仍看似卡住，给恢复循环一个周期再手动介入，通常它会自行回收。
聊天路由不匹配 聊天路由匹配的正则侧现在不区分大小写。若路由仍不触发，嫌疑在模式本身而非大小写。复查聊天配置中的匹配正则，然后重新同步清单。
代理运行时组织发现 代理运行时在启动时自动发现组织，不再需要 org_default 配置项。若新部署看不到某组织的任务，先确认该组织确实至少注册了一个项目 + 代理，再检查代理运行时日志，不要去找缺失的 org_default。
部署后应用不可达 确认部署任务成功（eve job result）；校验入口主机模式：{service}.{orgSlug}-{projectSlug}-{env}.{domain}；确保服务端口与 x-eve.ingress.port 匹配。
升级 若 CLI 输出不足，收集：eve system health、eve job diagnose <job-id>、manifest diff（最近变更），然后交给平台操作者。