# 配置文件说明 本目录存放应用的 TOML 配置文件，分为三层：应用主配置、Worker 注册配置、端点路由配置。 --- ## 文件总览 ```text config/ ├── zenoh_config.json5 # Zenoh 会话配置（JSON5 格式） └── workers/ ├── config.toml # Worker 插件加载列表 ├── auth/ # 鉴权插件 │ ├── config.toml # 分组配置（路由前缀、默认值） │ ├── register.toml # 用户注册 │ ├── login.toml # 登录 │ ├── me.toml # 获取用户信息 │ ├── change_password.toml # 修改密码 │ └── update_profile.toml # 更新资料 ├── doubao/ # 豆包视觉理解插件 │ ├── config.toml │ └── analyze.toml ├── aibox_sophon_adapter/ # AI Box 设备监控插件 │ ├── config.toml │ ├── board_ping.toml # 设备心跳 │ ├── list_devices.toml # 设备列表 │ ├── get_device.toml # 设备详情 │ ├── get_offline_devices.toml # 离线设备 │ ├── get_alarm.toml # 告警详情 │ └── list_alarms.toml # 告警列表 └── example/ # 示例插件 ├── config.toml ├── add.toml ├── subtract.toml ├── multiply.toml ├── divide.toml └── count.toml ``` > **注意**：应用主配置 `config.toml` 位于项目根目录，不在本 `config/` 目录下。 --- ## 1. 应用主配置（根目录 `config.toml`） 定义应用全局设置：环境、服务器、日志、安全、缓存、MQTT 等。 ### 主要节 | 节 | 说明 | | ---------------------------- | ----------------------------------------------------------------------------------------------------- | | `[default]` | 应用元信息：`app.name`, `app.version`, `app.description`, `app.debug`, `env`, `prefix`, `upload_path` | | `[zenoh]` | Zenoh 配置：`json5_path` 指向 Zenoh 会话配置文件 | | `[scheduler]` | 任务调度器：`job_store_path` | | `[cache]` | 缓存：`cache_store_path` | | `[security]` | JWT 安全：`secret_key`, `algorithm` | | `[development]` | 开发环境配置（server、logging、cors、mqtt） | | `[production]` | 生产环境配置 | | `[plugins_worker]` | 插件 Worker 注册配置路径 | | `[pyinstaller_build_import]` | PyInstaller 打包时的隐式导入声明（只放网关本体依赖；内置插件专属依赖见根目录 `plugins_deps.toml`） | ### 开发环境配置示例 ```toml [development] debug = true env = "development" [development.server] host = "0.0.0.0" port = 8000 reload = true access_log = false [development.logging] file = "logs" level = "DEBUG" format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s" [development.cors] allow_origins = ["*"] allow_methods = ["*"] allow_headers = ["*"] allow_credentials = true [development.mqtt] enabled = true host = "0.0.0.0" port = 1883 ``` --- ## 2. 插件注册配置（`workers//config.toml` 的 `[workers]` 节） 定义哪些插件被加载及运行时参数。网关启动时扫描 `config/workers/*/config.toml` 自动发现； **每个插件在自己目录的 `config.toml` 中用 `[workers]` 节注册**（与 `[worker]` 路由默认值共存于同一文件）。 ```toml # config/workers/auth/config.toml [workers] type = "auth" # 插件类型名（worker type） module = "plugins.auth" # Python 模块路径 factory = "create_workers" # 工厂函数名（Plugin 基类绑定的方法） cleanup = "cleanup" # 清理函数名 count = 3 # Worker 副本数 [workers.config] data_dir = "./data" # 插件运行时配置（展平后传给 create_workers） ``` > 旧式全局文件 `config/workers/config.toml`（`[[workers]]` 数组）仍兼容读取， > 仅加载其中尚未由各插件自注册的类型，新插件请勿使用。 ### 字段说明 | 字段 | 必填 | 说明 | | ------------------ | ---- | ---------------------------------------------------- | | `type` | ✅ | 插件类型名，需与 `config/workers//` 目录名一致 | | `module` | ✅ | Python 模块导入路径 | | `factory` | ✅ | 工厂函数名，用于创建 Worker 实例 | | `cleanup` | ❌ | 清理函数名，插件卸载时调用 | | `count` | ✅ | Worker 副本数（并行处理请求数） | | `[workers.config]` | ❌ | 传递给插件的运行时配置（展平合并，子节见各插件） | | `[[workers.mqtt_topics]]` | ❌ | 插件声明的 MQTT Bridge 额外订阅主题（topic/subject/response_topic） | --- ## 3. 分组配置（`workers//config.toml` 的 `[worker]` 节） 每个插件目录下的 `config.toml` 定义该插件所有路由的公共默认值 （与第 2 节的 `[workers]` 注册节共存于同一文件）。 ```toml [worker] name = "example" version = "0.1.0" description = "示例插件" defaults = { timeout = 3.0, auth_required = false, cacheable = true, internal = false } [worker.registration] router_prefix = "/calc" # 所有路由的统一前缀 tags = ["example"] # OpenAPI 分组标签 ``` ### 字段说明 | 字段 | 说明 | | ------------------------ | ------------------------------------------- | | `defaults.timeout` | 默认超时时间（秒） | | `defaults.cacheable` | 端点结果是否默认缓存 | | `defaults.auth_required` | 端点是否默认需要 JWT 鉴权 | | `defaults.internal` | 端点是否默认仅内部调用（不注册 HTTP 路由） | | `router_prefix` | 路由前缀，如 `/calc` → 完整路径 `/calc/add` | | `tags` | OpenAPI 文档分组标签 | --- ## 4. 端点配置 (`workers//.toml`) 每个操作一个 TOML 文件，支持 `[GET]`、`[POST]`、`[MQTT]` 三种节类型。 ```toml # add.toml — 每个方法节独立定义 [GET] summary = "加法运算（GET）" docstring = "通过 URL 参数执行加法运算" params = ["a: float", "b: float"] cacheable = true auth_required = false timeout = 5.0 internal = false [GET.response_model] result = { type = "float", required = true } operation = { type = "str", default = "add" } timestamp = { type = "float", required = false, default = 0.0 } [POST] summary = "加法运算（POST）" params = ["a: float", "b: float"] auth_required = true [POST.response_model] result = { type = "float", required = true } [MQTT] summary = "加法运算（MQTT）" params = ["a: float", "b: float"] ``` ### 端点字段 | 字段 | 类型 | 默认值 | 说明 | | --------------- | ----------- | ------------------------ | ---------------------------------------------------- | | `summary` | `str` | — | 端点描述，显示在 OpenAPI 文档 | | `docstring` | `str` | — | 详细说明（可选） | | `params` | `list[str]` | `[]` | 参数列表，格式 `"name: type"` | | `cacheable` | `bool` | `defaults.cacheable` | 结果是否可缓存 | | `auth_required` | `bool` | `defaults.auth_required` | 是否需要 JWT 鉴权 | | `timeout` | `float` | `defaults.timeout` | RPC 超时（秒） | | `internal` | `bool` | `false` | 设为 `true` 则只允许内部 Zenoh RPC，不注册 HTTP 路由 | ### 响应模型字段 ```toml [GET.response_model] required_field = { type = "str", required = true } optional_field = { type = "int", required = false, default = 0 } ``` 支持的 `type` 值： | TOML 类型 | Python 类型 | | ------------------ | ---------------- | | `str` / `string` | `str` | | `int` / `integer` | `int` | | `float` / `number` | `float` | | `bool` / `boolean` | `bool` | | `dict` | `dict[str, Any]` | | `list[type]` | `list[type]` | | `Optional[type]` | `Optional[type]` | --- ## 修改配置后 修改任何 TOML 配置后，**必须重新生成 Pydantic 模型**： ```bash uv run gen_models ``` 该命令扫描 `config/workers/*/` 下所有 `.toml` 文件，自动更新 `src/plugins/*/models/pydantic.py`。 --- ## 配置层级与优先级 ``` config.toml (全局) └─ workers//config.toml (插件注册 [workers] 节 + 分组默认值 [worker] 节) └─ workers//.toml (端点覆盖) ``` 每层可覆盖上层默认值，端点级字段 (`timeout`, `cacheable`, `auth_required`, `internal`) 优先级最高。 （旧式 `workers/config.toml` 全局注册文件仍兼容读取，仅作兜底。）