mirror of
https://github.com/rnvm9wjdtj-bot/myaps_api.git
synced 2026-06-02 05:54:40 +00:00
chaoge
fa5cecd6d1
- 安全: 修复鉴权失败返回码(HTTP 401/403替代200) - 安全: 新增SafeQueryBuilder封堵SQL注入入口 - 安全: 移除Pydantic json_encoders弃用配置 - 稳定: 统一后台任务托管与生命周期管理 - 稳定: 新增TaskManager统一管理后台任务 - 文档: 更新README.md与.env.example - 重构: routers.py使用安全SQL构建器替代字符串拼接
262 lines
5.8 KiB
Markdown
262 lines
5.8 KiB
Markdown
# MyAPS API
|
||
|
||
MyAPS API 是一个基于 FastAPI 的企业级数据操作平台，包含数据接口、数据清洗、监控、WebSocket 通信、日志与定时任务等能力。
|
||
|
||
## 项目概览
|
||
|
||
### 目录结构
|
||
|
||
```text
|
||
myaps_api/
|
||
├── apps/ # 业务模块
|
||
│ ├── common/ # 监控、帮助、通用工具
|
||
│ ├── data_opt/ # 数据操作、清洗、binlog、调度
|
||
│ └── io_api/ # 对外 API 接口
|
||
├── core/ # 应用工厂、配置、数据库、生命周期
|
||
├── globalobjects/ # 全局对象、日志、数据库管理
|
||
├── static/ # 前端静态资源
|
||
├── scripts/ # 开发、部署、迁移脚本
|
||
├── tests/ # 自动化测试
|
||
├── main.py # 应用入口
|
||
├── requirements.txt # Python 依赖
|
||
└── .env.example # 环境变量示例
|
||
```
|
||
|
||
### 技术栈
|
||
|
||
- FastAPI
|
||
- Uvicorn
|
||
- Tortoise ORM
|
||
- Pydantic
|
||
- MySQL / PostgreSQL / SQLite
|
||
- Redis
|
||
|
||
## 快速开始
|
||
|
||
### 1. 准备虚拟环境
|
||
|
||
项目依赖当前已安装在仓库内虚拟环境 `venv` 中。
|
||
|
||
Linux / macOS:
|
||
|
||
```bash
|
||
source venv/bin/activate
|
||
```
|
||
|
||
或者直接使用虚拟环境解释器执行命令：
|
||
|
||
```bash
|
||
./venv/bin/python --version
|
||
```
|
||
|
||
### 2. 准备环境变量
|
||
|
||
复制示例文件并按实际环境填写：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
至少需要确认以下配置：
|
||
|
||
```bash
|
||
PROJECT_DIR=YOUR_PROJECT_DIR
|
||
MYAPS_DB_HOST=localhost
|
||
MYAPS_DB_PORT=3333
|
||
MYAPS_DB_USER=your_db_user
|
||
MYAPS_DB_PASSWORD=your_db_password
|
||
MYAPS_DB_SET=db1,db2
|
||
MYAPS_MAIN_DB=db1
|
||
```
|
||
|
||
如使用 PostgreSQL staging / 清洗能力，还需要补充：
|
||
|
||
```bash
|
||
THIS_DB_HOST=localhost
|
||
THIS_DB_PORT=5432
|
||
THIS_DB_USER=postgres
|
||
THIS_DB_PASSWORD=your_password
|
||
THIS_DB_NAME=appsmith
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
使用项目脚本：
|
||
|
||
```bash
|
||
./scripts/dev_server.sh start
|
||
```
|
||
|
||
直接启动：
|
||
|
||
```bash
|
||
./venv/bin/python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
### 4. 访问服务
|
||
|
||
- 首页: `http://127.0.0.1:8000/`
|
||
- Swagger 文档: `http://127.0.0.1:8000/docs`
|
||
|
||
## 常用命令
|
||
|
||
### 测试
|
||
|
||
运行全部测试：
|
||
|
||
```bash
|
||
./venv/bin/python -m pytest tests/ -v
|
||
```
|
||
|
||
验证应用可导入：
|
||
|
||
```bash
|
||
./venv/bin/python -c "import main; print(main.app.title)"
|
||
```
|
||
|
||
### 开发脚本
|
||
|
||
```bash
|
||
./scripts/dev_server.sh start
|
||
./scripts/dev_server.sh stop
|
||
./scripts/dev_server.sh restart
|
||
./scripts/dev_server.sh status
|
||
./scripts/dev_server.sh logs
|
||
```
|
||
|
||
## 数据库配置说明
|
||
|
||
### 全局数据库账号
|
||
|
||
项目统一使用以下变量作为主数据库连接配置：
|
||
|
||
```bash
|
||
MYAPS_DB_HOST
|
||
MYAPS_DB_PORT
|
||
MYAPS_DB_USER
|
||
MYAPS_DB_PASSWORD
|
||
```
|
||
|
||
### binlog 配置说明
|
||
|
||
binlog 相关校验与参数设置逻辑当前也统一使用：
|
||
|
||
```bash
|
||
MYAPS_DB_USER
|
||
MYAPS_DB_PASSWORD
|
||
```
|
||
|
||
注意事项：
|
||
|
||
- 不再使用单独的 `MYAPS_ROOT_PASSWORD`
|
||
- binlog 相关逻辑不会再写死 `root` 用户
|
||
- 若 `MYAPS_DB_USER` 或 `MYAPS_DB_PASSWORD` 未配置，相关校验会显式失败
|
||
- 如需执行高权限 binlog 配置操作，请确保 `MYAPS_DB_USER` 对应账号本身具备所需权限
|
||
|
||
### staging / 清洗模式
|
||
|
||
- `THIS_DB_*` 用于 PostgreSQL staging 数据库配置
|
||
- `STAGING_DB_NAME` 默认为 `--s`
|
||
- 清洗模式与主业务数据库配置分离
|
||
|
||
## 安全配置说明
|
||
|
||
### API 认证
|
||
|
||
项目支持基于 API Key 的认证机制：
|
||
|
||
```bash
|
||
# 设置 API Key（可选）
|
||
API_KEY=your-api-key-here
|
||
```
|
||
|
||
- 未设置 `API_KEY` 时，所有接口可自由访问
|
||
- 设置后，非公开接口需要在请求头中携带 `X-API-Key`
|
||
- 认证失败返回 HTTP 401（不再返回 200）
|
||
|
||
### 公开接口
|
||
|
||
以下接口无需认证即可访问：
|
||
|
||
- `/health` - 健康检查（用于 K8s/负载均衡）
|
||
- `/health/database` - 数据库健康检查
|
||
- `/static/*` - 静态资源
|
||
- `/mds/*` - MDS 页面
|
||
- `/docs`, `/redoc` - API 文档（仅限内网访问）
|
||
|
||
### IP 白名单
|
||
|
||
支持多种格式的 IP 白名单配置：
|
||
|
||
```bash
|
||
IP_WHITELIST=127.0.0.1,192.168.1.*,10.0.0.0/8,192.168.1.100-200
|
||
```
|
||
|
||
支持的格式：
|
||
- 精确 IP: `192.168.1.100`
|
||
- 通配符: `192.168.1.*`
|
||
- IP 范围: `192.168.1.100-200`
|
||
- CIDR 表示法: `10.0.0.0/8`
|
||
|
||
### SQL 注入防护
|
||
|
||
项目已实现 SQL 注入防护机制：
|
||
|
||
- 使用安全 SQL 构建函数（`escape_sql_value`, `build_safe_condition`）
|
||
- 自动转义用户输入
|
||
- 标识符验证防止注入攻击
|
||
- 所有外部输入都经过安全处理
|
||
|
||
## 监控与日志
|
||
|
||
- 实时日志与历史日志页面位于 `/monitor`
|
||
- 统一日志系统位于 `globalobjects/logger/`
|
||
- 开发期可通过 `./scripts/dev_server.sh logs -f` 查看实时日志
|
||
|
||
## 生命周期管理
|
||
|
||
### 后台任务管理
|
||
|
||
项目使用统一的后台任务管理器（`core/task_manager.py`）：
|
||
|
||
- 所有后台任务统一注册和跟踪
|
||
- 支持优雅关闭和超时保护
|
||
- 自动清理已完成的任务
|
||
|
||
### 关闭顺序
|
||
|
||
应用关闭时按照以下顺序执行，确保资源正确释放：
|
||
|
||
```
|
||
阶段1: 取消所有后台任务（优先执行）
|
||
阶段2: 停止服务和监控器
|
||
阶段3: 释放资源和连接（数据库最后关闭）
|
||
阶段4: 关闭日志系统
|
||
```
|
||
|
||
关闭时会输出明确提示：
|
||
|
||
```
|
||
==================应用关闭完成==================
|
||
所有资源已释放，服务已完全停止
|
||
==================================================
|
||
MyAPS API 应用已完全关闭
|
||
感谢使用，再见！
|
||
==================================================
|
||
```
|
||
|
||
## 当前验证状态
|
||
|
||
在当前仓库环境下，以下命令已验证通过：
|
||
|
||
```bash
|
||
./venv/bin/python -m pytest tests/ -v
|
||
./venv/bin/python -c "import main; print(main.app.title)"
|
||
```
|
||
|
||
## 备注
|
||
|
||
- 若 `PROJECT_DIR` 未配置，应用配置加载会失败
|
||
- 若数据库或 Redis 未就绪，部分功能会在启动或运行阶段报出明确错误
|
||
- 修改数据库、binlog、生命周期逻辑后，建议至少重新执行一次测试和导入校验
|