# sanguo_vnpy NAS 部署指南

## 架构概述

严格遵循vnpy官方基础架构，不修改核心代码，只做部署层适配：

- **每个用户一对独立进程**：交易进程(RPC服务端) + Web进程(FastAPI)
- **彻底隔离**：每个用户独立数据目录、独立端口，互不干扰
- **统一入口**：Nginx反向代理按路径分发
- **稳定运维**：systemd管理进程，开机自启，崩溃自动恢复

## 目录结构

```
sanguo_vnpy/                  # 项目根目录（在NAS上对应 /mnt/nas-volume/sanguo_vnpy）
├── README-NAS-DEPLOY.md      # 本文件
├── jiangwei-platform/         # 平台基础设施（姜维维护）
│   └── deploy/
│       └── nas/
│           ├── create-user.sh           # 创建新用户脚本
│           ├── create-all-users.sh      # 创建所有预设用户
│           ├── generate-all-configs.sh  # 生成所有配置
│           ├── port-allocation.md      # 端口分配表
│           └── templates/              # 配置模板
├── config/                   # 全局配置
│   ├── systemd/              # systemd服务文件
│   └── nginx/                # Nginx location配置片段
├── data/                     # 全局共享数据
│   └── history/              # 共享历史行情数据（只读）
└── users/                    # 用户目录
    ├── zhugeliang/          # 诸葛亮
    │   ├── data/            # 个人数据
    │   ├── logs/            # 日志
    │   ├── strategies/      # 个人策略
    │   ├── start_trade.py  # 交易进程启动脚本
    │   └── start_web.py    # Web进程启动脚本
    ├── pangtong/
    └── ...
```

## 端口分配

| 用户 | 编号 | RPC请求 | RPC订阅 | Web端口 | Nginx路径 | 状态 |
|------|------|---------|---------|---------|-----------|------|
| 诸葛亮 | 1 | 2010 | 2011 | 8001 | `/zhugeliang/` | 已创建 |
| 庞统 | 2 | 2020 | 2021 | 8002 | `/pangtong/` | 已创建 |
| 司马懿 | 3 | 2030 | 2031 | 8003 | `/simayi/` | 已创建 |
| 张飞 | 4 | 2040 | 2041 | 8004 | `/zhangfei/` | 已创建 |
| 关羽 | 5 | 2050 | 2051 | 8005 | `/guanyu/` | 已创建 |
| 赵云 | 6 | 2060 | 2061 | 8006 | `/zhaoyun/` | 已创建 |
| 姜维 | 7 | 2070 | 2071 | 8007 | `/jiangwei/` | 已创建 |

## 部署到NAS步骤

### 1. 克隆项目到NAS

```bash
git clone <repo-url> /mnt/nas-volume/sanguo_vnpy
cd /mnt/nas-volume/sanguo_vnpy
```

### 2. 安装依赖

```bash
pip install vnpy vnpy_webtrader
# 安装需要的gateway和app
# pip install vnpy_ctp vnpy_ctastrategy ...
```

### 3. 启用systemd服务

```bash
# 复制服务文件
cp config/systemd/*.service /etc/systemd/system/

# 重载systemd
systemctl daemon-reload

# 启用并启动所有服务
for user in zhugeliang pangtong simayi zhangfei guanyu zhaoyun jiangwei; do
  systemctl enable --now sanguo-trade-$user
  systemctl enable --now sanguo-web-$user
done
```

### 4. 配置Nginx

在Nginx主配置中包含所有用户配置：

```nginx
server {
    listen 443 ssl;
    server_name your-nas-domain.com;

    # SSL证书配置...

    # 包含所有用户配置
    include /mnt/nas-volume/sanguo_vnpy/config/nginx/*.conf;
}
```

然后重载Nginx：

```bash
nginx -t && systemctl reload nginx
```

### 5. 访问

- https://your-nas-domain.com/zhugeliang/ → 诸葛亮
- https://your-nas-domain.com/zhangfei/ → 张飞
- 依此类推...

## 添加新用户

```bash
cd /mnt/nas-volume/sanguo_vnpy/jiangwei-platform/deploy/nas
./create-user.sh <username> <user-id>
```

然后按照脚本输出的后续步骤操作。

## 维护命令

### 查看状态

```bash
# 查看某个用户进程状态
systemctl status sanguo-trade-zhugeliang
systemctl status sanguo-web-zhugeliang

# 查看日志
journalctl -u sanguo-trade-zhugeliang -f
```

### 重启进程

```bash
systemctl restart sanguo-trade-zhugeliang
systemctl restart sanguo-web-zhugeliang
```

### 停止进程（不影响他人）

```bash
systemctl stop sanguo-trade-zhugeliang
systemctl stop sanguo-web-zhugeliang
```

## 设计原则

1. ✅ **不修改vnpy核心代码**：完全使用官方原生架构
2. ✅ **彻底隔离**：一人一个进程，一人一个数据目录，互不干扰
3. ✅ **易于维护**：可以独立启停单个用户进程，不影响全局
4. ✅ **自动配置**：脚本自动生成所有配置，减少手工出错
5. ✅ **保留已有功能**：项目原有的任务分配、agent协作完全不受影响

## 故障排查

1. **Web打不开** → 检查systemd状态 `systemctl status sanguo-web-<user>`
2. **无法连接交易进程** → 检查交易进程是否启动 `systemctl status sanguo-trade-<user>`
3. **端口冲突** → 检查 `port-allocation.md` 确认端口分配
4. **WebSocket连不上** → 检查Nginx配置是否包含了Upgrade连接头

---

*维护：姜维 伯约*
*更新：2026-03-31*