日志与诊断

目标：学会查看 LeLamp 的日志、运行自检脚本，并按流程定位常见故障

一、日志在哪里

LeLamp 的日志有两个来源，排查时先看 systemd 日志（最实时），再看文件日志（可回溯历史）。

1. systemd 服务日志

sudo journalctl -u lelamp.service -n 50 --no-pager   # 最近 50 行
sudo journalctl -u lelamp.service -f                 # 实时跟踪（Ctrl+C 退出）
sudo journalctl -u lelamp.service --since "1 hour ago"  # 最近 1 小时

你应看到什么：按时间顺序输出的运行日志，包含服务启动、配置加载、硬件初始化等记录。实时模式下，你对着台灯说话时能看到新的日志行滚动。

2. 文件日志

ls -la ~/.lelamp/logs/

你应看到什么：日志文件列表（.log 结尾）。如果目录不存在或为空，说明服务从未以写日志模式运行过（多见于前台调试启动）。

查看文件日志：tail -n 50 ~/.lelamp/logs/*.log

二、服务状态检查

sudo systemctl status lelamp.service

你应看到什么：

状态	含义	处理
`active (running)`	正常运行	无需处理
`failed`	启动/运行崩溃	看日志定位（`journalctl -u lelamp.service -n 50`）
`activating (auto-restart)`	反复重启中	大概率启动即崩溃，看日志；服务本身配置了自动重启（RestartSec 30 秒）
`inactive (dead)`	服务未运行	`sudo systemctl start lelamp.service`

三、运行自检脚本

项目自带一套自检脚本，位于 ~/lelampv2/scripts/，可以快速判断是软件还是硬件问题。

1. 全硬件综合检查（推荐先跑这个）

cd ~/lelampv2
bash scripts/check_all.sh          # 检查
bash scripts/check_all.sh --fix    # 检查并自动修复常见问题

自动依次检查：WiFi → 音频 → RGB 灯。

你应看到什么：每个检查项显示 ✓（通过）或 ✗（失败），最后汇总： 全部通过! (N/N) 或 总计: N 通过, M 失败。失败的项就是排查方向。

2. 单项检查脚本

脚本	检查内容
`bash scripts/check_wifi.sh`	网络连接与配置（`--fix` 可自动修复）
`bash scripts/check_audio.sh`	麦克风/扬声器设备与通路
`bash scripts/check_rgb.sh`	RGB LED 灯带

3. 硬件单项测试（更细粒度）

命令	测试内容
`uv run -m lelamp.test.test_motors --port /dev/lelamp`	舵机连接与动作
`uv run -m lelamp.test.test_rgb`	LED 红/绿/蓝/彩虹灯效
`uv run -m lelamp.test.test_audio`	播放音 + 录音回放
`bash scripts/test_ai_backend.sh`	AI 后端（LLM/STT/TTS）连通性
`uv run python scripts/diagnose_audio_pi.py`	音频问题深度诊断

4. 代码自检（开发者用）

bash scripts/self_check.sh

检查 Python 语法与常见问题，输出 / 清单。

四、常见故障定位流程

按下面顺序排查，能覆盖 90% 的问题：

第 1 步  服务在运行吗？
        sudo systemctl status lelamp.service
        └─ 不在运行 → 启动服务，再看日志

第 2 步  日志里报什么错？
        sudo journalctl -u lelamp.service -n 50 --no-pager
        └─ 找 ERROR / Exception / Traceback 关键词

第 3 步  硬件正常吗？
        bash scripts/check_all.sh
        └─ 有失败项 → 对应该硬件的单项测试

第 4 步  单项测试定位
        test_motors / test_rgb / test_audio（见上表）

第 5 步  配置对吗？
        检查 ~/.lelamp/config.yaml 与 ~/.lelamp/.env（API Key 是否有效）

示例：语音没反应 → 第 1 步服务正常 → 第 2 步日志无报错 → 第 3 步 check_all.sh 显示音频失败 → 第 4 步 check_audio.sh 定位到麦克风设备丢失 → 检查 USB 连接/arecord -l。

五、日志关键词速查

关键词	含义	常见应对
`Wake word detected`	唤醒词被触发	正常；若频繁出现说明灵敏度太高
`Porcupine initialized`	唤醒词引擎加载成功	无此条 → 唤醒词功能未启动
`vad` / `audio_level`	语音活动检测状态	结合电平判断麦克风是否收到声音
`ERROR` / `Exception` / `Traceback`	异常	重点排查对象，通常附带模块名
`WebUI listening`（或类似）	Web 服务启动成功	无此条 → 界面打不开的原因
`API key` / `auth`	凭据相关	检查 `~/.lelamp/.env`

常见问题

问题	处理
journalctl 提示权限不足	加 `sudo` 前缀
journalctl 里没有日志	服务从未启动过，或日志被清空；改用文件日志 `~/.lelamp/logs/`
check_all.sh 报音频失败但能出声	多为设备名匹配问题，运行 `bash scripts/check_audio.sh` 看具体失败项
日志刷屏、看不懂	用 `grep` 过滤：`journalctl -u lelamp.service -n 200 --no-pager \| grep -i error`
想拿到完整日志求助	`sudo journalctl -u lelamp.service > ~/lelamp-full.log`，把文件发给技术人员

智能台灯LeLampX快速入门教程 - 日志与诊断