# 小虾 SaaS Docker 部署指南

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

## 🐳 快速启动

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