---
name: edge-technical-zeroing-report
description: edge_collector 技术归零与现场故障报告编写规范。用于边缘网关、协议采集、云平台、网络、4G/WiFi、内网穿透、端口转发、AI 分析、部署同步等故障需要形成正式根因报告、归零报告、事故复盘或客户交付说明时使用。
---

# edge_collector 技术归零报告

## 目标

把现场故障从“现象描述”整理为证据闭环：

```text
现象
  -> 影响范围
  -> 现场证据
  -> 排查路径
  -> 根因
  -> 修复
  -> 验证
  -> 预防措施
```

## 适用故障

- 边缘服务异常、CPU/内存/磁盘异常。
- 云端设备离线、历史数据缺失、AI 接口失败。
- 协议采集失败、第三方库或跨架构运行问题。
- 4G/WiFi、frpc、端口转发等独立 agent 异常。
- 打包同步后运行异常、动态配置被覆盖。

## 报告结构

```text
问题概述
影响范围
现场环境
现象与时间线
证据清单
排查过程
根因分析
修复措施
验证结果
预防措施
结论
```

## 证据要求

优先收集：

- `git log`、`git status`、构建主机信息。
- `journalctl`、应用日志、浏览器 console、接口响应。
- `systemctl status`、进程、端口、CPU、内存、磁盘。
- 配置文件差异，但注意隐藏密钥。
- 远程主机系统版本和架构。

## 根因表达

结论必须具体到可操作层级：

- 不写“网络问题”，要写是哪段链路、哪个接口、什么失败。
- 不写“部署问题”，要写是哪个脚本、哪个文件、哪个动态配置规则。
- 不写“兼容问题”，要写构建系统、库版本、架构或符号冲突证据。

## 归零判定

只有同时满足以下条件才写“已归零”：

- 根因有证据支撑。
- 修复已实施。
- 回归验证通过。
- 已说明预防同类问题的规则或检查项。

否则写“暂不具备归零条件”，并列出缺失证据。

## 文档落点

- 通用事故：`docs/`
- 鲁班猫设备：`docs/鲁班猫*/`
- 协议故障：`collector/docs/protocols/`