PSSP 连接故障排查

当客户端无法连接、认证、订阅、发布、绑定 UDP 或恢复数据时，请使用本指南并从上到下检查。修改密码无法修复未监听的 Broker，修改 ACL 也无法修复失败的登录。

当命令行找不到 pssp-broker 时

仅检出此仓库不会自动把可执行文件安装到 PATH。其源代码位于 broker/；本地构建产物位于 target/debug/pssp-broker 或 target/release/pssp-broker（Windows 上带有 .exe）。在仓库根目录中，可以通过 Cargo 运行，也可以直接使用构建产物路径：

cargo run -p pssp-broker -- --help
./target/debug/pssp-broker --help                 # macOS/Linux
.\target\debug\pssp-broker.exe --help             # Windows PowerShell

按此顺序诊断

1. 启动 Broker。确认进程持续运行，没有因配置、证书、密钥或数据库错误而退出。
2. 确认 TCP 可达。确认预期进程正在监听 TCP 6688，且客户端能够访问该主机和端口。
3. 匹配安全模式。TLS、PSSP AES、客户端 TLS 选项、证书信任和仅 AES 公钥固定值必须一致。
4. 验证认证。精确的 clientId + username 记录必须存在、已启用且密码正确。
5. 验证授权。登录成功并不自动授予发布/订阅权限；检查主体的主题 ACL。
6. 测试数据流。依次测试 TCP 连通性、订阅/发布、UDP 绑定与连通性，以及重放与保留行为。

案例：pssp-admin / admin 无法连接

调查客户端使用客户端 ID pssp-admin、用户名 admin 和指定密码时发现了以下问题。开发环境很容易同时出现这些问题，因此在此保留完整记录。

正确启动桌面客户端

1. 首次安装依赖。

   cd client
   npm install

2. 启动包含 Rust 后端的 Tauri 应用。

   npm run tauri:dev

3. 不要把 npm run dev 当作完整客户端；它只启动 Vite 网页界面。connect 等原生命令需要 Tauri 桌面运行时。

如果构建失败，请确认 Node.js 20+、当前 Rust 工具链以及 Tauri 2 所需的操作系统依赖。可单独检查 Rust 工作区以显示后端编译错误：

cargo check --workspace

确认 Broker 已运行并监听

开发环境启动

cargo run -p pssp-broker -- serve \
  --config broker/config/pssp.example.toml

保持终端打开并读取第一条错误。健康启动会记录 TCP/UDP 监听地址及所选 TLS/AES 模式。

监听端口检查

如果 Broker 只监听 127.0.0.1，远程客户端无法连接。仅在防火墙限制到可信网络时使用 0.0.0.0:6688 等接口，并确认端口没有被其他进程占用。

服务检查

初始化 SQLite 并安全修复权限

数据库缺失、未初始化或不可读时，Broker 不会启动。SQLite 保存主体、Argon2id 密码哈希、启用状态、ACL 和凭据审计事件；主题负载与会话状态只保存在内存中。

1. 打开正在使用的 TOML 配置并确认 storage.sqlite_path。不要用一份配置排查，却用另一份配置启动 Broker。
2. 选择运行 Broker 服务的账号。在 Unix 上，将 storage.unix_owner_user 和 storage.unix_owner_group 同时设置为已存在的服务账号；用户自有的开发数据库则可同时省略这两项。不能只设置其中一项。
3. 用同一份配置初始化结构并创建引导管理员。命令会创建缺失的父目录与 SQLite 文件，并安全提示输入至少 12 个字符的密码。在 Unix 上，数据库及已有旁路文件权限会限制为 0600。如果配置了 Unix 所有者与组，父目录还会限制为 0700 并应用该所有权；应以 root 或该服务账号运行 setup，确保有权执行这些修改。

   pssp-broker setup --config /etc/pssp/pssp.toml \
     --bootstrap-client-id pssp-admin \
     --bootstrap-username admin

4. 验证元数据；以下命令不会显示密码哈希。

   pssp-broker list-principals --config /etc/pssp/pssp.toml
   pssp-broker list-acls --config /etc/pssp/pssp.toml \
     --client-id pssp-admin --username admin

5. 以同一账号启动服务，然后确认监听端口。

文件系统权限与主题授权是两回事

所有主体和 ACL 命令都必须使用与 serve 相同的 --config。修改型 CLI 命令会保留配置的 Unix 所有者和安全权限；把数据库文件手动改成所有人可读或可写，并不会授予任何 PSSP 主题权限。

本地仓库替代方案

本地开发使用 broker/config/pssp.example.toml，并从仓库根目录运行下列命令。配置的相对路径会在工作区内创建 data/pssp-broker.sqlite3，避免用户运行的 Broker 混用安装服务的数据库：

cargo run -p pssp-broker -- setup \
  --config broker/config/pssp.example.toml \
  --bootstrap-client-id pssp-admin --bootstrap-username admin

cargo run -p pssp-broker -- serve \
  --config broker/config/pssp.example.toml

解决 authentication_failed

线上登录包含三个独立值：clientId、username 和 password。前两个值选择一条精确 SQLite 记录，第三个值与 Argon2id 哈希比较。

1. 列出主体并确认精确拼写、大小写和启用状态。

   pssp-broker list-principals --config /etc/pssp/pssp.toml

2. 如果密码未知，请轮换密码；无法从哈希恢复原密码。

   pssp-broker rotate-password --config /etc/pssp/pssp.toml \
     --client-id pssp-admin --username admin

3. 启用已禁用主体。

   pssp-broker set-principal-enabled --config /etc/pssp/pssp.toml \
     --client-id pssp-admin --username admin --enabled

4. 修改或失败后等待 storage.auth_cache_seconds（默认 30 秒），或重启 Broker 后再测试。
5. 输入值时不要带前后空格。客户端按原样发送，不会创建账号或替换为默认密码。

逐步设置仅 AES 连接

仅 AES 表示关闭 TLS，同时启用 PSSP AES-256-GCM。Broker 使用长期 X25519 身份密钥；每个会话通过固定的 Broker 公钥、客户端临时密钥和 HKDF-SHA-256 派生新的 AES 密钥。AES 会话密钥不会通过网络传输。

1. 将仅 AES 模板复制到受保护的部署配置。

   cp broker/config/pssp.aes-only.example.toml /etc/pssp/pssp.toml

2. 生成随机私钥并保存在仅管理员可读的位置。

   umask 077
   pssp-broker generate-aes-only-private-key \
     > /etc/pssp/aes-only-private-key

3. 把生成值复制到 /etc/pssp/pssp.toml 的 encryption.static_private_key。不要使用 AAAAAAAA...AAA；它只是格式示例。
4. 派生客户端必须固定的公钥。

   pssp-broker aes-only-public-key \
     --private-key-file /etc/pssp/aes-only-private-key

5. 确认安全配置。

   [tls]
   enabled = false
   
   [encryption]
   enabled = true
   static_private_key = "GENERATED_PRIVATE_KEY"
   
   [transport]
   allow_insecure_tcp_udp = false

6. 使用同一配置初始化 SQLite，然后启动 Broker。

   pssp-broker setup --config /etc/pssp/pssp.toml \
     --bootstrap-client-id pssp-admin --bootstrap-username admin
   pssp-broker serve --config /etc/pssp/pssp.toml

7. 在桌面客户端输入 Broker 主机和端口，关闭 TLS 1.3 传输（TLS 1.3 transport），把派生公钥粘贴到 Broker 仅 AES X25519 公钥（Broker AES-only X25519 public key），输入准确凭据并选择连接（Connect）。
8. 确认客户端显示“AES 会话：活动（AES session: active）”，然后测试 TCP 连通性、订阅/发布、UDP 绑定和 UDP 连通性。

设置 TLS + AES

1. 从 broker/config/pssp.production.example.toml 开始。
2. 安装 Broker 服务账号可读的 TLS 证书和私钥。证书必须包含客户端使用的 DNS 名称。
3. 配置两个保护层。

   [tls]
   enabled = true
   certificate_file = "/etc/pssp/tls/fullchain.pem"
   private_key_file = "/etc/pssp/tls/privkey.pem"
   
   [encryption]
   enabled = true
   
   [transport]
   allow_insecure_tcp_udp = false

4. 初始化 SQLite、启动 Broker，并确认日志显示 tls=true 和 encryption=true。
5. 客户端使用证书中的 DNS 主机名连接并开启 TLS 1.3 传输（TLS 1.3 transport）；此模式不使用仅 AES 公钥输入框。

TLS 握手错误通常表示客户端 TLS 选项与 Broker 不一致、证书过期或不受信任、主机名不匹配，或缺少中间证书。除非证书的使用者可选名称（Subject Alternative Name）包含该 IP，否则使用 IP 地址连接会失败。

仅在隔离的本地环境使用明文

[tls]
enabled = false

[encryption]
enabled = false

[transport]
allow_insecure_tcp_udp = true

关闭客户端 TLS 并保持仅 AES 固定值为空。当 TLS/AES 都关闭时，Broker 要求显式设置 allow_insecure_tcp_udp = true；当 TLS 或 AES 任一开启时，该值又必须为 false。

修复发布和订阅授权

认证与授权相互独立。主体可以成功登录但没有任何 ACL。

pssp-broker list-acls --config /etc/pssp/pssp.toml \
  --client-id pssp-admin --username admin

为管理员测试账号授予所有主题权限：

pssp-broker grant-acl --config /etc/pssp/pssp.toml \
  --client-id pssp-admin --username admin \
  --action publish --topic-filter '#'

pssp-broker grant-acl --config /etc/pssp/pssp.toml \
  --client-id pssp-admin --username admin \
  --action subscribe --topic-filter '#'

修复 UDP 绑定与连通测试

1. 先完成已认证 TCP 连接。UDP 关联到活动 TCP 会话。
2. 先选择绑定 UDP（Bind UDP），再选择 UDP 连通测试（UDP Ping）。
3. 保持 TCP 连接；关闭后 UDP 令牌、AES 材料和端点关联全部失效。
4. 允许 UDP 6688 通过主机防火墙、云防火墙、VPN、NAT 以及容器/虚拟机转发。
5. 确认 TCP 与 UDP 指向相同 Broker 主机和配置端口。
6. 如果 TCP 正常而 UDP 超时，请在绑定时查看 Broker 日志。网络策略可能允许 TCP 但静默丢弃 UDP。

UDP 是 QoS 0：没有重放、接收保证或重试。一次心跳丢失不代表 TCP 会话已断开；使用 TCP 连通测试（TCP Ping）检查可靠控制路径。

重放、GAP、断线和慢客户端

常见错误与症状参考

收集有效的故障报告

向其他开发者求助前，请记录以下信息，但不要包含密码、私钥、原始会话密钥或敏感负载：

• 操作系统，以及 Broker 是通过 Cargo、systemd、launchd 还是任务计划程序运行。
• Broker 和客户端版本或提交 ID。
• 主机和端口；必要时隐藏私有地址。
• 所选模式：TLS + AES、仅 AES 或有意明文。
• 客户端显示的准确错误及对应 Broker 日志行。
• TCP 6688 是否监听且可远程访问。
• SQLite 配置路径及所有者/权限；不要提供数据库内容或密码哈希。
• list-principals 和相关 list-acls 输出；这些命令不会显示哈希。
• 问题属于 TCP 连接、认证、ACL、TCP 数据、UDP 还是重放。

部署与账号管理请参阅 Broker 指南，UI 操作请参阅客户端指南，记录级行为请参阅协议参考。· 专有软件 — © 2026 OX Recorder · 许可证信息