# qpet-backend

**Repository Path**: wongOld/qpet-backend

## Basic Information

- **Project Name**: qpet-backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Q宠乐斗 v5.0 Backend · qpet-backend

为 [duanwuqiufenmao.top](https://duanwuqiufenmao.top) 的 Q宠乐斗和农场游戏提供自动化引擎和 RESTful API 的后端服务。

本仓库是四仓库工作区中的 **v5.0 后端仓库**，承载 Python FastAPI 重构后的自动化引擎与 API。原版 Node.js 后台与逆向文档在 [main-server](https://gitee.com/wongOld/duanwuqiufenmao.git)。

## 仓库定位与兄弟仓库

| 仓库 | 说明 | 地址 |
|------|------|------|
| main-server | 原版 Node.js 自动化后台 + 逆向文档 + 攻略/工具 | [duanwuqiufenmao](https://gitee.com/wongOld/duanwuqiufenmao.git) |
| **qpet-backend（本仓库）** | v5.0 Python FastAPI 后端 | [qpet-backend](https://gitee.com/wongOld/qpet-backend.git) |
| qpet-frontend | v5.0 Ant Design Pro 前端 | [qpet-frontend](https://gitee.com/wongOld/qpet-frontend.git) |
| qpet-miniapp | 微信小程序骨架 | [qpet-miniapp](https://gitee.com/wongOld/qpet-miniapp.git) |

v5.0 前后端分离重构的整体进度见 main-server 仓库的 `docs/v5.0-development-progress.md`。

## 这是什么

这是一个游戏自动化后端，托管多个游戏账号，通过调用游戏 API 实现自动挂机：

- **乐斗自动化**：自动 NPC/好友对战、爬塔、帮派 BOSS、秘境副本、世界 BOSS
- **农场自动化**：自动播种/收获/翻地/偷菜/浇水/升级土地
- **婚姻自动化**：已婚送花+夫妻 BOSS，未婚送花求婚一条龙
- **智能军师**：装备评分推荐、技能加点方案、拍卖行比价
- **AI 助手小黑羊**：基于 DeepSeek 的对话式游戏咨询
- **Web Dashboard**：实时状态面板、日志流、配置管理、用户系统

## 技术栈

| 层 | 技术 |
|----|------|
| 框架 | Python 3.12+ / FastAPI |
| ORM | SQLAlchemy 2.0 (async) + Alembic |
| 数据库 | PostgreSQL 16 |
| 缓存 | Redis 7 |
| 消息队列 | RabbitMQ |
| 定时调度 | APScheduler |
| 认证 | JWT + ECDSA P-256 签名 |
| AI | DeepSeek API / SSE 流式响应 |
| 部署 | Docker Compose + GitHub Actions |

## 项目结构

```
backend/
├── app/
│   ├── main.py               # FastAPI 入口（生命周期/中间件/路由注册）
│   ├── config.py             # 配置管理（环境变量 + .env）
│   ├── core/                 # 基础设施层
│   │   ├── database.py       # SQLAlchemy async engine + session
│   │   ├── redis.py          # Redis 连接池（缓存/分布式锁）
│   │   ├── rabbitmq.py       # RabbitMQ 生产者/消费者
│   │   ├── auth_middleware.py# JWT 认证中间件
│   │   ├── crypto.py         # AES-256-GCM 加解密
│   │   ├── security.py       # 密码哈希/Token 生成
│   │   └── logger.py         # 结构化日志
│   ├── models/               # SQLAlchemy ORM（15+ 张表）
│   ├── schemas/              # Pydantic 请求/响应模型
│   ├── routers/              # API 路由层（薄）
│   │   ├── accounts.py       # 账号管理 CRUD
│   │   ├── auth.py           # 登录/注册
│   │   ├── config.py         # 配置读写
│   │   ├── ai.py             # AI 对话
│   │   ├── logs.py           # 日志查询
│   │   ├── auction.py        # 拍卖数据
│   │   └── preload.py        # 首页预加载
│   └── services/             # 业务逻辑层
│       ├── engine.py         # 核心引擎（循环调度）
│       ├── engine_account.py # 单账号引擎实例
│       ├── scheduler.py      # 定时任务管理
│       ├── auth.py           # 游戏 API 认证
│       ├── inventory.py      # 通用道具层
│       ├── supply.py         # 背包补给检测
│       ├── shop.py           # 商店自动购买
│       ├── farm/             # 农场模块
│       ├── marriage/         # 婚姻模块
│       ├── gang/             # 帮派模块
│       └── service_*.py      # 各游戏模块
├── alembic/                  # 数据库迁移
│   └── versions/
├── Dockerfile                # 多阶段构建
├── pyproject.toml
└── start.sh                  # 启动脚本
```

## 引擎架构

每个账号独立 Engine 实例，互不干扰：

```
Scheduler（全局调度器）
  ├── AccountManager（账号生命周期）
  │   ├── Engine #1（账号 A）
  │   │   └── 循环：farm → shop → marriage → fight → tower → gang → class → ...
  │   ├── Engine #2（账号 B）
  │   └── Engine #3（账号 C）
  └── 定时任务
      ├── 拍卖行快照（每小时）
      ├── AI 日报（凌晨）
      └── 数据库维护
```

引擎循环（`fullAutoCycle`）每 30 分钟执行一次完整周期，农场有独立的 15 秒快速轮询。

## 设计决策

1. **分层架构**：routers(薄) → schemas(校验) → services(业务) → models(ORM) → core(基础设施)，每层只依赖下层
2. **引擎隔离**：每账号独立 Engine 实例，解决旧版多账号互斥问题
3. **连接池控制**：禁止 `--reload` 启动（双进程双倍连接池撑爆 PG）
4. **Redis 缓存**：游戏 API 响应缓存 30-600s，减少重复请求
5. **婚姻两套逻辑**：已婚=送花 5 次/天+大色魔，未婚=送花 10 次/天+100 亲密度求婚
6. **道具系统**：通用 inventory.py 层，各业务模块按需调用

## 环境变量（.env）

仓库**不提交 `.env`**。首次使用请复制示例并填好：

```bash
cd backend
cp .env.example .env
```

全部可配置项见 `backend/.env.example`，关键项：

| 变量 | 说明 |
|------|------|
| `PG_HOST/PG_USER/PG_PASSWORD/PG_DATABASE` | PostgreSQL 连接 |
| `REDIS_*` | Redis（会话/缓存/限流/锁） |
| `RABBITMQ_*` + `MQ_PREFIX` | 引擎启停 MQ；本地开发 `MQ_PREFIX=dev_` |
| `JWT_SECRET` | 生产必须改成随机串 |
| `GAME_API_BASE_URL` | 游戏 API 地址 |
| `CRYPTO_KEY` | 账号密码 AES 加密密钥 |
| `TENCENT_CAPTCHA_APP_ID` / `TENCENT_CAPTCHA_AID_ENCRYPTED_TYPE` | 驾驶舱人工登录验证码（腾讯 Turing） |
| `SMTP_*` + `NOTIFY_FALLBACK_EMAIL` | 引擎自动停止邮件通知（QQ邮箱 SMTP） |
| `WECHAT_APPID/SECRET` | 微信小程序登录/绑定（可选） |

> 生产部署在服务器 `/opt/qpet/.env`（docker-compose 的 `env_file`），同样填这份模板。`.env` 不进 git。

## 启动方式

```bash
# 本地开发（先配好 backend/.env）
cd backend
python -m uvicorn app.main:app --host 0.0.0.0 --port 3456

# 生产（Docker，读取 /opt/qpet/.env）
docker compose up -d backend
```

> **禁止加 `--reload`**，原因见设计决策第 3 条（双进程双倍连接池撑爆 PG）。

### 数据库迁移
Docker 入口会自动执行 `alembic upgrade head`；`accounts.needs_login` 等新增列由启动时的幂等 SQL 迁移补齐，无需手工操作。

## 部署

Push 到 `master` 分支触发 **Gitea Actions** 自动构建镜像并重启服务（见 `backend/.gitea/workflows/deploy.yml`）。

> **服务器 `.env` 更新后必须重启后端容器才会生效**（Docker Compose 在容器创建时注入 env）。

## 常见问题

- **登录提示 `CAPTCHA_REQUIRED`**：游戏强制腾讯验证码。到驾驶舱「角色管理 / 角色切换器右键」点「启动」→ 人工过验证码 → 后端用新 token **自动重置 ECDSA 私钥**并启动引擎。
- **接口返回 `AUTOMATION_DETECTED`**：请求缺少浏览器安全头。后端已内置 `build_api_headers()`（含 `sec-fetch-*`），请确保部署的是最新代码。
- **引擎自动停止发信**：401 / 资源不存在 / 连续风控会停止引擎并邮件通知所属人（SMTP 需配置）。

## License

本项目遵循 [Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International](LICENSE)（CC BY-NC-ND 4.0），与 main-server 仓库一致。