80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
# chongming-gateway
|
||
|
||
chongming 网关本体：基于 **FastAPI + Zenoh** 的配置驱动微服务网关。
|
||
|
||
把宿主项目里的插件（inline 进程内 / external 独立进程）发布的路由统一挂载为 HTTP 端点，
|
||
并提供 Worker 服务发现、负载均衡、超时重试、实例定向、MQTT Bridge 与内置登录鉴权。
|
||
|
||
网关只提供**代码**：配置、插件与打包骨架由宿主项目提供（见「运行时约定」）。
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
# 作为依赖（宿主项目，从私有源安装）
|
||
uv add chongming-gateway
|
||
|
||
# 开发期可编辑安装（在 chongming-core 仓库内）
|
||
uv pip install -e utils/gateway
|
||
```
|
||
|
||
网关自带完整依赖清单（`fastapi` / `granian` / `zenoh` / `chongming-worker` 等），
|
||
宿主项目无需重复声明；需要哪些第三方包，见本包 `pyproject.toml`。
|
||
|
||
## 快速开始
|
||
|
||
宿主项目（cwd）下准备 `config.toml` 与 `config/workers/<type>/config.toml`，
|
||
并保证插件包（`plugins.<type>`）可导入。之后任选一种启动方式：
|
||
|
||
```bash
|
||
# 按 config.toml [<env>.server] 启动（三个入口等价，仅默认服务器不同）
|
||
uv run serve # uvicorn
|
||
uv run granian # granian
|
||
uv run gunicorn # gunicorn + uvicorn worker
|
||
|
||
# 或把 ASGI 应用交给任意服务器
|
||
uvicorn chongming.app:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
网关按 `config/workers/<name>/config.toml` 的 `[workers]` 节逐插件读取加载方式
|
||
（`load_mode = "inline" | "external"`）与副本数，启动时自动发现并挂载路由。
|
||
|
||
## 运行时约定
|
||
|
||
- **配置**：cwd 下 `config.toml`（环境、服务器、安全、MQTT、缓存等）与
|
||
`config/workers/**`（插件注册与路由定义），运行期读取，随宿主项目部署。
|
||
- **插件**：网关按 `plugins.<type>` 约定导入插件包，来源不限——`.mbank` 模块银行、
|
||
源码目录（开发态 `src/plugins`）或已安装包均可。
|
||
- **工作目录**：日志、上传、数据等相对路径均以 cwd 为基准。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
src/chongming/
|
||
├── __init__.py # 启动入口（serve / granian / gunicorn）与服务器参数转换
|
||
└── app/
|
||
├── __init__.py # FastAPI 应用装配（lifespan、中间件、异常处理）
|
||
├── core/ # WorkerManager / RouteGenerator / MQTT Bridge / 日志 / 鉴权
|
||
└── routes/ # 内置管理端点（stats / worker_admin / auth）
|
||
```
|
||
|
||
## 开发与发布
|
||
|
||
```bash
|
||
# 在 chongming-core 仓库内改代码后，让 venv 用本地源码（联调用）
|
||
uv pip install -e utils/gateway
|
||
|
||
# 发版：构建 wheel 并推私有源
|
||
uv build # dist/chongming_gateway-<version>-py3-none-any.whl
|
||
uv run twine upload --repository <私有源> dist/*
|
||
```
|
||
|
||
发版后依赖方执行 `uv lock --upgrade-package chongming-gateway` 刷新版本 pin。
|
||
注意 `uv sync` 会用锁文件版本替换可编辑安装——打包/发版前先确认 venv 指向目标版本。
|
||
|
||
## 相关文档
|
||
|
||
- [项目主 README](../../README.md)：整体架构、使用与构建部署
|
||
- [Worker 管理与多实例运维](../../docs/worker-management.md)：管理端点、扩缩容、实例定向
|