第 5 章　运维与排障

5.1　日志与状态位置

位置	内容
接入盒	journalctl -u uanbox-agent -u uanbox-mediamtx -f；/opt/uanbox/current/uanbox-agent probe 执行一次自检；黄口接电脑访问 http://192.168.88.1:8080 本地诊断页（只读：状态、相机、自检逐项、日志尾部，口令遮蔽）
控制面	journalctl -u uanlink；数据库 sqlite3 /var/lib/uanlink/uanlink.db（权限 600，root）；nginx 访问日志中 link.uanhon.cn 的记录
处理节点	journalctl -u uanhub-agent、journalctl -u uansense-node@<租户>；mediamtx API /v3/paths/list、/v3/webrtcsessions/list
中心	journalctl -u uansense@<租户>；中心审计表 audit_log 中 link_* 动作。中心管理员账号为 admin，口令在开通时随机生成，保存于中心主机 /srv/sense/<租户>/env.d/admin.pass（root 可读）
接入页	页面顶部红色提示表示中心无法连接控制面；相机行黄色提示可展开查看原因；"上送记录"显示每路本月字节数以及口令填写与暂停操作记录

控制面审计（租户侧 GET audit）记录每一笔写操作，操作人为中心登录名；指纹、来源 IP 与密文一律不记录。接管与回切的操作人记为 system:failover。

5.2　相机状态与原因

盒子心跳对每路携带 state（online / checking / connecting / shed / backoff / paused / failed）、cred（ok / bad / none / untested）、err、codec、bframes、chosen_stream、fps。接入页按下表显示：

原因	页面提示	处理方法
黄口未发现设备	黄口那边没有找到相机	确认相机交换机通电、网线接在黄口、相机指示灯亮；20 秒后自动重新发现
相机 RTSP 不通	相机能看到但连不上视频口	等待数分钟；持续不通时重启该相机
同 IP 多个 MAC	有两台相机用了同一个地址	由相机安装方修改其中一台的地址
未激活	有几台相机还没设过密码	先激活
cred none	还没有这台相机的口令	在口令框填写一次
cred bad	口令和填的不一样	单独为该相机填写。盒子只尝试一次，避免相机因多次口令错误锁定；填写正确后点击"重新检查"
H.265	视频格式是 H.265	第三码流改为 H.264
B 帧 / H.264+	开了 B 帧或 H.264+	关闭 H.264+
no_third	第三码流没开	相机网页 系统维护 > 系统服务 启用第三码流后重启；或点击"改用子码流"
res_out / fps_out	分辨率或帧率不合适	设为 1280×720、8 帧
shed	这条宽带暂时带不动这么多路	无需处理，带宽空闲后自动恢复；频繁出现时增加上行带宽
backoff	断线重连中	超过 15 分钟仍未恢复时检查现场网络
paused	已暂停上送	由操作者暂停，需要时恢复
指纹冲突	盒子的身份在两台机器上出现	已自动挂起，联系沅虹（常见原因是克隆镜像未清除 machine-id）

5.3　常见故障与根因

盒子在线但没有任何一路推送。 查看盒子日志是否出现"拉口令密文 HTTP 401"：盒子状态不是 active（已挂起或吊销）。再检查 cameras.secret 是否包含该相机：手工填写的条目优先，接入页下发的只补充缺失项。

盒子在推送但节点收不到。 查看 uanhub-agent 日志中的候选对类型：出现 relay 时立即记录 error（系统不使用 TURN）。对称 NAT 后的盒子只能连接节点宣告的固定端口 公网IP:8189，检查节点的公网地址跟随是否正常（webrtcAdditionalHosts）。推流地址必须将账号口令写入 URL 以 Basic 方式鉴权，mediamtx 的 whipBearerToken 与内置账号鉴权不兼容。

签名被拒。 盒子时间偏差超过 300 秒：chrony 未运行（安装脚本结尾会提示）。同一秒内同一请求的签名相同会被判为重放，自动化脚本需间隔 1.1 秒以上。

出口 IP 变更后盒子不重连。 自检中的 STUN 与 HTTPS 一旦恢复即清零全部退避；出口 IP 变更同样清零，但需要连续两次读到同一新地址（运营商级 NAT 的地址池）。

第二台盒子入网被拒："这台机器已有在用的盒子"。 硬件指纹相同：克隆镜像时未指定 --reset-machine-id。同一台主机运行第二个盒子实例做测试时，用 UANBOX_MACHINE_ID_FILE 指向另一份 machine-id。

保存口令后相机从"在线"变为"口令不对"并停止推送。 接入页口令框填写的是相机的预览账号，不是中心登录账号；盒子对新口令只尝试一次，不正确即停止推送并报 cred_bad，重新保存正确口令后恢复。

无法进入某个租户的中心。 入口是 vision.uanhon.cn（sense.uanhon.cn/app 并行保留），租户由门户签票决定；门户主库中需要存在该租户、已开通智眸应用、用户为成员且已授权，缺一项门户不签票。运维排障时可访问 https://vision.uanhon.cn/app/t/<租户> 种下路由 cookie 后用本地 admin 登录，/app/t/- 清除。

中心接入页整页 503。 中心环境缺少 UANLINK_TENANT_KEY，或写入中心环境的控制面地址是中心不可达的地址（应为 https://link.uanhon.cn）。

租户钥匙错误 5 次锁定 15 分钟。 按（来源 IP，租户码）计数，一个中心配错钥匙不会锁住经同一出口的其他租户。钥匙正确即放行，不受锁定影响。

节点未加载任何模型。 models 软链建到了目录内部（models/models）。执行 ls -la /srv/sense/<租户>/app/models 确认软链指向 /opt/uansense/models。

下载站安装包无法下载，其他文件正常。 nginx 配置引入了扫描器拦截片段，该片段对 .tar.gz 请求一律返回 444；下载站配置不得引入。

回放显示"文件回放（经服务器）"。 直连未在 20 秒内建立，前端已退回 HTTP 文件方式。查看处理节点 mediamtx 日志中 clip_<租户>_<告警号> 路径：无 runOnDemand command started 表示 WHEP 请求未到达节点（检查入口网关 /whep/ 转发）；有启动但无 stream is available 表示节点无法从中心取得短片（检查 centers.map 与中心 /api/clip/<id>?t= 可达性）；有 peer connection established 但立即关闭表示浏览器侧超时或页面切换。

5.4　多盒现场运维

• 接入页现场卡片的"冗余"状态：有效（两台以上在线且出口不同）、同一条宽带、仅 n 台在线、单盒、待自检。出口取控制面看到的来源地址，缺失时取自检中 STUN 测得的地址。
• 失联达到在线判定时限后接管，首选盒子恢复并稳定 600 秒后回切，巡检每 30 秒一轮。接管需同时满足三个条件：同现场在线、发现清单含该相机 IP、持有该相机 IP 的密文。未接管的常见原因是后加入的盒子未保存过口令，由管理员再保存一次即可。
• 两台盒子不会同时推送同一路：推流账号按相机签发，节点 mediamtx 只接受先到的发布者，旧盒子在取得新清单之前会被拒绝，取得清单后停止。
• --ha 现场：ip addr show <黄口> 查看 .1 当前所在的盒子，journalctl -u keepalived 查看切换记录；1 号恢复 30 秒后收回 .1。
• 演练切换 10 分钟到期自动切回；人工"结束演练"当场切回，不等待稳定期也不受回切开关影响。
• 吊销正在代推的盒子时，其代推的相机退回各自的首选盒子；该盒子自己首选的相机口令作废，需要重新登记。

5.5　控制面版本更新

1. 构建 musl 静态二进制，备份 /opt/uanlink/uanlink 与 /var/lib/uanlink/uanlink.db。
2. 新二进制复制到 /tmp 后 mv 替换，systemctl restart uanlink，日志出现"已监听"。
3. GET /v1/admin/hubs 返回 200；数据库中 box.last_seen_at 在 90 秒内刷新（盒子心跳正常）。
4. 数据库自动补列，旧版本不读新列，回滚只需替换二进制。
5. 在运维台账记录发版：每一步的操作、回滚方法、未在线上验证的项。

5.6　接入盒版本更新

1. make-bundle.sh --arch all 构建，publish.sh 发布（dirty 工作区拒绝发布，发布后回读大小核对）。
2. 现场再次执行安装命令，或 install.sh --bundle <新包>；新版本进入独立目录后原子切换。
3. 盒子心跳携带 agent_version，接入页盒子卡片可见；旧版本保留，回滚时改软链并重启两个单元。