# Jerry WebApp 2.0 (Backend API & Services) 基于 FastAPI + SQLAlchemy + MySQL/Redis 的现代化异步后端服务系统,主要提供签证预约调度协调(Coordinate)、增值服务任务管理(VAS Task)、订单与多渠道支付、智能 Agent 与大模型工具调用、以及消息通知等能力。 --- ## 目录 - [核心功能特性](#核心功能特性) - [系统架构与技术栈](#系统架构与技术栈) - [目录结构说明](#目录结构说明) - [环境配置与准备](#环境配置与准备) - [本地运行与部署](#本地运行与部署) - [1. 本地启动 (开发与生产模式)](#1-本地启动-开发与生产模式) - [2. Docker 与 Docker Compose 部署](#2-docker-与-docker-compose-部署) - [测试运行规范](#测试运行规范) - [API 接口与文档](#api-接口与文档) - [消息服务 (Iris Messenger)](#消息服务-iris-messenger) --- ## 核心功能特性 1. **签证预约与调度协同 (Coordinate & Free Config)** - 支持各大签证中心(TLSContact、VFS Global、BLS 等)配置抓取与空位轮询机制; - 具备代理节点声誉与熔断风控评分体系(Proxy Reputation & Circuit Breaker)。 2. **云端插件热升级与分发系统 (Plugins & Node Management)** - 云端插件版本管理、代码上传校验(SHA256)、安全下载分发; - 基于 Redis Pub/Sub 的实时插件版本下发与节点热重载。 3. **订单、账单与多渠道支付 (Orders & Payment)** - 订单全生命周期状态流转与幂等防重保障; - 支持多币种与支付手续费(Processing Fee)自动计算; - 集成 Stripe 与 Creem 支付网关(含生产与沙盒多套密钥环境隔离)及 Webhook 回调验签。 4. **增值服务与工单系统 (VAS Tasks & Tickets)** - 客户工单追踪处理、智能告警与防刷防重流控。 5. **大语言模型与 Agent 引擎 (LLM & Intelligent Agent)** - 兼容 OpenAI 格式 API(默认 DeepSeek),内置多种业务工具集(订单查询、节点控制、账单结算等)及上下文记忆管理。 6. **多渠道通知分发引擎 (Iris Messenger)** - 支持 Email、微信 (WeChat)、WhatsApp、Telegram 等渠道的异步消息轮询与重试发送。 --- ## 系统架构与技术栈 - **Web 框架**: [FastAPI](https://fastapi.tiangolo.com/) (Python 3.9+) - **ASGI 服务器**: [Uvicorn](https://www.uvicorn.org/) (结合 `uvloop` + `httptools`) - **ORM & 数据库**: [SQLAlchemy 2.x](https://www.sqlalchemy.org/) (异步驱动 `asyncmy` / `psycopg2-binary`) + MySQL 8.x - **缓存与消息中继**: [Redis](https://redis.io/) - **对象存储**: Cloudflare R2 / SeaweedFS - **数据校验**: Pydantic v2 - **测试框架**: pytest + pytest-asyncio --- ## 目录结构说明 ```text jerry_webapp_2/ ├── app/ │ ├── api/ # API 路由层 (公共路由、登录保护路由、管理员路由) │ │ └── endpoints/ # 各业务领域控制器 (auth, order, payment, plugin, proxy 等) │ ├── core/ # 核心基础设施 (配置 settings, 数据库 database, 权限 auth, 日志 logger) │ ├── models/ # SQLAlchemy ORM 数据模型 │ ├── schemas/ # Pydantic 请求/响应数据模型 │ ├── services/ # 核心业务逻辑与服务实现 │ │ └── agent/ # 智能 Agent 引擎、Memory 与内置 Tools │ ├── utils/ # 公共工具类 (限流 throttler, 优先级队列, 代理辅助, 统一响应等) │ ├── visa_free_config_fetchers/# 各签证中心自动化抓取适配器 │ └── main.py # FastAPI 应用主入口及中间件、全局异常处理 ├── docs/ # 系统详细设计文档 (如 plugin.md 插件管理系统设计) ├── scripts/ # 运维与后台脚本 (如 iris.py 消息推送 Worker、数据库迁移脚本) ├── tests/ # 单元测试与集成测试套件 ├── starter.py # 服务启动入口脚本 (支持 DEV / PROD 环境模式切换) ├── requirements.txt # Python 依赖清单 ├── Dockerfile # 容器化构建镜像配置 ├── docker-compose.yml # Docker Compose 编排文件 (API Backend + Iris Messenger) └── .env # 环境变量配置文件 (模板/本地环境) ``` --- ## 环境配置与准备 在项目根目录创建或修改 `.env` 配置文件(参考 `.env` 模板): ```ini # 全局环境配置: DEV (开发测试) | PROD (生产正式) ENV=DEV # 数据库连接 (MySQL 异步驱动) DATABASE_URL=mysql+asyncmy://:@:/?charset=utf8mb4 # Redis 缓存与 Pub/Sub REDIS_URL=redis://:@:/0 # LLM 大模型配置 (兼容 OpenAI 规范) LLM_API_KEY=sk-xxxx LLM_BASE_URL=https://api.deepseek.com LLM_MODEL=deepseek-v4-flash # 支付网关配置 (按 ENV 自动路由 PROD 或 TEST 密钥) STRIPE_PROD_API_KEY= STRIPE_PROD_WEBHOOK_SECRET= STRIPE_TEST_API_KEY= STRIPE_TEST_WEBHOOK_SECRET= CREEM_PROD_API_KEY= CREEM_PROD_WEBHOOK_SECRET= CREEM_TEST_API_KEY= CREEM_TEST_WEBHOOK_SECRET= # 消息通知网关配置 TELEGRAM_API_TOKEN= WECHAT_API_TOKEN= WHATSAPP_API_BASE_URL= WHATSAPP_API_KEY= # 对象存储配置 (Cloudflare R2) R2_ACCOUNT_ID= R2_ACCESS_KEY_ID= R2_SECRET_ACCESS_KEY= R2_BUCKET_NAME= ``` --- ## 本地运行与部署 ### 1. 本地启动 (开发与生产模式) #### 安装依赖 推荐在虚拟环境中执行: ```bash pip install -r requirements.txt ``` #### 启动服务 使用项目统一启动器 `starter.py`: - **开发模式(默认,热重载 + 开启 Swagger 文档)**: ```bash python starter.py ``` - **生产模式(多工作进程 + uvloop + 关闭公网 API 文档)**: ```bash # Linux / macOS ENV=PROD WORKERS=4 python starter.py # Windows PowerShell $env:ENV="PROD"; $env:WORKERS="4"; python starter.py ``` 服务默认监听 `0.0.0.0:8888`。 --- ### 2. Docker 与 Docker Compose 部署 通过容器化方式一键编排启动后端 API 和 Iris 消息队列服务: ```bash # 构建并启动后台容器 docker-compose up -d --build # 查看运行状态 docker-compose ps # 查看日志 docker-compose logs -f backend ``` --- ## 测试运行规范 为确保根包模块 `app` 正确被解析,在执行单元测试时建议使用 `-m pytest` 或设置 `PYTHONPATH`: ```bash # 执行全部单元测试 python -m pytest # 执行指定模块测试 (例如插件管理或 RBAC 防护测试) python -m pytest tests/test_plugin_api.py python -m pytest tests/test_rbac_idor_guards.py ``` --- ## API 接口与文档 在开发环境(`ENV=DEV`)启动后,可通过浏览器访问交互式 API 文档: - **Swagger UI**: [http://localhost:8888/docs](http://localhost:8888/docs) - **ReDoc UI**: [http://localhost:8888/redoc](http://localhost:8888/redoc) - **OpenAPI 规范 JSON**: [http://localhost:8888/openapi.json](http://localhost:8888/openapi.json) > **注**:在生产环境(`ENV=PROD`)下,出于安全考虑,文档路由将自动关闭。 --- ## 消息服务 (Iris Messenger) 独立后台服务负责异步消息发送(邮件、微信、Telegram、WhatsApp),具备指数退避重试和频道并发锁防护: ```bash python scripts/iris.py ``` 在 Docker 环境中,`docker-compose.yml` 已配置该服务作为独立容器 (`textskin-messenger`) 运行。