feat: 完成Rust User API完整开发
Some checks failed
Deploy to Production / Run Tests (push) Failing after 16m35s
Deploy to Production / Security Scan (push) Has been skipped
Deploy to Production / Build Docker Image (push) Has been skipped
Deploy to Production / Deploy to Staging (push) Has been skipped
Deploy to Production / Deploy to Production (push) Has been skipped
Deploy to Production / Notify Results (push) Successful in 31s

 新功能:
- SQLite数据库集成和持久化存储
- 数据库迁移系统和版本管理
- API分页功能和高效查询
- 用户搜索和过滤机制
- 完整的RBAC角色权限系统
- 结构化日志记录和系统监控
- API限流和多层安全防护
- Docker容器化和生产部署配置

🔒 安全特性:
- JWT认证和授权
- 限流和防暴力破解
- 安全头和CORS配置
- 输入验证和XSS防护
- 审计日志和安全监控

📊 监控和运维:
- Prometheus指标收集
- 健康检查和系统监控
- 自动化备份和恢复
- 完整的运维文档和脚本
- CI/CD流水线配置

🚀 部署支持:
- 多环境Docker配置
- 生产环境部署指南
- 性能优化和安全加固
- 故障排除和应急响应
- 自动化运维脚本

📚 文档完善:
- API使用文档
- 部署检查清单
- 运维操作手册
- 性能和安全指南
- 故障排除指南
This commit is contained in:
2025-08-07 16:03:32 +08:00
parent cf01d557b9
commit bb9d7a869d
45 changed files with 8433 additions and 85 deletions

340
docs/docker-deployment.md Normal file
View File

@@ -0,0 +1,340 @@
# 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` 并启用监控