docs: 添加调试信息收集指南
用于排查配置向导 500 错误，包含: - 日志收集方法 - Python 语法检查 - 依赖验证 - 常见问题解决方案 - 快速诊断脚本 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
impressionyang
parent
f7b4c60af2
commit
d58bf08472
313
调试信息收集.md
Normal file
313
调试信息收集.md
Normal file
@ -0,0 +1,313 @@
|
|||||||
|
# 调试信息收集指南
|
||||||
|
|
||||||
|
**问题**: 配置向导 500 Internal Server Error
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 必收集的信息
|
||||||
|
|
||||||
|
### 1.1 Home Assistant 日志
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 实时查看日志（在添加集成时）
|
||||||
|
tail -f ~/.homeassistant/home-assistant.log | grep -E "(sigmesh|error|Error|ERROR)" -i
|
||||||
|
|
||||||
|
# 或查看完整日志
|
||||||
|
cat ~/.homeassistant/home-assistant.log > ~/ha_full_log.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
**关键信息**:
|
||||||
|
- [ ] 集成加载时的错误堆栈
|
||||||
|
- [ ] 任何提到 `sigmesh_gateway` 的行
|
||||||
|
- [ ] 错误发生时间点的日志
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.2 Home Assistant 版本信息
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看 HA 版本
|
||||||
|
ha --version
|
||||||
|
|
||||||
|
# 或在 HA UI: 设置 → 关于
|
||||||
|
# 记录：HA 版本、Python 版本、操作系统
|
||||||
|
```
|
||||||
|
|
||||||
|
**需要记录**:
|
||||||
|
- Home Assistant 版本：__________
|
||||||
|
- Python 版本：__________
|
||||||
|
- 操作系统：__________
|
||||||
|
- 安装方式（HAOS/Container/Supervised/Core）: __________
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.3 浏览器控制台错误
|
||||||
|
|
||||||
|
**Chrome/Edge**:
|
||||||
|
1. 按 `F12` 打开开发者工具
|
||||||
|
2. 切换到 `Console` 标签
|
||||||
|
3. 点击添加集成按钮
|
||||||
|
4. 截图或复制所有红色错误信息
|
||||||
|
|
||||||
|
**需要记录**:
|
||||||
|
- [ ] 控制台错误截图
|
||||||
|
- [ ] Network 标签中失败的请求详情
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 代码相关问题排查
|
||||||
|
|
||||||
|
### 2.1 检查集成文件完整性
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 检查文件是否存在
|
||||||
|
ls -la ~/.homeassistant/custom_components/sigmesh_gateway/
|
||||||
|
|
||||||
|
# 预期输出应包含:
|
||||||
|
# __init__.py
|
||||||
|
# config_flow.py
|
||||||
|
# const.py
|
||||||
|
# coordinator.py
|
||||||
|
# manifest.json
|
||||||
|
# serial_reader.py
|
||||||
|
# protocol_parser.py
|
||||||
|
```
|
||||||
|
|
||||||
|
**检查项**:
|
||||||
|
- [ ] 所有文件都存在
|
||||||
|
- [ ] 文件大小不为 0
|
||||||
|
- [ ] 文件权限正确（homeassistant 用户可读）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.2 验证 manifest.json 格式
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 检查 JSON 格式
|
||||||
|
python3 -m json.tool ~/.homeassistant/custom_components/sigmesh_gateway/manifest.json
|
||||||
|
```
|
||||||
|
|
||||||
|
**如报错，说明 JSON 格式有问题**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.3 检查 Python 语法错误
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 逐个检查 Python 文件
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/__init__.py
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/config_flow.py
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/const.py
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/coordinator.py
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/serial_reader.py
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/protocol_parser.py
|
||||||
|
|
||||||
|
# 检查 platforms 目录
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/sensor.py
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/switch.py
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/light.py
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/binary_sensor.py
|
||||||
|
python3 -m py_compile ~/.homeassistant/custom_components/sigmesh_gateway/platforms/device_tracker.py
|
||||||
|
```
|
||||||
|
|
||||||
|
**如报错，记录具体错误信息**:
|
||||||
|
```
|
||||||
|
文件：__________
|
||||||
|
错误：__________
|
||||||
|
行号：__________
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.4 检查依赖是否安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看 manifest.json 中的依赖
|
||||||
|
cat ~/.homeassistant/custom_components/sigmesh_gateway/manifest.json | grep requirements
|
||||||
|
|
||||||
|
# 检查是否已安装
|
||||||
|
pip list | grep -E "(pyserial|bleak)"
|
||||||
|
```
|
||||||
|
|
||||||
|
**当前依赖**:
|
||||||
|
```json
|
||||||
|
"requirements": ["pyserial-asyncio==0.6", "bleak-mesh>=0.2.0"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 启用详细日志
|
||||||
|
|
||||||
|
### 3.1 修改 configuration.yaml
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# configuration.yaml
|
||||||
|
logger:
|
||||||
|
default: warning
|
||||||
|
logs:
|
||||||
|
custom_components.sigmesh_gateway: debug
|
||||||
|
custom_components.sigmesh_gateway.config_flow: debug
|
||||||
|
custom_components.sigmesh_gateway.serial_reader: debug
|
||||||
|
custom_components.sigmesh_gateway.protocol_parser: debug
|
||||||
|
custom_components.sigmesh_gateway.coordinator: debug
|
||||||
|
homeassistant.loader: debug
|
||||||
|
homeassistant.config_entries: debug
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 重启后重新测试
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 重启 HA
|
||||||
|
ha core restart
|
||||||
|
|
||||||
|
# 等待 30 秒后查看日志
|
||||||
|
tail -f ~/.homeassistant/home-assistant.log
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 常见问题和解决方案
|
||||||
|
|
||||||
|
### 问题 1: `No module named 'serial'`
|
||||||
|
|
||||||
|
**解决方案**:
|
||||||
|
```bash
|
||||||
|
# 进入 HA 环境安装
|
||||||
|
docker exec homeassistant pip install pyserial-asyncio==0.6
|
||||||
|
|
||||||
|
# 或 HAOS
|
||||||
|
ha addons ssh
|
||||||
|
|
||||||
|
# 然后重启
|
||||||
|
ha core restart
|
||||||
|
```
|
||||||
|
|
||||||
|
### 问题 2: `cannot import name 'XXX' from 'homeassistant.XXX'`
|
||||||
|
|
||||||
|
**原因**: HA 版本不兼容
|
||||||
|
|
||||||
|
**解决方案**:
|
||||||
|
- 检查 HA 版本是否 ≥ 2024.1.0
|
||||||
|
- 如版本过低，升级 HA 或修改代码适配
|
||||||
|
|
||||||
|
### 问题 3: `ModuleNotFoundError: No module named 'custom_components'`
|
||||||
|
|
||||||
|
**原因**: 文件路径错误
|
||||||
|
|
||||||
|
**解决方案**:
|
||||||
|
```bash
|
||||||
|
# 确认目录结构
|
||||||
|
ls -la ~/.homeassistant/custom_components/
|
||||||
|
# 应该是 sigmesh_gateway/ 直接在 custom_components/ 下
|
||||||
|
```
|
||||||
|
|
||||||
|
### 问题 4: config_flow 导入错误
|
||||||
|
|
||||||
|
**检查**:
|
||||||
|
```bash
|
||||||
|
# 查看 config_flow.py 的导入语句
|
||||||
|
head -30 ~/.homeassistant/custom_components/sigmesh_gateway/config_flow.py
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 调试信息模板
|
||||||
|
|
||||||
|
**请填写以下信息**:
|
||||||
|
|
||||||
|
```
|
||||||
|
=== 环境信息 ===
|
||||||
|
HA 版本：__________
|
||||||
|
Python 版本：__________
|
||||||
|
操作系统：__________
|
||||||
|
安装方式：__________
|
||||||
|
|
||||||
|
=== 错误信息 ===
|
||||||
|
浏览器控制台错误：
|
||||||
|
__________
|
||||||
|
|
||||||
|
HA 日志错误（完整堆栈）:
|
||||||
|
__________
|
||||||
|
|
||||||
|
=== 已尝试的排查 ===
|
||||||
|
- [ ] 检查文件完整性
|
||||||
|
- [ ] 验证 Python 语法
|
||||||
|
- [ ] 检查依赖安装
|
||||||
|
- [ ] 启用详细日志
|
||||||
|
|
||||||
|
=== 附加信息 ===
|
||||||
|
- 集成文件部署路径：__________
|
||||||
|
- 是否已重启 HA: [ ] 是 [ ] 否
|
||||||
|
- 之前是否能正常加载：[ ] 是 [ ] 否
|
||||||
|
- 最近是否有代码变更：[ ] 是 [ ] 否
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 快速诊断脚本
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# diagnose.sh - 快速诊断脚本
|
||||||
|
|
||||||
|
HA_CONFIG="${HOME}/.homeassistant"
|
||||||
|
INTEGRATION="${HA_CONFIG}/custom_components/sigmesh_gateway"
|
||||||
|
|
||||||
|
echo "=== SigMesh Gateway 诊断工具 ==="
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# 1. 检查文件存在
|
||||||
|
echo "1. 检查文件完整性..."
|
||||||
|
if [ -d "$INTEGRATION" ]; then
|
||||||
|
echo " ✓ 集成目录存在"
|
||||||
|
ls -1 "$INTEGRATION"
|
||||||
|
else
|
||||||
|
echo " ✗ 集成目录不存在"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 2. 检查 Python 语法
|
||||||
|
echo ""
|
||||||
|
echo "2. 检查 Python 语法..."
|
||||||
|
for file in "$INTEGRATION"/*.py "$INTEGRATION"/platforms/*.py; do
|
||||||
|
if python3 -m py_compile "$file" 2>/dev/null; then
|
||||||
|
echo " ✓ $(basename $file)"
|
||||||
|
else
|
||||||
|
echo " ✗ $(basename $file) - 语法错误"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# 3. 检查依赖
|
||||||
|
echo ""
|
||||||
|
echo "3. 检查依赖..."
|
||||||
|
pip list | grep -E "(serial|bleak)" || echo " 未找到相关依赖"
|
||||||
|
|
||||||
|
# 4. 查看最近日志
|
||||||
|
echo ""
|
||||||
|
echo "4. 最近日志 (sigmesh 相关)..."
|
||||||
|
tail -100 "${HA_CONFIG}/home-assistant.log" | grep -i sigmesh || echo " 无相关日志"
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
echo "=== 诊断完成 ==="
|
||||||
|
```
|
||||||
|
|
||||||
|
保存为 `diagnose.sh`，运行：
|
||||||
|
```bash
|
||||||
|
chmod +x diagnose.sh
|
||||||
|
./diagnose.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 下一步
|
||||||
|
|
||||||
|
收集完上述信息后：
|
||||||
|
|
||||||
|
1. **查看日志中的完整错误堆栈** - 这是定位问题的关键
|
||||||
|
2. **运行快速诊断脚本** - 自动检查常见问题
|
||||||
|
3. **提供调试信息模板中的内容** - 用于进一步分析
|
||||||
|
|
||||||
|
**最关键的调试信息**:
|
||||||
|
1. `home-assistant.log` 中集成加载时的完整错误堆栈
|
||||||
|
2. 浏览器控制台的 JavaScript 错误
|
||||||
|
3. `python3 -m py_compile` 的语法检查结果
|
||||||
Loading…
Reference in New Issue
Block a user