5c65c78752
- 36 files: module structure following module-development-spec - 7 table definitions: users_cache, pricing_cache, llmage_cache, uapi_cache, sync_state, customer_balance, accounting_records - Auth: dapi_auth + uapi_sign - Sync: base_sync + entity-specific sync modules (users/pricing/uapi/llmage) - Cache: LRU cache manager with TTL - API: balance, accounting, users, pricing, health handlers - Config: YAML config loader with env overrides - Utils: HTTP client, crypto helpers
84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
# SageAPI
|
||
|
||
独立 API 服务器模块，为外部客户提供余额查询、记账、用户/定价查询等 RESTful 接口。
|
||
|
||
## 架构
|
||
|
||
SageAPI 是独立于 Sage 的 API 服务器，支持多实例部署和水平扩展：
|
||
|
||
- 每个实例独立运行：自己的数据库连接池、内存缓存、同步调度器
|
||
- 多实例共享同一 MySQL 数据库，数据天然同步
|
||
- 增量同步模式：基于变更时间戳和事件驱动的混合策略
|
||
- 通过 dapi 提供认证，uapi 保障数据交互安全
|
||
- 纯 RESTful API 服务（无 Web 界面，除管理后台）
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
sageapi/
|
||
├── sageapi/ # Python 包
|
||
│ ├── __init__.py # 空文件（模块规范）
|
||
│ ├── init.py # 模块初始化：ServerEnv 注册
|
||
│ ├── config.py # 配置管理
|
||
│ ├── router.py # API 路由注册
|
||
│ ├── auth/ # 认证模块
|
||
│ │ ├── dapi_auth.py # dapi 认证中间件
|
||
│ │ └── uapi_sign.py # uapi 签名验证
|
||
│ ├── sync/ # 数据同步模块
|
||
│ │ ├── base_sync.py # 同步基类
|
||
│ │ ├── user_sync.py # 用户数据同步
|
||
│ │ ├── pricing_sync.py # pricing 数据同步
|
||
│ │ ├── uapi_sync.py # uapi 数据同步
|
||
│ │ └── llmage_sync.py # llmage 数据同步
|
||
│ ├── cache/ # 缓存层
|
||
│ │ └── cache_manager.py # 进程内存 LRU 缓存管理
|
||
│ ├── api/ # API 业务逻辑
|
||
│ │ ├── balance.py # 客户余额查询
|
||
│ │ ├── accounting.py # 记账接口
|
||
│ │ ├── users.py # 用户查询
|
||
│ │ ├── pricing.py # pricing 查询
|
||
│ │ └── health.py # 健康检查
|
||
│ └── utils/ # 工具函数
|
||
│ ├── http_client.py # 上游 HTTP 客户端
|
||
│ └── crypto.py # 加解密工具
|
||
├── wwwroot/ # 前端（管理界面）
|
||
├── models/ # 数据库表定义
|
||
├── json/ # CRUD 定义
|
||
├── init/data.json # 初始化数据
|
||
├── conf/config.yaml # 运行配置
|
||
├── pyproject.toml
|
||
├── build.sh
|
||
└── README.md
|
||
```
|
||
|
||
## API 端点
|
||
|
||
| 方法 | 路径 | 描述 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | /api/v1/health | 健康检查 | 无 |
|
||
| GET | /api/v1/balance | 客户余额查询 | dapi |
|
||
| POST | /api/v1/accounting | 创建记账记录 | dapi |
|
||
| GET | /api/v1/accounting | 查询记账记录 | dapi |
|
||
| GET | /api/v1/users | 用户查询 | dapi |
|
||
| GET | /api/v1/pricing | 定价查询 | dapi |
|
||
|
||
## 配置
|
||
|
||
配置文件位于 `conf/config.yaml`。支持环境变量覆盖，命名规则为 `SAGEAPI_<SECTION>_<KEY>`：
|
||
|
||
```bash
|
||
export SAGEAPI_DATABASE_HOST=10.0.0.1
|
||
export SAGEAPI_UPSTREAM_DAPI_KEY=your_key
|
||
export SAGEAPI_UPSTREAM_DAPI_SECRET=your_secret
|
||
```
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
bash build.sh
|
||
```
|
||
|
||
## 模块注册
|
||
|
||
在 Sage 启动时，`load_sageapi()` 函数自动注册所有公共函数到 `ServerEnv`，使它们在 dspy 脚本中可访问。
|