|
|
@@ -0,0 +1,210 @@
|
|
|
+# 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://<username>:<password>@<host>:<port>/<dbname>?charset=utf8mb4
|
|
|
+
|
|
|
+# Redis 缓存与 Pub/Sub
|
|
|
+REDIS_URL=redis://:<password>@<host>:<port>/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`) 运行。
|