桌面管理应用程序

使用 PSSP 客户端应用

跨平台 Tauri 应用可连接 Broker、认证会话、检查主题、发布测试 QoS 1 数据、检查 TCP/UDP 存活状态，并显示协议事件。它不是 OX Device 或 WebService 适配器。

投递模式由 Broker 决定

客户端发送持久 workerID，但不能自行成为共享 worker 或广播 viewer。请按照 Broker 配置为主体设置结构化投递授权。

本页内容

启动或打包
连接和认证
查找仅 AES 模式的 Broker 公钥
订阅和重放
发布 QoS 1 数据
验证 TCP/UDP
查看事件
故障排查

启动应用程序

cd client
npm install
npm run tauri:dev

在当前操作系统上创建安装包：

npm run tauri:build

平台	支持情况
Windows	受支持的 Tauri 目标；请在 Windows 或合适的 CI 目标上构建安装程序。
Linux	受支持的 Tauri 目标；在目标 Linux 构建环境中打包。
macOS	受支持的 Tauri 目标；在 macOS 上打包。

1. 连接和认证

请 Broker 管理员在其 SQLite 数据库中创建准确的客户端 ID、用户名、密码和 ACL。
打开连接（Connection）区域并输入 Broker 主机和端口。默认 PSSP 端口是 6688。
输入由 Broker 创建的凭据。客户端发送标准 PSSP AUTH，不会调用 WebService 或直接打开 SQLite。
将 TLS 1.3 传输（TLS 1.3 transport）设置为与 Broker 匹配。
- 使用内置明文开发配置时，保持关闭。
- 使用 TLS 生产配置时，设为开启。Broker 主机名必须匹配操作系统信任的证书。
- 使用关闭 TLS 的 AES 模式时，保持 TLS 关闭，并将预置的 Broker X25519 公钥填入 Broker 仅 AES X25519 公钥（Broker AES-only X25519 public key）。客户端会拒绝缺少或不匹配的固定值。
选择连接（Connect）。

连接成功

状态区会变为“已连接（Connected）”，显示 Broker 签发的连接 ID，并标明 AES 会话是否有效。密码仅用于当前连接；初始应用不会将密码保存到磁盘。

本地连接值	值
主机 / 端口	`127.0.0.1:6688`
客户端 ID / 用户名 / 密码	由 `pssp-broker setup` 或 `create-principal` 创建的准确主体。
TLS	仅本地明文或仅 AES 配置关闭。

绝不要在私有测试环境外使用示例凭据。

开发 Broker 在没有 TLS/AES 的情况下发送凭据和负载。任何不可信网络都应使用 TLS + AES，或使用安全预置 X25519 固定值的仅 AES 模式。

查找仅 AES 连接使用的 Broker X25519 公钥

只有当 Broker 设置为 tls.enabled = false 且 encryption.enabled = true 时，才需要此公钥。Broker 管理员只生成一次长期 X25519 私钥并将其保密，然后派生出供所有客户端固定的对应公钥。该公钥不是客户端凭据，也不存储在 Broker 的 SQLite 数据库中。

如果部署还没有私钥，请从仓库根目录生成。该命令只输出私钥值，不会自动将其保存到任何位置。
```
cargo run -p pssp-broker -- generate-aes-only-private-key
```
将输出值安全地保存为 Broker 配置中的 encryption.static_private_key，或保存为受保护密钥文件中的唯一内容。每个 Broker 部署只生成一次；更换私钥会改变公钥，因此必须更新所有客户端的固定公钥。
从受保护的密钥文件派生公钥：
```
cargo run -p pssp-broker -- aes-only-public-key \
  --private-key-file /protected/path/aes-only-private-key
```
如果私钥直接保存在 encryption.static_private_key 中，请省略输入选项，并在隐藏输入提示处粘贴该私钥值：
```
cargo run -p pssp-broker -- aes-only-public-key
```
将命令输出的单行公钥（不要复制私钥）粘贴到客户端的 Broker 仅 AES X25519 公钥（Broker AES-only X25519 public key）输入框，然后在关闭 TLS 1.3 传输（TLS 1.3 transport）的情况下连接。

已安装 Broker 的命令

如果部署系统已将 pssp-broker 安装到 PATH，请使用 pssp-broker generate-aes-only-private-key 和 pssp-broker aes-only-public-key，无需添加仓库环境使用的 cargo run -p pssp-broker -- 前缀。

密钥材料	保存位置	接收方
X25519 私钥	受保护 Broker 配置的 `encryption.static_private_key` 中，或管理员用于设置该配置项的受保护密钥文件中。	仅限 Broker 管理员和 Broker 进程。绝不要复制到客户端。
X25519 公钥	需要时由私钥派生；Broker 在仅 AES 连接设置期间也会派生并公布该公钥。	通过可信渠道预置到客户端，并在客户端连接设置中固定。
每连接 AES 密钥	通过 X25519 + HKDF 在内存中为当前会话派生；既不存储，也不通过 TCP 发送。	由 Broker 和客户端在该连接内部使用。

不要信任通过同一连接获知但未经核验的公钥。

请通过可信的管理员渠道核对或分发公钥。客户端会拒绝缺失或不匹配的固定值，因为接受被替换的公钥会导致中间人攻击。

在订阅（Subscriptions）区域中输入主题过滤器并选择其起始位置。

控件	输入内容	效果
过滤器（Filter）	例如 `#`、`devices/+/audio/#` 或 `control/room-7/#`	仅投递匹配且已授权的主题。`+` 匹配一个路径段；末尾 `#` 匹配后代主题。
重放：最新消息（Replay: Latest）	`latest`	跳过现有保留消息；接收订阅创建后发布的数据。
重放：最早可用消息（Replay: Earliest available）	`earliest`	接收匹配主题环中当前保留的消息，然后接收新消息。
重放：从确认处恢复（Replay: Resume after ACK）	`resume`	重连后复用相同订阅者标识，并接收最后一次 `MSGACK` 之后仍被保留的消息。
Worker ID	稳定名称，例如 `desktop-operator`	恢复身份的一部分。为同一逻辑消费者重连时保持不变。

选择订阅（Subscribe）。Broker 返回订阅确认，消息出现在协议事件列表中。管理应用在将消息接收到其内存诊断日志后确认；生产应用客户端必须在发送 MSGACK 前持久化或可靠排队负载。

3. 发布 QoS 1 测试负载

在发布 QoS 1（Publish QoS 1）中输入具体主题，例如 demo/topic。发布主题中不要使用通配符。
输入不透明的 UTF-8 测试负载。
选择发布（Publish）。

应用通过 TCP QoS 1 发送 PUBLISH，并自动管理发布者会话 ID 与序号。Broker 将负载接收到主题缓存后返回 PUBACK。所有匹配订阅——包括同一桌面应用中的订阅——都会收到 MESSAGE。

不透明意味着由应用定义

桌面 GUI 为了便于测试而发布 UTF-8。PSSP 本身接受任何字节。未来的应用客户端可以发送编码媒体分片、二进制文件、协议缓冲区（Protocol Buffers）、命令数据或同步数据，而无需修改 Broker。

4. 验证 TCP 和 UDP 存活状态

按钮	协议操作	预期结果
TCP 连通测试（TCP Ping）	TCP `PING`	出现 `PONG` 协议事件。适用于任何活动的 PSSP TCP 连接。
绑定 UDP（Bind UDP）	携带会话关联令牌的 `UDP_BIND`	Broker 绑定客户端 UDP 源端点。状态从“UDP：未绑定（UDP: not bound）”变为“UDP：已绑定（UDP: bound）”。
UDP 连通测试（UDP Ping）	UDP `PING`	客户端验证 Broker UDP `PONG` 后命令完成。请先绑定 UDP。

启用 AES 时，绑定和 ping 使用在 TLS 内或通过固定 X25519 + HKDF 创建的 AES 保护会话。在有意使用明文 Broker 模式时，UDP 使用临时的已认证会话令牌，但没有 TLS/AES 保护。

5. 阅读事件日志

事件	含义	操作
`connected`	登录和所需会话设置已完成。	订阅或发布。
`message`	收到 QoS 1 投递。主题、序列、元数据摘要和 base64url 负载可用。	检查负载，或使用专用应用客户端进行实际处理。
`pong`	Broker 响应了 TCP ping。	连接在协议层仍存活。
`gap`	请求重放的数据已从有限的 Broker 内存中淘汰。	从应用归档恢复，或检查保留限制。
`error`	Broker 拒绝操作，或本地操作失败。	查看显示的代码/详情，并检查 ACL、凭据、安全模式或网络配置。
`disconnected`	TCP 会话已结束；会话密钥和 UDP 绑定不再适用。	重连。适用时使用相同订阅者标识和 `resume`。

故障排查清单

详细诊断命令、安全模式设置和逐步恢复方法，请参阅专门的 PSSP 故障排查指南。

问题	检查项
连接立即失败	确认 Broker 正在运行、主机/端口正确，并且可访问 TCP 6688。
TLS 握手失败	仅在 Broker 配置启用 TLS 时在应用中启用 TLS；使用操作系统信任且主机名匹配的证书。
认证失败	验证全部三个字段：客户端 ID、用户名和密码。Broker 允许客户端 ID 有多个用户记录，但每个精确组合都必须存在。
订阅/发布未授权	使用 Broker CLI 检查该主体在 SQLite 中的 ACL。发布必须使用具体主题；过滤器仅可用于订阅/ACL。
UDP 连通测试超时	保持 TCP 活动，先点击“绑定 UDP（Bind UDP）”，并允许 UDP 6688 通过本地防火墙、NAT 和网络策略。
恢复后没有旧数据	使用相同订阅者标识，在恢复 TTL 过期前重连，并确认数据未被淘汰或因 Broker 重启丢失。