12. 故障排查与提交支持

POC 部署手册章节。按 2026.10 主线代码核对；命令输出以当次交付的安装器为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：本章是出现问题时的处理顺序：先自己确认最常见的三类原因，再一次性采集排查信息，然后按安装阶段、诊断代码、装后访问与调用三种场景对照处理；仍无法解决时，按 12.6 节准备材料提交支持。读者是客户方系统管理员与实施工程师。本章所有采集命令都是只读的，可以放心执行。

12.1 先自己确认三件事

适用场景：调用方反馈「调不通」「被拒绝」「突然不能用了」，但平台服务本身运行正常。

这类反馈里，大部分不是故障，而是平台按配置做出的拒绝。拒绝的结论写在两个地方，不需要查日志：

• 调用方收到的错误响应体里的 reason 字段（OpenAI、Anthropic 协议的错误体还带 request_id，与响应头 x-request-id 相同）；
• 控制台「网关请求」中按 x-request-id 查到的这次调用记录。

操作步骤

1. 向调用方要这次调用的 x-request-id，以及响应体中的 reason。
2. 在控制台「网关请求」中按 x-request-id 查到这次调用，核对调用人、模型与结果。
3. 按下表判断属于哪一类，并按「去哪里确认」核对配置。

你会看到

• 属于这三类时，平台服务状态正常，同一成员换一个在范围内、额度未用完、不触发规则的请求可以成功。
• 处理方式是调整配置（加入范围、调整额度、修改规则）或让调用方修改请求，不需要重启任何服务。

注意：这三类拒绝都会留下调用记录。如果「网关请求」里按 x-request-id 完全查不到这次调用，说明请求没有到达网关（地址错、网络不通、前置设备拦截），按 12.5 节排查。

12.2 一次性采集信息

适用场景：12.1 节无法解释的问题，或任何需要提交支持的问题。先采集，再动手处理——重启服务之后，部分现场信息就不在了。

操作步骤

1. 在安装主机上执行下面四条命令。四条都是只读的，不改变任何服务状态。

# 安装主机 · root · 只读（采集排查信息，输出写到暂存目录）
sudo zenova status --json > /root/zenova-install/status.json
sudo zenova doctor --all --save /root/zenova-install/doctor
sudo zenova logs control-plane --since '30 min ago' > /root/zenova-install/control-plane.log
sudo cp /opt/zenova/state/install.log /root/zenova-install/

1. 问题发生时间早于 30 分钟前时，把 --since 改为覆盖问题发生时刻的时间，例如 '2 hours ago'。--since 的值原样传给 journalctl。
2. 问题涉及某个外部地址（模型供应商、通知渠道、对象存储）的连通性时，补充一次定向体检：

# 安装主机 · root · 只读（对指定地址分层检查 DNS、TCP、TLS、HTTP）
sudo zenova doctor --target <目标地址>

你会看到

• status.json、doctor/ 目录、control-plane.log、install.log 四份材料出现在 /root/zenova-install/ 下。
• zenova doctor --target 的报告注明「直连，可能与生产出口不一致」时，结果只代表本机直连该地址的情况，不代表网关实际出口（例如经出口代理）的连通性。

注意：zenova status 只列 zenova- 开头的服务。postgres、clickhouse、caddy、secret-service、spicedb 用 systemctl status <名称> 查看。远端网关节点上的问题，在节点主机上执行 sudo zenova status、sudo zenova logs node-edge、sudo zenova logs node-caddy 采集。

注意：以上材料可能包含内部地址、账号名与请求内容片段。对外提交前按 12.6 节脱敏。不要采集或提交 /opt/zenova/.env、/etc/zenova/secret-service/、/opt/zenova/.env.runtime/root-password-initial，这三处含主密钥、密钥服务材料与初始密码。

12.3 安装阶段失败对照表

适用场景：zenova install（含 --check-only 预检）在确认安装前后停止，屏幕给出提示。

安装器在确认安装之前不写任何文件、不创建任何服务。确认前停止的，处理原因后重新执行同一条命令即可，本机没有需要清理的东西。

操作步骤

1. 按屏幕提示的原文在下表中查找。
2. 按「处理」列处理后，重新执行原命令。
3. 表中没有的，记下屏幕提示原文与诊断代码，查 12.4 节。

补充几种确认安装后才会出现的情况：

你会看到

• 处理后重跑，安装器从上次停下的位置继续：确认前停止的从头问答，确认后停止的沿用已有安装进度。

注意：--check-only 预检通过不代表正式安装一定通过。预检不包含业务入口端口检查、现有依赖检测、解包后的执行权限检查与通知测试，上面第二张表中的问题都可能在预检通过后才出现。

注意：不要删除 /opt/zenova/state/ 下的进度文件或手工删除目录来「重新开始」。需要从头安装时，使用第 11 章的清空重装。

12.4 诊断代码怎么读

适用场景：安装器、zenova doctor、装后验收、升级、清空重装、备份恢复的输出中带有形如 [HOST_DISK_LOW] 的代码。

诊断代码共 69 个，按前缀分为十组。代码是稳定的：同一个问题在不同版本、中英文界面下代码不变，可以直接把代码报给支持，不需要转述屏幕文字。完整列表与处理办法见产品文档站的「安装与运维诊断代码」页。

操作步骤

1. 先看前缀，确定是哪一类问题。
2. 再看代码后面的参数（如 path、have_gib、need_gib），它们给出了具体对象与数值。
3. 按屏幕给出的处理建议或下表处理；仍不清楚时，把代码与完整输出一并提交支持。

常见代码举例：

注意：zenova doctor 有阻断项时退出码为 2，没有阻断项为 0，可以据此在巡检脚本中判断。警告项不影响退出码，但应记入交付记录。

12.5 装完之后访问与调用异常

控制台打不开

操作步骤

1. 先用安装完成时打印的「本机直接访问」地址在内网打开控制台。它按管理入口实际端口拼出，不经前置转发。能打开，说明本机正常，问题在负载均衡、反向代理、NAT 或网络策略，转第 4 步。
2. 「本机直接访问」也打不开时，在安装主机上查看服务状态：

# 安装主机 · root · 只读（查看各服务状态）
sudo zenova status
systemctl status caddy postgres clickhouse secret-service spicedb

1. 对未运行的服务重启并查看日志：

# 安装主机 · root · 写入（重启指定服务）
sudo zenova restart <服务>
sudo zenova logs <组件> --since '10 min ago'

1. 本机正常但外部访问不通：检查主机防火墙、云安全组与域名解析；使用了前置 TLS 或代理时，确认前置设备转发到的本机端口与安装时填写的一致。

你会看到

• 重启后服务状态恢复为运行中，控制台可以打开。
• 控制面不可用期间，网关节点仍按最近一次配置继续服务，已有业务调用不受影响。

注意：zenova restart 只接受 zenova- 开头的服务。控制面切换槽位的几秒内，内部入口返回 503 属于正常现象，入口代理会暂存新请求最长 5 秒。中心网关节点数据面（3080）就绪检查返回 503、原因为 no_tenant_routes，表示还没有租户或模型路由，创建租户并配置模型后恢复，不是故障。

调用返回错误

网关的三种协议入口（OpenAI、Anthropic、Gemini）在失败时都返回统一的错误信封，错误体中带稳定的 reason。HTTP 状态由 reason 决定，三种协议一致；响应头 x-should-retry 说明重试是否有意义。

同一个 HTTP 状态码下，reason 不同，处置完全不同。 只看状态码会走错方向：同样是 429，可能是成员额度用完（要调额度），也可能是上游供应商限流（稍后重试即可）；同样是 503，可能是模型没配路由（要改配置），也可能是上游暂时不可用（稍后重试）。排查时一律以 reason 为准。

你会看到

• 「谁来处理」为调用方的，调用方修改请求后即可成功；为管理员的，重试不会改变结果，须调整配置；为上游的，重试可能成功。
• 流式请求在已开始输出后失败时，网关发送一条与所选协议错误体同形的流内错误帧，随后正常结束流；已输出的内容与用量照常计费和展示，reason 同样按上表解读。

注意：上表只列出最常见的 reason。完整列表（含每个 reason 的 HTTP 状态、错误类型与是否可重试）见产品文档站「错误参考」页。上表没有的 reason，直接把 reason 原文与 x-request-id 一起提交支持。

注意：模型供应商测试或 zenova doctor --target 报告连通失败时，失败分为七类：dnsFailed（域名解析）、proxyConnectFailed（出口代理建连）、connectFailed（目标 TCP 建连）、tlsFailed（TLS 握手与证书）、timeout（超时）、ssrfBlocked（出站安全策略拦截）、invalidEndpointUrl（地址格式非法）。按分类找对应层的负责人，不要从头逐层排查。

12.6 提交支持需要准备什么

适用场景：按 12.1～12.5 节处理后问题仍在，需要交付方或供应商支持。

操作步骤

1. 按 12.2 节采集四份材料。
2. 按下表整理问题信息。能提供的尽量提供，没有的写「无」，不要留空让支持猜。

1. 对全部材料脱敏（见下）。
2. 按以下顺序组织材料，打包提交：

你会看到

• 材料齐全时，支持可以直接按请求 ID 与诊断代码定位，不需要来回追问。

注意：以下内容必须脱敏或不得提交：

注意：初始密码与任何凭据不得通过即时通讯、邮件或工单传递；截图与录屏前确认画面中没有密码、完整密钥与恢复码。

能力说明

---

上一章：11. 清空重装与更换产品