KnotLinkService

KnotLinkService 是一个仅监听本机回环地址的 Qt5 TCP 消息路由服务，提供发布/订阅与请求/响应能力。

支持范围

平台	架构	安装包	服务管理器	状态
Windows	x64	现有发布方式	现有方式	保持兼容，本仓库 CI 暂不覆盖
Ubuntu 22.04	amd64	.deb	systemd	CI 编译、安装与协议测试
macOS 14	arm64	.pkg	launchd	CI 编译、安装与协议测试

当前版本记录在根目录的 VERSION.txt 文件中。GitHub 标签必须使用完全一致的 v<版本> 格式，例如 v3.1.0.0。文件使用 .txt 后缀是为了避免在大小写不敏感的 macOS 文件系统上遮蔽 C++ 标准头 <version>。

Qt5 已被 Homebrew 标记为 deprecated，并计划于 2027-05-19 禁用。当前版本继续使用 Qt5 以保持兼容，但必须在该日期前完成 Qt6 迁移。

端口与协议

服务只监听 127.0.0.1：

端口	用途
6370	发布消息
6372	订阅消息
6376	发起请求
6378	注册响应者并返回结果

每条 TCP 消息使用固定 8 字节大端头部：

1. 2 字节魔数：0x4B4B
2. 2 字节协议版本：0x0002
3. 4 字节无符号消息体长度
4. UTF-8 消息体，最大 16 MiB

发送 heartbeat 会收到 heartbeat_response。业务消息使用第一个 &*& 分隔 key 与 payload；payload 内后续出现的 &*& 会原样保留。

Linux 安装

校验并安装 Actions 生成的包：

sha256sum -c SHA256SUMS
sudo apt install ./KnotLinkService_3.1.0.0_amd64.deb

服务以 systemd DynamicUser 创建的非 root 身份运行：

systemctl status knotlink
journalctl -u knotlink -f

卸载：

sudo apt purge knotlinkservice

程序安装在 /opt/KnotLinkService/KnotLinkService，日志只写入 journald。

macOS 安装

Actions 的普通分支构建生成未使用 Developer ID 签名、未公证的测试 .pkg。它只适合内部验证，不应作为正式对外发布包。

shasum -a 256 -c SHA256SUMS
sudo installer -pkg KnotLinkService-3.1.0.0-macos-arm64.pkg -target /

安装后程序以 nobody 身份运行：

sudo launchctl print system/com.knotlink.service
tail -f /Library/Logs/KnotLinkService/service.log

macOS .pkg 没有原生卸载事务。手动卸载时使用以下明确路径：

sudo launchctl bootout system /Library/LaunchDaemons/com.knotlink.service.plist
sudo rm -f /Library/LaunchDaemons/com.knotlink.service.plist
sudo rm -rf /usr/local/KnotLinkService
sudo rm -rf /Library/Logs/KnotLinkService
sudo pkgutil --forget com.knotlink.service

构建与测试

项目使用 qmake：

mkdir -p build/local
cd build/local
qmake ../../KnotLinkService.pro
make

本仓库将 GitHub Actions 作为 Linux/macOS 的权威构建环境。每次 push 都会执行：

1. Qt5 编译，并将项目警告视为错误。
2. 裸二进制协议冒烟测试。
3. 平台安装包构建与结构检查。
4. 在 runner 上真实安装 systemd/launchd 服务。
5. 以安装后的服务再次执行协议测试并验证非 root 身份。
6. 卸载与残留检查。

测试脚本仅依赖 Python 标准库：

python3 tests/protocol_smoke.py --executable ./KnotLinkService
python3 tests/protocol_smoke.py --service

测试覆盖四端口心跳、TCP 拆包/粘包、发布订阅、请求响应、payload 分隔符保留、非法帧断开和端口占用启动失败。

GitHub 标签发布与 Apple 签名

v* 标签在 Linux/macOS 任务全部通过后创建 draft Release。仓库未配置 Apple secrets 时，草稿会明确标注 macOS 包未签名、未公证。

要启用 Developer ID 签名、公证与 staple，必须一次性配置完整的 Actions secrets：

• APPLE_APPLICATION_CERT_P12_BASE64
• APPLE_APPLICATION_CERT_PASSWORD
• APPLE_APPLICATION_IDENTITY
• APPLE_INSTALLER_CERT_P12_BASE64
• APPLE_INSTALLER_CERT_PASSWORD
• APPLE_INSTALLER_IDENTITY
• APPLE_NOTARY_KEY_P8_BASE64
• APPLE_NOTARY_KEY_ID
• APPLE_NOTARY_ISSUER_ID

只配置其中一部分会主动终止 macOS job，防止误发布未签名产物。证书使用 Developer ID Application 与 Developer ID Installer 类型，公证使用 App Store Connect API key。

第三方组件

• Qt 5 Core 与 Qt 5 Network：GNU LGPL v3 动态链接。
• QsLog：BSD 3-Clause。

许可证和第三方声明位于 deploy/common 与 QsLog/LICENSE.txt，并随 Linux/macOS 安装包分发。本仓库未在本次跨平台工作中新增或变更主项目许可证。