# 消息模块说明：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 → 客户端总线"的全链路。