故障排查

常见问题、原因和解决方法。大多数问题都从同一个地方入手：服务的 日志，里面有构建输出和应用自己的输出（日志）。

服务器

初始化时连接失败

• 连接超时或被拒绝：云服务商的防火墙或安全组没有开放 SSH 端口，或者地址、端口填错了。初始化期间允许任意来源访问 SSH 端口，完成后可以关闭（服务器要求）。
• 认证失败：检查 SSH 用户。云镜像通常禁止 root 登录，请使用 ubuntu、debian 或 ec2-user。密钥必须是私钥，不是 .pub 文件，并且不能有密码短语（添加服务器）。
• sudo 要求输入密码：用户需要能免密 sudo，或者改用 root 连接。
• 主机密钥已变化：服务器指纹与第一次初始化时不同，Zenavo 会拒绝连接。如果你是有意重装了机器，请移除服务器后重新添加；否则先查明原因再继续。

初始化在安装过程中失败

查看服务器 状态 标签页中初始化日志的最后几行。常见原因：

• 80 或 443 端口被占用，占用者是 Docker、Nginx、Apache 或其他 Web 服务器。服务器应当专用于 Zenavo；停止并禁用它们，然后点击 重试初始化。
• 内存或磁盘不足：至少 2 GB 内存和 20 GB 可用磁盘（服务器要求）。
• 在中国大陆下载超时：日志会显示初始化选择了哪些安装源（中国大陆的服务器）。
• Agent 一直连不上：服务器需要能出站访问 Zenavo 控制台的 HTTPS（443 端口）。

重试时会跳过已经完成的步骤。

服务器显示离线

Zenavo 几分钟没有收到服务器 agent 的消息。上面的项目会继续运行，只有部署和实时数据会暂停。检查机器是否开机、能否出站访问 HTTPS、内存或磁盘是否用尽。agent 恢复后，状态会自动回到 运行中。如果没有恢复，设置 → 运行初始化 会重新安装 agent，不影响正在运行的内容（管理服务器）。

构建

Zenavo 识别错了语言，或没有识别出构建计划

zbpack 根据根目录中的文件进行识别。在 monorepo 中，把 根目录 设为应用所在的文件夹。想完全控制构建，可以添加 Dockerfile，或者设置 zbpack 选项，例如 ZBPACK_BUILD_COMMAND 和 ZBPACK_START_COMMAND（构建方案）。

构建失败

打开 日志 → 构建日志。最后一条错误通常就是原因：缺少依赖、构建脚本失败，或者缺少构建需要的值。变量 标签页中的变量不会自动传给构建：构建需要哪些，就把它们作为构建参数引用。可以在本地用 docker build . 跑一遍同样的构建，区分是应用的问题还是平台的问题。

构建在排队或被中止

• 等待构建机：你的套餐允许的同时构建数已经用满，或者共享构建机正忙（构建队列）。
• 超时：构建超过套餐的单次构建上限后会被中止（用量与账单）。
• 被拒绝：工作空间本月的构建分钟数已用完。部署预先构建好的镜像不受影响。

部署

部署一直不健康

新实例启动了，但始终没有通过健康检查；旧实例会继续提供服务。通常是因为：

• 应用只监听 localhost 或固定端口。 请监听 0.0.0.0 和 PORT 变量（框架）。
• 端口不对。 服务在 网络 中的端口必须是应用实际监听的端口。
• 健康检查路径返回 404，或者应用需要更长的启动时间。修正路径，或者调大启动等待时间。

失败的部署会显示最后一次检查的原因和实例最新的日志。

服务反复崩溃或被暂停

容器启动后立刻退出。在 日志 中查看错误：缺少变量、连不上数据库，或启动时崩溃。因内存超限被终止的服务也会重启：请调高它的内存限制（服务设置）。重启次数达到崩溃限制后，Zenavo 会暂停服务；解决原因后恢复服务或重新部署。

因镜像传输被拒绝部署

工作空间达到了消费上限，或者用完了 Free 套餐包含的镜像传输。正在运行的服务不受影响。提高上限或升级套餐即可（镜像传输与消费上限）。

服务访问不到另一个服务

使用对方的内网主机名 <hostname>.zenavo.internal 和它监听的端口，不要用公网域名或 localhost。两个服务必须在同一个项目中。对方服务 网络 标签页的 内网 下显示了这个地址（内网通信）。

域名与 HTTPS

证书一直是等待中

Let's Encrypt 还没能验证这个域名。把鼠标悬停在服务 概览 中的 等待中 上可以看到原因。通常是：

• DNS 记录还没有指向这台服务器。 用 dig +short app.example.com 检查，输出应该是服务器的 IP 地址。新记录可能需要一段时间才能生效。
• 80 端口没有开放。 Let's Encrypt 通过 HTTP 验证域名。
• 开启了 Cloudflare 代理，并且 SSL 设为 Flexible。请改为 Full (strict)，或者在证书签发之前关闭代理。

状态大约每分钟刷新一次（域名与 HTTPS）。

域名显示 404 或错误页面

• 404 page not found：域名已经解析到服务器，但没有服务绑定它。在服务的 网络 标签页中绑定。
• Bad gateway 或 Service unavailable：域名已经绑定，但服务没有运行，或者它监听的端口不是域名路由到的端口。

账号与权限

无法添加服务器或部署

请先验证邮箱：打开 Zenavo 发给你的邮件中的链接，或者在 账号设置 中重新发送（你的账号）。观察者（Viewer）不能部署或修改任何内容，请让团队管理员把你的角色改为成员（团队与角色）。

丢失了两步验证设备

使用恢复码登录（两步验证）。如果没有恢复码，请用账号邮箱联系 info@zenavo.app。

仍然无法解决？

发邮件到 info@zenavo.app，附上项目或服务器 ID（在 设置 中复制）、发生的时间，以及日志中的内容。请不要发送密码、密钥或变量值。