# Docker 部署指南

本指南介绍如何使用 Docker Compose 部署 Sanguo VeighNa 量化交易平台。

## 目录

- [前置要求](#前置要求)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [启动服务](#启动服务)
- [访问界面](#访问界面)
- [数据管理](#数据管理)
- [生产部署](#生产部署)
- [常见问题](#常见问题)

---

## 前置要求

### 系统要求

- **操作系统**: Linux, macOS, Windows (with WSL2)
- **Docker**: 20.10+
- **Docker Compose**: 2.0+
- **内存**: 至少 2GB 可用内存
- **存储**: 至少 10GB 可用存储空间

### 安装 Docker

#### Linux

```bash
# Ubuntu/Debian
curl -fsSL https://get.docker.com | bash
sudo usermod -aG docker $USER

# 启用 Docker Compose
sudo apt-get install docker-compose-plugin
```

#### macOS

下载并安装 [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop/)

#### Windows

下载并安装 [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)

---

## 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/sanguo/sanguo_vnpy_v2.git
cd sanguo_vnpy_v2
```

### 2. 配置环境变量

```bash
cd docker
cp .env.example .env
vi .env  # 编辑配置
```

### 3. 启动服务

```bash
docker-compose up -d
```

### 4. 查看状态

```bash
docker-compose ps
docker-compose logs -f
```

---

## 配置说明

### 环境变量

编辑 `.env` 文件配置以下参数：

```env
# 数据目录
DATA_DIR=./data

# 端口配置
HTTP_PORT=8000
WS_PORT=8080

# 时区
TZ=Asia/Shanghai

# 日志级别
VNPY_LOG_LEVEL=INFO

# 数据库配置
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=your-secret-key-here
SESSION_TIMEOUT=3600
```

### 目录映射

默认目录映射：

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

---

## 启动服务

### 基本命令

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

# 仅启动核心服务
docker-compose up -d vnpy redis

# 启动并包含 Nginx
docker-compose --profile nginx up -d

# 启动并包含 PostgreSQL
docker-compose --profile postgres up -d
```

### 查看状态

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

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

# 查看所有服务日志
docker-compose logs -f
```

### 停止服务

```bash
# 停止服务
docker-compose down

# 停止并删除数据卷
docker-compose down -v
```

### 重启服务

```bash
# 重启所有服务
docker-compose restart

# 重启特定服务
docker-compose restart vnpy
```

### 进入容器

```bash
# 进入 VeighNa 容器
docker-compose exec vnpy bash

# 进入 Redis 容器
docker-compose exec redis sh
```

---

## 访问界面

### Web 界面

启动成功后，访问：

```
http://localhost:8000
```

### 默认登录

- **用户名**: `admin`
- **密码**: `admin123`

### WebSocket 端点

```
ws://localhost:8080
```

---

## 数据管理

### 数据备份

```bash
# 备份数据目录
tar czf vnpy_backup_$(date +%Y%m%d).tar.gz ./data

# 恢复数据
tar xzf vnpy_backup_YYYYMMDD.tar.gz
```

### 数据库操作

#### SQLite

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

# 访问数据库
sqlite3 /app/data/vnpy.db

# 常用命令
.tables          # 列出所有表
.schema          # 查看表结构
.quit            # 退出
```

#### PostgreSQL

```bash
# 进入 PostgreSQL 容器
docker-compose exec postgres psql -U vnpy -d vnpy

# 常用命令
\l               # 列出所有数据库
\dt              # 列出所有表
\q               # 退出
```

---

## 生产部署

### 使用 Nginx 反向代理

```bash
# 启用 Nginx
docker-compose --profile nginx up -d
```

### 配置 HTTPS

1. 获取 SSL 证书

```bash
# 使用 Let's Encrypt
mkdir -p data/nginx/ssl
# 将证书文件复制到该目录
cp cert.pem data/nginx/ssl/
cp key.pem data/nginx/ssl/
```

2. 更新 nginx 配置

3. 重启服务

```bash
docker-compose restart nginx
```

### 资源限制

在 `.env` 文件中配置：

```env
VNPY_CPU_LIMIT=2.0
VNPY_MEMORY_LIMIT=2G
WEB_WORKERS=4
```

### 安全建议

1. **修改默认密码**
2. **使用强 JWT 密钥**
3. **启用 HTTPS**
4. **配置防火墙**
5. **定期备份**
6. **监控日志**

---

## 常见问题

### 端口冲突

如果端口被占用，修改 `.env` 中的端口配置：

```env
HTTP_PORT=8001
WS_PORT=8081
```

### 权限问题

```bash
# 修复数据目录权限
sudo chown -R $USER:$USER ./data
sudo chmod -R 755 ./data
```

### 容器无法启动

```bash
# 查看详细日志
docker-compose logs vnpy

# 重新构建
docker-compose up -d --build
```

### 数据丢失

确保使用绑定挂载而非命名卷：

```yaml
volumes:
  - ./data:/app/data
```

---

## 高级配置

### 使用 PostgreSQL

```bash
# 启用 PostgreSQL
export USE_POSTGRES=1
docker-compose --profile postgres up -d
```

### 自定义配置

```bash
# 挂载自定义配置
mkdir -p config
cp your_config.yaml config/
```

### 多实例部署

```bash
# 修改端口和数据目录
docker-compose -f docker-compose.yml -p vnpy2 up -d
```

---

## 附录

### Docker Compose 命令参考

| 命令 | 说明 |
|------|------|
| `up -d` | 后台启动服务 |
| `down` | 停止并删除容器 |
| `ps` | 查看服务状态 |
| `logs` | 查看日志 |
| `exec` | 在容器中执行命令 |
| `restart` | 重启服务 |
| `build` | 重新构建镜像 |

### 目录结构

```
sanguo_vnpy_v2/
├── docker/
│   ├── .env                 # 环境变量配置
│   ├── .env.example         # 配置示例
│   ├── docker-compose.yml   # 编排配置
│   ├── Dockerfile           # 镜像构建
│   ├── entrypoint.sh        # 启动脚本
│   └── nginx/               # Nginx 配置
├── data/                    # 数据目录
├── logs/                    # 日志目录
└── docs/                    # 文档
```

---

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