配置文件说明
本目录存放应用的 TOML 配置文件，分为三层：应用主配置、Worker 注册配置、端点路由配置。
文件总览
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 打包时的隐式导入声明 |
开发环境配置示例
[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/<type>/config.toml 的 [workers] 节）
定义哪些插件被加载及运行时参数。网关启动时扫描 config/workers/*/config.toml 自动发现；
每个插件在自己目录的 config.toml 中用 [workers] 节注册（与 [worker] 路由默认值共存于同一文件）。
# 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/<type>/ 目录名一致 |
module |
✅ | Python 模块导入路径 |
factory |
✅ | 工厂函数名，用于创建 Worker 实例 |
cleanup |
❌ | 清理函数名，插件卸载时调用 |
count |
✅ | Worker 副本数（并行处理请求数） |
[workers.config] |
❌ | 传递给插件的运行时配置（展平合并，子节见各插件） |
[[workers.mqtt_topics]] |
❌ | 插件声明的 MQTT Bridge 额外订阅主题（topic/subject/response_topic） |
3. 分组配置（workers/<type>/config.toml 的 [worker] 节）
每个插件目录下的 config.toml 定义该插件所有路由的公共默认值
（与第 2 节的 [workers] 注册节共存于同一文件）。
[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/<type>/<operation>.toml)
每个操作一个 TOML 文件，支持 [GET]、[POST]、[MQTT] 三种节类型。
# 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 路由 |
响应模型字段
[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 模型：
uv run python -m chongming.scripts.gen_models
该命令扫描 config/workers/*/ 下所有 .toml 文件，自动更新 src/plugins/*/models/pydantic.py。
配置层级与优先级
config.toml (全局)
└─ workers/<type>/config.toml (插件注册 [workers] 节 + 分组默认值 [worker] 节)
└─ workers/<type>/<op>.toml (端点覆盖)
每层可覆盖上层默认值，端点级字段 (timeout, cacheable, auth_required, internal) 优先级最高。
（旧式 workers/config.toml 全局注册文件仍兼容读取，仅作兜底。）