buffer_platform/DOCKER_DEPLOY.md

# 数据缓冲平台 Docker 部署文档

## 目录结构

```
buffer_platform/
├── app/                    # 应用代码
├── config/                 # 配置文件
├── data/                   # 本地数据目录
├── Dockerfile             # Docker 镜像构建文件
├── docker-compose.yml     # Docker Compose 配置文件
├── .dockerignore          # Docker 构建忽略文件
└── requirements.txt       # Python 依赖
```

## 环境要求

- Docker Desktop for Windows
- Docker Compose v3.8+
- Windows 10/11 或 Windows Server

## 快速部署

### 1. 构建并启动容器

```powershell
cd d:\alpha_workspace\buffer_platform
docker-compose up -d --build
```

### 2. 查看容器状态

```powershell
docker-compose ps
```

### 3. 查看日志

```powershell
# 查看实时日志
docker-compose logs -f

# 查看最近 100 行日志
docker-compose logs --tail=100
```

## 访问地址

| 服务 | 地址 |
|------|------|
| 前端页面 | http://localhost:9600/ui |
| API 文档 | http://localhost:9600/docs |
| 健康检查 | http://localhost:9600/api/v1/health |

## 数据持久化

### 挂载路径

| 宿主机路径 | 容器路径 | 说明 |
|-----------|----------|------|
| `E:\docker_workspace\futures_datas` | `/app/data` | SQLite 数据库及缓存数据 |

### 数据目录结构

容器启动后，`E:\docker_workspace\futures_datas` 目录将包含：

```
E:\docker_workspace\futures_datas\
└── buffer.db          # SQLite 数据库文件
```

## 常用操作

### 停止服务

```powershell
docker-compose stop
```

### 启动服务

```powershell
docker-compose start
```

### 重启服务

```powershell
docker-compose restart
```

### 停止并删除容器

```powershell
docker-compose down
```

### 停止并删除容器及数据卷

> ⚠️ 警告：此操作将删除所有持久化数据！

```powershell
docker-compose down -v
```

### 重新构建并启动

```powershell
docker-compose up -d --build
```

### 更新镜像

```powershell
# 拉取最新代码后
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

## 环境变量配置

可在 `docker-compose.yml` 中修改以下环境变量：

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `BUFFER_DB_PATH` | `/app/data/buffer.db` | 数据库文件路径 |
| `BUFFER_HOST` | `0.0.0.0` | 服务监听地址 |
| `BUFFER_PORT` | `8600` | 容器内服务端口 |
| `CACHE_TTL` | `300` | 缓存过期时间（秒） |
| `BUFFER_LOG_LEVEL` | `INFO` | 日志级别 |
| `MAX_WORKERS` | `2` | 并发采集数 |

## 端口修改

如需修改宿主机绑定端口，编辑 `docker-compose.yml`：

```yaml
ports:
  - "9600:8600"  # 修改 9600 为其他端口
```

## 数据备份

### 备份数据库

```powershell
# 停止服务
docker-compose stop

# 复制数据文件
xcopy E:\docker_workspace\futures_datas\buffer.db E:\backup\buffer_$(Get-Date -Format 'yyyyMMdd').db

# 启动服务
docker-compose start
```

### 恢复数据库

```powershell
# 停止服务
docker-compose stop

# 复制备份文件到数据目录
copy E:\backup\buffer_20260517.db E:\docker_workspace\futures_datas\buffer.db

# 启动服务
docker-compose start
```

## 故障排查

### 容器无法启动

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

# 检查容器状态
docker ps -a
```

### 数据库权限问题

确保 `E:\docker_workspace\futures_datas` 目录存在且有写入权限：

```powershell
# 创建数据目录
mkdir E:\docker_workspace\futures_datas
```

### 端口冲突

```powershell
# 检查端口占用
netstat -ano | findstr "9600"
```

### 进入容器

```powershell
docker exec -it buffer-platform /bin/bash
```

## 健康检查

服务内置健康检查端点：

```powershell
# PowerShell
Invoke-WebRequest -Uri http://localhost:9600/api/v1/health

# 或使用 curl
curl http://localhost:9600/api/v1/health
```

正常响应：

```json
{
  "status": "ok",
  "service": "market-data-buffer"
}
```