# 排错

遇到问题先按本章对照症状自查。如果都没命中，到末尾的 "求助渠道" 联系我们。

## 1. 看不到画面（Live 一直缓冲）

| 可能原因 | 怎么验证 | 解决 |
| --- | --- | --- |
| RTSP URL 不对 | 用 VLC 试同样 URL | 改 URL 重新保存；ONVIF 自动发现错地址时改用手动 RTSP |
| 凭证错 | 网页后台提示鉴权失败 | 回 摄像头详情 改密码；ONVIF 密码 ≠ RTSP 密码 |
| 低延迟通道被拦 | DevTools → Network 看连接错误 | 防火墙开 UDP 23515；不能开会自动切到稳定通道（延迟 2–4s） |
| 相机用私协（Tapo / 小米） | 查相机品牌不在 [摄像头](/docs/cameras) 列表里 | 走 go2rtc 桥接 |
| 流媒体网关没起来 | `docker logs yunkan` 看启动错误 | 多半是端口被占；重启容器试试 |

## 2. 看回放黑屏 / 进度条不动

- **录像没开**：摄像头详情 → 录像设置 → 开启
- **磁盘满**：`df -h` 看 data 所在分区，删旧录像或调短保留天数
- **录像段坏了**：找到对应 `data/recordings/<id>/<date>/<HH-MM-SS>.mp4` 用 VLC 试播；坏段最多丢 5 分钟
- **时间不对**：服务器时区和摄像头时区不同步，回放时间轴会错 8 小时；`timedatectl` 检查

## 3. AI 检测不工作

| 症状 | 原因 | 解决 |
| --- | --- | --- |
| 事件页一直空 | 全局检测开关关了 | 设置 → 检测 → 启用 |
| 某相机不检测 | 该相机有 "检测失败" 状态 | 摄像头详情 → "清除检测错误" |
| GPU 0 占用 | 镜像变体不对（cpu 镜像跑 GPU 卡） | 拉对应变体镜像重启 |
| 人脸总是 "陌生人" | 库里没传过这个人 / 阈值太严 | 添加人脸 / 降低人脸相似度阈值 |
| 跌倒误报多 | 下落速度阈值太低 | 把跌倒下落速度阈值调高一点 |

## 4. 容器一直重启

用 `docker logs --tail 200 yunkan` 看最后输出。常见错：

- **配置缺失**：在向导模式但健康检查失败 → 浏览器走完 /setup 向导即可
- **端口被占**：`ss -tnlp | grep 23406`，把占用的服务关掉或换端口
- **硬件文件没挂载**：bind-mount 没带 `/etc/machine-id`，授权校验崩溃；按 [安装](/docs/install) 加上
- **架构不支持**：云瞰 只发布 x86_64 镜像，在 ARM 机器上无法运行（`uname -m` 应输出 `x86_64`）

## 5. 上传 115 失败

- **登录信息过期**（30 天左右）：设置 → 115 → 重新扫码登录
- **VIP 到期**：超大文件需要 115 VIP 的秒传通道；非 VIP 走限速通道
- **目标文件夹被删**：到 115 重建文件夹后回 云瞰 重选
- **网络不稳**：上传任务自带重试，看 `docker logs yunkan` 看具体错

## 6. 自动化不触发

- **静默时段**：设置 → 通知 → 静默时段，看是不是恰好处于这段时间
- **冷却时间**：30 秒内重复事件被吞，调低冷却或换不同事件类型
- **条件不匹配**：规则里加了 "识别到的人 = 张三" 但实际识别成 "陌生人"，规则不会触发；放宽条件
- **MQTT 没连上**：设置 → 集成 → MQTT 看连接状态，地址 / 凭证检查

## 7. 升级后向导又出现 / 数据没了

升级后跳到 /setup 几乎一定是 **data 目录没正确挂载**——容器看不到上次写的配置文件就以为是新装。检查：

```bash
docker inspect yunkan | grep -A 2 Mounts
# 应该看到 Source: /home/.../data, Destination: /app/data
# 如果路径变了 / 没挂，docker rm 容器，重新 docker run 时挂对
```

> **🛑 切勿在向导里再走一遍**
>
> 直接走 setup 会写一个新空数据库，原数据库虽然还在但被停用。先停容器、把挂载修好、重启，能直接进正常模式。

## 8. 看日志的方法

```bash
# 单镜像部署：所有功能日志混在一起
docker logs --tail 500 -f yunkan

# 想只看检测相关：
docker logs yunkan 2>&1 | grep -i detection

# 多容器部署：每个组件独立
docker compose logs -f api detection
```

## 求助渠道

- **后台工单**：[客户门户 → 我的订单 → 提工单](/portal/tickets/new)，附 `docker logs --tail 200 yunkan` 的输出，跟进最快
- **邮件**：support@yun-kan.com（24 小时内回）
- **微信群**：购买后客户门户的 "我的订单" 页面有入群二维码（仅付费用户）

---

来源:https://yun-kan.com/zh-TW/docs/troubleshooting