yu-zhi-ran/platform/DEPLOYMENT_GUIDE.md

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

🚀 快速开始

1. 克隆项目

git clone https://github.com/your-org/yuzhiran-platform.git
cd yuzhiran-platform

2. 启动服务

docker-compose up -d

3. 验证部署

# 检查服务状态
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	缓存

🛠️ 开发环境部署

方法一：直接运行（推荐用于开发）

# 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开发模式

# 启用开发模式（热重载）
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

一键部署脚本

#!/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监控

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

日志管理

# 查看所有容器日志
docker-compose logs

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

# 清理旧日志
docker system prune -f

🔐 安全加固

1. SSL证书

# 使用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. 防火墙配置

# 仅开放必要端口
ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP
ufw allow 443/tcp   # HTTPS
ufw enable

3. 定期备份

#!/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. 数据库优化

-- 添加更多索引
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. 应用层优化

# 添加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优化

# 增加worker进程数
worker_processes auto;

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

# 启用HTTP/2
listen 443 ssl http2;

🚨 故障排除

常见问题

1. 容器启动失败

   # 查看详细错误
   docker-compose logs app
   
   # 检查端口冲突
   netstat -tulpn | grep :8001
   

2. 数据库连接失败

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

3. 前端无法访问API

   # 检查CORS配置
   curl -v http://localhost:8001/api/system/status
   
   # 检查Nginx配置
   docker-compose exec nginx nginx -t
   

紧急恢复

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