# 量化交易系统 - 服务使用说明文档

**最后更新**: 2026-03-29  
**维护者**: 姜维（后勤总督）  
**数据负责人**: 赵云将军  
**状态**: ✅ 所有服务已就绪，可开始测试

## ⚠️ 重要说明：数据来源
当前回测服务使用 **akshare实时数据**，由赵云将军负责数据配置和维护。策略回测时直接从akshare API获取数据，财务数据（ROE、PE、PB等）需要单独获取接口。

如需完整历史数据、财务数据或数据更新服务，请与赵云将军协调。

---

## 📊 服务总览

### 🐳 NAS Docker容器服务
| 服务名称 | 端口 | 访问地址 | 用途 | 状态 |
|---------|------|----------|------|------|
| **Webtrader Backtest API** | 8088 | `http://192.168.2.154:8088` | 策略回测API接口 | ✅ 运行中 |
| **VS Code Server** | 8080 | `http://192.168.2.154:8080` | Web版VS Code开发环境 | ✅ 已配置 |
| **Jupyter Notebook** | 8888 | `http://192.168.2.154:8888` | 交互式Python数据分析 | ✅ 已配置 |
| **SSH访问** | 2222 | `ssh -p 2222 vnpy@192.168.2.154` | 容器命令行访问 | ✅ 已配置 |
| **端口8000服务** | 8000 | `http://192.168.2.154:8000` | 待确认的服务 | ✅ 端口开放 |

### 🔧 本地自动化服务
| 服务名称 | 状态 | 功能 |
|---------|------|------|
| **文件监控服务** | ✅ 运行中 | 自动监听策略文件变化，触发部署回测 |
| **Git Webhook服务** | ✅ 运行中 | Git推送后自动触发全流程部署回测 |

---

## 🚀 快速开始

### 1. 访问Webtrader Backtest API

**Swagger UI文档**: http://192.168.2.154:8088/docs

**API端点**:
- `POST /api/backtest/run` - 执行策略回测
- `GET /api/backtest/status` - 获取回测状态
- `GET /api/backtest/results/{task_id}` - 获取回测结果

**示例调用**:
```python
import requests

api_url = "http://192.168.2.154:8088/api/backtest/run"
payload = {
    "strategy_name": "guanyu_value_tech_strategy",
    "start_date": "2023-01-01",
    "end_date": "2023-12-31",
    "initial_capital": 1000000,
    "parameters": {
        "risk_profile": "BALANCED",
        "pe_max": 25,
        "pb_max": 2.5,
        "roe_min": 10.0
    }
}

response = requests.post(api_url, json=payload)
print(response.json())
```

### 2. 使用开发环境

**VS Code Server**:
- 地址: http://192.168.2.154:8080
- 用户名: vnpy
- 密码: sanguo123
- 功能: 完整的Web版VS Code，支持Python开发、Git等

**Jupyter Notebook**:
- 地址: http://192.168.2.154:8888
- 功能: 交互式数据分析和策略开发

### 3. 命令行访问
```bash
ssh -p 2222 vnpy@192.168.2.154
# 密码: sanguo123
```

---

## 📋 策略开发工作流

### 工作流示意图
```
[本地开发] → [Git推送] → [自动部署] → [NAS回测] → [结果同步]
     ↓          ↓          ↓          ↓          ↓
   VS Code    Webhook    CI/CD    Docker    本地目录
```

### 详细步骤

#### 1. 开发策略
```bash
# 本地开发
cd /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live
# 在strategies目录下创建策略文件
```

#### 2. 触发自动化回测
**方法一：文件监控（实时）**
- 修改策略文件 → 自动触发回测
- 结果保存到策略目录下的`backtest_results/`

**方法二：Git推送（批量）**
```bash
git add .
git commit -m "更新策略"
git push origin main
# 自动触发全流程部署回测
```

**方法三：手动脚本**
```bash
cd /Users/chufeng/.openclaw/workspace-jiangwei
./sync_and_redeploy.sh --strategy strategies.pangtong-value.strategy_A
```

#### 3. 查看结果
回测结果自动保存到：
```
sanguo_quant_live/strategies/[策略路径]/backtest_results/
├── [策略名]_[日期]_[时间].txt    # 文本结果
└── [策略名]_[日期]_[时间].png    # 图表结果
```

---

## 🛠️ 管理工具

### 本地自动化脚本
| 脚本名称 | 用途 | 使用方法 |
|---------|------|----------|
| `start_auto_watcher.sh` | 启动文件监控服务 | `./start_auto_watcher.sh {start|stop|status|restart}` |
| `start_webhook.sh` | 启动Git Webhook服务 | `./start_webhook.sh {start|stop|status|restart}` |
| `sync_and_redeploy.sh` | 同步并重新部署 | `./sync_and_redeploy.sh --strategy [策略路径]` |
| `sanguo_nas_ci_cd.sh` | NAS CI/CD流程 | `./sanguo_nas_ci_cd.sh` |
| `nas_manager.sh` | NAS挂载管理 | `./nas_manager.sh {status|mount|umount|restart|logs}` |

### 将军专用脚本
**张飞（将军）使用**:
```bash
./sync_and_run_backtest.sh --strategy strategies.your-strategy
```
- 一键同步策略到NAS
- 自动执行回测
- 同步结果回本地
- 不需要重启Docker

**姜维（后勤总督）使用**:
```bash
./sanguo_nas_ci_cd.sh
```
- 重建Docker容器
- 更新框架和依赖
- 需要重启服务

---

## 📊 已测试的策略

### 1. 关羽价值技术策略
- **文件**: `strategies/guanyu_value_tech_strategy.py`
- **类型**: 价值+技术综合选股
- **数据源**: akshare（实时获取）
- **状态**: ✅ 已成功测试
- **回测结果**: 
  - 价值筛选: 5,830只 → 640只 (11%通过率)
  - 技术筛选: 0只通过 (当前市场环境)
  - 策略框架: 运行正常
- **数据说明**: 该策略直接调用akshare API获取实时数据，财务数据（ROE等）需要单独获取

### ⚠️ 数据来源说明
当前回测服务使用 **akshare实时数据**，由赵云将军负责数据配置和维护。如需完整财务数据或历史数据，请与赵云将军协调。

### 2. 其他可用策略
- `strategies/pure-breakout-20260327/` - 突破策略
- `strategies/structured-dynamic-factors-20260327/` - 结构化动态因子

---

## 🔧 故障排除

### 常见问题

#### 1. NAS服务无法访问
```bash
# 检查网络连接
ping 192.168.2.154

# 检查端口
nc -zv 192.168.2.154 8088

# 检查Docker容器状态
ssh admin@192.168.2.154 "docker ps"
```

#### 2. API调用失败
```bash
# 检查API服务状态
curl http://192.168.2.154:8088/health

# 查看容器日志
ssh admin@192.168.2.154 "docker logs sanguo_vnpy"
```

#### 3. 自动化服务未运行
```bash
# 检查本地服务状态
cd /Users/chufeng/.openclaw/workspace-jiangwei
./start_auto_watcher.sh status
./start_webhook.sh status

# 重启服务
./start_auto_watcher.sh restart
./start_webhook.sh restart
```

#### 4. 策略回测无结果
- 检查策略文件路径是否正确
- 检查策略是否继承自正确的基类
- 查看容器内日志：`docker exec sanguo_vnpy cat /app/logs/backtest.log`

#### 5. 数据获取失败
- 检查网络连接：akshare需要访问外部API
- 检查akshare版本：容器中可能未安装或版本不兼容
- 联系赵云将军：确认数据源配置和权限
- 查看数据获取日志：检查akshare调用是否成功

### 日志位置
| 服务 | 日志文件 |
|------|----------|
| 文件监控服务 | `auto_watcher.log` |
| Git Webhook服务 | `webhook.log` |
| NAS Docker容器 | `/app/logs/`目录 |
| 本地环境 | `logs/`目录 |

---

## 🎯 下一步计划

### 短期目标（1-2周）
1. ✅ 完善所有服务文档
2. 🔄 测试更多策略类型
3. 🔄 优化API性能
4. 🔄 增加实时监控仪表板

### 中期目标（1个月）
1. 🔄 集成更多数据源
2. 🔄 开发策略模板库
3. 🔄 实现策略回测对比
4. 🔄 增加风险控制模块

### 长期目标（3个月）
1. 🔄 实盘交易接口集成
2. 🔄 多用户权限管理
3. 🔄 策略市场平台
4. 🔄 机器学习策略开发

---

## 📞 技术支持

### 遇到问题？
1. **查看日志**: 相关日志文件通常包含详细错误信息
2. **检查状态**: 使用管理脚本检查服务状态
3. **联系姜维**: 后勤总督随时待命

### 紧急联系方式
- **文件监控服务异常**: `./start_auto_watcher.sh restart`
- **API服务异常**: `ssh admin@192.168.2.154 "docker restart sanguo_vnpy"`
- **NAS连接异常**: `./nas_manager.sh restart`

---

**最后提醒**: 所有服务已自动化，主公和各位将军可专注于策略开发，后勤保障交给我！🚛

**姜维 - 三军后勤总督**
*恪尽职守，守护粮道，确保环境安稳*