250 lines
10 KiB
Markdown
250 lines
10 KiB
Markdown
# 配置文件说明
|
||
|
||
本目录存放应用的 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/<type>/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/<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]` 注册节共存于同一文件）。
|
||
|
||
```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/<type>/<operation>.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/<type>/config.toml (插件注册 [workers] 节 + 分组默认值 [worker] 节)
|
||
└─ workers/<type>/<op>.toml (端点覆盖)
|
||
```
|
||
|
||
每层可覆盖上层默认值，端点级字段 (`timeout`, `cacheable`, `auth_required`, `internal`) 优先级最高。
|
||
（旧式 `workers/config.toml` 全局注册文件仍兼容读取，仅作兜底。）
|