跳到主要内容

房卡编码器故障排查

快速修复

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

本指南帮助你解决常见的房卡编码器问题。

快速参考​

你看到的情况原因处理方式
编码器无响应电源或网络问题检查连接
无法解析预订房间PMS 查询没有返回可用房间重试房间解析
卡片无法编码卡片类型或设备问题验证卡片和设备
简明房卡失败AVA 已规范化供应商或会话错误阅读消息
Saflok 凭据缺失凭据不完整添加 Saflok 凭据
Saflok/Ambiance 编码失败或超时Agent、服务或设备离线重启编码器
复制卡需要第一张房卡Saflok 找不到有效注册修复第一张房卡
多房间卡需要房间级 ID房间没有子预订检查所选房间
编码器暂时离线没有活动会话检查编码器会话
出现原始 DoorLock generate fail 或 internal error技术载荷透传使用通用重试
Opera 时区错误时区缺失、无效或冲突检查 Opera 时区
编码器类型更改不生效保存留下混合状态重新保存类型
Be-Tech 连接失败Base URL、adapter 或服务问题修复连接
Be-Tech 客户端停止本地客户端正在恢复等待恢复
GreatLocks 连接失败服务器详情缺失或过期修复连接
GreatLocks 要求选择编码器有多个服务器或 agent选择编码器
GreatLocks 清单无法加载隧道或清单来源不可用检查同步
PMS 编码器发现无结果供应商错误或无终端检查 PMS 发现
Opera 路由不明确路由详情重复或缺失修复 Opera 路由
Opera 读卡错误 OPERAWS-FOF01920接口值过期或无效刷新路由
Opera 读卡错误 OPERAWS-FOF00199无法连接 Door Lock System检查连接
PMS 读卡不可用设置、能力或编码器问题检查 PMS 读卡
未检测到卡片读卡器未找到卡重新插卡
卡片类型不支持编码器无法识别类型使用受支持卡片
卡片无法读取编码器无法读取数据尝试其他卡
Opera 读卡一般性失败响应为空或无效检查响应
PMS kiosk 映射未解析映射标签不同检查映射
LockSDK 缺少 Service URL直连模式需要 URL添加 URL
LockSDK agent 未注册尚无 agent 设备注册 agent
Heartbeat Monitor 保存后关闭保存未持久化重新保存
Heartbeat unreachableagent 或隧道离线检查状态
Heartbeat unknownAVA 无法验证状态检查 unknown
Heartbeat 报告错误诊断或隧道失败检查错误
编码器仍不可用动态列表认为 agent 断开检查实时状态
Windows Agent Not connectedagent 未运行或安装不完整重新连接
Agent 太旧无法读卡不包含 Read Keycard更新 Agent
编码器隧道离线Universal Encoder Agent 隧道不可用重新连接隧道
Windows 请求权限服务控制需要提升权限批准 UAC

无法解析预订房间​

你会看到： 选择编码器后，AVA 显示 "We could not determine the room for this reservation."。

原因： 已验证的 PMS 查询没有返回可用房间标识。

解决方法：

  1. 刷新预订或 Operations View。
  2. 确认 PMS 中已分配房间。
  3. 重新开始预订、入住或房卡管理流程。
  4. AVA 询问时选择在线编码器。
  5. 消息仍出现时联系支持。

AVA 接受有效 PMS 房间标识，包括较长的 AVA PMS 标识符。不要手动缩短或编辑它。

编码器无响应​

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

解决方法：

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

卡片无法编码​

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

解决方法：

  1. 确认卡片类型匹配编码器。
  2. 重新插卡并重试。
  3. 使用新空白卡测试。
  4. Enable guest selection 关闭时，确认 kiosk 路由正确。
  5. 开启时，确认客人在 kiosk 选择在线编码器。

规范化的编码失败​

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

原因： AVA 规范化 Saflok、Be-Tech、Opera 和内部会话失败，优先显示结构化消息，必要时回退旧解析。HTTP 504 使用 KEYCARD_VENDOR_TIMEOUT。员工提醒和日志使用同一类别；卡片已在场的错误不会报告为 No card detected。

解决方法：

  1. 先阅读简短消息。
  2. 在支持视图查找 userMessage、errorCode、retriable、供应商名称和安全 upstream 详情。
  3. 联系支持时提供这些详情。
  4. 按消息检查房间、编码器、电源、网络、卡片、会话、映射、日期或供应商访问。
  5. retriable 为 true 时刷新后重试。
  6. retriable 为 false 时先修复映射或供应商问题。
旧版回退仍然启用

旧响应仍可能显示旧版供应商字符串。AVA 保留该解析路径，以便历史日志和旧集成正常读取。

Opera 时区不匹配​

你会看到： 房卡流程在 PMS 返回房间钥匙前停止，可能显示 "Request timezone does not match the hotel timezone" 或 "Hotel timezone configuration is invalid"。

原因： AVA 将 Opera 有效期格式化为酒店本地时间而非 UTC；时区缺失、无效或请求数据冲突时会安全停止。

解决方法：

  1. 前往 Settings → Essentials → Hotel Basic Details。
  2. 确认 Timezone 有效并匹配本地时钟。
  3. 更新后保存。
  4. 刷新预订或重新打开流程。
  5. 重试房卡请求。

Saflok/Ambiance 编码无法工作​

你会看到： 编码失败、超时或 kiosk 报告无响应。

解决方法： 按顺序完成三个检查，每一步先排除一个常见原因。

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. Not connected 时参阅 Windows Agent 未连接。PMSI 启动中则等待 10 秒并刷新。

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

agent 已连接但编码仍失败时登录 Ambiance。

  1. 进入 Device Management → Encoders。

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

  3. 确认 Status 为 Online。

    Ambiance Device Management 显示编码器 Status: Online

  4. Offline 时继续第 3 步。

3. 重启 Ambiance Encoder Service​

编码器离线时，在 Ambiance 服务器电脑上重启服务。

  1. 按 Windows 键或点击 Start。

  2. 输入 services manager，打开 Ambiance Services Manager。

  3. 选择 Ambiance Encoder Service。

    Ambiance Services Manager 中选中 Ambiance Encoder Service

  4. 点击 Stop，等待 Stopped。

  5. 点击 Start，确认 State 为 Running。

  6. 返回 Device Management → Encoders，确认 Online。

  7. 从 kiosk 再试一次测试卡。

为什么重启有效

网络中断或长时间空闲后服务可能丢失物理连接。停止并启动会强制重新建立连接。

Saflok 复制卡需要先有第一张房卡​

你会看到： AVA 显示 "Please create a new keycard first, then use Duplicate for any extra cards."

原因： Saflok 找不到有效注册或房卡记录；复制卡必须先有一张成功写入的房卡。

解决方法：

  1. 创建第一张房卡。
  2. 等待编码成功。
  3. 然后选择 Duplicate。
  4. 错误再次出现时确认 Ambiance 中仍有有效注册。
  5. 重试复制请求。
你不应该看到的内容

消息中不应出现原始 ReservationNotFound 或 SOAP fault 详情。

Saflok/Ambiance 多房间房卡需要房间级预订 ID​

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

原因： 复制卡使用所选房间的子预订 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. 问题重复时切换、保存，再切回并保存。

PMS 编码器发现没有返回结果​

你会看到： 点击 Load Encoders 后没有 PMS 终端。

原因： PMS vendor 不匹配，或 PMS 没有公开终端。

解决方法：

  1. 前往 Settings → Room Access → Keycard Encoding。
  2. 确认 PMS vendor 匹配酒店。
  3. 再次点击 Save。
  4. 返回 Physical Encoder Devices，点击 Load Encoders。
  5. 列表为空时确认 PMS 集成活动。
  6. 仍无终端时联系支持并提供供应商及酒店名称。

PMS 读卡不可用​

你会看到： Entitlements 没有 Start scanning，或提示物理房卡读取不可用。

原因： 读取禁用、PMS adapter 不支持或能力查询暂不可用；还需要活动 PMS 编码器。

解决方法：

  1. 前往 Settings → Room Access → Keycard Encoding 并选择 PMS Integration。
  2. 开启 Enable PMS Encoder Integration。
  3. 确认 vendor 匹配且编码器为 Active。
  4. 开启 Enable physical keycard reading，点击 Save。
  5. 重新加载 Entitlements 检查 Start scanning。
  6. 不可用时使用 Look up by room 或 Look up by confirmation number。

PMS 读卡直接使用 PMS transport，不需要 Universal Encoder Agent 会话。

Opera 路由不明确或不完整​

你会看到： 加载编码器后 Opera 读卡仍不可用。

原因： Opera 返回重复或不完整的路由详情，AVA 会安全停止而不是发送到错误的 Door Lock 路由。

解决方法：

  1. 确认 PMS vendor 为 Opera 且编码器 Active。
  2. 点击 Load Encoders，正确终端出现后点击 Add Selected。
  3. 请 Opera 管理员修正 Door Lock 接口详情。
  4. 重新加载 Entitlements，期间使用 Look up by room 或 Look up by confirmation number。

仍不可用时联系支持。

Opera 接口验证错误​

你会看到： 读卡显示 OPERAWS-FOF01920 或接口编号验证错误。

原因： Opera 拒绝接口值，旧路由可能仍在缓存。

解决方法：

  1. 确认工作站和编码器 ID 与物理设备匹配。
  2. 点击 Load Encoders 和 Add Selected。
  3. 确认 Active，重新加载 Entitlements。
  4. 再次 Start scanning；失败时使用房间或确认号查询。

AVA 使用类似 SL01 的值选择 Door Lock 路由，并使用数字 outbound code 读取。不要编辑接口值。

Opera Door Lock System 超时​

你会看到： 读卡显示 OPERAWS-FOF00199 或 Door Lock System 超时。

原因： Opera 接受请求但无法连接 Door Lock System，这是连接问题而非未检测到卡片。

解决方法：

  1. 确认 Saflok 接口和编码器通电。
  2. 检查酒店网络连接。
  3. 确认 Opera Door Lock 接口在线。
  4. 重新插卡并尝试 Start scanning。
  5. 接口离线时使用房间或确认号查询。
  6. 请 Opera 管理员检查连接。

不要将错误视为 No card detected。

不支持卡片类型​

你会看到： AVA 表示类型不支持或无法识别。

原因： 卡片存在，但编码器不识别其类型。

解决方法：

  1. 取出卡片。
  2. 确认使用认可的卡片类型。
  3. 放置受支持的空白卡。
  4. 再次编码。
  5. 消息再次出现时请经理确认设置。

不要继续反复调整不支持类型的卡片位置。

无法读取卡片​

你会看到： AVA 表示无法读取或读卡失败。

原因： 卡片存在但无法读取数据，可能损坏、不兼容或放置错误。

解决方法：

  1. 取出并检查损坏。
  2. 正确的一面朝上重新插入。
  3. 错误再次出现时尝试另一张受支持卡片。
  4. 多张卡都无法读取时联系支持。

未检测到卡片​

你会看到： 启动 PMS 扫描后 AVA 报告未检测到卡片。

原因： 读卡器没有找到卡片。

解决方法：

  1. 取出并正确插入卡片。
  2. 等待读卡器完成后再次扫描。
  3. 仍无法读取时使用房间或确认号查询。
  4. 多张已知正常卡片都返回无卡时联系支持。

Opera 读卡显示一般性失败​

你会看到： Opera 返回 HTTP 200 后出现一般性 PMS 读卡失败。

原因： Opera 可能返回离店日期和时间范围。AVA 接受非空范围并使用结束时间；空或格式错误范围无效。

解决方法：

  1. 确认卡片由 Opera 编码且属于预期预订。

  2. 重新插卡并选择 Start scanning。

  3. 没有房间时使用房间或确认号查询。

  4. 持续失败时使用手动查询并请管理员检查数据。

  5. 联系支持并提供扫描时间、酒店和编码器名称。

    ✓ 有效 Opera 卡片应显示读取数据，即使没有房间。

PMS kiosk 编码器映射未解析​

你会看到： PMS kiosk 无法编码，虽然编码器在 Physical Encoder Devices 中。

原因： Device Model 与旧版映射可能使用不同标签；AVA 先使用前者再回退。

解决方法：

  1. 前往 Settings → Kiosk → Device Routing 检查目标映射。

  2. 确认匹配 PMS 编码器为 Active。

  3. 目标改变时用当前 PMS 名称保存。

  4. 从 kiosk 重试测试卡。

    ✓ AVA 应解析到活动 PMS 编码器并发送请求。

缺少编码器时参阅 PMS 编码器发现没有返回结果。

Be-Tech 测试连接失败​

你会看到： "Test Connection" 失败或按钮禁用。

直接配置 Base URL 或出现一般请求失败时使用此方法；客户端消息请使用 Be-Tech 客户端程序不可用。

Be-Tech 可达性检查

405 视为可达；401、404 和 5xx 视为不可用。

解决方法：

  1. 确认 Base URL 以 http:// 或 https:// 开头。
  2. 验证服务在编码器工作站运行。
  3. 检查工作站和 kiosk 同网。
  4. Windows Agent 为 Connected 时再次输入 Hotel Name、Chain No、Workstation 和 Reader No。
  5. 再次点击 Test Connection。

Be-Tech 客户端或服务在重启或手动停止后停止​

你会看到： Windows 重启或手动停止后客户端或服务停止，AVA 可能短暂显示不可用。

原因： 客户端可独立于 Windows Agent 启动，托盘会自动恢复服务。

解决方法：

  1. 让 Windows Agent 服务继续运行。
  2. 等待托盘显示恢复及服务运行通知。
  3. 刷新 Settings → Room Access → Keycard Encoding。
  4. 确认 agent 和编码器为 Connected 或 Online。
  5. 重试房卡操作。
自动重试

恢复失败时托盘自动重试；持续失败时才使用 Restart。

多个安装时询问部署管理员 BETECH_CLIENT_PATH；路径必须指向可信的 Program Files 安装。

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

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

原因： Windows Agent 无法连接本地 Be-Tech 客户端服务。

解决方法：

  1. 前往编码器电脑。
  2. 检查托盘恢复通知。
  3. 稍等并刷新设置。
  4. agent 仍离线时使用托盘 Restart。
  5. 再次点击 Test Connection。
其他 Be-Tech 故障

看到 Be-Tech request failed 时参阅 Be-Tech 测试连接失败。客户端消息仅适用于 502 vendor-unavailable 响应。

GreatLocks 测试连接失败​

你会看到： 编辑服务器详情后 Test Connection 失败。

解决方法：

  1. 前往 Settings → Room Access → Keycard Encoding。
  2. 确认第一个活动行有 XHLSI Server IP Address 和 TCP Port。
  3. 点击 Save。
  4. 更新旧配置时保留服务器记录。
  5. 再次 Test Connection。

需要选择 GreatLocks 编码器​

你会看到： 操作要求选择编码器。

原因： 每个 Universal Encoder Agent 服务一个 GreatLocks 编码器；多个目标时无法安全选择。

解决方法：

  1. 打开 Physical Encoder Devices。
  2. 确认每行恰有一个 Encoder ID，不同物理设备使用不同 ID。
  3. 选择所需 Windows PC 的编码器并确认 agent Online。
  4. 保存后重复操作。
独立的编码器状态

每个编码器拥有自己的实时状态，一个在线 agent 不会使另一台上线。

GreatLocks 清单无法加载​

你会看到： 楼栋、楼层或房间清单为空。

原因： 隧道离线或清单来源不可达。

解决方法：

  1. 确认服务器记录已保存。
  2. 多个编码器时选择关联者。
  3. 检查 agent 隧道。
  4. 点击 Test Connection，恢复后刷新页面。

需要 LockSDK service URL​

你会看到： 保存被阻止或显示 "Service URL is required."。

解决方法：

  1. 选择 LockSDK，打开 Physical Encoder Devices 编辑编码器。
  2. 输入有效 Service URL，如 http://127.0.0.1:8092。
  3. 点击 Save，运行 Test Connection。

LockSDK agent 未注册​

你会看到： 卡片显示 Not registered。

解决方法：

  1. 确认编码器在 Physical Encoder Devices。
  2. 新卡片点击 Download Windows Agent，已有卡片点击 Reinstall。
  3. 解压并在 Windows PC 运行 .bat。
  4. 刷新，确认变为 Connected 或 Not connected。
  5. 仅用 Advanced options 执行 View Logs、Rotate Secret 或 Delete。

保存后 Heartbeat Monitor 关闭​

你会看到： 启用并保存 Heartbeat Monitor 后又关闭。

解决方法：

  1. 打开 Encoding Options → Advanced options。
  2. 开启 Heartbeat Monitor，只点击一次 Save 并等待成功。
  3. 刷新确认仍开启。
  4. 仍关闭时参阅 Settings Not Saving After Switching Hotels。

Heartbeat 故障​

你会看到： Heartbeat Monitor 显示 unreachable。

解决方法：

  1. 确认 agent 在 kiosk/PC 运行。
  2. 在 Registered Agents 查看在线状态和隧道。
  3. 查看日志，必要时重新安装。
状态含义

Online 表示已验证编码器和隧道；Offline 表示已验证不可用；Unknown 表示无法验证，不自动代表离线。

编码器状态显示 unknown​

你会看到： Heartbeat Monitor 显示 unknown，但会话和隧道正常。

原因： 可选供应商诊断或 Saflok Ambiance 凭据可能不可用。

解决方法：

  1. 确认 agent 已连接、Last Seen 较新且隧道可达。
  2. 不要仅因 unknown 重启或重装。
  3. 测试一张房卡确认功能。
  4. 错误持续或编码失败时联系支持。

Heartbeat 状态或隧道错误​

你会看到： Heartbeat 报告状态错误或隧道失败。

解决方法：

  1. 阅读完整消息并确定是状态还是隧道。
  2. 状态错误时检查供应商诊断。
  3. 隧道失败时确认 agent 运行且 Last Seen 较新。
  4. 刷新 Settings → Room Access 并再次检查。
  5. 错误持续或编码失败时联系支持。

实时编码器状态不一致​

你会看到： 编码器已配置，但预订弹窗仍标记不可用。

原因： AVA 验证 agent 和隧道后才显示 Online；Unknown 表示未验证。该状态驱动动态选择，GreatLocks 状态只属于关联编码器。

解决方法：

  1. 检查 Registered Agents 卡片。
  2. 确认设备连接且隧道可达。
  3. 先修复 agent 或网络问题。
  4. 刷新 Settings → Room Access，重试编码并检查 Status:。

Windows Agent 太旧，无法读取房卡​

你会看到： Read Keycard 失败，并显示 "This Windows Agent is too old to read keycards. Update the Universal Encoder Agent, then try again."

原因： 旧版 agent 不公开 Saflok read API，AVA 会访问默认网页。

解决方法：

  1. 前往设置。
  2. 显示 outdated 时先点击 Update。
  3. 等待重连，再次 Read Keycard。

编码器隧道离线​

你会看到： Read Keycard 显示 "The encoder tunnel is offline. Start the Universal Encoder Agent, then try again."

原因： 编码器电脑无法通过隧道连接 AVA。

解决方法：

  1. 找到 Saflok Windows Agent。
  2. 启动 Universal Encoder Agent。
  3. 等待 Connected 且 Last Seen 较新。
  4. 再次 Read Keycard；仍离线时参阅 Windows Agent 未连接。

Windows Agent 未连接​

你会看到： Not connected 或 "Never online."

解决方法：

  1. 运行 download-installer.bat，再运行下载的 .exe。
  2. 确认 Windows PC 可上网。
  3. 必要时点击 Reinstall。
  4. Be-Tech 配置还要确认 adapter 服务运行（重启后状态最多 5 分钟刷新）。
  5. 刷新 Registered Agents，确认 Status: 变为 online。
动态编码器列表

agent 连接且隧道可达时列表应显示 Online。嵌套卡片仍离线时刷新并先检查 agent。

Windows Agent 服务操作需要权限​

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

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

解决方法：

  1. 在 UAC 提示点击 Yes。
  2. 非管理员请让管理员批准。
  3. 取消后再次尝试。

Kiosk 路由规则不显示​

你会看到： 找不到路由规则。

解决方法：

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

仍然卡住？​

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

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

建议附上：

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