配置与排查
配置文件
安装包中的配置文件为 conf/zkipc-client.conf,默认内容如下:
[connection]
token=
resolver=114.114.114.114
reconnect=true
| 配置项 | 说明 |
|---|---|
token | 节点连接凭据。留空时自动生成 UUID 并写回配置,已有值保持不变;凭据需要在服务端登记。 |
resolver | 域名解析服务器,默认 114.114.114.114;留空时使用系统域名解析设置。 |
reconnect | 断线后是否自动重连,默认 true;设置为 false 时关闭自动重连。 |
当前客户端不开放多账号配置。
Windows 固定读取可执行文件旁的 conf/zkipc-client.conf。Linux 优先读取 /etc/zkipc-client/conf/zkipc-client.conf(该文件存在时),否则读取可执行文件旁的配置。启动日志中的“已读取客户端配置”会显示实际路径,修改前请先核对该路径。
配置修改后重启客户端或系统服务。不要为处理普通断线而清空 token,清空后重新生成的凭据需要再次登记。
日志位置与保留规则
前台运行时,日志同时输出到终端和文件;系统服务运行时写入日志文件。日志使用本地日期时间和中文级别,终端按级别显示颜色,文件保持纯文本。
| 平台 | 日志位置示例 |
|---|---|
| Windows | 可执行文件旁的 zkipc-client-2026-10-13.log |
| Linux | /var/log/zkipc-client-2026-10-13.log |
日志按天保存,保留当天及此前六天。客户端在启动和每天首次写入日志时清理更早的客户端日期日志,停止运行期间不会主动清理。
连接成功示例:
2026-10-13 15:09:32 [信息] 已连接服务器:gateway.zkipc.cn
常见问题
认证未完成或连接已关闭
可能看到以下日志:
2026-10-13 15:31:51 [错误] 连接失败:认证未完成(连接已关闭)
先在帮助菜单中选择 7 核对当前凭据,再登录云平台的节点管理,确认对应节点保存了相同的连接密钥且处于启用状态。凭据已登记仍无法连接时,应结合服务端认证日志检查服务是否正常及客户端安装包是否匹配。
“连接已关闭”表示认证过程中连接结束,不能仅凭这条日志断定凭据错误。当前客户端没有通信协议切换参数,需要升级时请使用新的安装包。
域名解析超时
先确认主机可以访问互联网,再检查配置中的域名解析服务器是否在现场网络中可用。可将 resolver 留空以使用系统域名解析设置,保存后重启客户端。
Windows 可使用:
Resolve-DnsName gateway.zkipc.cn
Resolve-DnsName gateway.zkipc.cn -Server 114.114.114.114
这两条指令分别检查系统解析和默认指定服务器的解析情况。若现场网络限制外部域名解析服务器,请使用网络管理员提供的可用地址。
服务尚未注册或没有操作权限
出现“系统服务尚未注册”时,先执行 install 或在菜单中选择 1,再启动服务。Windows 服务管理请使用管理员终端,Linux 请使用超级用户权限。
无法保存凭据时,检查配置目录写入权限;无法写入日志时,检查可执行文件所在目录或 /var/log 的权限。安装目录应保持固定。
服务正在运行,但节点仍离线
服务状态只反映本机服务是否运行。请检查客户端日期日志,依次核对配置路径、凭据登记、域名解析及现场网络。节点上线后,如果映射仍无法访问,再按隧道管理排查顺序检查目标服务和映射配置。
提示不支持启动参数
不带参数时直接连接服务器;help、--help、-h 打开菜单;服务管理使用 install、start、stop、restart、uninstall、status。请按服务管理中的示例运行,每次只执行一个指令。