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、生命周期逻辑后，建议至少重新执行一次测试和导入校验

Languages

JavaScript 59.5%

Python 33.5%

HTML 3.7%

CSS 1.1%

Shell 0.8%

Other 1.4%

README.md Unescape Escape

MyAPS API

项目概览

目录结构

技术栈