cosmo/DEPLOYMENT.md

# Cosmo Docker 部署指南

## 📦 系统架构

### 服务组件

| 服务 | 镜像版本 | 说明 | 配置位置 |
|------|---------|------|---------|
| **PostgreSQL** | `postgres:15-alpine` | 数据库 | `docker-compose.yml` |
| **Redis** | `redis:7-alpine` | 缓存服务 | `docker-compose.yml` |
| **Backend** | `python:3.12-slim` | FastAPI 后端 | `backend/Dockerfile` |
| **Frontend Build** | `node:22-alpine` | Vite 构建环境 | `frontend/Dockerfile` |
| **Frontend Server** | `nginx:1.25-alpine` | 静态文件服务 | `frontend/Dockerfile` |

### 版本说明

- **PostgreSQL 15**: 稳定的长期支持版本，性能优秀
- **Redis 7**: 最新稳定版，支持更多数据结构和优化
- **Python 3.12**: 最新稳定版，性能提升显著
- **Node 22**: LTS 长期支持版本，与开发环境一致
- **Nginx 1.25**: 稳定版本，完整支持 HTTP/2 和性能优化

## 📋 目录结构

```
cosmo/
├── docker-compose.yml          # Docker Compose 配置
├── .env.production            # 生产环境变量（需配置）
├── deploy.sh                  # 一键部署脚本
├── nginx/
│   └── nginx.conf            # Nginx 反向代理配置
├── backend/
│   ├── Dockerfile            # 后端镜像配置
│   ├── .dockerignore
│   └── scripts/
│       └── init_db.sql       # 数据库初始化 SQL
└── frontend/
    ├── Dockerfile            # 前端镜像配置（多阶段构建）
    └── .dockerignore
```

## 🚀 快速开始

### 前置要求

- Docker 20.10+
- Docker Compose 2.0+
- 至少 4GB 可用内存
- 至少 20GB 可用磁盘空间

### 1. 配置环境变量

编辑 `.env.production` 文件：

```bash
# 修改数据库密码（必须）
DATABASE_PASSWORD=your_secure_password_here

# 修改域名（必须）
CORS_ORIGINS=http://your-domain.com,https://your-domain.com
VITE_API_BASE_URL=http://your-domain.com/api
```

### 2. 初始化部署

```bash
# 赋予执行权限
chmod +x deploy.sh

# 初始化系统（首次部署）
./deploy.sh --init
```

初始化脚本会自动：
1. ✅ 创建数据目录 `/opt/cosmo/data`
2. ✅ 构建 Docker 镜像
3. ✅ 启动 PostgreSQL 和 Redis
4. ✅ 自动执行 `init_db.sql` 初始化数据库
5. ✅ 启动所有服务

### 3. 访问系统

- **前端**: http://your-server-ip
- **后端 API**: http://your-server-ip/api
- **API 文档**: http://your-server-ip/api/docs

## 📂 数据持久化

所有数据存储在 `/opt/cosmo/data/` 目录下：

```
/opt/cosmo/data/
├── postgres/          # PostgreSQL 数据文件
├── redis/            # Redis 持久化文件
├── upload/           # 用户上传文件（纹理、模型等）
├── logs/             # 应用日志
│   └── backend/      # 后端日志
└── backups/          # 备份文件
```

### 目录权限

```bash
sudo chown -R $(whoami):$(whoami) /opt/cosmo/data
sudo chmod -R 755 /opt/cosmo/data
```

## 🛠️ 常用命令

### 服务管理

```bash
# 启动服务
./deploy.sh --start

# 停止服务
./deploy.sh --stop

# 重启服务
./deploy.sh --restart

# 查看状态
./deploy.sh --status

# 查看日志
./deploy.sh --logs
```

### 数据备份

```bash
# 创建备份（数据库 + 上传文件）
./deploy.sh --backup

# 备份文件位置
ls -lh /opt/cosmo/data/backups/
```

### 系统更新

```bash
# 拉取最新代码并重启
./deploy.sh --update
```

### 清理操作

```bash
# 删除容器（保留数据）
./deploy.sh --clean

# 完全清除（删除容器和所有数据）⚠️ 危险操作
./deploy.sh --full-clean
```

## 🔧 手动操作

### 查看容器状态

```bash
docker-compose ps
```

### 进入容器

```bash
# 进入后端容器
docker-compose exec backend bash

# 进入数据库容器
docker-compose exec postgres psql -U postgres -d cosmo_db
```

### 查看日志

```bash
# 查看所有日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f postgres
```

### 重启单个服务

```bash
docker-compose restart backend
docker-compose restart frontend
```

## 🔒 生产环境安全配置

### 1. 修改默认密码

编辑 `.env.production`:
```bash
DATABASE_PASSWORD=strong_random_password_here
```

### 2. 配置 HTTPS（推荐）

使用 Let's Encrypt 免费证书：

```bash
# 安装 certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com

# 证书自动续期
sudo crontab -e
# 添加: 0 3 * * * certbot renew --quiet
```

修改 `nginx/nginx.conf` 添加 SSL 配置：

```nginx
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # 其他配置...
}

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}
```

### 3. 防火墙配置

```bash
# 开放端口
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# 限制数据库和 Redis 只能内部访问
# docker-compose.yml 中不要映射 5432 和 6379 到宿主机
```

## 📊 监控和日志

### 查看资源使用

```bash
docker stats
```

### 日志轮转

创建 `/etc/logrotate.d/cosmo`:

```
/opt/cosmo/data/logs/backend/*.log {
    daily
    rotate 7
    compress
    delaycompress
    notifempty
    create 0640 www-data www-data
    sharedscripts
}
```

## 🐛 故障排查

### 服务启动失败

1. 查看日志：
```bash
docker-compose logs backend
```

2. 检查数据库连接：
```bash
docker-compose exec backend python -c "from app.database import engine; print('DB OK')"
```

### 数据库连接失败

```bash
# 检查数据库是否就绪
docker-compose exec postgres pg_isready -U postgres

# 查看数据库日志
docker-compose logs postgres
```

### 前端访问 502

1. 检查后端是否运行：
```bash
docker-compose ps backend
curl http://localhost:8000/health
```

2. 检查 Nginx 配置：
```bash
docker-compose exec frontend nginx -t
```

### 磁盘空间不足

```bash
# 清理未使用的镜像和容器
docker system prune -a

# 检查磁盘使用
df -h /opt/cosmo/data
```

## 📝 版本升级

### 升级流程

1. 备份数据：
```bash
./deploy.sh --backup
```

2. 拉取最新代码：
```bash
git pull origin main
```

3. 重建镜像：
```bash
docker-compose build --no-cache
```

4. 重启服务：
```bash
docker-compose down
docker-compose up -d
```

## 🔄 数据迁移

### 导出数据

```bash
# 导出数据库
docker-compose exec postgres pg_dump -U postgres cosmo_db > cosmo_backup.sql

# 打包上传文件
tar -czf upload_backup.tar.gz /opt/cosmo/data/upload
```

### 导入数据

```bash
# 导入数据库
docker-compose exec -T postgres psql -U postgres cosmo_db < cosmo_backup.sql

# 恢复上传文件
tar -xzf upload_backup.tar.gz -C /opt/cosmo/data/
```

## 📞 技术支持

- 项目文档: [README.md](./README.md)
- Issue 反馈: GitHub Issues
- 配置说明: [CONFIG.md](./backend/CONFIG.md)

## 🎯 性能优化建议

1. **数据库优化**:
   - 增加 `shared_buffers` 至系统内存的 25%
   - 启用连接池复用

2. **Redis 优化**:
   - 根据需要调整 `maxmemory` 配置
   - 使用 AOF 持久化策略

3. **Nginx 优化**:
   - 启用 gzip 压缩（已配置）
   - 配置静态资源缓存（已配置）

4. **Docker 优化**:
   - 为容器设置资源限制
   - 使用 SSD 存储数据

---

**祝部署顺利！🚀**