运行并配置 PSSP Broker

Broker 是适用于 Windows/Linux/macOS 的独立服务。它认证客户端、检查 ACL、保存有限的内存主题缓存、分发不透明字节，并且从不解析媒体或应用程序负载。

在哪里查找以及如何运行 pssp-broker

Cargo 包和可执行文件名为 pssp-broker，但其源代码目录名为 broker/。检出仓库不会自动把可执行文件安装到 shell 的 PATH。因此，即使 Broker 源代码和本地构建的二进制文件存在，直接运行 pssp-broker list-principals ... 仍可能提示“找不到命令”。

对于本地构建的调试版 Broker，以下形式等效：

# 让 Cargo 构建并运行
cargo run -p pssp-broker -- --help
cargo run -p pssp-broker -- list-principals --config broker/config/pssp.example.toml

# 在 macOS/Linux 上直接运行构建产物
./target/debug/pssp-broker --help
./target/debug/pssp-broker list-principals --config broker/config/pssp.example.toml

# Windows PowerShell
.\target\debug\pssp-broker.exe --help

快速开始：本地可信网络

1. 从仓库根目录构建或检查工作区。

   cargo check --workspace

2. 初始化 Broker 自主管理的 SQLite 数据库。使用随附开发配置并以仓库根目录为工作目录时，会创建 data/pssp-broker.sqlite3。命令会安全地提示输入密码。

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

3. 运行配置。

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

选择传输模式

# 仅用于可信/私有网络模式
[tls]
enabled = false

[encryption]
enabled = false

[transport]
allow_insecure_tcp_udp = true

配置参考

本地测试从 broker/config/pssp.example.toml 开始；安全部署从 broker/config/pssp.production.example.toml 开始。

数据库创建与文件访问权限

storage.sqlite_path 是准确信息；Broker 不会始终把 SQLite 放在某个固定的操作系统目录。开发配置选择 data/pssp-broker.sqlite3。随附的 Linux 生产配置只有在保留模板值时才选择 /var/lib/pssp/pssp-broker.sqlite3，Windows 生产配置则选择 C:\ProgramData\PSSP\pssp-broker.sqlite3。其他部署应选择受保护的绝对路径，并为 setup、管理和 serve 使用同一份配置。

setup 会创建缺失的父目录与数据库、初始化结构、创建引导管理员，并授予该管理员对 # 的发布和订阅权限。在 Unix 上，数据库及已有 SQLite 旁路文件权限会限制为 0600。如果配置了 unix_owner_user 和 unix_owner_group，setup 及后续修改型管理命令还会把目录和文件分配给该服务身份，并将父目录限制为 0700。

凭据和主题 ACL

SQLite 是唯一认证来源。Broker 不会调用 WebService，客户端仅发送标准 AUTH 记录。账户需要手动创建；Broker 不会自动生成客户端 ID、用户名或密码。

创建设备账户

1. 选择稳定的客户端 ID 和用户名，然后创建主体。CLI 会安全地提示输入新密码，输入时不会显示字符。

   pssp-broker create-principal --config /etc/pssp/pssp.toml \
     --client-id ox-device-OXRC-001 \
     --username device-OXRC-001 \
     --principal-kind device

2. 授予通过 QoS 0 UDP 发布设备心跳的权限。

   pssp-broker grant-acl --config /etc/pssp/pssp.toml \
     --client-id ox-device-OXRC-001 --username device-OXRC-001 \
     --action publish \
     --topic-filter '/api/devices/OXRC-001/heartbeat'

3. 授予通过 QoS 1 TCP 发布音频的权限。

   pssp-broker grant-acl --config /etc/pssp/pssp.toml \
     --client-id ox-device-OXRC-001 --username device-OXRC-001 \
     --action publish \
     --topic-filter '/api/devices/OXRC-001/audio/chunks'

4. 授予订阅 QoS 1 命令的权限。

   pssp-broker grant-acl --config /etc/pssp/pssp.toml \
     --client-id ox-device-OXRC-001 --username device-OXRC-001 \
     --action subscribe \
     --topic-filter '/api/devices/OXRC-001/commands'

5. 检查账户和实际 ACL 条目。

   pssp-broker list-principals --config /etc/pssp/pssp.toml
   pssp-broker list-acls --config /etc/pssp/pssp.toml \
     --client-id ox-device-OXRC-001 --username device-OXRC-001

6. 在客户端中配置完全相同的客户端 ID、用户名和刚才输入的密码，以及 Broker 地址和固定的仅 AES 公钥。

账户生命周期

轮换丢失或过期的密码；CLI 会安全地提示输入替换密码：

pssp-broker rotate-password --config /etc/pssp/pssp.toml \
  --client-id ox-device-OXRC-001 --username device-OXRC-001

撤销权限时，需要指定最初授予的准确操作和主题过滤器：

pssp-broker revoke-acl --config /etc/pssp/pssp.toml \
  --client-id ox-device-OXRC-001 --username device-OXRC-001 \
  --action publish \
  --topic-filter '/api/devices/OXRC-001/audio/chunks'

不带 --enabled 可禁用账户；再次添加 --enabled 可重新启用：

# 禁用
pssp-broker set-principal-enabled --config /etc/pssp/pssp.toml \
  --client-id ox-device-OXRC-001 --username device-OXRC-001

# 重新启用
pssp-broker set-principal-enabled --config /etc/pssp/pssp.toml \
  --client-id ox-device-OXRC-001 --username device-OXRC-001 --enabled

仅在账户不再需要时永久删除账户及其所有 ACL：

pssp-broker delete-principal --config /etc/pssp/pssp.toml \
  --client-id ox-device-OXRC-001 --username device-OXRC-001

非交互式配置应使用 --password-file 或 --password-stdin，不要把密码直接写入 Shell 历史。认证和 ACL 变更会在 storage.auth_cache_seconds 后生效（默认 30 秒），或在重启 Broker 后立即生效。

发布条目必须使用具体主题。ACL 条目和订阅可以用 + 匹配一个路径段，并用最后一个 # 匹配后代主题。除非存在匹配的允许规则，否则拒绝访问。

主题缓存、确认与资源边界

主题内存仍然是易失性的：Broker 重启会删除主题环、去重状态、会话密钥、订阅、UDP 关联和恢复游标。只有主体、密码哈希、ACL 和凭据审计事件持久化到 SQLite。

安全部署

1. 构建发布二进制文件。

   cargo build --release -p pssp-broker

2. 将适合平台的生产模板复制到受保护的位置。把 storage.sqlite_path 设置为该部署使用的受保护绝对路径；不要假定仓库开发路径或其他操作系统的路径。
3. 在 Unix 上，先创建服务账号与组，再将 unix_owner_user 和 unix_owner_group 同时设置为该身份。在 Windows 上，为任务计划程序所用身份保护选定的 ProgramData 目录。
4. 配置 TLS，或通过 pssp-broker generate-aes-only-private-key 生成仅 AES 模式的 X25519 私钥，并保持 allow_insecure_tcp_udp = false。
5. 在仅 AES 模式中，用 pssp-broker aes-only-public-key --private-key-file /protected/path/private-key 派生客户端要固定的公钥；也可以省略输入选项使用隐藏提示。私钥仅保存在受保护的 Broker 配置或密钥文件中，通过可信客户端预置通道分发公钥。
6. 使用最终配置运行 pssp-broker setup；它会创建并保护 SQLite 和引导管理员。然后在启动服务前创建最小权限主体，只授予所需 ACL。密码由 CLI 安全提示输入，自动化可使用受保护的文件或标准输入。
7. 安装所提供的服务定义，并确保它使用同一个配置路径：systemd 使用 broker/deploy/pssp-broker.service，launchd 使用 broker/deploy/io.oxrecorder.pssp-broker.plist，Windows 使用 broker/deploy/Install-PsspBrokerTask.ps1。

Windows 后台任务

使用 Rust MSVC 工具链构建，以 config/pssp.windows.production.example.toml 作为受保护的配置模板，然后在提升权限的 PowerShell 中运行安装程序：

.\broker\deploy\Install-PsspBrokerTask.ps1 `
  -BrokerPath 'C:\Program Files\PSSP Broker\pssp-broker.exe' `
  -ConfigPath 'C:\ProgramData\PSSP\pssp.toml'

PowerShell 安装程序会创建以本地系统账户（LocalSystem）身份在启动时运行、并带失败重试设置的任务计划程序（Task Scheduler）后台任务。普通控制台二进制文件不能在没有服务控制管理器（Service Control Manager）包装器的情况下直接安装为 Windows 服务。使用 -Action Uninstall 删除任务。仅为获准网络添加 TCP 6688 和 UDP 6688 的 Windows 防火墙规则。

运行行为与故障排查

启动诊断、数据库权限恢复、完整的仅 AES 设置和更全面的错误目录，请参阅 PSSP 故障排查指南。

下一步：查看工作流程图，并使用 Tauri 客户端应用验证 Broker 实例。· 专有软件 — © 2026 OX Recorder · 许可证信息