跳到主要内容

设置门卡编码器

快速设置

选择编码器类型，按需选择连接方式，然后添加编码器。 预计用时约 15 分钟。

本指南帮助你为 kiosk 或前台配置编码器优先的门卡编码流程。 现在也涵盖 Be-Tech Windows Agent 的设置。 除非配置了直连 Base URL，否则 Be-Tech 默认使用 Windows Agent。 Kiosk 路由现在位于 Settings → Kiosk。 PMS 集成门卡会在添加编码器前，先从 PMS 供应商发现编码器终端。 Be-Tech Windows Agent 设置可以在 Windows 重启或手动停止后恢复已停止的客户端或服务。

快速参考​

任务作用点击位置
Select method启用门卡编码Room Access → Keycard Encoding
Choose encoder type选择锁系统Encoder Type
Choose connection method直连或 Windows Agent（Saflok/Be-Tech/GreatLocks）Advanced options → Enable direct communication
Configure encoder添加服务器或凭据信息特定类型的字段
Add encoders使用真实编码器 ID 注册物理设备Physical Encoder Devices
Load PMS encoders从 PMS 获取可用终端Physical Encoder Devices → Load Encoders
Enable PMS card reading允许 Entitlements 读取实体 PMS 门卡Enable physical keycard reading
Choose kiosk routing控制 kiosk 专用路由规则Settings → Kiosk → Device Routing
Download Windows Agent下载 agent 的引导包Windows Agent
Check agent version显示已安装版本和最新版本状态Windows Agent
Update agent打开更新说明弹窗Update
Manage agent cards主卡片显示安装、更新或重装操作Windows Agent
Advanced agent actions查看日志、轮换密钥或删除 agentAdvanced options
Set encoding defaults每次入住的卡片数量 + 过期时间Encoding Options

在哪里找到​

Settings → Room Access → Keycard Encoding

第 1 步：选择门卡方式​

  1. 前往 Settings → Room Access。
  2. 将房间访问方式选择为 Keycard Encoding。
  3. 点击 Save。

第 2 步：选择编码器类型​

  1. 滚动到 Keycard Encoder Settings。

  2. 选择 Saflok、Be-Tech、LockSDK、GreatLocks 或 PMS Integration。

    ✓ AVA 只会保留你所选的编码器类型处于启用状态。

第 3 步：选择连接方式​

  1. 在 Select Encoder Type 中打开 Advanced options。
  2. 对于 Saflok、GreatLocks 或 LockSDK，打开 Enable direct communication 以绕过 Windows Agent。
  3. 保持关闭则使用 Windows Agent（默认）。
  4. Be-Tech 默认使用 Windows Agent，除非已配置直连 Base URL。
  5. PMS Integration 仅使用直连，因此跳过此步骤。

第 4 步：配置编码器系统​

编码器凭据标题

如果使用多个编码器，区域标题会显示为 Encoder Credentials & Devices。

如果使用 Saflok
  • Direct communication
    • 输入 PMSI Server URL、Username 和 Password。
    • PMSI 服务器必须可以从互联网访问。
    • 点击 Test Connection。
  • Windows Agent
    • 仅输入 Username 和 Password。
    • PMSI URL 和连接测试由 agent 处理。
    • AVA 会持续重新检查 Saflok PMSI 是否就绪，因此启动缓慢和重启通常会自动恢复。
  • 在 Physical Encoder Devices 中添加编码器设备（需要 Encoder ID）。
  • 可选：为每个编码器设置 Location。
  • 如果多个 kiosk 共用编码器，请从 Settings → Kiosk → Device Routing 添加路由。
如果使用 Be-Tech
  • Direct communication
    • 输入 Be-Tech 服务的 Base URL。
    • 该服务必须可以从互联网访问。
    • 输入 Hotel Name、Chain No、Workstation 和 Reader No。
    • 如果 Be-Tech 设置需要，请设置 Category 和 Card Type。
    • 如果已保存 Base URL，AVA 会让 Be-Tech 保持直连模式。
    • 点击 Test Connection，确认编码器有响应。
  • Windows Agent
    • 在连接到 Be-Tech 工作站的 Windows 电脑上安装 agent。
    • 输入 Hotel Name、Chain No、Workstation 和 Reader No。
    • agent 处理本地 Be-Tech 适配器，并代理供应商流量。
    • AVA 每 5 分钟在 /check 上检查 agent。
    • Windows 重启或手动停止后，托盘程序可以自动启动 Be-Tech 客户端和服务。
    • 恢复后，托盘程序会刷新 Be-Tech 就绪状态，无需手动重启 agent。
    • 如果没有保存 Base URL，AVA 会回退到 Windows Agent 流程。
  • 在 Physical Encoder Devices 中添加编码器设备。
  • 如果使用多个编码器，可选从 Settings → Kiosk → Device Routing 添加路由。
多个 Be-Tech 安装

agent 会自动发现普通的 Be-Tech 安装。 仅当多个受保护安装造成歧义时，才请部署管理员设置 BETECH_CLIENT_PATH。 该覆盖路径必须指向受保护的 Windows Program Files 文件夹内。

如果使用 GreatLocks
  • Direct communication
    • 输入 Server Name（可选）、XHLSI Server IP Address 和 TCP Port。
    • 服务器必须可以从互联网访问。
    • GreatLocks 每个服务器支持一台编码器。
    • 点击 Test Connection。
  • Windows Agent
    • 服务器详情由 agent 处理；无需 IP/端口。
    • 在连接到每台 GreatLocks 编码器的电脑上安装一个 Universal Encoder Agent。
每台编码器使用一个 GreatLocks agent

每台 GreatLocks 编码器都要在 Physical Encoder Devices 中添加一行。 每行准确输入一个 Encoder ID。 每行使用唯一 ID，例如 front-desk 或 lobby-pc。 编辑已保存的行时，AVA 会保留现有 ID。 没有 ID 的旧行会在 AVA 加载时获得稳定 ID。 然后在对应的 Windows 电脑上安装一个 Universal Encoder Agent。 每个 agent 只服务于与其关联的编码器。

注意： AVA 使用你在 Room Access 中保存的 GreatLocks 服务器记录。 如果更新了旧设置，请在 Test Connection 前点击 Save。 如果启用了库存同步，AVA 会通过活动 agent 隧道读取建筑、楼层和房间数据。 保持 agent 在线，以便房间列表保持最新。 如果 GreatLocks 设置支持电梯访问，请打开 Enable lift access。 然后选择供应商支持的模式：

  • Room floor mapping 使用房间映射中的建筑和楼层值。
  • Access code groups 使用 Common access codes 处理共享门或电梯组。

AVA 每张卡只发送一种电梯选项类型。 使用访问代码组时，AVA 会将单个数字保存为两位数代码。 你可以输入 1,2,3 或 01,02,03。 代码必须处于供应商支持的范围内。

如果使用 LockSDK
  • Direct communication
    • 在 Physical Encoder Devices 中添加每台 LockSDK 编码器。
    • 为每台编码器输入 Encoder ID 和 Service URL。
    • 添加编码器条目后点击 Test Connection。
  • Windows Agent
    • 在 Physical Encoder Devices 中添加每台 LockSDK 编码器。
    • 为每台 LockSDK 编码器注册一个 Windows Agent。
    • agent 卡片显示匹配的编码器和实时状态。
  • 如果使用多个编码器，可选从 Settings → Kiosk → Device Routing 添加路由。
  • 对于合并房间，LockSDK 最多支持 4 个房间，并要求 RF50/Mifare lock type 5。
如果使用 PMS Integration
  • 确保 PMS 集成处于启用状态（Cloudbeds 或 Opera）。
  • 在加载编码器前，将 PMS vendor 设置为与你的物业匹配的供应商。
  • 打开 Enable PMS Encoder Integration。
  • 在 Physical Encoder Devices 中执行以下任一操作：
    • 点击 Load Encoders 和 Add Selected，或
    • 点击 Add Encoder，输入 Encoder ID 和 PMS Encoder ID。
  • 现在，加载的设备会直接保留供应商编码器 ID。
  • 重新发现会保存 PMS 读卡所需的工作站、编码器、接口和出站代码详情。
  • 只有这些详情准确标识一条 Door Lock 路由时，Opera 读取才会生效。
  • 使用 Active 停用不想使用的编码器。
  • 仅在 PMS 读卡 API 通过验证后，才打开 Enable physical keycard reading。
  • 更改读卡设置后点击 Save。
  • 如果列表为空，先检查 PMS 供应商设置。
  • 如果仍看不到编码器，请阅读 PMS encoder discovery returns no results。
PMS 读卡独立于编码

PMS 编码可以继续进行，而实体卡读取保持关闭。 在 PMS 和 Room Access 功能允许读取之前，Entitlements 会隐藏扫描控件。 在 PMS 供应商确认你所在物业的读卡 API 可用之前，请保持读卡关闭。

PMS 读卡支持​

PMS 供应商实体卡读取操作建议
Opera Cloud (OHIP)适配器声明该功能时支持启用读卡前完成硬件验收
其他 PMS 供应商除非供应商声明支持，否则不可用使用手动房间或确认信息查询

当 PMS 未声明支持实体卡读取时，AVA 会默认拒绝读取。 现有的门卡编码流程仍可使用。

启用 PMS 读卡​

PMS 读卡直接使用 PMS 传输通道。 它不需要 Universal Encoder Agent 会话。 只有商户设置和 PMS 功能都允许时，AVA 才会启用扫描。

  1. 在 Encoder Type 下选择 PMS Integration。

  2. 确认 Enable PMS Encoder Integration 已打开。

  3. 确认至少有一个已发现的编码器处于 Active 状态。

  4. 打开 Enable physical keycard reading。

  5. 点击 Save。

  6. 打开 Entitlements 并重新加载页面。

    ✓ 当 PMS 报告支持实体卡读取时，会出现 Start scanning。 ✓ 扫描不可用时，手动房间和确认信息查询仍可用。

PMS kiosk 映射

对于 PMS Integration，AVA 首先根据活动的 PMS 编码器设备解析 kiosk 的 Device Model 映射。 如果该映射不可用或不匹配，AVA 会使用旧版 kiosk 映射。 保持目标编码器处于 Active 状态，并在 Device Routing 中使用其当前 PMS 编码器名称。

Opera 路由匹配必须精确

Opera 读卡需要匹配的工作站、编码器 ID、接口和 Door Lock 出站代码。 如果 Opera 返回重复或不完整的路由，AVA 会停用读卡，而不是自行猜测。 请让 Opera 管理员修正编码器目录，然后再次点击 Load Encoders。

Saflok 接口值

Opera 可能会显示类似 SL01 的编码器接口值。 AVA 使用该值选择匹配的 Door Lock 路由。 读卡请求改用发现到的数字出站代码。 你不需要手动修改该值。

路由已迁移

AVA 现在在 Settings → Kiosk → Device Routing 中管理 kiosk 路由。 Room Access 页面保留编码器设置，并在路由方面指向这里。

第 5 步：设置 kiosk 路由（可选）​

仅在 kiosk 专用路由场景下使用此部分：

  1. 前往 Settings → Kiosk。

  2. 打开 Device Routing。

  3. 打开 Enable guest selection，让客人在 kiosk 上选择编码器。

  4. 保持关闭则为每个 kiosk 添加路由规则。

  5. AVA 会将这些 kiosk 规则保存到 Mini MDM Device ID。

  6. 保存时，旧的设备 ID 映射会自动更新。

    ✓ 开启客人选择后，AVA 会隐藏手动路由规则。 ⚠️ 你仍需要在 Physical Encoder Devices 中至少添加一个编码器设备。 ✓ AVA 无需 kiosk 映射即可使用 encoderId 发送编码请求。

运营中的编码器选择行为​

  • 如果恰好只有一台编码器在线，AVA 会自动选择它。
  • 如果有多台编码器在线，员工必须明确选择一台。
  • 对于 GreatLocks，请使用匹配的行执行动态状态或配置操作。
  • 如果有多个 GreatLocks 服务器或 agent 可用，AVA 无法推断目标。
实时在线状态

Online 表示 AVA 已验证编码器及其 agent 隧道。 Unknown 表示 AVA 无法验证编码器状态。 Unknown 不代表编码器已离线。 只有连接真正建立后，Status: 行才会显示 online。 如果编码器掉线，请先修复 agent 或隧道。

第 6 步：设置 Windows Agent（仅 Windows Agent）​

如果未启用 Direct communication，请安装 Windows Agent：

  1. 前往 Windows Agent。

  2. 在新卡片上点击 Download Windows Agent，或在已有卡片上点击 Reinstall。

  3. 将 agent 安装到连接编码器的 Windows 电脑上。

  4. 如果卡片显示 Not connected 或 Never online，请解压下载的 zip，然后运行 download-installer.bat。

  5. 下载完成后，运行它保存的安装程序 .exe。

    ✓ agent 会在 Registered Agents 下显示状态详情。 ✓ AVA 在判断编码器是否可用时会使用这个实时状态。 ✓ 每张卡片都会显示 Installed version，并在可用时显示 Latest version。 ✓ 如果 agent 已是最新，你会看到 Latest version installed。 ✓ 如果 agent 版本过旧，请先点击 Update 再点击 Reinstall。

Be-Tech、Saflok、GreatLocks 和 LockSDK 都可以使用 Windows Agent。 对于 GreatLocks，请为每台已配置的编码器和连接的电脑重复 agent 设置。 确认每个 agent 使用匹配的 Encoder ID。 当 agent 版本过旧时，主卡片上的 Update 会出现在 Reinstall 之前。 打开 Advanced options 可执行 View Logs、Rotate Secret 或 Delete。 Rotate Secret 现在会先打开确认对话框，然后 AVA 才会断开当前 agent。

服务控制

Be-Tech 恢复时通常会自动启动已停止的客户端或服务。 需要手动控制服务时，可在 Windows Agent 托盘中使用 Start、Stop 或 Restart。 如果 Windows 请求权限，请在 UAC 提示中批准后继续。 如果取消了提示，请重新执行操作并批准它。

版本过期时会看到什么​

你会看到： 卡片显示 Outdated，或提示 heartbeat 没有上报已安装版本。

解决方法：

  1. 点击 Update。
  2. 阅读更新弹窗。
  3. 打开 Windows Agent 应用。
  4. 点击 Check for Update。
  5. 安装提供的更新。
  6. 刷新 Settings → Room Access，确认版本状态为最新。

LockSDK agent 卡片也会显示相同的版本状态。

第 7 步：设置编码默认值​

  1. 设置 Number of Cards to Encode（通常为 1–2）。
  2. 设置 Keycard Expiration Time（默认：11:00 AM）。 手动编码门卡时，该时间会预填到 Valid Until。
日用预订

如果预订明确为 day use 且已启用日用，AVA 会改用解析后的退房时间。 过夜预订仍使用 Keycard Expiration Time。

可选：展开 Advanced options 以启用 Heartbeat Monitor。

可选：将 PMS 房间映射到编码器名称​

如果编码器使用的房间名称与 PMS 不同：

故障排除​

如果编码器没有响应或门卡编码失败，请使用完整检查清单：

仍然卡住？​

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

  • ❌ 编码器设置可以保存，但设备仍处于离线状态
  • ❌ 任何房间的门卡都无法编码
  • ❌ agent 在 Registered Agents 中始终不显示在线

建议附上：

  • 编码器类型和型号
  • Keycard Encoder Settings 的截图
  • 问题开始的时间