diff --git a/README.md b/README.md index 4bc77e3..9a17423 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,35 @@ # 配置文件说明 -本目录存放应用所有 TOML 配置文件。 +本目录存放应用的 TOML 配置文件，分为三层：应用主配置、Worker 注册配置、端点路由配置。 --- ## 文件总览 -``` +```text config/ -├── config.toml # 应用主配置 ├── zenoh_config.json5 # Zenoh 会话配置（JSON5 格式） └── workers/ ├── config.toml # Worker 插件加载列表 - ├── auth/ # 鉴权插件路由定义 + ├── auth/ # 鉴权插件 │ ├── config.toml # 分组配置（路由前缀、默认值） │ ├── register.toml # 用户注册 │ ├── login.toml # 登录 │ ├── me.toml # 获取用户信息 │ ├── change_password.toml # 修改密码 │ └── update_profile.toml # 更新资料 - ├── doubao/ # 豆包视觉理解路由定义 + ├── doubao/ # 豆包视觉理解插件 │ ├── config.toml │ └── analyze.toml - └── example/ # 示例路由定义 + ├── 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 @@ -31,37 +38,70 @@ config/ └── count.toml ``` +> **注意**：应用主配置 `config.toml` 位于项目根目录，不在本 `config/` 目录下。 + --- -## 1. 应用主配置 (`config.toml`) +## 1. 应用主配置（根目录 `config.toml`） -定义应用全局设置：环境、服务器、日志、安全、缓存、对象存储等。 +定义应用全局设置：环境、服务器、日志、安全、缓存、MQTT 等。 ### 主要节 -| 节 | 说明 | -| --------------- | ------------------------------------------------------ | -| `[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]` | 生产环境配置 | +| 节 | 说明 | +| ---------------------------- | ----------------------------------------------------------------------------------------------------- | +| `[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 打包时的隐式导入声明 | + +### 开发环境配置示例 + +```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. Worker 加载配置 (`workers/config.toml`) -定义哪些插件被加载，以及每个插件的运行时参数。 +定义哪些插件被加载及运行时参数。每个插件一个 `[[workers]]` 数组项。 ```toml [[workers]] type = "auth" # 插件类型名 module = "plugins.auth" # Python 模块路径 factory = "create_workers" # 工厂函数名 -cleanup = "cleanup" # 清理函数名 +cleanup = "cleanup" # 清理函数名（可选） count = 3 # Worker 副本数 [workers.config] @@ -84,7 +124,7 @@ data_dir = "./data" # 插件自定义配置 ## 3. 分组配置 (`workers//config.toml`) -每个插件目录下的 `config.toml` 定义该插件所有路由的公共设置。 +每个插件目录下的 `config.toml` 定义该插件所有路由的公共默认值。 ```toml [worker] @@ -107,18 +147,19 @@ tags = ["example"] # OpenAPI 分组标签 | `defaults.auth_required` | 端点是否默认需要 JWT 鉴权 | | `defaults.internal` | 端点是否默认仅内部调用（不注册 HTTP 路由） | | `router_prefix` | 路由前缀，如 `/calc` → 完整路径 `/calc/add` | +| `tags` | OpenAPI 文档分组标签 | --- ## 4. 端点配置 (`workers//.toml`) -每个操作一个 TOML 文件，支持多个 HTTP 方法节。 +每个操作一个 TOML 文件，支持 `[GET]`、`[POST]`、`[MQTT]` 三种节类型。 ```toml # add.toml — 每个方法节独立定义 [GET] -summary = "Add two numbers" +summary = "加法运算（GET）" docstring = "通过 URL 参数执行加法运算" params = ["a: float", "b: float"] cacheable = true @@ -132,40 +173,53 @@ operation = { type = "str", default = "add" } timestamp = { type = "float", required = false, default = 0.0 } [POST] -summary = "Add two numbers (POST)" +summary = "加法运算（POST）" params = ["a: float", "b: float"] auth_required = true [POST.response_model] result = { type = "float", required = true } -operation = { type = "str", default = "add" } + +[MQTT] +summary = "加法运算（MQTT）" +params = ["a: float", "b: float"] ``` ### 端点字段 -| 字段 | 类型 | 默认值 | 说明 | -| --------------- | ----------- | ------------------------ | -------------------------------------------------------------- | -| `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 路由 | +| 字段 | 类型 | 默认值 | 说明 | +| --------------- | ----------- | ------------------------ | ---------------------------------------------------- | +| `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] -field_name = { type = "str", required = true } # 必填字段 -optional_field = { type = "int", required = false, default = 0 } # 可选字段 +required_field = { 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]`。 +支持的 `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 模型**： @@ -173,4 +227,17 @@ optional_field = { type = "int", required = false, default = 0 } # 可选字段 uv run python -m chongming.scripts.gen_models ``` -该命令会扫描所有 `config/workers/*/` 下的 `.toml` 文件，自动更新 `src/plugins/*/models/pydantic.py`。 +该命令扫描 `config/workers/*/` 下所有 `.toml` 文件，自动更新 `src/plugins/*/models/pydantic.py`。 + +--- + +## 配置层级与优先级 + +``` +config.toml (全局) + └─ workers/config.toml (插件注册) + └─ workers//config.toml (分组默认值) + └─ workers//.toml (端点覆盖) +``` + +每层可覆盖上层默认值，端点级字段 (`timeout`, `cacheable`, `auth_required`, `internal`) 优先级最高。