HandyCafe Docs
owner it-admin

旧版客户端设置

HandyCafe 可以与较旧的 V3 和 V4 客户端安装并行运行而不会中断。旧版客户端设置页控制两项彼此独立的功能：

  1. 运行时协议。 启用可让 V3 和 V4 客户端按原始端口连接到此服务端的网络侦听器。
  2. 数据库迁移。 可选地将旧版本地安装中的会员、定价、商品、订单、交易和日志导入新的 HandyCafe 数据库。此功能仅限 Windows。

这两个功能彼此独立。您可以只启用运行时支持而不迁移数据，也可以只迁移数据而不启用运行时支持，或者两者同时启用。

运行时协议区域

启用旧版客户端支持

该区域顶部有一个总开关。开启后，服务端会启动三个网络侦听器：

  • 绑定到已配置组播地址的 UDP 侦听器。
  • 位于 UDP port + 2 的 TCP 命令侦听器。
  • 位于 UDP port + 7 的 TCP 文件传输侦听器。

关闭该开关会一次性停止这三个侦听器。您可以在禁用状态下调整端口号或编码，然后重新启用以应用更改。

配置字段

字段 默认值 说明
认证密钥 HANDYCAFE 共享的 10 字符密钥。每个入站和出站帧都会携带这个字符串。不匹配的帧会被丢弃。所有旧版客户端都必须使用相同的密钥。
UDP 组播 IP 230.4.4.46 用于客户端发现广播和基于 UDP 的命令下发的组播组。大多数旧版客户端构建中都是硬编码的。
服务端 UDP 端口 710 服务端接收客户端广播和命令的 UDP 端口。旧版客户端会把数据发送到这个端口。
客户端 UDP 端口 711 旧版客户端监听的 UDP 端口。服务端会向已发现的客户端 IP 发送单播管理命令到这个端口。
编码 cp1254 线缆格式字符串字段的字符编码。土耳其安装请使用 cp1254，西欧安装请使用 cp1252。未知值会回退到 cp1254，并在服务端日志中写入警告。
服务端版本 3.4.01 每个 UDP 广播中都会发送的版本字符串。有些旧版客户端会拒绝它们无法识别的版本帧。请将其设置为与您原始服务端版本一致。
协议变体 STE 线缆格式选择。见下方的变体对比。
不活跃超时 10 秒。按 MAC 地址计算的看门狗。如果在此时间窗口内没有收到客户端流量，就会将该客户端标记为离线。对于每 2 到 3 秒广播一次的旧版客户端，10 秒是合适的。

派生端口

表单下方会显示一行只读内容，列出派生出来的 TCP 端口：

TCP 命令端口: 712   文件传输端口: 717

这些端口是根据 UDP 服务端端口计算出来的，无需单独配置。如果您把服务端 UDP 端口改成其他值，派生端口也会随之变化。

协议变体

协议变体字段用于选择服务端使用的线缆格式。请选择与您旧版服务端构建方式相匹配的变体。

变体 适用场景
STE（Smart/Turbo Edition） 现代旧版代码库。会在帧结构前添加 70 字节的 license-info 前缀。帧大小为 1337 字节。如果您的旧版安装使用的是 Smart 或 Turbo 版本，请选择它。
Standard 朴素的基础旧版构建。没有 license-info 前缀，帧大小为 1267 字节。只有在您的旧版安装是没有注册许可的 Standard 版本时才选择它。

选错变体会导致帧被丢弃或误读。常见症状是客户端看起来在线，但会忽略每一条命令，或者命令数据因 70 字节偏移而错位。

与现代客户端共存

旧版端口（710、711、712、717）与现代 HandyCafe 协议端口（TCP 5001、5002、5003，UDP 5004）完全分离，不会冲突。您可以在同一局域网中混合使用新旧客户端，并在同一个管理面板中统一管理。

应用更改

运行时协议区域中的每个字段都会在页面底部的全局“保存”按钮点击后保存。保存时，服务端会：

  1. 如果旧版侦听器正在运行，则先停止它们。
  2. 验证认证密钥（不能为空）。
  3. 根据更新后的字段构建新的侦听器配置。
  4. 并发重启侦听器。
  5. 当三个侦听器全部恢复在线后发送通知。

如果某个端口已被其他进程占用，服务端会报告错误，并将开关切回关闭状态。请使用 netstat 检查防火墙和其他服务，并选择一个空闲端口范围。

数据库迁移区域（仅限 Windows）

该功能仅在 HandyCafe 运行于 Windows 时可用。在 macOS 和 Linux 上，该区域会显示提示：“数据库迁移仅支持 Windows。”

检测

打开页面时，服务端会扫描系统中的旧版安装。检测会查看：

  • 注册表以及典型安装路径，例如 Program Files\HandyCafe 和 C:\HandyCafe。
  • 与安装目录并存的数据库文件。
  • 安装目录中的配置 INI 文件。

检测成功后，页面会显示：

标签 含义
安装路径 旧版安装所在的磁盘路径。
数据库路径 旧版数据库文件的完整路径。
服务端版本 从旧版配置中解析出的版本。
INI 文件数量 检测到的配置文件数量。用于快速确认安装是否完整。

如果没有检测到安装，页面会显示“未检测到旧版安装”。此时您仍然可以启用运行时支持；只是迁移功能没有可导入的数据。

迁移状态

页面会跟踪迁移历史：

状态 含义
never 您尚未运行过迁移。
in_progress 当前正在执行迁移。此状态下请勿关闭服务端。
completed 最近一次迁移完成，且没有警告。
completed_with_warnings 最近一次迁移完成，但有一些记录被跳过（例如编码错误或日期格式错误）。继续之前请先查看警告。
undone 最近一次迁移已回滚。

第一次成功运行后，“开始迁移” 按钮会变为“重新运行迁移”。

会迁移哪些内容

表 说明
会员 包含名称、联系方式和账户余额的顾客记录。
定价 价格表和按小时的费率。
商品 商品目录条目。
订单 带有时段引用的订单历史。
交易 包含时间戳、金额和支付方式的账本记录。
日志 来自旧版数据库的审计与警告记录。

“文件安全”保证

页面会以蓝色提示：“原始数据库文件不会被删除。只要迁移结果确认无误，您就可以安全删除它们。”迁移对源数据是只读的。即使您多次运行迁移，旧版数据库也会保持不变。这让您可以放心试验导入、查看计数并在必要时回滚。

开始、重新运行与撤销

  • 开始迁移。 打开进度弹窗。导入进行时，弹窗会显示当前阶段和已处理的记录数。迁移期间请勿关闭 HandyCafe。
  • 重新运行迁移。 在完成一次迁移后可用。它会从头重新导入，新的导入结果会替换 HandyCafe 中先前的数据。
  • 撤销迁移。 在完成一次迁移后可用。打开确认对话框后，确认即可删除 HandyCafe 中所有已迁移的行。旧版源数据不会受到影响。撤销后状态会回到 never。

完成但有警告

如果迁移以 completed_with_warnings 结束，会出现一条黄色横幅，并附带一个“详情”链接。点击后可展开被跳过记录的列表及原因。常见原因包括：

  • 编码不匹配。 源记录中的字符无法使用当前编码正确解码。请更改编码字段（cp1254 或 cp1252）后重新运行迁移。
  • 日期格式错误。 一些旧版记录包含无效时间戳。系统会跳过这些记录，以便仍然导入有效记录。
  • 重复键。 某条记录的标识符已经存在于 HandyCafe 中。迁移会保留现有记录并跳过重复项。

提示

  • 在执行迁移前先停止旧版服务端。如果旧系统仍在向数据库写入，导入可能会看到过期或不完整的数据。
  • 在第一次迁移前，请把编码字段设成与旧版地区相匹配的值。导入完成后再改编码，无法修复已经损坏的名称。
  • 一定要先做一次测试迁移。在提交给员工使用新系统之前，先检查“上次计数”下的记录数，并抽查几条会员和交易记录。
  • 在过渡期内启用运行时支持并保持旧版客户端在线。这样您可以在退役旧服务端之前先确认新服务端对它们的服务行为完全一致。
  • 如果您更改了服务端 UDP 端口，请记得派生出来的命令和文件传输端口也会一起变化，防火墙规则需要同步更新。