配置文件说明

本目录存放应用所有 TOML 配置文件。

---

文件总览

config/
├── config.toml                         # 应用主配置
├── 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
    └── example/                        # 示例路由定义
        ├── config.toml
        ├── add.toml
        ├── subtract.toml
        ├── multiply.toml
        ├── divide.toml
        └── count.toml

---

1. 应用主配置 (config.toml)

定义应用全局设置：环境、服务器、日志、安全、缓存、对象存储等。

主要节

节	说明
[default]	应用元信息：app.name, app.version, env, prefix
[nanio]	S3 兼容存储配置：endpoint、access key、bucket
[zenoh]	Zenoh 配置：json5_path 指向 Zenoh 会话配置文件
[scheduler]	任务调度器：job_store_path
[cache]	缓存：cache_store_path
[security]	JWT 安全：secret_key, algorithm
[development]	开发环境配置（server、logging、cors）
[production]	生产环境配置

---

2. Worker 加载配置 (workers/config.toml)

定义哪些插件被加载，以及每个插件的运行时参数。

[[workers]]
type = "auth"                        # 插件类型名
module = "plugins.auth"              # Python 模块路径
factory = "create_workers"           # 工厂函数名
cleanup = "cleanup"                  # 清理函数名
count = 3                            # Worker 副本数

[workers.config]
type = "auth"
data_dir = "./data"                  # 插件自定义配置

字段说明

字段	必填	说明
type	✅	插件类型名，需与 config/workers/<type>/ 目录名一致
module	✅	Python 模块导入路径
factory	✅	工厂函数名，用于创建 Worker 实例
cleanup	❌	清理函数名，插件卸载时调用
count	✅	Worker 副本数（并行处理请求数）
[workers.config]	❌	传递给插件的自定义配置字典

---

3. 分组配置 (workers/<type>/config.toml)

每个插件目录下的 config.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

---

4. 端点配置 (workers/<type>/<operation>.toml)

每个操作一个 TOML 文件，支持多个 HTTP 方法节。

# add.toml — 每个方法节独立定义

[GET]
summary = "Add two numbers"
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 = "Add two numbers (POST)"
params = ["a: float", "b: float"]
auth_required = true

[POST.response_model]
result = { type = "float", required = true }
operation = { type = "str", default = "add" }

端点字段

字段	类型	默认值	说明
summary	str	—	端点描述，显示在 OpenAPI 文档
docstring	str	—	详细说明（可选）
params	list[str]	[]	GET 参数列表，格式 "name: type"，POST 也需定义以生成请求模型
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]
field_name = { type = "str", required = true }            # 必填字段
optional_field = { type = "int", required = false, default = 0 }  # 可选字段

支持的 type 值：str/string、int/integer、float/number、bool/boolean、dict、list[type]、Optional[type]。

---

修改配置后的操作

修改任何 TOML 配置后，必须重新生成 Pydantic 模型：

uv run python -m chongming.scripts.gen_models

该命令会扫描所有 config/workers/*/ 下的 .toml 文件，自动更新 src/plugins/*/models/pydantic.py。