sanguo_vnpy_v2/README.md

# Sanguo VeighNa 量化交易平台 v2.0

> ⚠️ **本 README 内容截至 2026-07，架构已大幅迁移**（Web 入口=sanguo_api 单进程 8000+Vue 前端、三环境部署、因子体系/流水线/监控均已上线）。当前权威文档：
> - 部署/运维：`docs/deployment/vps-production-runbook.md`
> - 发布/晋升：`docs/three-env-code-promote.md`
> - Agent 工作入口：`.claude/CLAUDE.md`
>
> 下方内容仅作历史参考，按其操作（端口/凭据/安装步骤）会失败。

基于 VeighNa 4.4.0 的二次开发量化交易平台，支持 Web 界面和 Docker 容器化部署。

## 特性

- 🚀 **基于 VeighNa 4.4.0** - 最新稳定版本
- 🌐 **Web 界面** - FastAPI + WebSocket 实时数据推送
- 🐳 **Docker 部署** - 支持 Synology NAS 等容器环境
- 📊 **完整功能** - 行情订阅、交易下单、策略管理
- 🔐 **安全认证** - JWT Token 认证机制
- 📡 **实时推送** - WebSocket 行情、成交、持仓实时更新

## 项目结构

```
sanguo_vnpy_v2/
├── vnpy_v4.4.0/              # VeighNa 上游源码
├── sanguo_trader/             # 核心交易模块
├── sanguo_research/           # 量化投研模块
├── sanguo_data/               # 数据管理模块
├── sanguo_common/             # 公共模块
├── sanguo_web/                # Web 服务模块
│   ├── api/                   # REST API
│   ├── websocket/             # WebSocket 服务
│   └── services/              # 业务服务
├── docker/                    # Docker 配置
│   ├── Dockerfile             # 镜像构建
│   ├── docker-compose.yml     # 容器编排
│   ├── entrypoint.sh          # 启动脚本
│   └── deploy-synology.sh     # NAS 部署脚本
├── tests/                     # 测试代码
├── docs/                      # 文档
└── examples/                  # 示例代码
```

## 快速开始

### 方式 1: Docker 部署（推荐）

#### 本地开发

```bash
# 构建镜像
cd docker
docker-compose build

# 启动服务
docker-compose up -d

# 访问 Web 界面
open http://localhost:8000
```

#### Synology NAS 部署

1. 开启 SSH 服务
2. 上传部署包到 NAS
3. 运行部署脚本：

```bash
cd /volume1/docker/containers/sanguo_vnpy_v2/docker
sudo bash deploy-synology.sh
```

详细说明请参考 [Synology NAS 部署指南](docs/deployment/synology-nas.md)

### 方式 2: 本地开发

#### 环境要求

- Python 3.10+
- 推荐 Python 3.13

#### 安装步骤

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# 安装依赖
pip install -r requirements/base.txt

# 启动 Web 服务
python run_web.py
```

#### Web 服务启动

```bash
# 开发模式（端口 8002）
python run_web.py

# 生产模式
uvicorn sanguo_web.api:app --host 0.0.0.0 --port 8000 --workers 2
```

> ⚠️ **2026-10-01 勘误（audit/20261001_docs_audit/ P0-1）**：上方「生产模式」命令启动的是 **`sanguo_web` legacy 平行后端**——已退役、生产不部署、自带硬编码密钥/默认口令/CORS 全开（架构审计 P0-3），**勿按此启动**。现行生产入口=`run_web.py`（`sanguo_api.main:create_app` 工厂，单进程 :8000，NAS 容器与 VPS sanguo-api 同款）。

## API 文档

启动服务后访问：

- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`

## 认证

> ⚠️ 2026-10-01 勘误：本节为 07 月历史内容。现行认证=`sanguo_api` JWT（凭据在 `config/backtest.yaml` auth 段 bcrypt hash，**不入库不写文档**）；`sanguo_web` 的 admin/admin123 默认口令随该后端一并退役。

## WebSocket 连接

```javascript
// 连接 WebSocket
const ws = new WebSocket('ws://localhost:8080');

// 订阅行情
ws.send(JSON.stringify({
    type: 'subscribe',
    data: { subscription: ['tick', 'order', 'trade'] }
}));

// 接收消息
ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    console.log('Received:', message);
};
```

## 测试

```bash
# 运行 API 测试
pytest tests/test_api.py -v

# 运行 WebSocket 测试
python tests/test_websocket.py

# 运行所有测试
pytest tests/ -v
```

## 开发指南

详细开发指南请查看：

- [文档中心索引](docs/README.md)
- [开发文档](docs/development.md)

## 主要功能模块

### 1. 认证系统 (`/api/v1/auth`)
- 用户登录/登出
- Token 验证
- 用户信息获取

### 2. 网关管理 (`/api/v1/gateway`)
- 可用网关列表
- 网关连接/断开
- 网关配置管理

### 3. 行情数据 (`/api/v1/market`)
- 实时行情查询
- 行情订阅/取消订阅
- 合约信息查询

### 4. 交易功能 (`/api/v1/trading`)
- 账户信息查询
- 持仓查询
- 订单管理（下单、撤单）
- 成交记录查询

### 5. 策略管理 (`/api/v1/strategy`)
- 策略列表
- 策略启动/停止
- 策略参数配置

## 环境变量

主要环境变量（见 `docker/.env.example`）：

```env
# 数据目录
DATA_DIR=/volume1/docker/stock/sanguo_vnpy

# 端口配置
HTTP_PORT=8000
WS_PORT=8080

# 时区
TZ=Asia/Shanghai

# JWT 密钥
JWT_SECRET_KEY=your-secret-key-here

# 数据库
DB_TYPE=sqlite
DB_PATH=/app/data/vnpy.db
```

## 分支策略

- `master` - 主分支，保持稳定可部署
- `develop` - 开发分支，日常开发合并
- `feature/*` - 功能分支
- `hotfix/*` - 热修复分支

## 版本历史

查看 [CHANGELOG.md](CHANGELOG.md)

## 技术栈

- **后端框架**: FastAPI 0.100+
- **WebSocket**: websockets 12.0+
- **数据库**: SQLite (可扩展 PostgreSQL)
- **缓存**: Redis 7+
- **容器**: Docker + Docker Compose
- **认证**: JWT (python-jose)
- **测试**: pytest + httpx

## 许可证

MIT License

## 致谢

基于 [VeighNa](https://github.com/vnpy/vnpy) 框架开发

## 联系方式

- 问题反馈: GitHub Issues
- 文档: `docs/` 目录