impress_sig_mesh_hacs/调试信息收集.md

调试信息收集指南

问题: 配置向导 500 Internal Server Error

---

1. 必收集的信息

1.1 Home Assistant 日志

# 实时查看日志（在添加集成时）
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 版本信息

# 查看 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 检查集成文件完整性

# 检查文件是否存在
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 格式

# 检查 JSON 格式
python3 -m json.tool ~/.homeassistant/custom_components/sigmesh_gateway/manifest.json

如报错，说明 JSON 格式有问题

---

2.3 检查 Python 语法错误

# 逐个检查 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 检查依赖是否安装

# 查看 manifest.json 中的依赖
cat ~/.homeassistant/custom_components/sigmesh_gateway/manifest.json | grep requirements

# 检查是否已安装
pip list | grep -E "(pyserial|bleak)"

当前依赖:

"requirements": ["pyserial-asyncio==0.6", "bleak-mesh>=0.2.0"]

---

3. 启用详细日志

3.1 修改 configuration.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 重启后重新测试

# 重启 HA
ha core restart

# 等待 30 秒后查看日志
tail -f ~/.homeassistant/home-assistant.log

---

4. 常见问题和解决方案

问题 1: No module named 'serial'

解决方案:

# 进入 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'

原因: 文件路径错误

解决方案:

# 确认目录结构
ls -la ~/.homeassistant/custom_components/
# 应该是 sigmesh_gateway/ 直接在 custom_components/ 下

问题 4: config_flow 导入错误

检查:

# 查看 config_flow.py 的导入语句
head -30 ~/.homeassistant/custom_components/sigmesh_gateway/config_flow.py

---

5. 调试信息模板

请填写以下信息:

=== 环境信息 ===
HA 版本：__________
Python 版本：__________
操作系统：__________
安装方式：__________

=== 错误信息 ===
浏览器控制台错误：
__________

HA 日志错误（完整堆栈）:
__________

=== 已尝试的排查 ===
- [ ] 检查文件完整性
- [ ] 验证 Python 语法
- [ ] 检查依赖安装
- [ ] 启用详细日志

=== 附加信息 ===
- 集成文件部署路径：__________
- 是否已重启 HA: [ ] 是 [ ] 否
- 之前是否能正常加载：[ ] 是 [ ] 否
- 最近是否有代码变更：[ ] 是 [ ] 否

---

6. 快速诊断脚本

#!/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，运行：

chmod +x diagnose.sh
./diagnose.sh

---

7. 下一步

收集完上述信息后：

1. 查看日志中的完整错误堆栈 - 这是定位问题的关键
2. 运行快速诊断脚本 - 自动检查常见问题
3. 提供调试信息模板中的内容 - 用于进一步分析

最关键的调试信息:

1. home-assistant.log 中集成加载时的完整错误堆栈
2. 浏览器控制台的 JavaScript 错误
3. python3 -m py_compile 的语法检查结果