SwitchOps 交换机巡检
故障排查与安全
排查 SwitchOps 的配置、SSH、设备类型、命令、Excel 和 EXE 问题，并落实安全使用要求。
推荐排查顺序
遇到巡检失败时，按以下顺序检查：
devices.yaml是否能正常加载。- 管理电脑能否到达目标 IP 和 SSH 端口。
- 账号密码能否通过系统 SSH 客户端登录。
device_type是否与设备平台匹配。- 巡检账号是否有权执行对应查询命令。
logs/app.log中记录了什么错误。raw/是否保存了部分成功命令的回显。- Excel 中是连接失败、解析未知还是达到告警阈值。
常见问题
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 提示配置文件不存在 | 未创建 devices.yaml，或 EXE 同级缺少 config/ | 从示例复制设备文件；部署 EXE 时复制完整 config 目录。 |
| 提示 YAML 格式错误 | 缩进错误、使用 Tab、引号不成对 | 使用空格缩进，通过 YAML 编辑器检查语法。 |
| 提示设备清单为空 | 顶层没有 devices，或列表为空 | 确认使用 devices: 并至少配置一台设备。 |
| 提示缺少必填字段 | 缺少名称、地址、设备类型、用户名或密码 | 根据错误中的设备序号补齐字段。 |
| 没有可巡检的启用设备 | 全部 enabled: false，或 --target 未精确匹配 | 启用目标设备，核对名称/IP。 |
| SSH 连接超时 | 路由不通、端口被拦截、SSH 未启用或 device_type 不匹配 | 测试 TCP 端口，检查 ACL、防火墙、SSH 服务和平台类型。 |
| 用户名或密码错误 | 凭据错误、账号锁定或认证方式不兼容 | 人工 SSH 登录验证，并检查 AAA/本地用户配置。 |
| 登录成功但命令失败 | 巡检账号权限不足，或该型号命令不同 | 在设备上人工执行命令，调整账号权限或只读命令模板。 |
| 提示禁止执行非只读命令 | 命令前缀不在白名单或包含危险词 | 移除命令；不要绕过只读安全校验。 |
| CPU、内存显示未知 | 设备回显与当前正则规则不一致 | 查看 raw 文件，补充解析规则和测试。 |
| 板卡、电源、风扇或温度显示未知 | 命令无对应信息或回显关键词未识别 | 核对命令模板和原始回显；未知项会进入关注摘要。 |
| 端口台账为空 | interface brief 命令失败或格式无法解析 | 检查原始回显，确认接口行包含可识别的 up/down 状态。 |
| 重点接口状态未知 | 端口名错误、命令失败或回显不含状态字段 | 使用完整接口名，并先执行单端口查询验证。 |
| Excel 无法生成或保存 | 文件被 Excel 占用、目录无写权限 | 关闭同名文件，检查输出目录权限后重试。 |
| 查询结果为空 | 本地关键字没有匹配任何回显行 | 清空关键字重新查询，检查大小写以外的拼写和空格。 |
| 趋势提示数据库不存在 | 尚未巡检，关闭了数据库，或数据库路径错误 | 先巡检一次，确认 db_enabled: true，核对 --db。 |
| EXE 双击无反应 | 配置缺失、依赖加载失败或被安全软件拦截 | 检查同级 config，查看终端安全日志；必要时用源码模式定位。 |
读取日志
默认日志路径：
outputs/YYYY-MM-DD/logs/app.log
重点搜索：
连接失败
命令执行失败
禁止执行非只读命令
历史数据库写入失败
日志不会主动输出明文密码，但可能包含设备名称、IP、命令、文件路径和错误详情，分享前仍需脱敏。
原始回显与解析问题
连接成功但报告字段为“未知”时，先查看：
outputs/YYYY-MM-DD/raw/<设备名称>_<IP>.txt
判断顺序：
- 对应命令是否成功执行。
- 回显是否完整，是否因分页或超时被截断。
- 当前型号的字段名称是否与解析器预期不同。
- 是否需要调整
commands.yaml或switch_ops/parser.py。
修改解析器后运行测试：
pytest tests/
新增规则应同时补充脱敏后的真实回显示例测试，避免修复一个型号后破坏其他型号。
安全使用清单
- 使用专用、最小权限、只读的交换机巡检账号。
-
config/devices.yaml不提交 Git，不放入公共网盘或共享群聊。 - 管理电脑只允许从受控网络访问交换机管理地址。
- 不在
commands.yaml中加入保存、重启、删除、配置模式命令。 - 新命令先在测试设备人工验证，再进行单台工具测试。
- 控制并发，避免对设备 SSH 管理平面造成压力。
- 保护
outputs/，因为原始回显可能暴露网络结构信息。 - 定期清理或归档报告、日志和查询结果。
- 发布 EXE 时保留源码版本、构建记录和文件摘要。
- 修改安全校验代码时执行人工复核和回归测试。
已知边界
- 当前仅内置华为 VRP 和华三 Comware 命令模板。
- 解析基于常见回显正则，不同版本或型号可能出现“未知”。
- 停止任务为软停止，不会强制中断已经开始的 SSH 会话。
- CLI 历史趋势是文本表格，不是完整的监控或告警平台。
- SQLite 写入失败不会阻止 Excel 生成，需要关注日志中的历史库警告。
- 配置备份尚未开放，程序会拒绝读取当前或已保存配置的命令。
- 工具不能替代 SNMP、Telemetry、日志平台或厂商网管系统的持续监控。
如果同一类设备持续出现兼容问题，建议保留脱敏后的原始回显、设备型号、软件版本、device_type 和失败命令，作为后续适配依据。