rust-user-api/docs/docker-deployment.md

# Docker 容器化部署指南

## 概述

本文档介绍如何使用Docker容器化部署Rust User API应用。

## 文件结构

```
.
├── Dockerfile                 # Docker镜像构建文件
├── docker-compose.yml         # 完整的Docker Compose配置（包含监控）
├── docker-compose.simple.yml  # 简化的Docker Compose配置（仅应用）
├── .dockerignore              # Docker构建忽略文件
└── docs/
    └── docker-deployment.md   # 本文档
```

## 快速开始

### 1. 简单部署（推荐）

使用简化配置快速启动应用：

```bash
# 构建并启动应用
docker-compose -f docker-compose.simple.yml up --build

# 后台运行
docker-compose -f docker-compose.simple.yml up -d --build
```

应用将在 `http://localhost:3000` 启动。

### 2. 完整部署（包含监控）

使用完整配置启动应用和监控服务：

```bash
# 仅启动主应用
docker-compose up rust-user-api --build

# 启动应用和监控服务
docker-compose --profile monitoring up --build
```

服务端口：
- 应用: `http://localhost:3000`
- Prometheus: `http://localhost:9090`
- Grafana: `http://localhost:3001` (admin/admin123)

## Docker镜像特性

### 多阶段构建

- **构建阶段**: 使用 `rust:1.88-slim` 编译应用
- **运行阶段**: 使用 `debian:bookworm-slim` 运行应用
- **优化**: 最小化最终镜像大小

### 安全特性

- 使用非root用户运行应用
- 最小权限原则
- 安全的文件权限设置

### 健康检查

内置健康检查机制：
```dockerfile
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:3000/health || exit 1
```

## 环境变量配置

### 核心配置

| 变量名 | 默认值 | 描述 |
|--------|--------|------|
| `RUST_LOG` | `info` | 日志级别 |
| `DATABASE_URL` | `sqlite:///app/data/users.db?mode=rwc` | 数据库连接字符串 |
| `SERVER_HOST` | `0.0.0.0` | 服务器监听地址 |
| `SERVER_PORT` | `3000` | 服务器端口 |

### 日志配置

| 变量名 | 默认值 | 描述 |
|--------|--------|------|
| `LOG_LEVEL` | `info` | 日志级别 |
| `LOG_FORMAT` | `pretty` | 日志格式 |
| `LOG_TO_CONSOLE` | `true` | 控制台输出 |
| `LOG_TO_FILE` | `false` | 文件输出 |

## 数据持久化

### 数据卷

应用使用Docker卷持久化数据：

```yaml
volumes:
  api_data:
    driver: local
```

数据存储位置：
- 容器内: `/app/data/`
- SQLite数据库: `/app/data/users.db`

### 备份数据

```bash
# 备份数据卷
docker run --rm -v rust-server_api_data:/data -v $(pwd):/backup alpine tar czf /backup/api_data_backup.tar.gz -C /data .

# 恢复数据卷
docker run --rm -v rust-server_api_data:/data -v $(pwd):/backup alpine tar xzf /backup/api_data_backup.tar.gz -C /data
```

## 常用命令

### 构建和运行

```bash
# 构建镜像
docker build -t rust-user-api .

# 运行容器
docker run -p 3000:3000 rust-user-api

# 使用环境变量
docker run -p 3000:3000 -e RUST_LOG=debug rust-user-api
```

### 管理服务

```bash
# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs rust-user-api

# 重启服务
docker-compose restart rust-user-api

# 停止服务
docker-compose down

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

### 调试和维护

```bash
# 进入容器
docker-compose exec rust-user-api /bin/bash

# 查看容器资源使用
docker stats rust-user-api

# 查看容器详细信息
docker inspect rust-user-api
```

## 监控和日志

### 应用监控

访问内置监控端点：
- 健康检查: `GET /health`
- 系统指标: `GET /monitoring/metrics/system`
- 应用指标: `GET /monitoring/metrics/app`
- 监控仪表板: `GET /monitoring/dashboard`

### 日志查看

```bash
# 实时查看日志
docker-compose logs -f rust-user-api

# 查看最近100行日志
docker-compose logs --tail=100 rust-user-api

# 查看特定时间段日志
docker-compose logs --since="2024-01-01T00:00:00" rust-user-api
```

## 生产环境部署

### 安全建议

1. **环境变量管理**
   ```bash
   # 使用.env文件管理敏感信息
   echo "DATABASE_URL=sqlite:///app/data/production.db" > .env
   echo "JWT_SECRET=your-production-secret" >> .env
   ```

2. **网络安全**
   ```yaml
   # 限制端口暴露
   ports:
     - "127.0.0.1:3000:3000"  # 仅本地访问
   ```

3. **资源限制**
   ```yaml
   deploy:
     resources:
       limits:
         cpus: '1.0'
         memory: 512M
       reservations:
         cpus: '0.5'
         memory: 256M
   ```

### 性能优化

1. **镜像优化**
   - 使用多阶段构建减小镜像大小
   - 利用Docker层缓存加速构建
   - 使用.dockerignore排除不必要文件

2. **运行时优化**
   - 配置适当的健康检查间隔
   - 设置合理的重启策略
   - 使用专用网络隔离服务

## 故障排除

### 常见问题

1. **端口冲突**
   ```bash
   # 检查端口占用
   netstat -tulpn | grep :3000
   
   # 修改端口映射
   ports:
     - "3001:3000"
   ```

2. **权限问题**
   ```bash
   # 检查文件权限
   docker-compose exec rust-user-api ls -la /app/data/
   
   # 修复权限
   docker-compose exec rust-user-api chown -R appuser:appuser /app/data/
   ```

3. **数据库连接问题**
   ```bash
   # 检查数据库文件
   docker-compose exec rust-user-api ls -la /app/data/
   
   # 查看数据库日志
   docker-compose logs rust-user-api | grep -i database
   ```

### 调试模式

启用调试模式：

```yaml
environment:
  - RUST_LOG=debug
  - LOG_LEVEL=debug
```

## 更新和维护

### 应用更新

```bash
# 拉取最新代码
git pull origin main

# 重新构建并部署
docker-compose up --build -d

# 验证更新
curl http://localhost:3000/health
```

### 数据库迁移

```bash
# 备份数据
docker-compose exec rust-user-api cp /app/data/users.db /app/data/users.db.backup

# 应用迁移（如果需要）
docker-compose exec rust-user-api ./rust-user-api --migrate

# 验证数据完整性
docker-compose exec rust-user-api sqlite3 /app/data/users.db ".tables"
```

## 扩展配置

### 负载均衡

使用多个实例：

```yaml
services:
  rust-user-api:
    # ... 现有配置
    deploy:
      replicas: 3
```

### 外部数据库

连接外部PostgreSQL：

```yaml
environment:
  - DATABASE_URL=postgresql://user:password@db:5432/rust_api
```

### SSL/TLS

使用反向代理（如Traefik或Nginx）处理SSL终止。

## 总结

Docker容器化部署提供了：
- ✅ 环境一致性
- ✅ 简化部署流程
- ✅ 易于扩展和维护
- ✅ 完整的监控和日志
- ✅ 生产环境就绪

选择适合的部署方式：
- **开发/测试**: 使用 `docker-compose.simple.yml`
- **生产环境**: 使用 `docker-compose.yml` 并启用监控