故障排查

本文档整理了用户在日常使用 TestNet 平台过程中可能遇到的高频问题及其标准排查步骤。

---

一、扫描节点 常见问题

1. 探针在后台已启动，但 Web 界面显示「离线」

• 排查步骤 1：核对连接密钥 (Client Secret)
  • 探针启动命令中 -secret 参数必须与服务端的 TESTNET_CLIENT_SECRET 环境变量完全一致。若密钥错误，服务端会拒绝探针心跳与注册。
• 排查步骤 2：验证服务端地址连通性
  • 在探针机器上执行 curl -k -s -o /dev/null -w "%{http_code}\n" https://<your-server-ip>:3100，返回 200 即代表网络通畅、端口未被安全组拦截（默认部署仅发布 3100 端口）。
• 排查步骤 3：时钟同步 (NTP)
  • 建议为探针宿主机与服务端配置统一的时钟源（如 ntpdate ntp.aliyun.com），保证日志时间线可互相比对，TLS 证书校验也更加稳定。

2. 探针在线，但工作流任务一直处于「排队中」不执行

• 检查节点工具白名单：
  • 若在线节点的「工具白名单」未包含任务所用的工具，调度器不会把任务派发给它。进入「扫描节点」→「配置」检查该节点的白名单范围（留空表示不限制）。
• 检查并发度上限：
  • 若探针机器正在执行多个重型任务已达到并发上限，新任务会自动排队。

3. Docker 模式执行器报错：permission denied while trying to connect to the Docker daemon socket

• 原因：运行 testnet-client 的系统用户没有访问 /var/run/docker.sock 的权限。
• 解决办法：

  sudo usermod -aG docker $USER
  newgrp docker
  # 或临时提权赋予 socket 读写权限
  sudo chmod 666 /var/run/docker.sock

---

二、工作流与扫描任务常见问题

1. 工作流卡在某个节点无法推进

• 检查上一级节点是否有有效数据产出：
  • 若上游节点（如子域名挖掘）未发现任何目标，产出的资产信封为空，下游依赖节点（如 Web 探活）将自动跳过或优雅终止。
• 检查任务运行日志：
  • 进入「运行中心」找到对应的原子任务，点击「查看日志」，检查工具是否因目标域名解析失败、网络不通或内存溢出（OOM）而异常闪退。

2. 任务执行报错：Command not found / Tool not installed

• Native 模式排查：若配置使用原生 Shell 模式运行工具，必须确保探针宿主机的 PATH 环境变量中已安装该二进制文件（如 subfinder、httpx）。
• Docker 模式建议：建议优先使用 Docker 镜像执行模式（如 registry.cn-hangzhou.aliyuncs.com/testnet-tools/subfinder:latest），探针会在首次执行时自动拉取镜像，环境完全自闭环。

---

三、资产管理常见问题

1. 刚刚手动新增或批量导入了资产，在表格中却看不到

• 检查顶部「项目切换器」：
  • TestNet 严格采用项目级数据隔离。新增或导入资产会自动归属于当前选定的项目。请确认顶部导航栏的项目名称与导入时一致。
• 检查快捷筛选器 (Quick Filters)：
  • 检查页面上方的快捷过滤器与高级查询条件是否处于激活状态。清除已激活的筛选条件后即可查看全量资产。

2. 为什么相同的主机/域名没有重复入库？

• 自动去重保护：TestNet 内部对资产实施严格的去重保护机制：
  • 主域名以 FQDN（小写）去重；
  • IP 以标准 IPv4/IPv6 格式去重；
  • Web 站点以去除末尾斜杠的标准 URL（协议+主机+端口）去重。
• 再次扫描到相同资产时，系统只会自动更新该资产的「最后存活时间 (Last Seen)」和新检测到的指纹/标签，不会产生脏数据。

---

四、AI / MCP 智能体连接常见问题

1. Claude Desktop / Cursor 连接 MCP 报错：SSE connection failed (401 Unauthorized)

• 检查 API Key：
  • 在 MCP 配置文件中检查 Authorization: Bearer <API_KEY> 或 Query 参数中的 apiKey 是否与系统「AI」→「MCP 接入」中展示的一致。
• 检查服务端反向代理超时配置：
  • MCP 基于 Server-Sent Events (SSE) 协议保持长连接。如果使用了 Nginx 作为前端反向代理，需确保 Nginx 配置中关闭了代理缓冲：

    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding off;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 86400s;

---

五、授权许可 常见问题

1. 提示「系统未授权」或「机器码不匹配」

• 原因：系统更换了物理宿主机、更换了主网卡或重装了操作系统，导致硬件指纹哈希（Machine ID）发生变化。
• 解决流程：
  1. 在控制台运行 ./testnet-license show-machine-id 查看当前服务器最新的机器码。
  2. 将新机器码提交给您的系统管理员或通过商务支持重新签发专属 .lic 文件。
  3. 登录 Web 管理端，在「系统管理」→「授权管理」中上传新许可证，系统即时验证激活、恢复使用。

---

相关文档

• 常见问题 — 高频使用问题速查
• 部署与激活 — 安装配置与环境变量
• 节点安全 — 探针沙箱与安全加固