常见问题

先找到最后一个正常的环节，再检查紧接着的下一步。建议使用一名测试人员复现问题，记下发生时间、所在页面、设备标识和错误提示；先查看状态与日志，避免重复提交或清空数据。

遇到的问题	从哪里开始
网站无法访问	页面打不开
能打开页面，无法登录	心跳正常但登录失败
终端没有出现在系统配置	系统节点未被发现
录入房间为空或结果不对	录入端无法完成登记
服务端有人员，设备不认识	人员没有同步到设备
设备能识别，大屏没有变化	大屏没有新识别结果
未归名单与现场不一致	未归结果不符合预期

Web 页面打不开

1. 确认浏览器中的地址、协议和端口与交付地址一致。
2. 由维护人员在宿主机检查 Web 服务运行状态，并从宿主机访问首页。
3. 宿主机可访问但办公电脑不可访问时，检查虚拟机网络、端口映射、路由和防火墙。
4. 首页可访问但业务请求失败时，继续检查中心服务反向代理与日志。

恢复标准： 从实际使用的电脑打开管理页面，并能够完成登录和数据查询。

维护人员：只读检查命令

在交付目录执行，示例使用默认 Web 端口：

docker compose ps
docker compose logs --tail 100 web server
curl -I http://127.0.0.1/
curl --fail http://127.0.0.1/api/heartbeat

如 Compose 要求变量插值，应通过既有部署环境提供配置，不要将完整配置、密码或令牌贴入公开问题单。

心跳正常但登录失败

心跳反映中心健康接口响应，不验证学校、账户或完整业务数据库。

1. 核对学校入口和账户，检查是否使用了其他环境的账户信息。
2. 记录页面错误文字与请求发生时间；账户失效时重新登录。
3. 由管理员核对当前数据库中的学校、账户及关联关系。
4. 若是部署后首次出现，检查数据库连接、初始化结果及当前挂载的数据卷。

恢复标准： 正确账户能登录，并查到本学校的已知业务数据。不要为修复登录直接重建数据卷或导入整份历史数据。

维护人员：区分接口路由与业务失败

学校 WebApi 使用 m 指定接口、k 指定学校关键字；出现 404 时先核对实际请求和交付配置。

出现 404 时，先核对浏览器的实际请求、反向代理和接口路径；请求到达应用后，再根据新产生的日志区分参数、数据库结构和鉴权问题。HTTP 200 不代表业务成功，还需检查响应 state 与消息。

系统节点未被发现

本节针对“系统配置”中的录入端、大屏端等系统节点。外接识别设备应检查其协议心跳。

1. 确认终端应用正在运行，与中心服务所在网络允许 UDP 广播或发现通信。
2. 刷新系统配置，查看是否有旧节点及其最后广播时间。
3. 检查 UDP 20785、中心节点发现进程，以及虚拟机或容器网络是否转发该通信。
4. 多网卡主机检查对外广播地址，避免广播容器内部地址或回环地址。

节点能发现但批量配置失败时，继续检查中心到终端管理接口的访问和响应。修复后逐项确认配置结果，并从终端验证房间查询或中心连接。

录入端无法完成登记

现象	处理方式
只有楼层，没有房间	检查设备用户 ID 和中心楼栋关联，再查该楼层的房间数据
证件读不到	调整证件位置，检查读卡器和 USB 权限
不能提交	补齐姓名、证件号、性别和现场照片
提示成功，服务端查不到	核对学校及人员标识，请管理员检查业务响应和实际数据
选择房间后未入住	在管理端完成人员分房；录入页面选房不作为分房成功依据

当前终端对后端部分业务失败可能仍显示成功提示，必须以服务端查到的人员和照片为准。网络中断或超时后，先查结果再决定是否重试。完整流程见录入端。

人员没有同步到设备

1. 在服务端查到该人员，核对唯一标识和人脸照片。
2. 核对人员关联的楼栋、设备或设备组，确认目标设备属于同步范围。
3. 确认设备心跳正常，检查人员同步任务是否等待、失败或已完成。
4. 由维护人员检查主动推送进程，或设备拉取与回调链路，并查看设备返回消息。
5. 在设备侧查询该人员，核对标识、照片和最近修改结果。

恢复标准： 设备侧人员资料正确，且该人员完成一次真实识别。心跳恢复不等于积压同步任务全部完成。

大屏没有新识别结果

1. 确认测试确实产生了新识别，记下设备与时间，排除启动时的历史或演示卡片。
2. 查看大屏运行模式：本地模式检查设备到大屏上传；云端模式检查中心接收与中心到大屏回调。
3. 核对事件上传地址、协议及接收端响应。中心“已连接”只验证大屏到中心的心跳访问。
4. 接收端已有记录时，继续检查大屏事件处理、照片与显示日志。

在线设备为 0 时，按模式检查本机或中心设备心跳；显示 -- 时表示尚未取得有效统计，不应直接等同为没有设备。

恢复标准： 最新卡片显示本次测试的同一人员、设备和时间。详情见大屏端。

未归结果不符合预期

先核对选中的楼栋、截止时间和姓名筛选，再检查人员是否正确分房。接着核对设备时间、出入方向，以及截止时间前的识别事件是否完整到达服务端。

修复设备或数据问题后重新查询。不要仅因未归名单为空就认定全员在寝，也不要直接将缺失事件导致的状态当作现场事实。

向维护人员提供什么

提供问题发生时间、页面或终端类型、操作步骤、预期结果、实际错误和可复现的测试标识。附上相关版本、运行模式及必要的脱敏日志片段；涉及真实人员、证件、人脸或密钥的资料通过受控渠道提供。

服务恢复后，用最初失败的操作重新验证，记录结果。只看到页面恢复或服务重启完成，不代表原业务问题已经解决。