arbitrage-engine/docs/ai/05-build-run-test.md

generated_by	version	created	last_updated	source_commit	coverage
repo-insight	1	2026-03-03	2026-03-03	0d9dffa	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	用于进程管理（需全局安装）

后端依赖安装

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 等。运行前需确认完整依赖已安装。

后端启动

单进程开发模式

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 生产模式

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 配置。

环境变量配置

数据库（所有后端进程共用）

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

认证

export JWT_SECRET=<>  # 生产环境必填，长度 ≥32
# 测试网有默认值 "arb-engine-jwt-secret-v2-2026"，生产环境 TRADE_ENV != testnet 时必须设置

交易环境

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）

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>

前端

# .env.local 或部署环境
NEXT_PUBLIC_API_URL=              # 留空=同源，生产时设为 https://arb.zhouyangclaw.com

数据库初始化

# 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()"

前端构建与启动

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 反向代理处理跨域。

回测（离线验证）

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 控制：

{
  "enabled": true,
  "enabled_strategies": ["v52_8signals"],
  "initial_balance": 10000,
  "risk_per_trade": 0.02,
  "max_positions": 4
}

修改后 signal_engine 下次循环自动读取（无需重启）。

监控模拟盘：

cd backend
python3 paper_monitor.py

管理员 CLI

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 配置