chongming/chongming-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

modify: 说明文档

Browse Source
This commit is contained in:
chakcy
2026-08-05 18:19:29 +08:00
parent 4984787158
commit 5a55da3c7d
1 changed files with 106 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+106 -39
View File
@@ -1,28 +1,35 @@
# 配置文件说明 # 配置文件说明
本目录存放应用所有 TOML 配置文件。 本目录存放应用的 TOML 配置文件，分为三层：应用主配置、Worker 注册配置、端点路由配置。
--- ---
## 文件总览 ## 文件总览
``` ```text
config/ config/
├── config.toml # 应用主配置
├── zenoh_config.json5 # Zenoh 会话配置（JSON5 格式） ├── zenoh_config.json5 # Zenoh 会话配置（JSON5 格式）
└── workers/ └── workers/
├── config.toml # Worker 插件加载列表 ├── config.toml # Worker 插件加载列表
├── auth/ # 鉴权插件路由定义 ├── auth/ # 鉴权插件
│ ├── config.toml # 分组配置（路由前缀、默认值） │ ├── config.toml # 分组配置（路由前缀、默认值）
│ ├── register.toml # 用户注册 │ ├── register.toml # 用户注册
│ ├── login.toml # 登录 │ ├── login.toml # 登录
│ ├── me.toml # 获取用户信息 │ ├── me.toml # 获取用户信息
│ ├── change_password.toml # 修改密码 │ ├── change_password.toml # 修改密码
│ └── update_profile.toml # 更新资料 │ └── update_profile.toml # 更新资料
├── doubao/ # 豆包视觉理解路由定义 ├── doubao/ # 豆包视觉理解插件
│ ├── config.toml │ ├── config.toml
│ └── analyze.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 ├── config.toml
├── add.toml ├── add.toml
├── subtract.toml ├── subtract.toml
@@ -31,37 +38,70 @@ config/
└── count.toml └── count.toml
``` ```
> **注意**：应用主配置 `config.toml` 位于项目根目录，不在本 `config/` 目录下。
--- ---
## 1. 应用主配置 (`config.toml`) ## 1. 应用主配置（根目录 `config.toml`）
定义应用全局设置：环境、服务器、日志、安全、缓存、对象存储等。 定义应用全局设置：环境、服务器、日志、安全、缓存、MQTT 等。
### 主要节 ### 主要节
| 节 | 说明 | | 节 | 说明 |
| --------------- | ------------------------------------------------------ | | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `[default]` | 应用元信息：`app.name`, `app.version`, `env`, `prefix` | | `[default]` | 应用元信息：`app.name`, `app.version`, `app.description`, `app.debug`, `env`, `prefix`, `upload_path` |
| `[nanio]` | S3 兼容存储配置：endpoint、access key、bucket | | `[zenoh]` | Zenoh 配置：`json5_path` 指向 Zenoh 会话配置文件 |
| `[zenoh]` | Zenoh 配置：`json5_path` 指向 Zenoh 会话配置文件 | | `[scheduler]` | 任务调度器：`job_store_path` |
| `[scheduler]` | 任务调度器：`job_store_path` | | `[cache]` | 缓存：`cache_store_path` |
| `[cache]` | 缓存：`cache_store_path` | | `[security]` | JWT 安全：`secret_key`, `algorithm` |
| `[security]` | JWT 安全：`secret_key`, `algorithm` | | `[development]` | 开发环境配置（server、logging、cors、mqtt） |
| `[development]` | 开发环境配置（server、logging、cors） | | `[production]` | 生产环境配置 |
| `[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`) ## 2. Worker 加载配置 (`workers/config.toml`)
定义哪些插件被加载，以及每个插件的运行时参数。 定义哪些插件被加载及运行时参数。每个插件一个 `[[workers]]` 数组项。
```toml ```toml
[[workers]] [[workers]]
type = "auth" # 插件类型名 type = "auth" # 插件类型名
module = "plugins.auth" # Python 模块路径 module = "plugins.auth" # Python 模块路径
factory = "create_workers" # 工厂函数名 factory = "create_workers" # 工厂函数名
cleanup = "cleanup" # 清理函数名 cleanup = "cleanup" # 清理函数名（可选）
count = 3 # Worker 副本数 count = 3 # Worker 副本数
[workers.config] [workers.config]
@@ -84,7 +124,7 @@ data_dir = "./data" # 插件自定义配置
## 3. 分组配置 (`workers/<type>/config.toml`) ## 3. 分组配置 (`workers/<type>/config.toml`)
每个插件目录下的 `config.toml` 定义该插件所有路由的公共设置。 每个插件目录下的 `config.toml` 定义该插件所有路由的公共默认值。
```toml ```toml
[worker] [worker]
@@ -107,18 +147,19 @@ tags = ["example"] # OpenAPI 分组标签
| `defaults.auth_required` | 端点是否默认需要 JWT 鉴权 | | `defaults.auth_required` | 端点是否默认需要 JWT 鉴权 |
| `defaults.internal` | 端点是否默认仅内部调用（不注册 HTTP 路由） | | `defaults.internal` | 端点是否默认仅内部调用（不注册 HTTP 路由） |
| `router_prefix` | 路由前缀，如 `/calc` → 完整路径 `/calc/add` | | `router_prefix` | 路由前缀，如 `/calc` → 完整路径 `/calc/add` |
| `tags` | OpenAPI 文档分组标签 |
--- ---
## 4. 端点配置 (`workers/<type>/<operation>.toml`) ## 4. 端点配置 (`workers/<type>/<operation>.toml`)
每个操作一个 TOML 文件，支持多个 HTTP 方法节。 每个操作一个 TOML 文件，支持 `[GET]`、`[POST]`、`[MQTT]` 三种节类型。
```toml ```toml
# add.toml — 每个方法节独立定义 # add.toml — 每个方法节独立定义
[GET] [GET]
summary = "Add two numbers" summary = "加法运算（GET）"
docstring = "通过 URL 参数执行加法运算" docstring = "通过 URL 参数执行加法运算"
params = ["a: float", "b: float"] params = ["a: float", "b: float"]
cacheable = true cacheable = true
@@ -132,40 +173,53 @@ operation = { type = "str", default = "add" }
timestamp = { type = "float", required = false, default = 0.0 } timestamp = { type = "float", required = false, default = 0.0 }
[POST] [POST]
summary = "Add two numbers (POST)" summary = "加法运算（POST）"
params = ["a: float", "b: float"] params = ["a: float", "b: float"]
auth_required = true auth_required = true
[POST.response_model] [POST.response_model]
result = { type = "float", required = true } result = { type = "float", required = true }
operation = { type = "str", default = "add" }
[MQTT]
summary = "加法运算（MQTT）"
params = ["a: float", "b: float"]
``` ```
### 端点字段 ### 端点字段
| 字段 | 类型 | 默认值 | 说明 | | 字段 | 类型 | 默认值 | 说明 |
| --------------- | ----------- | ------------------------ | -------------------------------------------------------------- | | --------------- | ----------- | ------------------------ | ---------------------------------------------------- |
| `summary` | `str` | — | 端点描述，显示在 OpenAPI 文档 | | `summary` | `str` | — | 端点描述，显示在 OpenAPI 文档 |
| `docstring` | `str` | — | 详细说明（可选） | | `docstring` | `str` | — | 详细说明（可选） |
| `params` | `list[str]` | `[]` | GET 参数列表，格式 `"name: type"`，POST 也需定义以生成请求模型 | | `params` | `list[str]` | `[]` | 参数列表，格式 `"name: type"` |
| `cacheable` | `bool` | `defaults.cacheable` | 结果是否可缓存 | | `cacheable` | `bool` | `defaults.cacheable` | 结果是否可缓存 |
| `auth_required` | `bool` | `defaults.auth_required` | 是否需要 JWT 鉴权 | | `auth_required` | `bool` | `defaults.auth_required` | 是否需要 JWT 鉴权 |
| `timeout` | `float` | `defaults.timeout` | RPC 超时（秒） | | `timeout` | `float` | `defaults.timeout` | RPC 超时（秒） |
| `internal` | `bool` | `false` | 设为 `true` 则只允许内部 Zenoh RPC 调用，不注册 HTTP 路由 | | `internal` | `bool` | `false` | 设为 `true` 则只允许内部 Zenoh RPC，不注册 HTTP 路由 |
### 响应模型字段 ### 响应模型字段
```toml ```toml
[GET.response_model] [GET.response_model]
field_name = { type = "str", required = true } # 必填字段 required_field = { type = "str", required = true }
optional_field = { type = "int", required = false, default = 0 } # 可选字段 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 模型**： 修改任何 TOML 配置后，**必须重新生成 Pydantic 模型**：
@@ -173,4 +227,17 @@ optional_field = { type = "int", required = false, default = 0 } # 可选字段
uv run python -m chongming.scripts.gen_models 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/<type>/config.toml (分组默认值)
└─ workers/<type>/<op>.toml (端点覆盖)
```
每层可覆盖上层默认值，端点级字段 (`timeout`, `cacheable`, `auth_required`, `internal`) 优先级最高。