modify: 添加 internal 路由屏蔽
This commit is contained in:
@@ -2,22 +2,175 @@
|
|||||||
|
|
||||||
本目录存放应用所有 TOML 配置文件。
|
本目录存放应用所有 TOML 配置文件。
|
||||||
|
|
||||||
## 主要文件
|
---
|
||||||
|
|
||||||
- `config.toml`：应用主配置（环境、服务器、日志、安全、缓存等）
|
## 文件总览
|
||||||
- `zenoh_config.json5`：Zenoh 会话配置（JSON5 格式）
|
|
||||||
- `workers/config.toml`：Worker 插件加载列表（指定模块、工厂函数、副本数）
|
|
||||||
- `workers/<worker_type>/*.toml`：每个 Worker 的路由定义（如 `add.toml`, `divide.toml`）
|
|
||||||
|
|
||||||
## Worker 路由配置格式
|
```
|
||||||
|
config/
|
||||||
每个接口文件（如 `add.toml`）包含 HTTP 方法节（`[GET]`, `[POST]` 等）：
|
├── config.toml # 应用主配置
|
||||||
|
├── zenoh_config.json5 # Zenoh 会话配置（JSON5 格式）
|
||||||
```toml
|
└── workers/
|
||||||
[GET]
|
├── config.toml # Worker 插件加载列表
|
||||||
summary = "Add two numbers"
|
├── auth/ # 鉴权插件路由定义
|
||||||
params = ["a: float", "b: float"]
|
│ ├── config.toml # 分组配置（路由前缀、默认值）
|
||||||
response_model = { result = { type = "float", required = true }, operation = { type = "str", default = "add" } }
|
│ ├── 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
|
||||||
```
|
```
|
||||||
|
|
||||||
执行 `uv run gen_models config/workers/example src/plugins/example` 可自动生成对应的 Pydantic 模型。
|
---
|
||||||
|
|
||||||
|
## 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`)
|
||||||
|
|
||||||
|
定义哪些插件被加载，以及每个插件的运行时参数。
|
||||||
|
|
||||||
|
```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` 定义该插件所有路由的公共设置。
|
||||||
|
|
||||||
|
```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 方法节。
|
||||||
|
|
||||||
|
```toml
|
||||||
|
# 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 路由 |
|
||||||
|
|
||||||
|
### 响应模型字段
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[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 模型**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run python -m chongming.scripts.gen_models
|
||||||
|
```
|
||||||
|
|
||||||
|
该命令会扫描所有 `config/workers/*/` 下的 `.toml` 文件，自动更新 `src/plugins/*/models/pydantic.py`。
|
||||||
|
|||||||
@@ -3,7 +3,7 @@ name = "example"
|
|||||||
version = "0.1.0"
|
version = "0.1.0"
|
||||||
description = "chongming worker example — demonstrates new config features"
|
description = "chongming worker example — demonstrates new config features"
|
||||||
config_version = "1.0"
|
config_version = "1.0"
|
||||||
defaults = { method = "GET", ttl = 30, timeout = 2.0, auth_required = true, cacheable = false }
|
defaults = { method = "GET", ttl = 30, timeout = 2.0, auth_required = true, cacheable = false, internal = false }
|
||||||
|
|
||||||
[worker.registration]
|
[worker.registration]
|
||||||
router_prefix = "/calc"
|
router_prefix = "/calc"
|
||||||
|
|||||||
Reference in New Issue
Block a user