外观

故障排查 ​

先区分卡在安装、订阅下载还是实际连接。保留完整版本号、错误发生时间及首条错误，隐藏订阅令牌、密码和节点认证信息。

卡在哪里先看什么
面板打不开容器日志、数据库连接、反向代理和 /readyz
分配后没有订阅零金额订单也须管理员确认；检查原订单状态
订阅里没有线路对应订阅的权限组、额度、协议状态及发布结果
只能直连，前置不可用入口授权、父协议凭据、托管发布或外部转发实际状态
节点在线却连接失败对外端口、防火墙、TLS/传输与真实客户端报错

服务无法启动 ​

检查：

  • ZBOARD_DATABASE_DRIVER 是否与数据源相符；
  • MySQL 连接是否可用，或 SQLite 数据目录是否已持久挂载且可写；
  • 环境变量是否完整；
  • JWT 和凭证加密密钥是否满足要求；
  • 容器磁盘空间和 inode 是否充足；
  • /readyz 是否返回数据库和应用就绪状态。

如果镜像构建或同步失败，不要只看最后的 Docker 错误。先确认失败发生在构建、数据库备份、候选启动还是应用切换阶段，再决定是否需要清理可重建缓存。

节点无法上线或发布失败 ​

检查：

  1. SSH 凭证和节点网络是否可用；
  2. 节点上的 Zero 版本是否与选择值一致；
  3. 配置校验返回的第一条字段错误；
  4. 监听端口是否冲突；
  5. 证书文件和规则资源是否可访问；
  6. 激活后的服务、控制接口和 Connector 是否健康。

协议服务保存成功不代表发布成功。依赖托管用户能力时，还要确认节点实际内核具备所需协议能力，并完成一次成功发布。

本地内核上传失败 ​

  • 413 或上传超时：检查专用上传路由及 CDN/反向代理限制，文件本身不能超过 128 MiB。
  • 制品目录未配置、只读或已满：核对独立的 kernel-uploads 可写持久挂载，按存储说明检查容量，不要把整个制品根目录改成可写。
  • 文件或版本被拒绝：确认是匹配节点平台的 Zero ELF 或官方内核包，“文件版本”与实际构建一致。
  • SSH/SCP 阶段失败：检查已验证主机身份、认证与提权、远端 scp，不要跳过指纹校验。

请求超时先查原安装任务；安装成功后仍需检查 Connector 与真实连接。完整步骤见本地上传内核。

协议配置校验失败 ​

VLESS/VMess 常见原因：

  • 服务端和客户端选择了不同传输；
  • WebSocket 路径没有以 / 开头；
  • 两端 WebSocket 路径或请求头不同；
  • 两端 gRPC Service Name 不同；
  • 同时配置 WebSocket 和 gRPC；
  • VLESS REALITY 使用了非 TCP 传输；
  • VMess 缺少要求的 TLS 配置。

不要用统一的版本号替代能力检查。Mieru 等协议可能受面板内核契约、节点构建和实际发布状态限制；页面提示不可用时应先处理该提示。详细说明见协议服务配置。

订阅配置异常 ​

确认：

  • 节点服务最近一次发布成功；
  • 订阅令牌未撤销，用户和订阅状态有效；
  • 订阅模板、节点组成员和策略组引用正确；
  • mixed_port 在 1–65535 范围内且未被占用；
  • 客户端使用正确的模板或 User-Agent；
  • ZNet Sink/native 响应按 Base64 文本解码；
  • HTTP 响应不是无效令牌触发的 302 伪装跳转。

Base64 不是加密。不要把完整订阅 URL、令牌或解码后的凭据放进公开日志。

流量已上报但剩余额度看起来不变 ​

先区分计算和显示：

  • 数据库和 API 使用精确字节；
  • 管理端会自动显示 B、KB、MB 或 GB；
  • 小于 1 MiB 的记录不应再显示成固定的 0 MiB；
  • 剩余流量等于套餐额度减去计费后的已用流量。

检查原始流量字节、协议服务倍率、订阅累计已用值和套餐额度。客户端本地测速成功但节点没有归属到该用户的 flow.completed 时，不会产生面板计费记录。

DNS 更新或删除失败 ​

  • 检查 Cloudflare Token 的 Zone 和 DNS 编辑权限；
  • 确认记录保存的 Zone/record ID 与远端一致；
  • revision 冲突时刷新后重试；
  • 同步任务运行期间不要并发删除；
  • 当前删除只清理面板记录，不调用供应商 API；真实 DNS 记录保留。供应商权限只影响同步，删除失败应核对并发任务与数据库事务。

更改供应商账号、完整域名或记录类型需要删除后重建。

HTTP-01 证书 unauthorized ​

依次检查：

  1. A/AAAA 是否指向目标节点；
  2. 公网 80 端口是否可达；
  3. /.well-known/acme-challenge/ 是否映射到配置的 Webroot；
  4. HTTP/HTTPS 重定向后是否仍返回相同测试 token；
  5. CDN、反向代理、应用路由或缓存是否改写内容。

Zboard 会先写入临时 token 并从域名请求验证。预检失败时先修复 Webroot 映射，不要直接重复申请。

DNS-01 缺少 Certbot Cloudflare 插件 ​

自动任务会依次尝试：

  1. 系统 python3-certbot-dns-cloudflare 包；
  2. /opt/zboard-certbot Python venv；
  3. /opt/zboard-certbot-packages pip target 和 wrapper。

出现 Unable to locate package python3-certbot-dns-cloudflare 或 python3-venv has no installation candidate 时，继续查看后续回退日志。全部失败才需要人工修复 Python、pip/venv、软件源、外网访问或磁盘空间。

证书无法编辑或绑定 ​

  • 签发或续期运行中不能编辑；
  • revision 冲突时刷新页面；
  • 节点、域名、环境和 challenge 类型属于不可变身份，需要新建证书；
  • 绑定时确认证书属于同一节点、覆盖协议域名且状态可用。

详细流程见DNS 与证书管理。

维护后普通用户或节点无法访问 ​

先在“服务系统 → 系统维护”检查维护状态。维护期间业务接口与节点上报会收到维护响应；健康检查仍可用，所以健康正常不代表业务已恢复。迁移复制完成后，仍需切换部署配置、重启验证并手动结束维护，见维护指南。

公告未出现或注册邮件未收到 ​

公告先核对受众、发布状态、开始/结束时间和已读状态。邮件先区分注册前验证码、欢迎任务和订阅告警，再检查 SMTP 与“运营任务”的结果。订阅告警还要检查邮件任务总开关、对应告警开关和同一用户的共享提醒间隔，见公告与邮件。

MySQL 升级报 1419 或 1050 ​

先核对是否处于小时流量迁移 0024 的部分完成状态。包含该迁移修复的版本提供恢复路径：停止其他应用写入后，用单一目标版本实例执行迁移，详见升级步骤。不要删除流量账本、手动跳过迁移或为此授予 SUPER。

找不到原来的菜单 ​

默认入口为用户、订阅、节点和服务系统；服务器在“服务器管理”，协议及前置入口在“节点协议”，节点组显示为“权限组”。升级保留你已改过的菜单展示，站点间名称可能不同。见日常使用。

ZeroDeNet