704 lines
34 KiB
Markdown
704 lines
34 KiB
Markdown
# 消息模块说明：broker 部署 / 客户端配置 / 服务端开发
|
||
|
||
svfs 的消息模块让**服务端能主动把消息推给某个用户或某个插件**：给用户看的进客户端
|
||
「消息中心」，给插件的（仪表盘数据、行情、位号刷新这类业务载荷）只投给那个插件。
|
||
|
||
整套东西只需要三样：一个 MQTT broker、客户端里配好连接、服务端把消息发出去。
|
||
本文按这三块展开——
|
||
|
||
| 你要做的事 | 看哪一节 |
|
||
|---|---|
|
||
| 把 broker 跑起来（Docker） | 二、Docker 部署 broker |
|
||
| 让客户端连上、看到消息 | 三、前端配置（客户端） |
|
||
| 在自己的服务端里发消息 | 四、服务端开发 |
|
||
|
||
可直接运行的部署资产在 `deploy/mqtt/`：`docker compose up -d` 起一个 mosquitto，
|
||
配置里预留了认证、ACL、TLS 三段（默认全关，注释形式）。
|
||
|
||
> 关于本文的验证程度：主题方案、封套解析、去重、配置优先级这些都对着源码逐条核过
|
||
> （各节标注了出处），仓库里的测试也覆盖了这些路径；但 `deploy/mqtt/` 的
|
||
> compose / mosquitto 配置是按 mosquitto 2.x 的官方语义写的，**开发机上没有 Docker，
|
||
> 没有实际起过容器**。第一次落地前先在内网按第二节跑一遍，有问题再回来对。
|
||
|
||
---
|
||
|
||
## 一、模块速览
|
||
|
||
### 两条通道
|
||
|
||
| 通道 | 时机 | 说明 |
|
||
|---|---|---|
|
||
| MQTT 推送 | 实时 | 服务端主动推；broker 地址由登录响应下发（也可在设置里手配） |
|
||
| HTTP 补齐 | **登录成功后先做一次**，也可点「立即同步」 | `GET /api/messages?since=…` 把离线期间攒下的消息补回来 |
|
||
|
||
登录后的顺序是**先补齐、再交给 MQTT**（`shell.py` 的 `_start_messaging`）：MQTT 只能保证
|
||
"从现在起"的消息，离线那批只能靠补齐拿回来。两条路的消息都喂进同一个总线、按 id 去重，
|
||
所以推送与补齐重叠不会重复显示。
|
||
|
||
### 消息怎么走
|
||
|
||
```text
|
||
服务端 ──publish──> MQTT broker ──> MqttTransport（paho 网络线程）
|
||
│ on_message（回调还在网络线程）
|
||
▼
|
||
MqttService（Qt 排队信号 → 主线程）
|
||
│
|
||
┌──────────────────┘
|
||
▼
|
||
MessageBus：按主题分类 → 归属校验 → 去重 → 分发
|
||
│
|
||
┌───────────┴────────────┐
|
||
▼ ▼
|
||
消息中心（✉ 未读徽标） 插件队列（页面打开后投递）
|
||
```
|
||
|
||
### 实现分层
|
||
|
||
| 模块 | 层 | 职责 |
|
||
|---|---|---|
|
||
| `topics.py` | 纯标准库 | 主题拼装 / 解析 / 层级转义 |
|
||
| `messages.py` | 纯标准库 | 消息封套解析 + 消息日志（环形缓冲、未读、去重） |
|
||
| `bus.py` | 纯标准库 | 总线：分类、归属校验、去重、分发 |
|
||
| `mqtt.py` | 纯标准库（paho 可选） | 连接、重连、订阅、收包 |
|
||
| `mqtt_service.py` | Qt | 把网络线程回调转成主线程信号 |
|
||
| `messages_page.py` | Qt | 消息中心界面 |
|
||
| `shell.py` | Qt | 生命周期编排（登录后先补齐再连） |
|
||
|
||
纯层不 import Qt，可以在没有 PySide6 的环境里单独测；`mqtt.py` 里的 paho 是可选依赖，
|
||
缺了只报 `missing` 状态，不影响其它功能。
|
||
|
||
### 四条语义（先记住，后面都用得上）
|
||
|
||
* **只有登录后才有消息**：没有身份时总线一律不收（`bus._allowed`），退出登录即断开并清空；
|
||
* **分类只看主题，不看载荷内容**：所以服务端不会"一不小心把仪表盘数据推进用户的消息列表"；
|
||
* **主机消息有封套、进消息中心；插件消息原样投给插件**，两类泾渭分明；
|
||
* **实时通道是 QoS 0**（丢了不补，靠登录后补齐兜底），去重按消息 id。
|
||
|
||
客户端侧依赖：
|
||
|
||
```bash
|
||
pip install "sqlite-vfs[mqtt]" # paho-mqtt，实时推送通道需要
|
||
```
|
||
|
||
没装不会坏事：状态显示「未安装 paho-mqtt，实时推送不可用」，补齐照常把消息带回来。
|
||
开发环境 `uv sync` 已经带了 paho（dev 依赖里有）；打包客户端时，构建环境里装了它就会一并打进去。
|
||
|
||
---
|
||
|
||
## 二、Docker 部署 broker（mosquitto）
|
||
|
||
### 五分钟起步
|
||
|
||
```bash
|
||
cd deploy/mqtt
|
||
docker compose up -d
|
||
docker compose logs -f mqtt # 看到 "Opening ipv4 listen socket on port 1883" 就是好了
|
||
```
|
||
|
||
目录长这样：
|
||
|
||
```text
|
||
deploy/mqtt/
|
||
├── docker-compose.yml # eclipse-mosquitto:2，映射 1883（8883 注释着）
|
||
├── .gitignore # 密码文件与证书不进仓库
|
||
└── config/ # 整份挂到容器的 /mosquitto/config
|
||
├── mosquitto.conf # 默认匿名；认证/ACL/TLS 三段注释着
|
||
└── acl # 最小权限 ACL 示例（要用才在 conf 里启用）
|
||
```
|
||
|
||
`config/` 是整目录挂载（不是单文件）：`mosquitto_passwd` 要往这里写密码文件，
|
||
只挂单个文件的话写进去的东西落在容器层，重启就没了。数据与日志用具名卷
|
||
（`mqtt-data` / `mqtt-log`），免得撞上 Linux 上的目录属主问题（容器里的
|
||
mosquitto 是 uid 1883）。
|
||
|
||
### 先确认 broker 真的在收发
|
||
|
||
镜像里自带 `mosquitto_sub` / `mosquitto_pub`，不用另装客户端：
|
||
|
||
```bash
|
||
# 终端 1：订阅所有 svfs 主题（-v 顺带打出主题）
|
||
docker compose exec mqtt mosquitto_sub -h localhost -t 'svfs/#' -v
|
||
|
||
# 终端 2：模拟服务端推给 alice 的一条主机消息
|
||
docker compose exec mqtt mosquitto_pub -h localhost \
|
||
-t svfs/default/user/alice/message \
|
||
-m '{"id":"t1","title":"你好","body":"来自 mosquitto_pub","level":"info"}'
|
||
```
|
||
|
||
终端 1 应当原样打印出主题与载荷。这一对通了，说明 broker 与主题方案没问题，
|
||
剩下的就是服务端和客户端的事。
|
||
|
||
### 配置逐行看
|
||
|
||
| 配置 | 作用 | 注意 |
|
||
|---|---|---|
|
||
| `listener 1883` | 开监听口 | mosquitto 2.x 不写 listener 时只接受 loopback 连接（容器里等于没人连得上） |
|
||
| `allow_anonymous true` | 放行无凭据连接 | 定义了 listener 之后它**默认是 false**，必须显式写——"端口通、连不上"多半是这里 |
|
||
| `persistence true` | 落盘会话/保留消息 | 本模块 QoS 0 + clean session，其实用不上；留着是免得以后调 QoS 时回头改 |
|
||
| `log_dest stdout` | 日志进 `docker compose logs` | 另一条 `log_dest file` 是留档，用 `docker compose exec mqtt cat /mosquitto/log/mosquitto.log` 看 |
|
||
|
||
**客户端带用户名密码连匿名 broker 会被拒吗？** 不会。客户端总是带上用户名
|
||
（默认是登录名）与密码（默认是登录 token），而 `allow_anonymous true` 且没有
|
||
`password_file` 时，broker 没有可校验的东西，直接放行。所以内网匿名是最省事的组合：
|
||
客户端零配置，broker 地址由登录响应下发。
|
||
|
||
### 档 A：内网匿名（默认，先用它跑通）
|
||
|
||
适合内网、开发、演示。风险是**任何能连到 1883 的人都能订阅所有主题**，包括别人的消息。
|
||
真要收紧就把它绑到内网地址、只对服务端所在网段放行，或者直接进档 B。
|
||
|
||
### 档 B：认证 + 最小权限 ACL（生产该用）
|
||
|
||
`config/mosquitto.conf` 的「认证 + ACL」段里写了三步（造密码文件、准备客户端密码、
|
||
解开三行重启）。这里补三处最容易踩的：
|
||
|
||
**1）客户端的密码默认是登录 token，不是你在 passwd 里设的那个密码。**
|
||
|
||
取值顺序是 `mqtt_password` 设置 → 服务端下发的 `mqtt.password` → **登录 token**
|
||
（`settings.py` 的 `mqtt_config`）。所以开了 `password_file` 之后二选一：
|
||
|
||
* 服务端在登录响应的 `mqtt` 段里多下发一个 `password`（客户端零配置，推荐；
|
||
示例服务端只下发 host/port/tls/prefix/org，需要就自己加上这两个键）；
|
||
* 或在客户端 `settings.json` 里写 `mqtt_password`（明文落盘，见第三节的安全提示）。
|
||
|
||
**2）服务端自己也连不上了。**
|
||
|
||
示例服务端的 `_mqtt_publish` 不带 broker 账号，`allow_anonymous false` 之后每条推送
|
||
都会失败（`/api/push` 会如实返回 `error: …`，不会假装成功）。给它加账号：
|
||
|
||
```python
|
||
# examples/plugin_server.py 的 _mqtt_publish 里，mqtt.Client(...) 之后、connect 之前
|
||
user = os.environ.get("SVFS_MQTT_USER", "").strip()
|
||
if user:
|
||
client.username_pw_set(user, os.environ.get("SVFS_MQTT_PASS") or None)
|
||
```
|
||
|
||
然后带 `SVFS_MQTT_USER=svfs-server SVFS_MQTT_PASS=…` 启动，并在 ACL 里给它写权限
|
||
（`config/acl` 的 `svfs-server` 段就是现成的）。更正规的做法是服务端用一条常驻连接
|
||
发布，见第四节的发布代码。
|
||
|
||
**3）ACL 里的用户名是 broker 用户名，组织段要写死。**
|
||
|
||
ACL 的 `<用户名>` 默认就等于 svfs 登录名（`mqtt_username` 留空时）；组织段（`acl` 里的
|
||
`default`）要换成你的 `SVFS_ORG` 并保持固定——多租户隔离靠的就是这一段，写成 `+`
|
||
等于没隔离。用 `pattern` 时 `%u` 必须独占一个主题层级（`svfs/x/user/%u/#` 可以，
|
||
`svfs/x/user/%u-2/#` 不行）。
|
||
|
||
### 档 C：TLS（8883）
|
||
|
||
解开 `config/mosquitto.conf` 的 TLS 段、把证书放进 `config/certs/`、打开 compose 里的
|
||
8883 端口映射。证书自签即可：
|
||
|
||
```bash
|
||
cd deploy/mqtt/config && mkdir -p certs && cd certs
|
||
openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt -days 3650 \
|
||
-subj "/CN=svfs-dev-ca"
|
||
openssl req -newkey rsa:2048 -nodes -keyout server.key -out server.csr \
|
||
-subj "/CN=mqtt.example"
|
||
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
|
||
-out server.crt -days 3650 -extfile <(printf "subjectAltName=DNS:mqtt.example,IP:10.0.0.5")
|
||
```
|
||
|
||
**关键约束：客户端没有 CA 配置项。** 它只做「系统信任库 + `CERT_REQUIRED`」校验
|
||
（`mqtt.py` 的 `_configure`：`tls_set(cert_reqs=ssl.CERT_REQUIRED)`），
|
||
设置里的 `ca_bundle` 只管 HTTP（`netutil`），没有接到 MQTT 上。所以自签证书要么把
|
||
CA 装进**每台客户端**的系统信任库（Windows：导入「受信任的根证书颁发机构」；
|
||
macOS：钥匙串；Linux：`/usr/local/share/ca-certificates` + `update-ca-certificates`），
|
||
要么内网先用明文 1883 + 网络层隔离。**证书里的 CN/SAN 必须和客户端填的 host 一致**，
|
||
用 IP 连就写 IP。
|
||
|
||
自测（在客户端机器上跑，验证信任链）：
|
||
|
||
```bash
|
||
openssl s_client -connect 10.0.0.5:8883 -CAfile ca.crt </dev/null | head -5
|
||
```
|
||
|
||
服务端侧 `SVFS_MQTT_TLS=1` 时走的是 `client.tls_set()`，同样是系统信任库。
|
||
|
||
### 排障对照表
|
||
|
||
| 现象 | 多半是 | 处理 |
|
||
|---|---|---|
|
||
| 状态灯一直「连接中…」 | 端口/防火墙/DNS，或 host 写错 | `docker compose logs -f mqtt` 里没有连接记录，就是包根本没到 broker |
|
||
| 「连接失败：broker 拒绝连接（code=4/5）」 | 认证没过 | code=4 是用户名/密码不对（最常见：客户端用的还是登录 token，而 passwd 里是另一个密码），code=5 是没有权限（ACL 里没给这条主题的读）；见档 B |
|
||
| 连上了但一条都收不到 | 组织或前缀对不上（最常见），或发布主题与订阅主题不一致 | 对一下设置里显示的那行「生效的配置」（含 org / prefix）与发布时用的 prefix/org |
|
||
| 收到别人的消息 | broker 的 ACL 没生效 | 总线会挡住并记 `forbidden`（消息不显示），但要在 broker 侧修 |
|
||
| 消息偶尔丢/重复 | QoS 0 + 推送与补齐重叠 | 丢的靠「立即同步」补；重复由 id 去重（不填 id 时按"时间+标题+正文"，同一秒内相同内容会被当成重投） |
|
||
| Linux 上容器起不来，日志报权限 | 宿主的 `config/` 属主不是 uid 1883 | `sudo chown -R 1883:1883 config`（数据/日志已用具名卷规避） |
|
||
| 诊断日志里 `unknown topic` | 服务端主题拼错了 | 用 `svfs_client.topics` 拼，别手写（见第四节） |
|
||
| 诊断日志里 `消息没有可展示的内容` | 载荷是空对象/空串 | 主机消息至少要有 `title` 或 `body` |
|
||
|
||
---
|
||
|
||
## 三、前端配置（客户端）
|
||
|
||
### broker 地址从哪来
|
||
|
||
| 优先级 | 来源 | 什么时候生效 |
|
||
|---|---|---|
|
||
| 1 | 设置里**显式改过**的值 | 本地调试、服务端没下发 |
|
||
| 2 | 登录响应下发的 `mqtt: {host, port, tls, prefix, org[, username, password]}` | 正常部署（推荐，客户端零配置） |
|
||
| 3 | 内置默认 | 兜底（端口 1883、prefix `svfs`、org `default`） |
|
||
|
||
**为什么强调"显式改过"**：`mqtt_port` / `mqtt_tls` 自带默认值（1883 / 关），如果按
|
||
"有值就优先"来判，服务端下发的 8883 与 TLS 会被默认值永久压掉——这是实现时踩过的坑
|
||
（`settings.py` 的 `mqtt_config` 注释里记着），所以判据是"与默认值不同才算你改过"。
|
||
反过来说：想恢复"跟随服务端下发"，就把这些字段改回默认值（broker 留空、端口 1883、TLS 取消勾选）。
|
||
|
||
### 设置界面 ↔ settings.json
|
||
|
||
「设置 → 服务器 → 消息推送（MQTT）」：
|
||
|
||
| 设置项 | `settings.json` 键 | 默认 | 说明 |
|
||
|---|---|---|---|
|
||
| broker | `mqtt_host` | 空 | 接受 `host`、`host:1884`、`mqtts://host:8883`；URL 形式里的 scheme 与端口优先 |
|
||
| 组织 | `org` | 空 | 留空 = 用服务端下发的，再不行 `default` |
|
||
| TLS | `mqtt_tls` | false | 勾上就是 mqtts |
|
||
| 端口 | `mqtt_port` | 1883 | TLS 时缺省是 8883 |
|
||
| 主题前缀 | `mqtt_prefix` | `svfs` | 两端必须一致 |
|
||
| broker 账号 | `mqtt_username` | 空 | 留空 = 用登录用户名 |
|
||
| （无界面） | `mqtt_password` | 空 | 留空 = 用登录 token；手写是明文，见下 |
|
||
| 「保存并重连」 | — | — | 改完立即重连，不用等下次登录 |
|
||
|
||
那一节底部会显示**生效**的配置与来源（`mqtt://host:1883（org=acme，prefix=svfs）`
|
||
加上「· 来自服务端下发」或「· 已保存并重连」）。手改文件也可以，路径是
|
||
|
||
```text
|
||
Windows: %LOCALAPPDATA%\svfs-client\settings.json
|
||
其它: ~/.svfs-client/settings.json # 数据目录被「设置 → 存储」挪过就用挪后的
|
||
```
|
||
|
||
写是原子的（临时文件 + `os.replace`），手改不怕写坏；但改完要重启客户端（除了上面那几个
|
||
界面上的字段，它们是保存即生效）。
|
||
|
||
### 凭据怎么存
|
||
|
||
| 用什么 | 取值顺序 | 存在哪 |
|
||
|---|---|---|
|
||
| broker 用户名 | `mqtt_username` → 登录用户名 | 明文（`settings.json` / 登录响应） |
|
||
| broker 密码 | `mqtt_password` → 服务端下发的 `mqtt.password` → **登录 token** | 前两者是明文；登录 token 在 `credentials.dat`（Windows DPAPI / keyring 加密） |
|
||
| HTTP 补齐用的 token | 登录拿到的 | 同上，加密 |
|
||
|
||
安全提示：**别把长期的 broker 密码手写进 `settings.json`**（明文落盘）。要独立密码就让
|
||
服务端在登录响应里下发——那是每次登录现拿的；或者干脆让 broker 校验登录 token（见 4.8）。
|
||
|
||
### 连接状态六态
|
||
|
||
| 状态 | 界面上显示（状态：明细） | 灯色 | 含义 |
|
||
|---|---|---|---|
|
||
| `disabled` | 未启用：未配置 broker | 灰 | 没配 broker，服务端也没下发 |
|
||
| `missing` | 未安装 paho-mqtt，实时推送不可用：需要可选依赖… | 黄 | 缺可选依赖，补齐照常工作 |
|
||
| `connecting` | 连接中…：127.0.0.1:1883，掉线时是「连接中…：连接断开（code=0），正在重连…」 | 黄 | 正在连或退避重连（1→30 秒）；重连成功后自动重新订阅 |
|
||
| `connected` | 已连接：127.0.0.1:1883（已收 3 条） | 绿 | 已订阅两条主题；括号里的条数在"连上了却收不到"时最有用 |
|
||
| `error` | 连接失败：broker 拒绝连接（code=5） | 红 | broker 拒连（认证/ACL 问题） |
|
||
| `stopped` | 已断开：已主动断开 | 灰 | 退出登录/关窗主动断开 |
|
||
|
||
在哪看：侧栏底部的 ✉ 进「消息中心」，右上角就是状态灯与那行状态文字；连不上时状态栏
|
||
也会提示一句。「设置 → 诊断」里能导出诊断报告，滚动日志在数据目录的
|
||
`logs/client.log`（Windows：`%LOCALAPPDATA%\svfs-client\logs\client.log`）——里面按时间记着
|
||
`MQTT 状态 …`、每一条订阅、以及总线的越权丢弃（`forbidden`）与积压丢弃（`dropped`）。
|
||
|
||
### 消息中心行为
|
||
|
||
* 侧栏 ✉ 带未读数（`✉3`），tooltip 是「消息中心（3 条未读）」；**进入消息中心就算全部已读**；
|
||
* 顶部按钮：立即同步 / 全部已读 / 清空；
|
||
* 每条卡片显示级别、标题、正文、时间、来源，组织广播带「广播」标记；
|
||
* `warn` / `error` 级别的消息会顺手弹一条系统托盘通知（6 秒）；`info` 不打扰；
|
||
* 上限 500 条（超了丢最旧的），按时间倒序；列表只显示该登录用户自己的消息 + 组织广播；
|
||
* 退出登录/切账号：断开连接、清空列表，此后再来的推送一律丢弃（不是"藏起来"，是真的不收）。
|
||
|
||
### 插件怎么收消息（插件前端）
|
||
|
||
清单里声明 `messages` 权限（桥 API 版本要 ≥ 5）：
|
||
|
||
```json
|
||
{
|
||
"id": "com.example.dash",
|
||
"api_version": 5,
|
||
"permissions": ["storage", "net", "messages"]
|
||
}
|
||
```
|
||
|
||
```js
|
||
// 插件页面里
|
||
const svfs = await window.svfsReady;
|
||
if (svfs.messages) {
|
||
const off = svfs.messages.subscribe((message) => {
|
||
// message.text 是原文；能解析成对象时另有 message.json
|
||
render(message.json ?? message.text);
|
||
});
|
||
}
|
||
```
|
||
|
||
消息对象是 `{text: string, json?: object, time: string}`——`time` 目前恒为空串
|
||
（投递路径里没带时间），要时间戳就自己把它放在载荷里。
|
||
|
||
**不用怕"消息比页面先到"**，这条链路上有三层缓冲：
|
||
|
||
1. 插件页面是懒加载的，可能还没打开；
|
||
2. 总线按插件缓存最近 50 条（超了丢最旧的并计 `dropped`），去重记忆 200 条；
|
||
3. 页面打开时宿主把攒下的投进去；页面里的 `window.__svfsPush` 在 DocumentCreation 阶段
|
||
就立好了，订阅之前到的先排队、`subscribe` 时补发。
|
||
|
||
所以 `subscribe` 只写"收到消息怎么办"就够了，不需要自己去拉历史。调试时可以用客户端
|
||
「设置 → 桥调试台 → 安装调试插件」里的 messages 面板对照（`sample.py` 里的实现）。
|
||
|
||
---
|
||
|
||
## 四、服务端开发
|
||
|
||
### 要做的两件事
|
||
|
||
1. **发布**：把消息 publish 到 broker 的对应主题；
|
||
2. **下发**：在登录响应里带上 broker 信息，让客户端自动连上（否则用户得自己填地址）。
|
||
|
||
### 4.1 拼主题别手写
|
||
|
||
```python
|
||
from svfs_client.topics import (
|
||
user_message_topic, user_plugin_topic,
|
||
broadcast_message_topic, broadcast_plugin_topic,
|
||
)
|
||
```
|
||
|
||
装 `pip install sqlite-vfs` 就能复用（纯标准库，不需要 PySide6）。**为什么必须复用**：
|
||
用户名与插件 id 要占一个主题层级，得先过一层可逆的百分号编码（安全字符
|
||
`[A-Za-z0-9._@-]` 原样保留，其余编码），两端规则不一致就会"发得出去、收不到"，
|
||
而且 `a b` 与 `a_b` 会撞成同一个主题、串了租户。示例服务端就是直接 import 这个模块的。
|
||
|
||
### 4.2 主题与通道
|
||
|
||
| 主题 | 谁收 | 进消息中心 |
|
||
|---|---|---|
|
||
| `<prefix>/<org>/user/<user>/message` | 该用户 | 是 |
|
||
| `<prefix>/<org>/user/<user>/plugin/<plugin_id>` | 该用户的该插件 | 否 |
|
||
| `<prefix>/<org>/broadcast/message` | 整个组织 | 是（带广播标记） |
|
||
| `<prefix>/<org>/broadcast/plugin/<plugin_id>` | 整个组织的该插件 | 否 |
|
||
|
||
客户端登录后只订阅两条（最小权限，不是整个组织的 `#`）：
|
||
|
||
```text
|
||
<prefix>/<org>/user/<user>/#
|
||
<prefix>/<org>/broadcast/#
|
||
```
|
||
|
||
即使 broker 的 ACL 配错、把别人的消息推了过来，总线还会按当前组织/用户再挡一道
|
||
（记 `forbidden` 计数 + 诊断日志）。
|
||
|
||
### 4.3 发布代码
|
||
|
||
示例服务端（`examples/plugin_server.py` 的 `_mqtt_publish`）为了演示简单，是
|
||
"连上 → 发一条 → 断开"，每条消息一次握手；生产上换成常驻连接更合适：
|
||
|
||
```python
|
||
import json
|
||
import os
|
||
import threading
|
||
from datetime import datetime
|
||
|
||
import paho.mqtt.client as mqtt
|
||
from svfs_client.topics import user_message_topic, user_plugin_topic
|
||
|
||
MQTT_HOST = os.environ.get("SVFS_MQTT_HOST", "")
|
||
MQTT_PORT = int(os.environ.get("SVFS_MQTT_PORT", "") or 1883)
|
||
MQTT_PREFIX = os.environ.get("SVFS_MQTT_PREFIX", "svfs")
|
||
ORG = os.environ.get("SVFS_ORG", "").strip() or "default"
|
||
|
||
_lock = threading.Lock()
|
||
_client = None
|
||
|
||
|
||
def _connection():
|
||
"""进程内共用一条连接（paho 自己管心跳与重连）。"""
|
||
global _client
|
||
with _lock:
|
||
if _client is None:
|
||
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
|
||
client_id="svfs-server")
|
||
user = os.environ.get("SVFS_MQTT_USER", "").strip()
|
||
if user: # broker 开了认证就必须给账号
|
||
client.username_pw_set(user, os.environ.get("SVFS_MQTT_PASS") or None)
|
||
if os.environ.get("SVFS_MQTT_TLS", "").lower() in ("1", "true", "yes"):
|
||
client.tls_set() # 用系统信任库；自签证书见第二节「档 C：TLS」
|
||
client.connect_async(MQTT_HOST, MQTT_PORT, 30)
|
||
client.loop_start()
|
||
_client = client
|
||
return _client
|
||
|
||
|
||
def publish(topic, payload, qos=0):
|
||
"""发一条；没配 broker / 没连上都返回说明字符串（不抛，消息通道不能拖垮业务）。"""
|
||
if not MQTT_HOST:
|
||
return "skipped: 未配置 SVFS_MQTT_HOST"
|
||
client = _connection()
|
||
if not client.is_connected():
|
||
# connect_async 不阻塞：进程刚起或断线重连中就是 False。如实报这一条失败
|
||
# （paho 会自己连回来），别把业务请求堵在握手上
|
||
return "error: 还没连上 broker（重连中）"
|
||
try:
|
||
info = client.publish(topic, payload, qos=qos)
|
||
if info.rc != mqtt.MQTT_ERR_SUCCESS:
|
||
return f"error: {mqtt.error_string(info.rc)}"
|
||
info.wait_for_publish(timeout=5) # QoS 0 一般立刻返回
|
||
except Exception as exc:
|
||
return f"error: {exc}"
|
||
return "published"
|
||
|
||
|
||
def push_message(user, title, body, level="info", msg_id=""):
|
||
message = {
|
||
"id": msg_id, # 建议给：客户端按它去重
|
||
"title": title,
|
||
"body": body,
|
||
"level": level, # info | warn | error
|
||
"time": datetime.now().isoformat(timespec="seconds"),
|
||
"source": "my-service",
|
||
}
|
||
topic = user_message_topic(MQTT_PREFIX, ORG, user)
|
||
return topic, publish(topic, json.dumps(message, ensure_ascii=False))
|
||
```
|
||
|
||
上面这段有两个刻意的选择，都是踩过才知道的：
|
||
|
||
* `connect_async` 不阻塞，所以进程刚起的那一小会儿 `is_connected()` 还是 False——
|
||
这期间的推送会返回 `error: 还没连上 broker（重连中）`。**宁可如实报错误，也不要让业务
|
||
请求卡在 TCP 握手上**；要"启动即确认连上"，就把 `connect_async` 换成同步的 `connect`
|
||
（连不上会抛，自己接住），或者在连上之前先不对外提供服务；
|
||
* 返回字符串而不是抛异常：`/api/push` 这类接口即使发不出去也要能正常返回——消息本来
|
||
就会进待收列表，客户端登录后还能补齐。
|
||
|
||
给插件发数据就是换主题、载荷随便（原样投递）：
|
||
|
||
```python
|
||
topic = user_plugin_topic(MQTT_PREFIX, ORG, user, "com.example.dash")
|
||
publish(topic, json.dumps({"cpu": 0.42}))
|
||
```
|
||
|
||
### 4.4 登录响应里下发 broker
|
||
|
||
客户端会读登录响应里的 `mqtt` 段，据此自动连接：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"token": "…",
|
||
"username": "alice",
|
||
"org": "acme",
|
||
"mqtt": {
|
||
"host": "10.0.0.5",
|
||
"port": 1883,
|
||
"tls": false,
|
||
"prefix": "svfs",
|
||
"org": "acme"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 键 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `host` | 是 | 客户端能访问到的 broker 地址（不是 broker 眼里的自己） |
|
||
| `port` | 否 | 不给就按 `tls` 推 1883 / 8883 |
|
||
| `tls` | 否 | true 走 mqtts |
|
||
| `prefix` | 否 | 缺省 `svfs`，两端必须一致 |
|
||
| `org` | 否 | 缺省 `default`；也是客户端订阅时的租户段 |
|
||
| `username` / `password` | 否 | 给客户端一套独立的 broker 账号时用（客户端优先用它，`settings.py` 的 `mqtt_config`） |
|
||
|
||
`GET /api/me`（启动时静默校验 token）也会带上同样的段，所以客户端重启后不用重新登录
|
||
也能拿到 broker 信息。**没配 broker 就别带 `mqtt` 键**（示例服务端的
|
||
`_mqtt_announcement` 就返回 None）——客户端会走"只补齐、不实时"的降级，这是正常状态。
|
||
|
||
### 4.5 主机消息的封套
|
||
|
||
```json
|
||
{
|
||
"id": "b7c1…",
|
||
"title": "备份完成",
|
||
"body": "3 个包已同步",
|
||
"level": "info",
|
||
"time": "2026-09-16T10:00:00",
|
||
"source": "backup"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 上限 | 缺省 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `id` | 字符串 | 120 | 空 | 去重键，**强烈建议给**（给了就不会重复显示） |
|
||
| `title` | 字符串 | 200 | 空 | 标题 |
|
||
| `body` | 字符串 | 4000 | 空 | 正文 |
|
||
| `level` | 字符串 | — | `info` | `info` / `warn` / `error`，认不出来的当 `info` |
|
||
| `time` | 字符串 | 40 | 收到的时间 | ISO8601；要能被**字符串比较**（增量补齐靠它） |
|
||
| `source` | 字符串 | 120 | 空 | 来源标记，界面上显示 |
|
||
|
||
解析很宽松，下面这些也能用：
|
||
|
||
* 载荷是**纯字符串**或 JSON 标量（数字、带引号的串）→ 整段当正文；
|
||
* 不是合法 JSON 的字符串 → 整段当正文；
|
||
* `title` 与 `body` **都空**的（空串、`{}`）→ 整条丢弃，不往消息中心塞空气。
|
||
|
||
**去重规则**：有 `id` 就按 `id`；没有就按 `时间|标题|正文`。所以同一秒里发两条内容
|
||
完全相同、又都没带 `id` 的消息，第二条会被当成重投丢掉——给 `id` 最省事。
|
||
|
||
广播的封套一样，只是走 `broadcast` 主题；建议把 `source` 写成能看出是谁发的
|
||
（示例是 `broadcast@<用户名>`）。
|
||
|
||
### 4.6 插件消息
|
||
|
||
* 载荷**原样投递**，宿主不解析、不加封套（插件自己的协议自己定）；
|
||
* 不进消息中心、不进待收列表——它是实时业务载荷，补历史没有意义；
|
||
* 去重是"内容 + 秒"级别（同一插件、同一正文、同一秒视为重复），这是为了挡 QoS 1 重投
|
||
与推送/补齐的重叠。**所以：要分帧或累积的数据请自己带序号**，否则同一秒里两帧一模一样的
|
||
数据会被当成重投丢掉。
|
||
|
||
### 4.7 HTTP 补齐接口（离线消息）
|
||
|
||
客户端登录后（以及点「立即同步」时）会拉一次：
|
||
|
||
| 项 | 约定 |
|
||
|---|---|
|
||
| 方法与路径 | `GET <base_url>/api/messages` |
|
||
| 请求头 | `Accept: application/json`、`Authorization: Bearer <token>` |
|
||
| 参数 | `since`（可选）：本地最新一条消息的 `time`，只要这之后的消息 |
|
||
| 响应 | `{"ok": true, "messages": [封套, …]}`；没有新消息就是空数组 |
|
||
| 没这个接口 | 返回 404，客户端当作"服务端不支持"，静默降级（不报错、不刷状态） |
|
||
| 客户端限制 | 15 秒超时、失败重试 1 次、最多读 2MB、最多取 500 条 |
|
||
|
||
服务端侧要注意的：
|
||
|
||
* **只返回该 token 对应用户的消息**（示例服务端按 username 分桶存）；
|
||
* `since` 用字符串比较 `>` 就够了（ISO8601 定长、字典序即时间序）；
|
||
* 返回的封套与 MQTT 推送用的是同一套，客户端按 id 去重——所以你**可以放心把发过的消息
|
||
也留在待收列表里**，推送与补齐重叠不会显示两条；
|
||
* 示例的待收列表是内存里每人 100 条、重启即清（`MESSAGE_BACKLOG`），生产该入库；
|
||
* 广播不进待收列表（示例如此）：**组织广播只有在线的人看得到**，要保证人人可见就得自己
|
||
把广播也存下来并在补齐接口里带上。
|
||
|
||
### 4.8 认证怎么落地
|
||
|
||
| 方案 | 客户端怎么连 | broker 侧 | 适合 |
|
||
|---|---|---|---|
|
||
| 内网匿名 | 用户名=登录名、密码=token，broker 不校验 | `allow_anonymous true` | 内网/开发/演示 |
|
||
| 静态账号 + 独立密码 | 服务端下发 `mqtt.password`，或客户端写 `mqtt_password` | `password_file` + `acl_file` | 多数生产场景 |
|
||
| broker 校验登录 token | **默认行为**（密码就是 token） | broker 的认证回调打到你的服务端：EMQX 5.x 的 HTTP 认证、mosquitto 的动态安全插件或 mosquitto-go-auth 这类外部插件 | 想"零配置 + 和登录体系联动" |
|
||
|
||
第三种最贴合本模块的现成设计（客户端本来就把登录 token 当 broker 密码发），代价是
|
||
broker 侧要接一个认证回调：收到 `(username, password)` 就调你的 `/api/verify` 校验这个
|
||
token 是否有效、属于谁，顺便还能把 ACL 一起下发（"你只能读写 `svfs/<org>/user/<你>/#`"）。
|
||
|
||
### 4.9 端到端跑一遍
|
||
|
||
```bash
|
||
# 0) broker
|
||
cd deploy/mqtt && docker compose up -d
|
||
|
||
# 1) 服务端：下发 broker 地址（客户端登录后自动连上）
|
||
SVFS_MQTT_HOST=127.0.0.1 SVFS_MQTT_PORT=1883 SVFS_ORG=acme \
|
||
uv run python examples/plugin_server.py
|
||
|
||
# 2) 登录取 token
|
||
token=$(curl -s -X POST http://127.0.0.1:8000/api/login \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"username":"admin","password":"admin123"}' \
|
||
| python -c "import json,sys; print(json.load(sys.stdin)['token'])")
|
||
|
||
# 3) 主机消息 → 消息中心
|
||
curl -s -X POST http://127.0.0.1:8000/api/push -H "Authorization: Bearer $token" \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"kind":"message","title":"备份完成","body":"3 个包已同步","level":"info"}'
|
||
|
||
# 4) 插件数据 → 只给 com.svfs.demo 这个插件
|
||
curl -s -X POST http://127.0.0.1:8000/api/push -H "Authorization: Bearer $token" \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"kind":"plugin","plugin":"com.svfs.demo","data":{"cpu":0.42}}'
|
||
|
||
# 5) 组织广播 → 组织内所有在线客户端
|
||
curl -s -X POST http://127.0.0.1:8000/api/broadcast -H "Authorization: Bearer $token" \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"title":"停机维护","body":"今晚 22:00 开始","level":"warn"}'
|
||
```
|
||
|
||
（curl 的中文参数在 Git Bash 下没问题；PowerShell 里更稳的做法是把 JSON 写进文件再用 `-d @body.json`。）
|
||
|
||
注意示例服务端把 uvicorn 绑在 `127.0.0.1`（源码里写死的），所以这套跑法只适用于
|
||
"客户端和服务端在同一台机器"；要让别的机器连，改 `examples/plugin_server.py` 结尾那句
|
||
`uvicorn.run(...)` 的 host（同时记得 `SVFS_MQTT_HOST` 要下发**客户端能访问到的**地址，
|
||
不是服务端眼里的 `127.0.0.1`）。
|
||
|
||
响应里看 `"mqtt"` 字段就知道有没有真的发出去：`"published"` 是发出去了，
|
||
`"skipped: …"` 是没配 broker 或服务端没装 paho，`"error: …"` 是连不上/被拒。
|
||
即使 `skipped`，消息也已经进了待收列表，客户端登录后能补齐看到。
|
||
|
||
### 4.10 边界与降级
|
||
|
||
* 没配 `SVFS_MQTT_HOST`：`/api/push` 只写待收列表，响应 `mqtt=skipped`，客户端靠补齐看到；
|
||
* 服务端没装 paho：同上（`skipped: 服务端没装 paho-mqtt`），不影响接口本身；
|
||
* 推送只对**已登录**的客户端有效；退出登录即断开（客户端侧行为，见第三节）；
|
||
* QoS 0 不保证送达：要"必达"就靠待收列表 + 补齐 + `id` 去重，别指望 broker 重投；
|
||
* 广播不落库（示例如此）：离线的人看不到组织广播，除非你自己也存一份。
|
||
|
||
---
|
||
|
||
## 五、速查
|
||
|
||
### 5.1 示例服务端的环境变量
|
||
|
||
| 变量 | 默认 | 作用 |
|
||
|---|---|---|
|
||
| `SVFS_MQTT_HOST` | 空 | broker 地址；**空 = 不启用 MQTT**（推送只进待收列表） |
|
||
| `SVFS_MQTT_PORT` | 空 | broker 端口；空则按 tls 推 1883 / 8883 |
|
||
| `SVFS_MQTT_TLS` | 空 | `1` / `true` / `yes` 走 TLS |
|
||
| `SVFS_MQTT_PREFIX` | `svfs` | 主题前缀 |
|
||
| `SVFS_ORG` | `default` | 组织/租户标识 |
|
||
| `SVFS_USERS` | `admin:admin123` | 登录账号表，`user:pass,user2:pass2` |
|
||
| `SVFS_PORT` | 8000 | HTTP 端口 |
|
||
| `SVFS_PLUGINS_DIR` | `./svfs-plugins-root` | 插件包根目录 |
|
||
| `SVFS_UPLOAD_TOKEN` | 空 | 上传插件时的 `X-SVFS-Token` |
|
||
| `SVFS_CLIENT_VERSION` / `_URL` / `_NOTES` | 空 | 客户端自更新清单（不设则 404） |
|
||
|
||
### 5.2 客户端 settings.json 的 MQTT 相关键
|
||
|
||
| 键 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `mqtt_host` | `""` | 空 = 不启用推送（但服务端下发的仍会用） |
|
||
| `mqtt_port` | `1883` | |
|
||
| `mqtt_tls` | `false` | |
|
||
| `mqtt_prefix` | `"svfs"` | |
|
||
| `mqtt_username` | `""` | 空 = 登录用户名 |
|
||
| `mqtt_password` | `""` | 空 = 登录 token（加密存储的那份） |
|
||
| `org` | `""` | 空 = 服务端下发 → `default` |
|
||
|
||
### 5.3 总线处理结果与计数
|
||
|
||
`deliver()` 返回的 `action`：`host`（进消息中心）/ `plugin`（投给插件）/ `duplicate`
|
||
（重复，丢弃）/ `unknown`（主题不认识）/ `forbidden`（不是发给当前身份的）/ `empty`
|
||
（解析不出正文）。这些动作各自都有计数，`MessageBus.stats()` 能拿到快照（`received`、
|
||
`host`、`plugin`、`duplicate`、`unknown`、`forbidden`、`empty`、`dropped`）——所以
|
||
`forbidden` / `dropped` 有两条线索可查：诊断日志里的那两行文字，以及这个计数快照。
|
||
|
||
### 5.4 客户端连接参数（写死在代码里，没有配置项）
|
||
|
||
| 参数 | 值 | 出处 |
|
||
|---|---|---|
|
||
| 客户端 id | `svfs-<org>-<user>-<6 位随机>` | 随机后缀是为了"同一人开两个客户端不互相踢下线" |
|
||
| clean session | 是 | 不指望 broker 记会话 |
|
||
| keepalive | 30 秒 | |
|
||
| 重连退避 | 1 → 30 秒（指数） | 交给 paho，重连成功后自动重新订阅 |
|
||
| 发布 / 订阅 QoS | 0 | 服务端示例也是 0 |
|
||
|
||
---
|
||
|
||
## 六、测试
|
||
|
||
```bash
|
||
uv run python tests/run_tests.py -p "test_client_messages.py" # 主题/封套/总线（纯层）
|
||
uv run python tests/run_tests.py -p "test_client_mqtt.py" # MQTT 通道（含自建 broker 端到端）
|
||
uv run python tests/run_tests.py -p "test_plugin_server.py" # 服务端 /api/push → broker → 客户端
|
||
uv run python tests/run_tests.py -p "test_client_ui.py" # 设置界面与消息中心
|
||
```
|
||
|
||
`test_client_mqtt.py` 里的 `_MiniBroker` 是测试里手写的 MQTT 3.1.1 broker（QoS 0，
|
||
认 CONNECT / SUBSCRIBE / PUBLISH / PINGREQ / DISCONNECT 这几种报文），
|
||
所以**这些测试不需要 Docker、也不需要真 broker**，CI 上直接跑。覆盖到的点：
|
||
主题拼装/解析与转义、封套解析与长度上限、
|
||
去重（id 与"内容+秒"两种）、越权消息丢弃、订阅两条主题、重连后重新订阅、拒连报错、
|
||
TLS 开关、以及"服务端 push → broker → 客户端总线"的全链路。
|