feat(deployment): add Docker and docker-compose configuration

- Create production-ready Dockerfile with health check - Add docker-compose.yml with PostgreSQL and Redis - Include all services with proper health checks and dependencies - Add comprehensive Docker deployment documentation - Support environment variable configuration - Include backup/restore commands and monitoring guide - Add security recommendations and troubleshooting section Phase 4 Task 31/68 completed
2026-06-17 07:51:55 +08:00
parent 37836b2755
commit eb11fe2dab
4 changed files with 449 additions and 0 deletions
@@ -0,0 +1,276 @@
+# 小虾 SaaS Docker 部署指南
+
+## 🐳 快速启动
+
+### 1. 准备环境变量
+
+```bash
+# 创建 .env 文件
+cat > .env << EOF
+# PostgreSQL
+POSTGRES_PASSWORD=your_secure_password
+
+# JWT
+JWT_SECRET_KEY=$(openssl rand -base64 32)
+
+# Email (Gmail example)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=your-email@gmail.com
+SMTP_PASSWORD=your-app-password
+
+# App
+BASE_URL=https://yourdomain.com
+ENVIRONMENT=production
+EOF
+```
+
+### 2. 启动所有服务
+
+```bash
+# 启动（首次会自动构建镜像）
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f api
+
+# 查看状态
+docker-compose ps
+```
+
+### 3. 验证部署
+
+```bash
+# 健康检查
+curl http://localhost:8000/health
+
+# API 文档
+open http://localhost:8000/docs
+```
+
+---
+
+## 🔧 常用命令
+
+### 服务管理
+
+```bash
+# 启动所有服务
+docker-compose up -d
+
+# 停止所有服务
+docker-compose down
+
+# 重启 API
+docker-compose restart api
+
+# 查看日志
+docker-compose logs -f [service_name]
+
+# 进入容器
+docker-compose exec api bash
+docker-compose exec postgres psql -U xiaoxia_user xiaoxia_saas
+```
+
+### 数据库操作
+
+```bash
+# 备份数据库
+docker-compose exec postgres pg_dump -U xiaoxia_user xiaoxia_saas > backup.sql
+
+# 恢复数据库
+docker-compose exec -T postgres psql -U xiaoxia_user xiaoxia_saas < backup.sql
+
+# 查看数据库状态
+docker-compose exec postgres psql -U xiaoxia_user -c "\l"
+```
+
+### 更新部署
+
+```bash
+# 拉取最新代码
+git pull
+
+# 重新构建镜像
+docker-compose build api
+
+# 重启服务
+docker-compose up -d api
+```
+
+---
+
+## 📦 单独构建镜像
+
+```bash
+# 构建
+docker build -t xiaoxia-saas:latest .
+
+# 运行
+docker run -d \
+  --name xiaoxia-api \
+  -p 8000:8000 \
+  --env-file .env \
+  xiaoxia-saas:latest
+
+# 推送到仓库
+docker tag xiaoxia-saas:latest your-registry/xiaoxia-saas:latest
+docker push your-registry/xiaoxia-saas:latest
+```
+
+---
+
+## 🚀 生产环境部署
+
+### 1. 使用外部数据库
+
+修改 `docker-compose.yml`，注释掉 postgres 和 redis 服务，直接使用云数据库：
+
+```yaml
+services:
+  api:
+    environment:
+      DATABASE_URL: postgresql://user:pass@your-rds.amazonaws.com:5432/xiaoxia_saas
+      REDIS_URL: redis://your-elasticache.amazonaws.com:6379/0
+```
+
+### 2. 反向代理（Nginx）
+
+```nginx
+server {
+    listen 80;
+    server_name api.yourdomain.com;
+
+    location / {
+        proxy_pass http://localhost:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+### 3. SSL 证书（Let's Encrypt）
+
+```bash
+# 安装 certbot
+apt-get install certbot python3-certbot-nginx
+
+# 获取证书
+certbot --nginx -d api.yourdomain.com
+```
+
+### 4. 自动重启（systemd）
+
+创建 `/etc/systemd/system/xiaoxia-api.service`：
+
+```ini
+[Unit]
+Description=小虾 SaaS API
+Requires=docker.service
+After=docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+WorkingDirectory=/opt/xiaoxia-saas
+ExecStart=/usr/bin/docker-compose up -d
+ExecStop=/usr/bin/docker-compose down
+TimeoutStartSec=0
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启用：
+```bash
+systemctl enable xiaoxia-api
+systemctl start xiaoxia-api
+```
+
+---
+
+## 📊 监控和日志
+
+### 日志管理
+
+```bash
+# 实时查看日志
+docker-compose logs -f --tail=100 api
+
+# 日志轮转（在 docker-compose.yml 中配置）
+logging:
+  driver: "json-file"
+  options:
+    max-size: "10m"
+    max-file: "3"
+```
+
+### 资源监控
+
+```bash
+# 查看资源使用
+docker stats
+
+# 查看容器详情
+docker inspect xiaoxia-api
+```
+
+---
+
+## 🔒 安全建议
+
+1. **修改默认密码**
+   - PostgreSQL 密码
+   - JWT Secret Key
+
+2. **限制端口暴露**
+   - 只暴露必要的端口
+   - 使用防火墙规则
+
+3. **定期备份**
+   - 数据库自动备份
+   - 代码版本控制
+
+4. **更新依赖**
+   - 定期更新 Docker 镜像
+   - 更新 Python 依赖包
+
+---
+
+## 🐛 故障排查
+
+### API 启动失败
+
+```bash
+# 查看详细日志
+docker-compose logs api
+
+# 检查数据库连接
+docker-compose exec api python -c "import psycopg2; psycopg2.connect('$DATABASE_URL')"
+```
+
+### 数据库连接失败
+
+```bash
+# 检查 PostgreSQL 状态
+docker-compose ps postgres
+
+# 测试连接
+docker-compose exec postgres psql -U xiaoxia_user -c "SELECT 1"
+```
+
+### 性能问题
+
+```bash
+# 增加 worker 数量
+CMD ["uvicorn", "apps.api.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]
+
+# 启用 Gunicorn（更适合生产）
+CMD ["gunicorn", "apps.api.main:app", "--workers", "4", "--worker-class", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:8000"]
+```
+
+---
+
+**支持联系:** xiaoxia@example.com