claude_dev
918bbed0fc
- 修复 deps.py 中 get_vn_service 的引用错误 (vn_service.vn_service -> vn_service) - 移除登录页面上的明文密码提示 - 改进前端错误处理，避免数据加载失败导致登录显示错误
241 lines
4.9 KiB
Markdown
241 lines
4.9 KiB
Markdown
# Sanguo VeighNa 量化交易平台 v2.0
|
||
|
||
基于 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
|
||
```
|
||
|
||
## API 文档
|
||
|
||
启动服务后访问：
|
||
|
||
- Swagger UI: `http://localhost:8000/docs`
|
||
- ReDoc: `http://localhost:8000/redoc`
|
||
|
||
## 认证
|
||
|
||
默认登录凭据：
|
||
|
||
- **用户名**: `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/development.md)
|
||
- [API 设计文档](docs/api/README.md)
|
||
- [部署文档](docs/deployment/README.md)
|
||
- [用户指南](docs/user_guide/README.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/` 目录
|