门卡编码器故障排查

快速修复

先检查网络和电源，再尝试重新编码一张门卡。通常只需 2 分钟。

本指南帮助你解决常见的门卡编码器问题，并快速判断是设备问题、凭据问题还是连接问题。

快速参考

你看到的情况	原因	处理方式
编码器无响应	电源或网络问题	检查连接
门卡无法编码	卡片类型或设备问题	核对卡片和设备
"UserCredentialsNotProvided.NotApplicable"	Saflok 凭据缺失或不完整	添加 Saflok 凭据
Saflok/Ambiance 编码失败或超时	Windows Agent、Ambiance 编码服务或设备离线	重启 Saflok/Ambiance 编码器
"Please create a new keycard first, then use Duplicate for any extra cards."	Saflok 找不到该预订的现有有效登记	修复缺失的第一张门卡
编码器类型切换不生效	上次保存留下了混合编码器状态	重新保存编码器类型
"Test Connection" 失败（Be-Tech）	Base URL 或服务问题	修复 Be-Tech 连接
"Test Connection" 失败（GreatLocks）	保存的 GreatLocks 服务器信息缺失或已过期	修复 GreatLocks 连接
"Service URL is required"（LockSDK）	直连模式下每个编码器都需要一个 Service URL	添加 LockSDK service URL
LockSDK agent 显示 Not registered	还没有对应的 per-encoder agent 设备	注册 LockSDK agent
Heartbeat Monitor 保存后关闭	保存未在当前酒店会话中持久化	重新保存 Heartbeat Monitor
Heartbeat 显示 unreachable	agent 离线或隧道异常	检查 agent 状态
编码器仍显示不可用	动态列表仍将该 agent 视为已断开	检查实时编码器状态
Windows Agent 显示 Not connected	agent 未运行或安装不完整	重新连接 agent

编码器无响应

你看到的情况： 编码器在 AVA 中显示离线或没有响应。

解决方法：

1. 检查编码器的电源和布线。
2. 验证 kiosk 与编码器之间的网络连通性（仅 Direct Connection）。
3. 确认服务器 IP 和端口正确。
4. 重启编码器软件。

门卡无法编码

你看到的情况： 写卡失败或生成了空白卡。

解决方法：

1. 确认卡片类型与编码器匹配。
2. 重新插入门卡后再试。
3. 使用一张新的空白卡测试。
4. 如果 Enable guest selection 关闭，请确认 kiosk 已路由到正确的编码器。
5. 如果 Enable guest selection 开启，请确认客人在 kiosk 上选择了在线编码器。

Saflok/Ambiance 编码无法工作

你看到的情况： 门卡编码失败、超时，或者 kiosk 报告没有从 Saflok/Ambiance 编码器收到响应。

解决方法： 按顺序完成以下三个检查。每一步都会先排除一种常见原因，再继续下一步。

1. 检查 Windows Agent 是否已在 AVA 中连接

1. 前往 Settings → Room Access → Keycard Encoding。

2. 找到这个编码器对应的 Windows Agent 卡片。

3. 确认状态显示 Connected，并且 Last Seen 时间很近。

   

4. 如果 agent 显示 Not connected，请先参阅 Windows Agent 未连接，再继续。

2. 检查编码器在 Ambiance 中是否在线

如果 agent 已连接但编码仍然失败，请登录 Ambiance 服务器并验证编码器设备。

1. 打开 Ambiance，前往 Device Management → Encoders。

2. 找到这个 kiosk 对应的编码器（例如 Vouch 编码器）。

3. 确认 Status 显示 Online。

   

4. 如果编码器显示 Offline，继续执行第 3 步，重启编码器服务。

3. 重启 Ambiance Encoder Service

如果编码器在 Ambiance 中离线，请在安装了 Ambiance 服务器的电脑上重启编码器服务。

1. 在运行 Ambiance 服务器的电脑上，按 Windows 键，或点击 Start 菜单。

2. 输入 services manager，然后从结果中打开 Ambiance Services Manager。

3. 在服务列表中选择 Ambiance Encoder Service。

   

4. 点击 Stop（红色方块）按钮。

5. 等待几秒，直到服务状态变为 Stopped。

6. 点击 Start（红色播放）按钮。

7. 确认 State 恢复为 Running。

8. 返回 Ambiance 的 Device Management → Encoders，确认编码器已变为 Online。

9. 在 kiosk 上尝试编码一张测试卡。

为什么重启会有效

编码器服务在网络波动或长时间空闲后，可能会丢失与物理编码器的连接。停止再启动服务会强制它重新建立连接。

Saflok 复制门卡需要先有第一张门卡

你看到的情况： AVA 显示“Please create a new keycard first, then use Duplicate for any extra cards.”

原因： Saflok 找不到该预订的有效登记或门卡记录。 复制卡需要先有一张成功的第一张门卡，AVA 才能继续添加更多门卡。

解决方法：

1. 为该预订创建第一张门卡。
2. 等待第一张门卡成功编码完成。
3. 只有在第一张门卡存在后，才选择 Duplicate。
4. 如果错误再次出现，请确认该预订在 Ambiance 中仍有有效登记。
5. 再次尝试复制请求。

你不应该看到的内容

消息中不应直接显示原始 ReservationNotFound 或 SOAP fault 细节。

Saflok 凭据未提供

你看到的情况： 门卡编码时出现 "UserCredentialsNotProvided.NotApplicable"。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 将 Encoder Type 设为 Saflok。
3. 在 Encoder Credentials 中输入 Username 和 Password。
4. 如果开启了直连，请输入 PMSI Server URL。
5. 点击 Save。
6. 点击 Test Connection，然后编码一张测试门卡。

编码器类型切换不生效

你看到的情况： 你选择了某一种编码器类型，但另一种编码器仍然处于启用状态。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 在 Keycard Encoder Settings 中选择你想要的编码器类型。
3. 只点击一次 Save，并等待成功提示。
4. 刷新页面，确认只有该编码器类型处于启用状态。
5. 如果问题仍然出现，先切换到其他类型保存，再切回并再次保存。

Be-Tech 连接测试失败

你看到的情况： "Test Connection" 显示失败，或者按钮一直不可用。

解决方法：

1. 确认 Base URL 以 http:// 或 https:// 开头。
2. 验证编码器工作站上的 Be-Tech 服务正在运行。
3. 检查工作站和 kiosk 是否在同一网络。
4. 重新输入 Hotel Name、Chain No、Workstation 和 Reader No。
5. 再次点击 Test Connection。

GreatLocks 连接测试失败

你看到的情况： 修改 GreatLocks 服务器信息后，Test Connection 失败。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 确认 GreatLocks 服务器已有 XHLSI Server IP Address 和 TCP Port。
3. 再次点击 Save。
4. 如果你在更新旧设置，请保留现有服务器记录。
5. 再次点击 Test Connection。

LockSDK service URL 是必填项

你看到的情况： 保存被阻止，或者编码器表单显示 "Service URL is required."。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 选择 LockSDK。
3. 打开 Physical Encoder Devices 并编辑该编码器。
4. 输入有效的 Service URL，例如 http://127.0.0.1:8092。
5. 点击 Save，然后运行 Test Connection。

LockSDK agent 未注册

你看到的情况： Windows Agent 中的 LockSDK 编码器卡片显示 Not registered。

解决方法：

1. 确认 Physical Encoder Devices 中确实存在该 LockSDK 编码器。
2. 前往 Windows Agent 并找到该编码器卡片。
3. 如果该卡片是新建的，点击 Download Windows Agent；如果已经存在，点击 Reinstall。
4. 解压安装包，并在连接的 Windows 电脑上运行 .bat 文件。
5. 刷新状态，确认卡片从 Not registered 变为 Connected 或 Not connected。
6. 仅在需要查看日志、轮换密钥或删除时，才使用 Advanced options。

Heartbeat Monitor 保存后关闭

你看到的情况： 你启用了 Heartbeat Monitor，点击 Save 后它又关闭了。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 打开 Encoding Options → Advanced options。
3. 打开 Heartbeat Monitor。
4. 只点击一次 Save，并等待成功提示。
5. 刷新页面，确认 Heartbeat Monitor 仍然开启。
6. 如果它仍然关闭，请参阅 Settings Not Saving After Switching Hotels。

Heartbeat 失败

你看到的情况： Heartbeat Monitor 显示 unreachable。

解决方法：

1. 确认 agent 正在 kiosk/PC 上运行。
2. 在 Registered Agents 中检查在线状态和隧道可达性。
3. 查看 agent 日志是否有错误。
4. 必要时重新安装 agent。

实时编码器状态不匹配

你看到的情况： 编码器看起来已配置好，但 AVA 仍然在预订弹窗中将其标记为不可用。

原因： 只有当 agent 已连接且隧道可达时，AVA 才会显示 online。 这个状态现在也会驱动动态编码器选择。

解决方法：

1. 在 Registered Agents 中查看编码器卡片。
2. 确认设备已连接且隧道可达。
3. 先修复任何 agent 或网络问题。
4. 刷新 Settings → Room Access。
5. 再次尝试编码。
6. 重新检查设置页上的 Status: 行。

动态编码器列表

当 agent 已连接且隧道可达时，动态编码器列表应显示 Online。 如果嵌套编码器卡片仍然看起来离线，请刷新页面并先检查 agent。

Windows Agent 未连接

你看到的情况： 状态显示 Not connected 或 “Never online.”。

解决方法：

1. 打开下载的 zip 并运行 download-installer.bat。
2. 让它下载安装程序 .exe，然后运行该文件。
3. 确认 Windows 电脑可以访问互联网。
4. 如有需要，在 Windows Agent 中的 agent 卡片上点击 Reinstall。
5. 刷新 Registered Agents 状态。
6. 返回 Settings → Room Access，确认 Status: 变为 online。

动态编码器列表

当 agent 已连接且隧道可达时，动态编码器列表应显示 Online。 如果嵌套编码器卡片仍然看起来离线，请刷新页面并先检查 agent。

Kiosk 路由规则未显示

你看到的情况： 在 Kiosk to Encoder Routing 下找不到路由规则。

解决方法：

1. 检查 Enable guest selection 是否开启。
2. 关闭它以显示手动路由规则。
3. 在 Physical Encoder Devices 中至少添加一个设备。

仍有问题？

如果出现以下情况，请联系 success@vouch-technologies.com：

• ❌ 检查电源和网络后，编码器仍然离线
• ❌ 多个 kiosk 都无法编码门卡
• ❌ Heartbeat 持续 30 分钟以上仍不健康

建议附上：

• 编码器类型和型号
• Registered Agents 与 Heartbeat Monitor 的截图
• 问题开始时间

相关指南

• 门卡编码器概览
• 设置门卡编码器
• 门卡客人指引