happy-life-star/web_client/DEPLOYMENT.md

🚀 部署指南

生产环境部署

使用 Gunicorn（推荐）

1. 安装 Gunicorn

pip3 install gunicorn

2. 创建 Gunicorn 配置文件

创建 gunicorn.conf.py:

# Gunicorn配置
bind = "0.0.0.0:5000"
workers = 4
worker_class = "sync"
timeout = 120
keepalive = 5

# 日志
accesslog = "logs/access.log"
errorlog = "logs/error.log"
loglevel = "info"

# 进程命名
proc_name = "ai-assistant-web-client"

# 后台运行
daemon = False

3. 启动服务

# 创建日志目录
mkdir -p logs

# 启动Gunicorn
gunicorn -c gunicorn.conf.py app:app

使用 uWSGI

1. 安装 uWSGI

pip3 install uwsgi

2. 创建 uWSGI 配置文件

创建 uwsgi.ini:

[uwsgi]
module = app:app
master = true
processes = 4
socket = 0.0.0.0:5000
protocol = http
chmod-socket = 660
vacuum = true
die-on-term = true

3. 启动服务

uwsgi --ini uwsgi.ini

Docker 部署

1. 创建 Dockerfile

创建 Dockerfile:

FROM python:3.12-slim

WORKDIR /app

# 复制依赖文件
COPY requirements.txt .

# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt gunicorn

# 复制应用文件
COPY . .

# 暴露端口
EXPOSE 5000

# 启动命令
CMD ["gunicorn", "-b", "0.0.0.0:5000", "-w", "4", "app:app"]

2. 创建 docker-compose.yml

version: '3.8'

services:
  web-client:
    build: .
    ports:
      - "5000:5000"
    environment:
      - DEBUG=False
      - PORT=5000
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped

3. 构建和运行

# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

Nginx 反向代理

配置示例

创建 /etc/nginx/sites-available/ai-assistant-web:

server {
    listen 80;
    server_name your-domain.com;

    # 静态文件
    location /static {
        alias /path/to/web_client/static;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # 代理到Flask应用
    location / {
        proxy_pass http://127.0.0.1:5000;
        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;
        
        # WebSocket支持（如果需要）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

启用配置：

sudo ln -s /etc/nginx/sites-available/ai-assistant-web /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Systemd 服务

创建服务文件

创建 /etc/systemd/system/ai-assistant-web.service:

[Unit]
Description=AI Assistant Web Client
After=network.target

[Service]
Type=notify
User=www-data
Group=www-data
WorkingDirectory=/path/to/web_client
Environment="PATH=/path/to/venv/bin"
ExecStart=/path/to/venv/bin/gunicorn -c gunicorn.conf.py app:app
ExecReload=/bin/kill -s HUP $MAINPID
KillMode=mixed
TimeoutStopSec=5
PrivateTmp=true

[Install]
WantedBy=multi-user.target

管理服务

# 重载systemd配置
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start ai-assistant-web

# 开机自启
sudo systemctl enable ai-assistant-web

# 查看状态
sudo systemctl status ai-assistant-web

# 查看日志
sudo journalctl -u ai-assistant-web -f

性能优化

1. 启用 Gzip 压缩

在 Nginx 配置中添加：

gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain text/css text/xml text/javascript application/javascript application/json;

2. 静态文件缓存

location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

3. 使用 CDN

将静态资源（CSS、JS、字体）托管到CDN。

安全建议

1. 使用 HTTPS

# 使用 Let's Encrypt
sudo certbot --nginx -d your-domain.com

2. 设置安全头

在 Nginx 配置中添加：

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;

3. 限制请求速率

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

location /api/ {
    limit_req zone=api burst=20 nodelay;
}

监控和日志

1. 日志轮转

创建 /etc/logrotate.d/ai-assistant-web:

/path/to/web_client/logs/*.log {
    daily
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 www-data www-data
    sharedscripts
    postrotate
        systemctl reload ai-assistant-web > /dev/null 2>&1 || true
    endscript
}

2. 健康检查

使用 /api/health 端点进行健康检查。

故障排查

查看日志

# Gunicorn日志
tail -f logs/error.log

# Nginx日志
tail -f /var/log/nginx/error.log

# Systemd日志
journalctl -u ai-assistant-web -f

常见问题

1. 502 Bad Gateway - 检查Flask应用是否运行
2. 静态文件404 - 检查Nginx静态文件路径配置
3. CORS错误 - 检查Flask-CORS配置

---

部署成功后，记得测试所有功能！ ✅