故障排除
本页按类别列出常见问题的解决方案。
连接问题
客户端找不到服务端
症状： 客户端显示"正在搜索服务端"或"未找到服务端"。
解决方案：
- 确认 HandyCafe Server 在管理 PC 上正在运行。
- 确认两台 PC 在同一子网上（如都在 192.168.1.x）。
- 检查 mDNS 是否被网络交换机或路由器阻止。
- 尝试手动连接：在客户端设置中直接输入服务端 IP 地址。
- 确认没有其他软件占用服务端的 TCP 端口（默认：5001）。
客户端连接后立即断开
症状： 客户端短暂显示"已连接"然后回到"搜索中"。
解决方案：
- 确认服务端和客户端的连接密钥一致。密钥在服务端的"设置 > 网络"中设置。
- 检查网络稳定性（丢包、网线问题）。
- 确保服务端未达到许可证 PC 限制。
- 查看服务端日志中的认证失败消息。
客户端在服务端显示"离线"但 PC 正在运行
症状： 客户端 PC 已开机且客户端应用正在运行，但服务端显示其为离线。
解决方案：
- 在客户端 PC 上确认 HandyCafe Client 确实在运行（检查系统托盘）。
- 检查客户端 PC 的网络连接（能否 ping 通服务端？）。
- 确认防火墙规则：TCP 端口 5001-5003 必须在服务端和客户端上都开放。
- 重启受影响 PC 上的 HandyCafe Client。
- 如果使用 VLAN，确保服务端和客户端 VLAN 可以通信。
更改网络设置后无法连接
症状： 更改端口或连接密钥后，客户端无法连接。
解决方案：
- 确保客户端已更新为新的端口号和连接密钥。
- 更改网络设置后重启 HandyCafe Server。
- 更新防火墙规则以允许新端口。
- 所有客户端必须配置新的值。
时段问题
无法在客户端上开始时段
症状： 开始按钮被禁用或开始操作失败并显示错误。
解决方案：
- 检查许可证状态。如果处于只读模式，无法开始新时段。
- 确认客户端状态为"空闲"。只能在空闲客户端上开始时段。
- 检查收银员权限。角色必须有 AUTH_CLIENT_LOGIN 权限。
- 确保定价已配置（设置 > 定价必须有有效的小时费率）。
时段计时器显示不正确
症状： 显示的时间与实际经过的时间不符。
解决方案：
- 检查服务端和客户端 PC 的系统时钟。应保持同步（使用 NTP）。
- 如果时段已暂停，暂停时间不计入。
- 预付费时段的计时器显示剩余时间而非已用时间。
时段费用似乎不正确
症状： 收取的金额与预期不符。
解决方案：
- 检查定价排期。如果启用，时段可能经过了多个具有不同倍率的定价档位。
- 查看定价设置：基础小时费率、增值税、起步费、取整。
- 在交易详情中查看时段的定价分段以了解明细。
- 确认支付方式的手续费和固定手续费。
- 预付费时段检查是"购买时锁定"还是"实时排期"模式。
支付问题
下拉菜单中缺少支付方式
症状： 关闭时段或订单时，预期的支付方式未出现。
解决方案：
- 确认支付方式存在于"管理 > 支付方式"中。
- 检查支付方式是否处于启用状态（未删除或禁用）。
- 检查收银员权限。必须授予 PAYMENT_MANAGE 才能看到所有方式。
手续费计算似乎不正确
症状： 扣除的手续费与预期费率不符。
解决方案：
- 确认支付方式的手续费率（百分比）和固定手续费。
- 手续费公式：手续费 = (收费金额 * 手续费率 / 100) + 固定手续费。
- 检查收银员是否手动覆盖了收费金额。
客户端显示问题
客户端待机画面空白
症状： 待机画面显示空白而非已配置的幻灯片。
解决方案：
- 确认"设置 > 客户端 > 待机画面"中已启用待机画面。
- 检查是否已添加至少一个媒体项目（图片或视频）。
- 确认媒体文件有效且未损坏。
- 触发同步以推送最新设置到客户端。
客户端菜单不显示应用
症状： 应用启动器为空或缺少分类。
解决方案：
- 确认"设置 > 客户端 > 内容"中已配置应用和分类。
- 检查分类和应用的可见性开关是否已启用。
- 确认客户端已收到最新的菜单数据（变更通过 TCP 自动推送）。
- 如果实时同步未生效，重启客户端。
远程桌面问题
远程桌面卡顿
症状： 视频画面延迟、卡顿或帧率低。
解决方案：
- 降低比特率（局域网标准使用建议 1000-2000 kbps）。
- 降低帧率设置。
- 使用有线以太网代替 Wi-Fi。
- 检查网络拥塞或其他应用的高带宽使用。
- 确保 UDP 端口 5004 未被阻止或限速。
远程桌面显示黑屏
症状： 远程桌面窗口打开但只显示黑色。
解决方案：
- 确认客户端在线且响应正常（先尝试截图）。
- 检查 UDP 端口 5004 双向开放。
- 客户端的显卡驱动可能需要更新。
- 尝试请求关键帧刷新。
许可证问题
许可证显示"offline_grace"
症状： 许可证状态显示 offline_grace 及倒计时。
解决方案：
- 恢复服务端 PC 的互联网连接。
- 检查 DNS 解析。服务端必须能访问许可证服务器。
- 检查代理或防火墙是否阻止了出站 HTTPS 连接。
- 您有 72 小时恢复连接，否则服务端将锁定。
许可证显示"over_limit"
症状： 连接的客户端数量超过许可证允许的上限。
解决方案：
- 断开不使用的空闲客户端。
- 检查当前客户端数量与许可证限制。
- 升级许可证以获得更多 PC 容量。
- 注意：主机计入总 PC 限制。
许可证显示"expired"或"revoked"
症状： 服务端进入受限模式。
解决方案：
- 检查许可证过期日期。
- 通过 HandyCafe 官方网站续期许可证。
- 许可证被吊销时，联系 HandyCafe 支持。
常规问题
设置更改未保存
症状： 离开设置页面后更改恢复原样。
解决方案：
- 确保更改后点击了保存按钮。
- 检查验证错误（带有错误消息的高亮字段）。
- 确认您拥有管理员权限。
审计日志缺少条目
症状： 预期的操作未出现在日志页面。
解决方案：
- 检查日志筛选条件。确保选择了正确的类别和日期范围。
- 确认已授予 LOG_DISPLAY_FULL 权限（否则只显示今日日志）。
- 使用文本搜索字段搜索特定操作。