cloud
87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
---
|
||
name: edge-bugfix
|
||
description: edge_collector 缺陷排查与根因修复流程。用于用户报告边缘侧、云平台、协议采集、前端白屏、部署同步、远程主机 CPU/内存异常、脚本失败、接口失败等 Bug 或异常时，按读取证据、根因定位、最小修复、定向验证和报告沉淀推进。
|
||
---
|
||
|
||
# edge_collector Bug 修复流程
|
||
|
||
## 适用范围
|
||
|
||
- 边缘服务：`collector`、`configurator`、`edge` systemd 服务。
|
||
- 云平台：`cloud_server`、`frontend/cloud_app`、`deploy_cloud.sh`。
|
||
- 前端：`frontend/config_app`、`frontend/cloud_app`。
|
||
- 协议采集：FANUC、西门子、Modbus、OPC UA、传感器等。
|
||
- 脚本/部署：`scripts/`、`package.sh`、`scripts/migrate_edge.sh`。
|
||
- 远程主机：82/87/94/97、云服务器 `119.45.4.75`。
|
||
|
||
## 核心原则
|
||
|
||
1. 先只读取证据，后修改。
|
||
2. 必须定位根因，禁止只修表面症状。
|
||
3. 不回滚用户改动，不清空运行配置。
|
||
4. 涉及远程同步默认使用既有项目脚本，不手写替代流程。
|
||
5. 修改后必须给出定向验证命令和关键结果。
|
||
|
||
## 排查流程
|
||
|
||
### 1. 收集现场
|
||
|
||
按问题类型优先读取：
|
||
|
||
- Git 状态：`git status --short`
|
||
- 相关日志：`logs/`、`journalctl -u edge`、`journalctl -u cloud-server`
|
||
- 配置：`runtime/edge/config/`、`collector/config/`、`configurator/config/`
|
||
- 前端：浏览器错误、接口响应、构建产物、路由
|
||
- 远程主机：`uptime`、`free -h`、`df -h`、`systemctl status`
|
||
|
||
远程数字主机遵循 `host-connection-defaults`；边缘同步遵循 `edge-sync-host`。
|
||
|
||
### 2. 定位根因
|
||
|
||
优先沿真实链路追踪：
|
||
|
||
```text
|
||
用户现象
|
||
-> 前端页面 / API
|
||
-> configurator 或 cloud_server
|
||
-> collector / agent / 脚本
|
||
-> 配置文件 / SQLite / 网络 / systemd
|
||
```
|
||
|
||
典型链路：
|
||
|
||
- 前端白屏：CSS -> DOM -> JS -> API -> 构建产物。
|
||
- 云端接口失败：前端代理 -> cloud_server 路由 -> 数据库/外部服务。
|
||
- 采集异常：设备配置 -> DriverRegistry -> 驱动日志 -> 协议依赖库。
|
||
- 同步后异常：构建主机架构 -> 打包产物 -> runtime 配置排除 -> systemd 重启。
|
||
|
||
### 3. 修复策略
|
||
|
||
- 小范围修改，不做无关重构。
|
||
- C++ 遵循 `cpp-coding-style`。
|
||
- 后端接口/配置遵循 `backend-conventions`。
|
||
- 前端遵循 `frontend-ui-conventions`、`frontend-debug`、`frontend-dialog`。
|
||
- Shell 遵循 `shell-scripting`。
|
||
- 第三方库遵循 `third-party-libs`。
|
||
|
||
### 4. 验证要求
|
||
|
||
按改动选择最小但可信的验证：
|
||
|
||
- JSON 配置：`jq empty <file>`
|
||
- C++ collector：`cmake --build build --target collector -j2`
|
||
- configurator/cloud_server：对应 target 或项目测试脚本。
|
||
- 前端：能运行 npm 的环境执行 `npm run build`。
|
||
- 边缘打包：`./package.sh --edge-only`
|
||
- 远程部署：按用户明确要求再同步/重启。
|
||
|
||
### 5. 报告沉淀
|
||
|
||
复杂 Bug 或远程事故修复后，在 `docs/` 下写简短报告，建议位置：
|
||
|
||
- 远程主机/设备类：`docs/鲁班猫*/`
|
||
- 协议类：`collector/docs/protocols/`
|
||
- 通用事故：`docs/`
|
||
|
||
报告至少包含：现象、根因、修复、验证、后续预防。
|