# Synology NAS 部署指南

本指南介绍如何在 Synology NAS 上部署 Sanguo VeighNa 量化交易平台。

## 目录

- [前置要求](#前置要求)
- [快速开始](#快速开始)
- [详细步骤](#详细步骤)
- [配置说明](#配置说明)
- [访问界面](#访问界面)
- [数据备份](#数据备份)
- [故障排除](#故障排除)
- [升级指南](#升级指南)

---

## 前置要求

### 硬件要求

- **Synology NAS**：DSM 7.x 或更高版本
- **内存**：至少 2GB 可用内存（推荐 4GB+）
- **存储**：至少 10GB 可用存储空间（用于数据和日志）

### 软件要求

- **Container Manager**（或 Docker 套件）
- SSH 访问权限（用于高级操作）
- 文本编辑器（如 Text Editor、vim）

### 网络要求

- 固定 IP 地址（推荐）
- 或使用 DDNS 服务
- 开放相应端口（默认 8000）

---

## 快速开始

### 1. 开启 SSH 访问

在 DSM 控制面板中：
1. 进入 **控制面板** > **终端机和 SNMP**
2. 勾选 **启用 SSH 服务**
3. 端口使用默认 22
4. 点击 **应用**

### 2. SSH 登录 NAS

```bash
ssh admin@your-nas-ip
# 或
ssh your-username@your-nas-ip
```

### 3. 创建数据目录

```bash
# 创建主目录
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy

# 创建子目录
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy/{data,logs,config,temp,redis,nginx}
```

### 4. 上传项目文件

在本地电脑上执行：

```bash
# 压缩项目文件
tar czf sanguo_vnpy_v2.tar.gz sanguo_vnpy_v2/

# 上传到 NAS
scp sanguo_vnpy_v2.tar.gz admin@your-nas-ip:/tmp/

# 或使用 rsync
rsync -avz sanguo_vnpy_v2/ admin@your-nas-ip:/volume1/docker/containers/sanguo_vnpy_v2/
```

在 NAS 上解压：

```bash
# SSH 登录后执行
cd /volume1/docker/containers/
sudo tar xzf /tmp/sanguo_vnpy_v2.tar.gz
```

### 5. 配置环境变量

```bash
cd /volume1/docker/containers/sanguo_vnpy_v2/docker
sudo cp .env.example .env
sudo vi .env  # 或使用其他编辑器
```

关键配置项：

```env
# 数据目录 - 确保 此目录存在
DATA_DIR=/volume1/docker/stock/sanguo_vnpy

# 端口配置 - 根据需要修改
HTTP_PORT=8000
WS_PORT=8080

# 时区
TZ=Asia/Shanghai

# JWT 密钥 - 请修改为随机字符串
JWT_SECRET_KEY=your-random-secret-key-here
```

### 6. 启动服务

```bash
cd /volume1/docker/containers/sanguo_vnpy_v2/docker
sudo docker-compose up -d
```

### 7. 检查运行状态

```bash
# 查看容器状态
sudo docker-compose ps

# 查看日志
sudo docker-compose logs -f vnpy
```

---

## 详细步骤

### 步骤 1: 准备数据目录

创建完整的目录结构：

```bash
# 主目录
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy

# 数据子目录
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy/data      # 数据库和数据文件
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy/logs      # 运行日志
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy/config    # 配置文件
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy/temp      # 临时文件
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy/redis     # Redis 持久化
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy/nginx     # Nginx 相关
sudo mkdir -p /volume1/docker/stock/sanguo_vnpy/nginx/ssl # SSL 证书

# 设置权限
sudo chmod -R 755 /volume1/docker/stock/sanguo_vnpy
```

### 步骤 2: 配置 Docker Compose

编辑 `.env` 文件：

```bash
cd /volume1/docker/containers/sanguo_vnpy_v2/docker
sudo cp .env.example .env
sudo vi .env
```

完整配置示例：

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

# ============================================
# 端口配置
# ============================================
HTTP_PORT=8000
WS_PORT=8080
NGINX_HTTP_PORT=80
NGINX_HTTPS_PORT=443

# ============================================
# 时区配置
# ============================================
TZ=Asia/Shanghai

# ============================================
# VeighNa 配置
# ============================================
VNPY_LOG_LEVEL=INFO
VNPY_LOG_FILE=/app/logs/vnpy.log

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

# ============================================
# Web 服务配置
# ============================================
WEB_HOST=0.0.0.0
WEB_PORT=8000
WEB_WORKERS=2

# ============================================
# 安全配置
# ============================================
JWT_SECRET_KEY=please-change-this-to-a-secure-random-key
SESSION_TIMEOUT=3600

# ============================================
# 资源限制
# ============================================
VNPY_CPU_LIMIT=2.0
VNPY_MEMORY_LIMIT=2G
```

### 步骤 3: 构建和启动

```bash
# 构建镜像（首次运行）
sudo docker-compose build

# 启动服务
sudo docker-compose up -d

# 查看启动日志
sudo docker-compose logs -f
```

### 步骤 4: 验证部署

```bash
# 检查容器状态
sudo docker-compose ps

# 应该看到类似输出：
# NAME             STATUS          PORTS
# sanguo-vnpy      Up              0.0.0.0:8000->8000/tcp
# sanguo-redis     Up              6379/tcp

# 检查日志
sudo docker-compose logs vnpy | tail -20

# 进入容器检查
sudo docker-compose exec vnpy bash
ls -la /app/data
exit
```

---

## 配置说明

### 端口配置

| 端口 | 用途 | 说明 |
|------|------|------|
| 8000 | HTTP API | Web 界面和 REST API |
| 8080 | WebSocket | 实时数据推送 |
| 80 | Nginx HTTP | 反向代理（可选） |
| 443 | Nginx HTTPS | SSL 反向代理（可选） |

### 目录映射

| 容器路径 | 宿主机路径 | 说明 |
|----------|------------|------|
| /app/data | `{DATA_DIR}/data` | 数据库和数据文件 |
| /app/logs | `{DATA_DIR}/logs` | 运行日志 |
| /app/config | `{DATA_DIR}/config` | 配置文件 |
| /app/temp | `{DATA_DIR}/temp` | 临时文件 |
| /data | `{DATA_DIR}/redis` | Redis 持久化数据 |

### 资源限制

默认资源限制（可在 `.env` 中调整）：

| 服务 | CPU 限制 | 内存限制 |
|------|----------|----------|
| vnpy | 2.0 | 2G |
| redis | 0.5 | 256M |
| nginx | 0.5 | 256M |

---

## 访问界面

### Web 界面

启动成功后，可以通过以下地址访问：

```
http://your-nas-ip:8000
```

### 默认登录凭据

- **用户名**: `admin`
- **密码**: 通过环境变量 `ADMIN_PASSWORD` 配置

**配置方式**：在 `.env` 文件中设置：
```env
ADMIN_PASSWORD=your-secure-password
```

**安全提示**：
- 生产环境请使用强密码
- 不要在代码中硬编码密码
- 建议使用密钥管理服务存储敏感信息

### WebSocket 连接

WebSocket 端点：

```
ws://your-nas-ip:8080
```

---

## 数据备份

### 重要数据位置

所有重要数据都存储在 `/volume1/docker/stock/sanguo_vnpy/`：

```
/volume1/docker/stock/sanguo_vnpy/
├── data/           # 数据库和数据文件
├── logs/           # 运行日志
├── config/         # 配置文件
├── redis/          # Redis 持久化数据
└── nginx/          # Nginx 配置和证书
```

### 备份方法

#### 方法 1: 使用 Hyper Backup 套件（推荐）

1. 打开 **Hyper Backup**
2. 创建新备份任务
3. 选择 **从文件夹备份**
4. 选择 `/volume1/docker/stock/sanguo_vnpy/`
5. 配置备份目标和计划

#### 方法 2: 手动备份

```bash
# 创建备份
sudo tar czf \
  /volume1/Backup/vnpy_backup_$(date +%Y%m%d_%H%M%S).tar.gz \
  /volume1/docker/stock/sanguo_vnpy/

# 列出备份文件
ls -lh /volume1/Backup/vnpy_backup_*

# 恢复备份
sudo tar xzf \
  /volume1/Backup/vnpy_backup_YYYYMMDD_HHMMSS.tar.gz \
  -C /
```

#### 方法 3: 使用 rsync 同步到其他位置

```bash
# 同步到另一个共享文件夹
sudo rsync -avz \
  /volume1/docker/stock/sanguo_vnpy/ \
  /volume1/Backup/sanguo_vnpy_backup/

# 同步到远程服务器
rsync -avz -e ssh \
  /volume1/docker/stock/sanguo_vnpy/ \
  user@remote-server:/backup/path/
```

### 自动备份脚本

创建定时任务：

```bash
# 创建备份脚本
sudo vi /volume1/docker/stock/backup_vnpy.sh
```

脚本内容：

```bash
#!/bin/bash
# Sanguo VeighNa 自动备份脚本

BACKUP_DIR="/volume1/Backup"
DATA_DIR="/volume1/docker/stock/sanguo_vnpy"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/vnpy_backup_$TIMESTAMP.tar.gz"

# 保留最近 7 天的备份
find $BACKUP_DIR -name "vnpy_backup_*.tar.gz" -mtime +7 -delete

# 创建备份
tar czf $BACKUP_FILE $DATA_DIR

# 记录日志
echo "Backup created: $BACKUP_FILE" >> $BACKUP_DIR/backup.log

echo "Backup completed: $BACKUP_FILE"
```

设置定时任务：

```bash
# 给脚本执行权限
sudo chmod +x /volume1/docker/stock/backup_vnpy.sh

# 添加到 crontab（每天凌晨 2 点执行）
sudo crontab -e

# 添加以下行
0 2 * * * /volume1/docker/stock/backup_vnpy.sh
```

---

## 故障排除

### 常见问题

#### 1. 容器无法启动

**检查日志**：

```bash
sudo docker-compose logs vnpy
```

**常见原因**：

- 端口被占用：修改 `.env` 中的端口配置
- 数据目录不存在：创建所需目录
- 权限问题：检查目录权限

#### 2. 数据目录权限问题

```bash
# 修复权限
sudo chown -R $(id -u):$(id -g) /volume1/docker/stock/sanguo_vnpy
sudo chmod -R 755 /volume1/docker/stock/sanguo_vnpy
```

#### 3. 端口冲突

```bash
# 检查端口占用
sudo netstat -tulpn | grep :8000

# 或使用 lsof
sudo lsof -i :8000
```

#### 4. Redis 连接失败

```bash
# 检查 Redis 容器
sudo docker-compose logs redis

# 重启 Redis
sudo docker-compose restart redis

# 跳过 Redis 检查（开发环境）
# 在 .env 中设置
SKIP_REDIS_CHECK=1
```

#### 5. 日志文件过大

```bash
# 清理旧日志
sudo find /volume1/docker/stock/sanguo_vnpy/logs -name "*.log" -mtime +30 -delete

# 或配置日志轮转
sudo vi /etc/logrotate.d/vnpy
```

### 重置部署

如果需要完全重置：

```bash
# 停止并删除容器
sudo docker-compose down

# 备份数据
sudo cp -r /volume1/docker/stock/sanguo_vnpy /volume1/Backup/

# 清理数据（谨慎操作）
sudo rm -rf /volume1/docker/stock/sanguo_vnpy/data/*
sudo rm -rf /volume1/docker/stock/sanguo_vnpy/logs/*

# 重新启动
sudo docker-compose up -d
```

---

## 升级指南

### 升级步骤

1. **备份当前版本**：

```bash
# 备份数据
sudo tar czf /volume1/Backup/vnpy_pre_upgrade_$(date +%Y%m%d).tar.gz \
  /volume1/docker/stock/sanguo_vnpy/
```

2. **下载新版本**：

```bash
# 停止服务
cd /volume1/docker/containers/sanguo_vnpy_v2/docker
sudo docker-compose down
```

3. **替换项目文件**：

```bash
# 备份旧代码
sudo mv /volume1/docker/containers/sanguo_vnpy_v2 \
        /volume1/docker/containers/sanguo_vnpy_v2_old

# 解压新版本
sudo tar xzf /tmp/sanguo_vnpy_v2_new.tar.gz -C /volume1/docker/containers/
```

4. **复制配置**：

```bash
# 复制 .env 配置
sudo cp /volume1/docker/containers/sanguo_vnpy_v2_old/docker/.env \
         /volume1/docker/containers/sanguo_vnpy_v2/docker/.env
```

5. **启动新版本**：

```bash
cd /volume1/docker/containers/sanguo_vnpy_v2/docker
sudo docker-compose up -d --build
```

6. **验证升级**：

```bash
# 检查状态
sudo docker-compose ps
sudo docker-compose logs -f
```

### 回滚

如果升级失败：

```bash
# 停止新版本
cd /volume1/docker/containers/sanguo_vnpy_v2/docker
sudo docker-compose down

# 恢复旧版本
sudo mv /volume1/docker/containers/sanguo_vnpy_v2 \
        /volume1/docker/containers/sanguo_vnpy_v2_new
sudo mv /volume1/docker/containers/sanguo_vnpy_v2_old \
        /volume1/docker/containers/sanguo_vnpy_v2

# 启动旧版本
cd /volume1/docker/containers/sanguo_vnpy_v2/docker
sudo docker-compose up -d
```

---

## 性能优化

### 资源调整

根据 NAS 配置调整资源限制：

```env
# .env 文件中
VNPY_CPU_LIMIT=4.0      # 增加 CPU
VNPY_MEMORY_LIMIT=4G    # 增加内存
WEB_WORKERS=4           # 增加 Worker 数量
```

### 存储优化

- 将数据目录放在 SSD 缓存盘上（如果有）
- 定期清理旧日志
- 使用数据库的 VACUUM 功能优化 SQLite

### 网络优化

- 使用有线网络连接
- 配置 QoS 优先级
- 考虑使用本地网络而非远程访问

---

## 安全建议

1. **修改默认密码**：首次登录后立即修改
2. **使用 HTTPS**：配置 SSL 证书
3. **限制访问**：使用防火墙规则
4. **定期备份**：设置自动备份任务
5. **更新系统**：保持 DSM 和套件更新
6. **监控日志**：定期检查访问日志

---

## 附录

### A. Docker Compose 常用命令

```bash
# 启动服务
sudo docker-compose up -d

# 停止服务
sudo docker-compose down

# 重启服务
sudo docker-compose restart

# 查看状态
sudo docker-compose ps

# 查看日志
sudo docker-compose logs -f

# 进入容器
sudo docker-compose exec vnpy bash

# 更新并重启
sudo docker-compose up -d --build

# 删除容器和数据（危险）
sudo docker-compose down -v
```

### B. 目录结构参考

```
/volume1/docker/
├── stock/
│   └── sanguo_vnpy/
│       ├── data/           # 数据库
│       ├── logs/           # 日志
│       ├── config/         # 配置
│       ├── temp/           # 临时文件
│       ├── redis/          # Redis 数据
│       └── nginx/          # Nginx 相关
└── containers/
    └── sanguo_vnpy_v2/     # 项目文件
        └── docker/
            ├── .env
            ├── .env.example
            ├── docker-compose.yml
            ├── Dockerfile
            └── entrypoint.sh
```

### C. 支持和反馈

如有问题，请通过以下方式获取支持：

- GitHub Issues
- 项目文档
- 社区论坛

---

**最后更新**: 2026-07-01
**文档版本**: 1.0.0