MyAPS API

MyAPS API 是一个基于 FastAPI 的企业级数据操作平台，包含数据接口、数据清洗、监控、WebSocket 通信、日志与定时任务等能力。

项目概览

目录结构

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:

source venv/bin/activate

或者直接使用虚拟环境解释器执行命令：

./venv/bin/python --version

2. 准备环境变量

复制示例文件并按实际环境填写：

cp .env.example .env

至少需要确认以下配置：

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 / 清洗能力，还需要补充：

THIS_DB_HOST=localhost
THIS_DB_PORT=5432
THIS_DB_USER=postgres
THIS_DB_PASSWORD=your_password
THIS_DB_NAME=appsmith

3. 启动服务

使用项目脚本：

./scripts/dev_server.sh start

直接启动：

./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

常用命令

测试

运行全部测试：

./venv/bin/python -m pytest tests/ -v

验证应用可导入：

./venv/bin/python -c "import main; print(main.app.title)"

开发脚本

./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

数据库配置说明

全局数据库账号

项目统一使用以下变量作为主数据库连接配置：

MYAPS_DB_HOST
MYAPS_DB_PORT
MYAPS_DB_USER
MYAPS_DB_PASSWORD

binlog 配置说明

binlog 相关校验与参数设置逻辑当前也统一使用：

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 的认证机制：

# 设置 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 白名单配置：

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 应用已完全关闭
感谢使用，再见！
==================================================

当前验证状态

在当前仓库环境下，以下命令已验证通过：

./venv/bin/python -m pytest tests/ -v
./venv/bin/python -c "import main; print(main.app.title)"

备注

• 若 PROJECT_DIR 未配置，应用配置加载会失败
• 若数据库或 Redis 未就绪，部分功能会在启动或运行阶段报出明确错误
• 修改数据库、binlog、生命周期逻辑后，建议至少重新执行一次测试和导入校验