説明なし

robot 8d6dff5e73 fix(#2): 写一下README 1 ヶ月 前
.agents 88241d02f9 update 1 ヶ月 前
app 4f9da9341c feat: add payment processing fee calculation and migration support 1 ヶ月 前
docs fbb82bb807 feat: add provider templates and refactor node configuration endpoints 2 ヶ月 前
scripts 4f9da9341c feat: add payment processing fee calculation and migration support 1 ヶ月 前
tests 4ca1e696eb feat: add admin endpoint and service method to permanently delete orders and related data 1 ヶ月 前
.env 0846199123 refactor: add environment-aware configuration for payment providers and update error messages 1 ヶ月 前
.gitignore a918c49743 vas 10 ヶ月 前
Dockerfile 5fc3a15992 feat: update 10 ヶ月 前
README.md 8d6dff5e73 fix(#2): 写一下README 1 ヶ月 前
docker-compose.yml f395419b74 refactor: modularize api router, clean unused services, enhance logging & fix configs 2 ヶ月 前
migrate_plugin_cols.py 88241d02f9 update 1 ヶ月 前
requirements.txt 09cf110e05 feat: update 1 ヶ月 前
starter.py 11dd03fb09 feat(vas_task): add pause status guards, lifecycle handling, and optimize starter config 2 ヶ月 前

README.md

Jerry WebApp 2.0 (Backend API & Services)

基于 FastAPI + SQLAlchemy + MySQL/Redis 的现代化异步后端服务系统,主要提供签证预约调度协调(Coordinate)、增值服务任务管理(VAS Task)、订单与多渠道支付、智能 Agent 与大模型工具调用、以及消息通知等能力。


目录


核心功能特性

  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 (Python 3.9+)
  • ASGI 服务器: Uvicorn (结合 uvloop + httptools)
  • ORM & 数据库: SQLAlchemy 2.x (异步驱动 asyncmy / psycopg2-binary) + MySQL 8.x
  • 缓存与消息中继: Redis
  • 对象存储: Cloudflare R2 / SeaweedFS
  • 数据校验: Pydantic v2
  • 测试框架: pytest + pytest-asyncio

目录结构说明

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 模板):

# 全局环境配置: 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. 本地启动 (开发与生产模式)

安装依赖

推荐在虚拟环境中执行:

pip install -r requirements.txt

启动服务

使用项目统一启动器 starter.py:

  • 开发模式(默认,热重载 + 开启 Swagger 文档):

    python starter.py
    
  • 生产模式(多工作进程 + uvloop + 关闭公网 API 文档):

    # 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 消息队列服务:

# 构建并启动后台容器
docker-compose up -d --build

# 查看运行状态
docker-compose ps

# 查看日志
docker-compose logs -f backend

测试运行规范

为确保根包模块 app 正确被解析,在执行单元测试时建议使用 -m pytest 或设置 PYTHONPATH:

# 执行全部单元测试
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 文档:

注:在生产环境(ENV=PROD)下,出于安全考虑,文档路由将自动关闭。


消息服务 (Iris Messenger)

独立后台服务负责异步消息发送(邮件、微信、Telegram、WhatsApp),具备指数退避重试和频道并发锁防护:

python scripts/iris.py

在 Docker 环境中,docker-compose.yml 已配置该服务作为独立容器 (textskin-messenger) 运行。