modify:网关配置控制amqtt broker

README.md

@@ -12,7 +12,7 @@
 | --------------------- | -------------------------------------------------------------------- |
 | **FastAPI + Uvicorn** | 高性能异步 Web 框架，自动生成 OpenAPI 文档                           |
 | **Zenoh 服务发现**    | 基于 liveliness 的 Worker 注册与 RPC 调用，负载均衡 + 超时重试       |
-| **MQTT 集成**         | 内嵌 amqtt Broker，MQTT ↔ Worker 双向桥接                            |
+| **MQTT 集成**         | amqtt Broker（内嵌或外部），MQTT ↔ Worker 双向桥接                |
 | **动态路由生成**      | 扫描 `config/workers/*/*.toml` 自动注册 HTTP 路由                    |
 | **Worker 框架**       | `@rpc_method` 装饰器 + `Plugin` 基类统一生命周期 + Pydantic 模型绑定 |
 | **启动契约校验**      | TOML 路由 ↔ `@rpc_method` ↔ 生成模型三方一致性校验，fail fast        |
@@ -205,7 +205,8 @@ graph TB
 uv run serve → FastAPI lifespan:
   1. setup_storage()           — 本地文件系统存储
   2. setup_zenoh()             — Zenoh peer 会话
-  3. setup_mqtt_broker()       — 内嵌 Broker（子进程 + 文件锁单例）
+  3. setup_mqtt_broker()       — 内嵌 amqtt Broker（子进程 + 文件锁单例；
+                                  `use_embedded_broker=false` 时跳过，改用外部 Broker）
   4. setup_worker_manager()    — WorkerManager + 定期 liveliness 刷新
   5. load_workers()            — 按插件 [workers].load_mode 分派:
        inline   → 进程内 import 插件 → 启动 Worker 协程
@@ -337,6 +338,39 @@ start.sh                       容器入口：uv sync + worker_serve --type <nam
 | 请求 | `chongming/<type>/<op>`          | MQTT → Worker                  |
 | 响应 | `chongming/<type>/<op>/response` | Worker → MQTT（`None` 时跳过） |
 
+### Broker 来源（内嵌 vs 外部）
+
+网关默认启动内嵌 amqtt Broker（子进程 + 文件锁单例），`[<env>.mqtt].use_embedded_broker` 控制 Broker 来源：
+
+```toml
+[development.mqtt]
+enabled = true
+host = "0.0.0.0"          # true 时为内嵌 Broker 监听地址；false 时为外部 Broker 地址
+port = 1883
+use_embedded_broker = true   # true（默认）网关启动 amqtt Broker；false 连接外部 Broker
+```
+
+- `use_embedded_broker = true`（默认）：网关启动内嵌 amqtt Broker 子进程，MQTT Bridge 作为客户端连回自身。
+- `use_embedded_broker = false`：网关**不启动** Broker，MQTT Bridge 直接连接 `host:port` 指向的外部 MQTT Broker（如独立部署的 EMQX/Mosquitto）。`host` 需改为外部 Broker 地址，`enabled = false` 时整个 MQTT 通道关闭。
+
+### Broker 认证（用户名/密码）
+
+`[<env>.mqtt].username` / `password` 配置 Broker 认证（可选，默认匿名）：
+
+```toml
+[development.mqtt]
+enabled = true
+host = "0.0.0.0"
+port = 1883
+username = "chongming"   # 可选；内嵌/外部 Broker 均生效
+password = "change-me"
+```
+
+- **内嵌 Broker**（`use_embedded_broker=true`）：配置后启用认证（amqtt FileAuthPlugin + argon2 哈希），所有客户端（含网关 Bridge）必须携带该账号密码连接；未配置则保持匿名。
+- **外部 Broker**：网关 Bridge 以该账号密码连接，broker 侧需自行创建对应账号。
+- 客户端连接示例：`mqtt://chongming:change-me@localhost:1883/`（密码含特殊字符时需百分号编码，如 `@` → `%40`；网关 Bridge 内部自动处理）。
+- 注意：密码明文存放于配置，生产环境建议使用外部 Broker + 环境变量注入。
+
 ### 自定义订阅主题
 
 除内置的 `chongming/<type>/<op>` 接口外，可将外部 MQTT 主题桥接到任意 Worker。**推荐在插件自己的配置** `config/workers/<type>/config.toml` 中通过 `[[workers.mqtt_topics]]` 声明（目标 worker 即该插件本身）：