xiaoxia-saas/docs/DOCKER-DEPLOYMENT.md

小虾 SaaS Docker 部署指南

⚠️ 历史文档，仅供归档参考。当前 canonical 部署入口是 infra/docker/compose.yml 和 infra/docker/deploy-staging.sh；生产发布必须按 docs/PRODUCTION-RELEASE-CHECKLIST.md 执行。

🐳 快速启动

1. 准备环境变量

# 创建 .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. 启动所有服务

# 启动（首次会自动构建镜像）
docker-compose up -d

# 查看日志
docker-compose logs -f api

# 查看状态
docker-compose ps

3. 验证部署

# 健康检查
curl http://localhost:8000/health

# API 文档
open http://localhost:8000/docs

---

🔧 常用命令

服务管理

# 启动所有服务
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

数据库操作

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

更新部署

# 拉取最新代码
git pull

# 重新构建镜像
docker-compose build api

# 重启服务
docker-compose up -d api

---

📦 单独构建镜像

# 构建
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 服务，直接使用云数据库：

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）

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）

# 安装 certbot
apt-get install certbot python3-certbot-nginx

# 获取证书
certbot --nginx -d api.yourdomain.com

4. 自动重启（systemd）

创建 /etc/systemd/system/xiaoxia-api.service：

[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

启用：

systemctl enable xiaoxia-api
systemctl start xiaoxia-api

---

📊 监控和日志

日志管理

# 实时查看日志
docker-compose logs -f --tail=100 api

# 日志轮转（在 docker-compose.yml 中配置）
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

资源监控

# 查看资源使用
docker stats

# 查看容器详情
docker inspect xiaoxia-api

---

🔒 安全建议

1. 修改默认密码

   • PostgreSQL 密码
   • JWT Secret Key

2. 限制端口暴露

   • 只暴露必要的端口
   • 使用防火墙规则

3. 定期备份

   • 数据库自动备份
   • 代码版本控制

4. 更新依赖

   • 定期更新 Docker 镜像
   • 更新 Python 依赖包

---

🐛 故障排查

API 启动失败

# 查看详细日志
docker-compose logs api

# 检查数据库连接
docker-compose exec api python -c "import psycopg2; psycopg2.connect('$DATABASE_URL')"

数据库连接失败

# 检查 PostgreSQL 状态
docker-compose ps postgres

# 测试连接
docker-compose exec postgres psql -U xiaoxia_user -c "SELECT 1"

性能问题

# 增加 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