@@ -0,0 +1,703 @@
# 消息模块说明：broker 部署 / 客户端配置 / 服务端开发
svfs 的消息模块让**服务端能主动把消息推给某个用户或某个插件**：给用户看的进客户端
「消息中心」，给插件的（仪表盘数据、行情、位号刷新这类业务载荷）只投给那个插件。
整套东西只需要三样：一个 MQTT broker、客户端里配好连接、服务端把消息发出去。
本文按这三块展开——
| 你要做的事 | 看哪一节 |
|---|---|
| 把 broker 跑起来（Docker）
| 让客户端连上、看到消息 | 三、前端配置（客户端） |
| 在自己的服务端里发消息 | 四、服务端开发 |
可直接运行的部署资产在 `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（
│ on_message（回调还在网络线程）
▼
MqttService（
│
┌──────────────────┘
▼
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（ ）
### 五分钟起步
``` 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（
├── .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 的 `<用户名>` 默认就等于 svfs 登录名（`mqtt_username` 留空时）；组织段（`acl` 里的
`default` ）要换成你的 `SVFS_ORG` 并保持固定——多租户隔离靠的就是这一段，写成 `+`
等于没隔离。用 `pattern` 时 `%u` 必须独占一个主题层级（`svfs/x/user/%u/#` 可以，
`svfs/x/user/%u-2/#` 不行）。
### 档 C： （ ）
解开 `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` ；
| 组织 | `org` | 空 | 留空 = 用服务端下发的，再不行 `default` |
| TLS | `mqtt_tls` | false | 勾上就是 mqtts |
| 端口 | `mqtt_port` | 1883 | TLS 时缺省是 8883 |
| 主题前缀 | `mqtt_prefix` | `svfs` | 两端必须一致 |
| broker 账号 | `mqtt_username` | 空 | 留空 = 用登录用户名 |
| （无界面） | `mqtt_password` | 空 | 留空 = 用登录 token；手写是明文，见下 |
| 「保存并重连」 | — | — | 改完立即重连，不用等下次登录 |
那一节底部会显示**生效**的配置与来源（`mqtt://host:1883（ ， ）
加上「· 来自服务端下发」或「· 已保存并重连」）。手改文件也可以，路径是
``` 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` （
| 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）
| `stopped` | 已断开：已主动断开 | 灰 | 退出登录/关窗主动断开 |
在哪看：侧栏底部的 ✉ 进「消息中心」，右上角就是状态灯与那行状态文字；连不上时状态栏
也会提示一句。「设置 → 诊断」里能导出诊断报告，滚动日志在数据目录的
`logs/client.log` （ ： `%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， `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"}'
```
（ `-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（ ，
认 CONNECT / SUBSCRIBE / PUBLISH / PINGREQ / DISCONNECT 这几种报文），
所以**这些测试不需要 Docker、也不需要真 broker**，CI 上直接跑。覆盖到的点：
主题拼装/解析与转义、封套解析与长度上限、
去重（id 与"内容+秒"两种）、越权消息丢弃、订阅两条主题、重连后重新订阅、拒连报错、
TLS 开关、以及"服务端 push → broker → 客户端总线"的全链路。
