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