claude_dev
1803610f23
新增 docs/deployment/nas-deploy-plan.md，固化应用层/镜像层分离的部署流程（rsync + docker restart）。CLAUDE.md 参考文档段加入索引。
686 lines
14 KiB
Markdown
686 lines
14 KiB
Markdown
# 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
|