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. 简单部署（推荐）

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

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

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

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

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

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

# 仅启动主应用
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用户运行应用
• 最小权限原则
• 安全的文件权限设置

健康检查

内置健康检查机制：

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卷持久化数据：

volumes:
  api_data:
    driver: local

数据存储位置：

• 容器内: /app/data/
• SQLite数据库: /app/data/users.db

备份数据

# 备份数据卷
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

常用命令

构建和运行

# 构建镜像
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

管理服务

# 查看服务状态
docker-compose ps

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

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

# 停止服务
docker-compose down

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

调试和维护

# 进入容器
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

日志查看

# 实时查看日志
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. 环境变量管理

   # 使用.env文件管理敏感信息
   echo "DATABASE_URL=sqlite:///app/data/production.db" > .env
   echo "JWT_SECRET=your-production-secret" >> .env
   

2. 网络安全

   # 限制端口暴露
   ports:
     - "127.0.0.1:3000:3000"  # 仅本地访问
   

3. 资源限制

   deploy:
     resources:
       limits:
         cpus: '1.0'
         memory: 512M
       reservations:
         cpus: '0.5'
         memory: 256M
   

性能优化

1. 镜像优化

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

2. 运行时优化

   • 配置适当的健康检查间隔
   • 设置合理的重启策略
   • 使用专用网络隔离服务

故障排除

常见问题

1. 端口冲突

   # 检查端口占用
   netstat -tulpn | grep :3000
   
   # 修改端口映射
   ports:
     - "3001:3000"
   

2. 权限问题

   # 检查文件权限
   docker-compose exec rust-user-api ls -la /app/data/
   
   # 修复权限
   docker-compose exec rust-user-api chown -R appuser:appuser /app/data/
   

3. 数据库连接问题

   # 检查数据库文件
   docker-compose exec rust-user-api ls -la /app/data/
   
   # 查看数据库日志
   docker-compose logs rust-user-api | grep -i database
   

调试模式

启用调试模式：

environment:
  - RUST_LOG=debug
  - LOG_LEVEL=debug

更新和维护

应用更新

# 拉取最新代码
git pull origin main

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

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

数据库迁移

# 备份数据
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"

扩展配置

负载均衡

使用多个实例：

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

外部数据库

连接外部PostgreSQL：

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

SSL/TLS

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

总结

Docker容器化部署提供了：

• ✅ 环境一致性
• ✅ 简化部署流程
• ✅ 易于扩展和维护
• ✅ 完整的监控和日志
• ✅ 生产环境就绪

选择适合的部署方式：

• 开发/测试: 使用 docker-compose.simple.yml
• 生产环境: 使用 docker-compose.yml 并启用监控