22787b3e0a
- Generate full AI-consumable docs (docs/ai/): system overview, architecture, module cheatsheet, API contracts, data model, build guide, decision log, glossary, and open questions (deep tier coverage) - Add PROBLEM_REPORT.md: categorized bug/risk summary - Add DETAILED_CODE_REVIEW.md: full line-by-line review of all 15 backend files, documenting 4 fatal issues, 5 critical deployment bugs, 4 security vulnerabilities, and 6 architecture defects with prioritized fix plan
252 lines
6.8 KiB
Markdown
252 lines
6.8 KiB
Markdown
---
|
||
generated_by: repo-insight
|
||
version: 1
|
||
created: 2026-03-03
|
||
last_updated: 2026-03-03
|
||
source_commit: 0d9dffa
|
||
coverage: deep
|
||
---
|
||
|
||
# 05 — Build, Run & Test
|
||
|
||
## Purpose
|
||
所有构建、运行、测试、部署相关命令及环境变量配置说明。
|
||
|
||
## TL;DR
|
||
- 无 CI/CD 流水线；手动部署到 GCP VM，PM2 管理进程。
|
||
- 后端无构建步骤，直接 `python3 main.py` 或 PM2 启动。
|
||
- 前端标准 Next.js：`npm run dev` / `npm run build` / `npm start`。
|
||
- 测试文件未发现；验证通过 backtest.py 回测和 paper trading 模拟盘进行。
|
||
- 本地开发：前端 `/api/*` 通过 Next.js rewrite 代理到 `http://127.0.0.1:4332`（即 uvicorn 端口）。
|
||
- 数据库 schema 自动在启动时初始化（`init_schema()`），无独立 migration 工具。
|
||
|
||
## Canonical Facts
|
||
|
||
### 环境要求
|
||
| 组件 | 要求 |
|
||
|------|------|
|
||
| Python | 3.10+（使用 `list[dict]` 等 3.10 语法） |
|
||
| Node.js | 推荐 20.x（package.json `@types/node: ^20`） |
|
||
| PostgreSQL | 本地实例 + Cloud SQL（`10.106.0.3`） |
|
||
| PM2 | 用于进程管理（需全局安装） |
|
||
|
||
### 后端依赖安装
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
# requirements.txt 内容：fastapi, uvicorn, httpx, python-dotenv, psutil
|
||
# 实际还需要（从源码 import 推断）：
|
||
# asyncpg, psycopg2-binary, aiohttp, websockets
|
||
```
|
||
|
||
> [inference] `requirements.txt` 内容不完整，仅列出 5 个包，但源码 import 了 `asyncpg`、`psycopg2`、`aiohttp` 等。运行前需确认完整依赖已安装。
|
||
|
||
### 后端启动
|
||
|
||
#### 单进程开发模式
|
||
```bash
|
||
cd backend
|
||
|
||
# FastAPI HTTP API（默认端口 4332，从 next.config.ts 推断）
|
||
uvicorn main:app --host 0.0.0.0 --port 4332 --reload
|
||
|
||
# 信号引擎（独立进程）
|
||
python3 signal_engine.py
|
||
|
||
# aggTrades 收集器
|
||
python3 agg_trades_collector.py
|
||
|
||
# 市场数据收集器
|
||
python3 market_data_collector.py
|
||
|
||
# 清算数据收集器
|
||
python3 liquidation_collector.py
|
||
|
||
# 实盘执行器
|
||
TRADE_ENV=testnet python3 live_executor.py
|
||
|
||
# 风控模块
|
||
TRADE_ENV=testnet python3 risk_guard.py
|
||
|
||
# 信号推送（Discord）
|
||
python3 signal_pusher.py
|
||
```
|
||
|
||
#### PM2 生产模式
|
||
```bash
|
||
cd backend
|
||
|
||
# 使用 ecosystem 配置（目前只定义了 arb-dev-signal）
|
||
pm2 start ecosystem.dev.config.js
|
||
|
||
# 查看进程状态
|
||
pm2 status
|
||
|
||
# 查看日志
|
||
pm2 logs arb-dev-signal
|
||
|
||
# 停止所有
|
||
pm2 stop all
|
||
|
||
# 重启
|
||
pm2 restart all
|
||
```
|
||
|
||
> [inference] `ecosystem.dev.config.js` 当前只配置了 `signal_engine.py`，其他进程需手动启动或添加到 PM2 配置。
|
||
|
||
### 环境变量配置
|
||
|
||
#### 数据库（所有后端进程共用）
|
||
```bash
|
||
export PG_HOST=127.0.0.1 # 本地 PG
|
||
export PG_PORT=5432
|
||
export PG_DB=arb_engine
|
||
export PG_USER=arb
|
||
export PG_PASS=arb_engine_2026 # 测试网默认，生产需覆盖
|
||
|
||
export CLOUD_PG_HOST=10.106.0.3 # Cloud SQL
|
||
export CLOUD_PG_ENABLED=true
|
||
```
|
||
|
||
#### 认证
|
||
```bash
|
||
export JWT_SECRET=<> # 生产环境必填，长度 ≥32
|
||
# 测试网有默认值 "arb-engine-jwt-secret-v2-2026"，生产环境 TRADE_ENV != testnet 时必须设置
|
||
```
|
||
|
||
#### 交易环境
|
||
```bash
|
||
export TRADE_ENV=testnet # 或 production
|
||
export LIVE_STRATEGIES='["v52_8signals"]'
|
||
export RISK_PER_TRADE_USD=2 # 每笔风险 USD
|
||
export MAX_POSITIONS=4 # 最大同时持仓数
|
||
```
|
||
|
||
#### 实盘专用（live_executor + risk_guard）
|
||
```bash
|
||
export DB_HOST=10.106.0.3
|
||
export DB_PASSWORD=<生产密码>
|
||
export DB_NAME=arb_engine
|
||
export DB_USER=arb
|
||
|
||
# 币安 API Key（需在 Binance 配置）
|
||
export BINANCE_API_KEY=<key>
|
||
export BINANCE_API_SECRET=<secret>
|
||
```
|
||
|
||
#### 前端
|
||
```bash
|
||
# .env.local 或部署环境
|
||
NEXT_PUBLIC_API_URL= # 留空=同源，生产时设为 https://arb.zhouyangclaw.com
|
||
```
|
||
|
||
### 数据库初始化
|
||
```bash
|
||
# schema 在 FastAPI 启动时自动创建（init_schema + ensure_auth_tables）
|
||
# 手动初始化：
|
||
cd backend
|
||
python3 -c "from db import init_schema; init_schema()"
|
||
|
||
# 分区维护（自动在 init_schema 内调用）：
|
||
python3 -c "from db import ensure_partitions; ensure_partitions()"
|
||
```
|
||
|
||
### 前端构建与启动
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
|
||
# 开发模式（热重载，端口 3000）
|
||
npm run dev
|
||
|
||
# 生产构建
|
||
npm run build
|
||
npm start
|
||
|
||
# Lint
|
||
npm run lint
|
||
```
|
||
|
||
### 前端 API 代理配置
|
||
`frontend/next.config.ts` 将 `/api/*` 代理到 `http://127.0.0.1:4332`。
|
||
- 本地开发时 uvicorn 需监听 **4332 端口**。
|
||
- 生产部署时通过 `NEXT_PUBLIC_API_URL` 或 nginx 反向代理处理跨域。
|
||
|
||
### 回测（离线验证）
|
||
```bash
|
||
cd backend
|
||
|
||
# 指定天数回测
|
||
python3 backtest.py --symbol BTCUSDT --days 20
|
||
|
||
# 指定日期范围回测
|
||
python3 backtest.py --symbol BTCUSDT --start 2026-02-08 --end 2026-02-28
|
||
|
||
# 输出：胜率、盈亏比、夏普比率、最大回撤等统计
|
||
```
|
||
|
||
### 模拟盘（Paper Trading）
|
||
通过 `paper_config.json` 控制：
|
||
```json
|
||
{
|
||
"enabled": true,
|
||
"enabled_strategies": ["v52_8signals"],
|
||
"initial_balance": 10000,
|
||
"risk_per_trade": 0.02,
|
||
"max_positions": 4
|
||
}
|
||
```
|
||
修改后 signal_engine 下次循环自动读取（无需重启）。
|
||
|
||
监控模拟盘：
|
||
```bash
|
||
cd backend
|
||
python3 paper_monitor.py
|
||
```
|
||
|
||
### 管理员 CLI
|
||
```bash
|
||
cd backend
|
||
python3 admin_cli.py gen_invite [count] [max_uses]
|
||
python3 admin_cli.py list_invites
|
||
python3 admin_cli.py disable_invite <code>
|
||
python3 admin_cli.py list_users
|
||
python3 admin_cli.py ban_user <user_id>
|
||
python3 admin_cli.py unban_user <user_id>
|
||
python3 admin_cli.py set_admin <user_id>
|
||
python3 admin_cli.py usage
|
||
```
|
||
|
||
### 日志位置
|
||
| 进程 | 日志文件 |
|
||
|------|---------|
|
||
| signal_engine | `signal-engine.log`（项目根目录） |
|
||
| risk_guard | `backend/logs/risk_guard.log`（RotatingFileHandler，10MB×5） |
|
||
| 其他进程 | stdout / PM2 logs |
|
||
|
||
### 无测试框架
|
||
项目中未发现 `pytest`、`unittest` 或任何测试文件。验证策略依赖：
|
||
1. **回测**：`backtest.py` 逐 tick 回放历史数据
|
||
2. **模拟盘**：paper trading 实时验证信号质量
|
||
3. **手动测试**：前端页面人工验证
|
||
|
||
## Interfaces / Dependencies
|
||
- uvicorn 端口：**4332**（从 `next.config.ts` 推断）
|
||
- 前端开发端口：**3000**（Next.js 默认）
|
||
- CORS 允许 `localhost:3000` 和 `localhost:3001`
|
||
|
||
## Unknowns & Risks
|
||
- [inference] uvicorn 端口 4332 从 `next.config.ts` 推断，未在 `main.py` 或启动脚本中显式确认。
|
||
- [inference] `requirements.txt` 不完整，实际依赖需从源码 import 语句归纳。
|
||
- [unknown] 生产部署的 nginx 配置未在仓库中。
|
||
- [risk] 无自动化测试，代码变更风险完全依赖人工回测和 paper trading 验证。
|
||
|
||
## Source Refs
|
||
- `frontend/next.config.ts` — API rewrite 代理到 `127.0.0.1:4332`
|
||
- `backend/ecosystem.dev.config.js` — PM2 配置（仅 signal_engine）
|
||
- `backend/requirements.txt` — 后端依赖（不完整）
|
||
- `backend/backtest.py:1-13` — 回测用法说明
|
||
- `backend/paper_config.json` — 模拟盘配置
|
||
- `backend/admin_cli.py:88` — CLI usage 函数
|
||
- `backend/risk_guard.py:81-82` — 日志 RotatingFileHandler 配置
|