# 云盘应用 Linux 环境部署指南

本文档介绍如何将云盘应用后端打包成 Docker 镜像并部署到 Linux 环境。

## 📋 部署前准备

### 1. 系统要求
- Linux 操作系统（推荐 Ubuntu 20.04+ 或 CentOS 8+）
- Docker 20.10+
- Docker Compose 2.0+
- 至少 2GB 内存
- 至少 10GB 磁盘空间

### 2. 安装 Docker

#### Ubuntu/Debian:
```bash
# 更新包索引
sudo apt-get update

# 安装必要的包
sudo apt-get install ca-certificates curl gnupg lsb-release

# 添加 Docker 官方 GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 设置仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
```

#### CentOS/RHEL:
```bash
# 安装 yum-utils
sudo yum install -y yum-utils

# 添加 Docker 仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装 Docker Engine
sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin
```

### 3. 启动 Docker 服务
```bash
sudo systemctl start docker
sudo systemctl enable docker
```

### 4. 将用户添加到 docker 组（可选）
```bash
sudo usermod -aG docker $USER
# 重新登录或执行
newgrp docker
```

## 🚀 快速部署

### 方法一：使用自动部署脚本（推荐）

1. 将 backend 目录上传到服务器
2. 进入 backend 目录
3. 给脚本添加执行权限：
   ```bash
   chmod +x build-docker.sh
   ```
4. 运行部署脚本：
   ```bash
   # 完整部署（构建镜像 + 运行容器）
   ./build-docker.sh

   # 或者使用 Docker Compose 部署
   ./build-docker.sh compose
   ```

### 方法二：手动部署

1. **构建镜像**
   ```bash
   docker build -t cloud-drive-backend:latest .
   ```

2. **运行容器**
   ```bash
   docker run -d \
     --name cloud-drive-backend \
     --restart unless-stopped \
     -p 8002:8002 \
     -v $(pwd)/uploads:/app/uploads \
     -v $(pwd)/logs:/app/logs \
     -e ENVIRONMENT=production \
     cloud-drive-backend:latest
   ```

### 方法三：使用 Docker Compose

1. **配置环境变量**
   ```bash
   cp .env.example .env
   # 编辑 .env 文件，设置正确的配置
   ```

2. **启动服务**
   ```bash
   docker-compose up -d
   ```

## ⚙️ 配置说明

### 环境变量配置

创建 `.env` 文件：
```bash
# 数据库配置
DATABASE_URL=mysql://username:password@mysql:3306/mytest_db
MYSQL_ROOT_PASSWORD=your_root_password
MYSQL_DATABASE=mytest_db
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password

# Redis 配置
REDIS_URL=redis://redis:6379/0

# 应用配置
SECRET_KEY=your-production-secret-key
CORS_ORIGINS=http://localhost:3003,https://yourdomain.com
ENVIRONMENT=production
```

### 端口配置
- 应用端口：8002
- MySQL 端口：3306
- Redis 端口：6379

### 数据持久化
- `./uploads` - 文件上传目录
- `./logs` - 应用日志目录
- `mysql_data` - MySQL 数据目录
- `redis_data` - Redis 数据目录

## 🛠️ 常用命令

### 容器管理
```bash
# 查看容器状态
./build-docker.sh status

# 查看容器日志
./build-docker.sh logs

# 重启容器
./build-docker.sh restart

# 停止容器
./build-docker.sh stop

# 清理资源
./build-docker.sh cleanup
```

### Docker Compose 命令
```bash
# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 重启服务
docker-compose restart

# 停止服务
docker-compose down

# 更新并重启
docker-compose up -d --build
```

## 🔍 健康检查

应用包含内置的健康检查端点：
- 端点：`http://localhost:8002/api/v1/health`
- 检查间隔：30秒
- 超时时间：30秒
- 重试次数：3次

手动检查：
```bash
curl http://localhost:8002/api/v1/health
```

## 🔧 故障排除

### 1. 容器无法启动
```bash
# 查看容器日志
docker logs cloud-drive-backend

# 检查端口占用
netstat -tulpn | grep 8002
```

### 2. 数据库连接失败
- 检查数据库服务是否运行
- 验证连接字符串是否正确
- 确认网络连通性

### 3. 文件上传问题
- 检查 uploads 目录权限
- 确认磁盘空间充足
- 验证文件大小限制

### 4. 内存不足
```bash
# 检查内存使用
free -h

# 检查容器资源使用
docker stats
```

## 📊 监控

### 日志监控
```bash
# 实时查看日志
tail -f logs/app.log

# 查看错误日志
grep ERROR logs/app.log
```

### 性能监控
```bash
# 查看容器资源使用
docker stats cloud-drive-backend

# 查看系统资源
htop
```

## 🔒 安全配置

### 1. 防火墙设置
```bash
# Ubuntu UFW
sudo ufw allow 8002
sudo ufw allow 22
sudo ufw enable

# CentOS firewalld
sudo firewall-cmd --permanent --add-port=8002/tcp
sudo firewall-cmd --reload
```

### 2. SSL/TLS 配置
建议使用 Nginx 或 Caddy 作为反向代理来处理 HTTPS：

```nginx
server {
    listen 443 ssl;
    server_name yourdomain.com;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;

    location / {
        proxy_pass http://localhost:8002;
        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;
    }
}
```

## 📈 扩展部署

### 1. 负载均衡
使用多个容器实例配合负载均衡器：

```yaml
# docker-compose.scale.yml
version: '3.8'
services:
  app:
    image: cloud-drive-backend:latest
    scale: 3
    # ... 其他配置
```

### 2. 集群部署
使用 Docker Swarm 或 Kubernetes 进行集群部署。

## 📞 支持

如遇到问题，请：
1. 查看本文档的故障排除部分
2. 检查应用日志和 Docker 日志
3. 确认所有配置正确
4. 验证系统资源是否充足

---

**注意**: 生产环境部署前请务必：
- 更改默认密码和密钥
- 配置适当的备份策略
- 设置监控和告警
- 进行充分的测试