跳到主要内容

房卡编码器故障排查

快速修复

先检查网络和电源，然后重新尝试编码一张卡。大约需要 2 分钟。

本指南帮助你解决常见的房卡编码器问题，并快速定位设备、会话和供应商回调故障。

快速参考​

你看到什么原因处理方式
编码器无响应电源或网络问题检查连接
卡片无法编码卡类型或设备问题验证卡片和设备
简单语言的房卡失败消息AVA 已规范化供应商、房间或会话错误阅读消息
"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 找不到该预订现有的有效注册记录修复缺失的第一张房卡
多房间 Saflok/Ambiance 卡需要房间级 ID所选房间还没有自己的子预订检查所选房间
"The keycard encoder is temporarily offline. Please approach the Front Desk for assistance."编码器没有活动会话检查编码器会话
原始 DoorLock generate fail 或 internal error 文本出现在弹窗中技术性的房卡访问载荷透传了出来使用通用重试路径
编码器类型更改没有生效之前的保存留下了混合的编码器状态重新保存编码器类型
"Test Connection" 失败（Be-Tech）或 agent 一直离线Base URL、adapter 或服务问题修复 Be-Tech 连接
"Make sure the Be-Tech client program is running on the encoder computer."Windows Agent 返回了 502 的 vendor-unavailable 响应检查 Be-Tech 客户端程序
"Test Connection" 失败（GreatLocks）已保存的 GreatLocks 服务器详情缺失或过期修复 GreatLocks 连接
"Service URL is required"（LockSDK）直连模式需要每个编码器都有 Service URL添加 LockSDK service URL
LockSDK agent 显示 Not registered还没有为该编码器创建对应的 agent 设备注册 LockSDK agent
Heartbeat Monitor 在保存后关闭保存没有在当前酒店会话中持久化重新保存 Heartbeat Monitor
Heartbeat 显示 unreachableagent 离线或隧道问题检查 agent 状态
编码器一直不可用动态列表仍把该 agent 视为断开检查实时编码器状态
Windows Agent 显示 Not connectedagent 未运行或安装不完整重新连接 agent
Windows 要求权限托盘服务控制需要提升权限批准 UAC 提示

编码器无响应​

你会看到： 编码器在 AVA 中显示离线或无响应。

解决方法：

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

卡片无法编码​

你会看到： 房卡写入失败，或生成空白卡。

解决方法：

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

规范化的编码失败​

你会看到： 预订弹窗显示的是简短的自然语言消息，而不是原始供应商字符串。

原因： AVA 现在会在显示之前保留已规范化的 Saflok、Be-Tech、Opera 和内部会话失败。 它会优先使用结构化消息，然后在需要时回退到旧的供应商字符串解析。

解决方法：

  1. 先阅读简短消息。
  2. 在支持视图中查找 userMessage、errorCode、供应商名称和安全详情。
  3. 联系支持时使用这些详情。
  4. 将消息匹配到下面最可能的修复方案：
    • Occupied room：刷新预订，然后再试一次。
    • Encoder offline：检查电源、网络或 agent 状态。
    • Failed detect/write：重新插入卡片或使用新的空白卡。
    • No active session：重新连接编码器会话。
    • Missing mapping：确认房间映射正确。
    • Invalid room or date：核对入住日期和房间分配。
    • Vendor auth, gateway, or timeout：检查供应商访问或稍后重试。
    • Invalid request：重新打开正确的预订并重试。
旧版回退仍然启用

旧响应仍然可能显示旧的供应商字符串。 AVA 会保留这条解析路径，以便历史日志和旧集成仍能正确读取。

Saflok/Ambiance 编码无法工作​

你会看到： 房卡编码失败、超时，或 kiosk 报告 Saflok/Ambiance 编码器没有响应。

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

Saflok 自动恢复

如果 Saflok PMSI 启动较慢或稍后重启，AVA 会每 10 秒重新检查就绪状态。 先稍等片刻，然后刷新，再考虑重新安装 agent。

1. 检查 Windows Agent 是否已连接到 AVA​

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

  2. 找到此编码器的 Windows Agent 卡片。

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

    Windows Agent 显示 Connected，且 Last Seen 时间较新

  4. 如果 agent 是 Not connected，请先查看 Windows Agent 未连接 再继续。 如果 Saflok PMSI 仍在启动，请先等 10 秒并刷新一次，再考虑重新安装。

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

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

  1. 打开 Ambiance，进入 Device Management → Encoders。

  2. 找到该 kiosk 的编码器（例如 Vouch 编码器）。

  3. 确认 Status 显示 Online。

    Ambiance Device Management 显示编码器 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。

    Ambiance Services Manager 中选中 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/Ambiance 多房间房卡需要房间级预订 ID​

你会看到： 你尝试为多房间住宿中的某个房间编码房卡时，AVA 会停止流程。

原因： Saflok/Ambiance 复制卡使用的是所选房间的子预订 ID。 如果该房间还没有自己的 ID，就会出现快速失败错误。

解决方法：

  1. 打开预订并选择你想要的确切房间行。
  2. 如果该房间刚被拆分或移动，请等待 PMS 同步。
  3. 确认该房间在你的 PMS 中作为独立子预订存在。
  4. 再次尝试 Encode Keycard。

编码器没有活动会话​

你会看到： AVA 显示 "The keycard encoder is temporarily offline. Please approach the Front Desk for assistance."。

原因： 编码器当前没有活动会话。 AVA 会把它视为离线就绪问题。

解决方法：

  1. 确认编码器已通电并连接。
  2. 刷新 Settings → Room Access → Keycard Encoding。
  3. 检查编码器是否显示 Online 或 Connected。
  4. 会话重新连接后再试一次编码。
  5. 如果仍然失败，请使用另一台编码器或联系支持。

原始房卡访问载荷出现在弹窗中​

你会看到： 弹窗显示原始文本，例如 DoorLock generate fail! 或 internal error。

原因： AVA 捕获到了一个技术性的房卡访问 blob。 现在它会回退到通用重试消息，而不是显示原始载荷。

解决方法：

  1. 关闭弹窗。
  2. 等几秒。
  3. 再次尝试编码房卡。
  4. 如果同样的消息再次出现，请确认编码器在线。
  5. 如果仍然失败，请切换到另一台编码器或联系支持。

没有提供 Saflok 凭据​

你会看到： 房卡编码过程中出现 "UserCredentialsNotProvided.NotApplicable"。

解决方法：

  1. 前往 Settings → Room Access → Keycard Encoding。
  2. 将 Encoder Type 设置为 Saflok。
  3. 在 Encoder Credentials 中输入 Username 和 Password。
  4. 如果开启了 direct communication，请输入 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" 显示失败，或者按钮一直不可用。

当你有意配置了直接 Base URL，或看到一般性的 Be-Tech 请求失败时使用此方法。 如果你看到的是客户端程序消息，请使用 Be-Tech 客户端程序不可用。

解决方法：

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

Be-Tech 客户端程序不可用​

你会看到： AVA 显示 "Make sure the Be-Tech client program is running on the encoder computer."。

原因： Windows Agent 返回了 Be-Tech 的 vendor-unavailable 502 响应。 AVA 现在会针对这种情况显示直接消息。

解决方法：

  1. 前往编码器电脑。
  2. 确认 Be-Tech 客户端程序正在运行。
  3. 如果客户端程序已停止，请重启它。
  4. 如果客户端程序已经在运行，则重启 Windows Agent。
  5. 再次点击 Test Connection。
其他 Be-Tech 故障

如果你看到 Be-Tech request failed，请查看 Be-Tech 测试连接失败。 直接的客户端程序消息只适用于 502 vendor-unavailable 响应。

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 未注册​

你会看到： LockSDK 编码器卡在 Windows Agent 中显示 Not registered。

解决方法：

  1. 确认 LockSDK 编码器已存在于 Physical Encoder Devices 中。
  2. 前往 Windows Agent 并找到该编码器卡片。
  3. 如果是新卡片，点击 Download Windows Agent；如果已经存在，则点击 Reinstall。
  4. 解压包并在已连接的 Windows 电脑上运行 .bat 文件。
  5. 刷新状态并确认卡片从 Not registered 变为 Connected 或 Not connected。
  6. 只有在使用 View Logs、Rotate Secret 或 Delete 时才用 Advanced options。 Rotate Secret 会在 AVA 断开当前 agent 前打开确认对话框。

保存后 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: 一行。

Windows Agent 未连接​

你会看到： 状态显示 Not connected 或 "Never online."。

解决方法：

  1. 打开下载的 zip 文件并运行 download-installer.bat。
  2. 让它下载安装程序 .exe，然后运行该文件。
  3. 确认 Windows 电脑可以访问互联网。
  4. 必要时在 Windows Agent 的 agent 卡片上点击 Reinstall。
  5. 如果这是 Be-Tech 配置，也请确认本地 adapter 服务正在运行。 Be-Tech 状态在重启后最多可能需要 5 分钟才能刷新。
  6. 刷新 Registered Agents 状态。
  7. 返回 Settings → Room Access 并确认 Status: 变为 online。
动态编码器列表

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

Windows Agent 服务操作需要权限​

你会看到： 当你点击 Start、Stop 或 Restart 时，Windows 会要求管理员权限。

原因： 托盘按钮需要提升权限才能控制 Windows 服务。

解决方法：

  1. 在 UAC 提示中点击 Yes。
  2. 如果你不是管理员，请请一位有管理员权限的人批准。
  3. 如果你取消了提示，请再次尝试该操作。

Kiosk 路由规则不显示​

你会看到： 你在 Room Access 下或旧的 Kiosk to Encoder Routing 区域中找不到路由规则。

解决方法：

  1. 前往 Settings → Kiosk。
  2. 打开 Device Routing。
  3. 关闭 Enable guest selection 以显示手动路由规则。
  4. 在 Physical Encoder Devices 中至少添加一台设备。

仍然卡住？​

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

  • ❌ 经过电源和网络检查后，编码器仍然离线
  • ❌ Be-Tech 客户端程序持续停止
  • ❌ 多个 kiosk 的卡片编码都失败
  • ❌ Heartbeat 超过 30 分钟仍然不健康

建议附上：

  • 编码器类型和型号
  • 精确的 Be-Tech 错误消息
  • 你是否使用 Windows Agent 或直接 Base URL
  • Registered Agents 和 Heartbeat Monitor 的截图
  • 问题开始时间