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>：
export SAGEAPI_DATABASE_HOST=10.0.0.1
export SAGEAPI_UPSTREAM_DAPI_KEY=your_key
export SAGEAPI_UPSTREAM_DAPI_SECRET=your_secret
构建
bash build.sh
模块注册
在 Sage 启动时，load_sageapi() 函数自动注册所有公共函数到 ServerEnv，使它们在 dspy 脚本中可访问。