# 宇之然内容创作平台 - 生产环境部署指南

## 🚀 快速开始

### 1. 克隆项目
```bash
git clone https://github.com/your-org/yuzhiran-platform.git
cd yuzhiran-platform
```

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

### 3. 验证部署
```bash
# 检查服务状态
docker-compose ps

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

# 健康检查
curl http://localhost:8001/health
```

## 📋 系统架构

```
                    +------------------+
                    |     用户浏览器     |
                    +------------------+
                            ↓ HTTPS
                    +------------------+
                    |      Nginx       |
                    |   (反向代理)     |
                    +------------------+
                            ↓
         +----------------------------------+
         |                                  |
    +--------+                      +-----------+
    | 前端   |                      | 后端API   |
    |(Nginx) |                      |(FastAPI)  |
    +--------+                      +-----------+
         ↑                                  ↑
         |                                  |
    +--------+                      +-----------+
    | 静态资源 |                      | PostgreSQL|
    +--------+                      +-----------+
                                      ↑
                                      |
                              +---------------+
                              |    Redis      |
                              |   (缓存)      |
                              +---------------+
```

## 🔧 配置说明

### 环境变量
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `DATABASE_URL` | postgresql://... | PostgreSQL连接字符串 |
| `SECRET_KEY` | your-secret-key... | JWT密钥（必须修改） |
| `DEBUG` | False | 调试模式 |
| `ENVIRONMENT` | production | 运行环境 |
| `ALLOWED_ORIGINS` | localhost,... | CORS允许的源 |

### 端口映射
| 服务 | 容器端口 | 主机端口 | 用途 |
|------|----------|----------|------|
| 前端 | 8000 | 8000 | 静态文件服务 |
| 后端 | 8001 | 8001 | API服务 |
| Nginx | 80 | 80 | HTTP反向代理 |
| Nginx | 443 | 443 | HTTPS反向代理 |
| PostgreSQL | 5432 | 5432 | 数据库 |
| Redis | 6379 | 6379 | 缓存 |

## 🛠️ 开发环境部署

### 方法一：直接运行（推荐用于开发）
```bash
# 1. 配置数据库
sudo -u postgres psql
CREATE DATABASE yuzhiran_db;
CREATE USER yuzhiran WITH PASSWORD 'yuzhiran';
GRANT ALL PRIVILEGES ON DATABASE yuzhiran_db TO yuzhiran;

# 2. 安装依赖
cd backend
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 4. 初始化数据库
python -c "from database import init_db; init_db()"

# 5. 启动服务
uvicorn main:app --host 0.0.0.0 --port 8001 --reload
```

### 方法二：Docker开发模式
```bash
# 启用开发模式（热重载）
docker-compose -f docker-compose.dev.yml up -d

# 进入后端容器调试
docker-compose exec app bash

# 进入数据库容器
docker-compose exec db psql -U yuzhiran -d yuzhiran_db
```

## ☁️ 生产环境部署

### 服务器要求
- CPU: 2核以上
- 内存: 4GB+
- 磁盘: 20GB+
- 操作系统: Ubuntu 20.04/22.04 LTS

### 一键部署脚本
```bash
#!/bin/bash
# deploy.sh

set -e

echo "=========================================="
echo "宇之然内容创作平台 - 生产部署"
echo "=========================================="

# 1. 安装Docker和Docker Compose
apt-get update && apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt-get update && apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 2. 克隆代码
git clone https://github.com/your-org/yuzhiran-platform.git /opt/yuzhiran
cd /opt/yuzhiran

# 3. 配置SSL证书（使用Let's Encrypt）
apt-get install -y certbot python3-certbot-nginx
certbot --nginx -d yourdomain.com -d www.yourdomain.com

# 4. 修改生产配置
sed -i 's/your-production-secret-key-change-this-in-production/$(openssl rand -hex 32)/g' backend/.env

# 5. 启动服务
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# 6. 验证部署
sleep 10
curl -I http://localhost:8001/health

echo "✅ 部署完成！"
echo "访问地址: https://yourdomain.com"
echo "API文档: https://yourdomain.com/docs"
```

## 🔍 监控和维护

### Prometheus + Grafana监控
```yaml
# 在docker-compose.yml中添加
services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    depends_on:
      - app

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    depends_on:
      - prometheus
```

### 日志管理
```bash
# 查看所有容器日志
docker-compose logs

# 实时跟踪特定服务
docker-compose logs -f app

# 清理旧日志
docker system prune -f
```

## 🔐 安全加固

### 1. SSL证书
```bash
# 使用Let's Encrypt自动获取证书
certbot --nginx -d yourdomain.com -d www.yourdomain.com

# 设置自动续期
(crontab -l 2>/dev/null; echo "0 3 * * * certbot renew --quiet") | crontab -
```

### 2. 防火墙配置
```bash
# 仅开放必要端口
ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP
ufw allow 443/tcp   # HTTPS
ufw enable
```

### 3. 定期备份
```bash
#!/bin/bash
# backup.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/yuzhiran"

mkdir -p $BACKUP_DIR

# 数据库备份
docker exec db pg_dump -U yuzhiran yuzhiran_db > $BACKUP_DIR/db_$DATE.sql

# 上传备份到云存储（可选）
# aws s3 cp $BACKUP_DIR/db_$DATE.sql s3://your-bucket/backups/

# 清理30天前的备份
find $BACKUP_DIR -name "db_*.sql" -mtime +30 -delete

echo "备份完成: $BACKUP_DIR"
```

## 📈 性能优化

### 1. 数据库优化
```sql
-- 添加更多索引
CREATE INDEX idx_topics_generated_at ON topics(generated_at);
CREATE INDEX idx_topics_published_at ON topics(published_at);

-- 定期清理旧数据
DELETE FROM audit_logs WHERE timestamp < NOW() - INTERVAL '90 days';
VACUUM ANALYZE;
```

### 2. 应用层优化
```python
# 添加Redis缓存
from redis import Redis
import json

redis_client = Redis.from_url(os.getenv("REDIS_URL"))

@cache(ttl=300)  # 5分钟缓存
async def get_system_status():
    # 查询逻辑...
    return result
```

### 3. Nginx优化
```nginx
# 增加worker进程数
worker_processes auto;

# 优化连接处理
events {
    worker_connections 4096;
    use epoll;
    multi_accept on;
}

# 启用HTTP/2
listen 443 ssl http2;
```

## 🚨 故障排除

### 常见问题
1. **容器启动失败**
   ```bash
   # 查看详细错误
   docker-compose logs app
   
   # 检查端口冲突
   netstat -tulpn | grep :8001
   ```

2. **数据库连接失败**
   ```bash
   # 进入数据库容器
   docker-compose exec db psql -U yuzhiran -d yuzhiran_db
   
   # 测试连接
   \l  # 列出数据库
   \dt # 列出表
   ```

3. **前端无法访问API**
   ```bash
   # 检查CORS配置
   curl -v http://localhost:8001/api/system/status
   
   # 检查Nginx配置
   docker-compose exec nginx nginx -t
   ```

### 紧急恢复
```bash
# 重启所有服务
docker-compose restart

# 重新构建并启动
docker-compose down && docker-compose up -d --build

# 回滚到上一版本
git checkout HEAD~1 && docker-compose up -d --build
```

## 📞 技术支持

如有问题，请联系：
- 技术文档: docs.yuzhiran.com
- 邮件支持: support@yuzhiran.com
- GitHub Issues: github.com/your-org/yuzhiran-platform/issues

---

**最后更新**: 2026-04-26
**维护人员**: 宇之然技术团队
**版本**: v1.0.0