ai-chat-ui/docs/cosmic-greeting-lantern.md

多并发支持规划 (100 持续在线用户)

Context

用户需要为 AI Chat UI 项目支持 100 个持续在线用户，需要数据持久化，使用裸机部署 (systemd 服务管理)。

需求确认

• 并发类型: 持续在线 (日常稳定有100个用户在线使用)
• 会话存储: 需要持久化 (支持多实例部署)
• 部署方式: 裸机部署 (systemd 管理)

---

实现方案

阶段 1: 后端多进程支持 (核心)

目标: 使用 Gunicorn + Uvicorn workers 实现多进程

修改文件:

1. server/requirements.txt - 添加 gunicorn
2. 新建 server/gunicorn.conf.py - Gunicorn 配置文件
3. 新建 server/start.sh - 启动脚本

关键配置 (server/gunicorn.conf.py):

import multiprocessing

workers = multiprocessing.cpu_count() * 2 + 1  # 推荐配置
worker_class = "uvicorn.workers.UvicornWorker"
bind = "0.0.0.0:8000"
keepalive = 120
timeout = 300  # AI 响应可能较慢
graceful_timeout = 30

---

阶段 2: 会话持久化 (Redis)

目标: 使用 Redis 替代内存存储，支持多进程共享数据

修改文件:

1. server/requirements.txt - 添加 redis
2. 新建 server/utils/redis_store.py - Redis 存储层
3. 修改 server/api/chat_routes.py - 替换 conversations_db 字典

Redis 数据结构设计:

conversations:{conversation_id} -> JSON (单个对话详情)
conversations:list -> Sorted Set (按更新时间排序的ID列表)

安装 Redis (Ubuntu/Debian):

sudo apt install redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server

---

阶段 3: 请求限流

目标: 防止 API 过载

修改文件:

1. server/requirements.txt - 添加 slowapi
2. 新建 server/middleware/rate_limit.py
3. 修改 server/main.py - 注册限流中间件

限流策略:

• 聊天接口: 30 请求/分钟/IP (长连接场景)
• 其他接口: 100 请求/分钟/IP

---

阶段 4: Systemd 服务配置

新建文件: server/ai-chat.service

[Unit]
Description=AI Chat Backend Service
After=network.target redis.service

[Service]
Type=exec
User=mt
WorkingDirectory=/home/mt/project/ai-chat-ui/server
Environment="PATH=/home/mt/project/ai-chat-ui/server/.venv/bin"
Environment="LLM_BACKEND=glm"
Environment="REDIS_URL=redis://localhost:6379"
ExecStart=/home/mt/project/ai-chat-ui/server/.venv/bin/gunicorn main:app -c gunicorn.conf.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

安装服务:

sudo cp server/ai-chat.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable ai-chat
sudo systemctl start ai-chat

---

阶段 5: Nginx 反向代理 (可选但推荐)

新建文件: nginx/ai-chat.conf

upstream backend {
    server 127.0.0.1:8000;
    keepalive 32;
}

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

    # 前端静态文件
    location /chat-ui/ {
        root /home/mt/project/ai-chat-ui/dist;
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api/ {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # SSE 支持
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }
}

---

关键文件修改清单

文件	操作	说明
server/requirements.txt	修改	添加 gunicorn, redis, slowapi
server/gunicorn.conf.py	新建	多进程配置
server/start.sh	新建	启动脚本
server/utils/redis_store.py	新建	Redis 存储层
server/api/chat_routes.py	修改	集成 Redis 存储
server/middleware/rate_limit.py	新建	限流中间件
server/main.py	修改	注册中间件
server/ai-chat.service	新建	Systemd 服务配置

---

验证方案

1. 服务状态检查:

   sudo systemctl status ai-chat
   curl http://localhost:8000/health
   

2. 并发压测:

   # 安装 wrk
   sudo apt install wrk
   # 测试 100 并发
   wrk -t4 -c100 -d30s http://localhost:8000/api/chat-ui/models
   

3. Redis 验证:

   redis-cli ping
   redis-cli keys "conversations:*"
   

4. 日志监控:

   sudo journalctl -u ai-chat -f
   

---

风险与注意事项

1. SSE 长连接 - Gunicorn 需要配置 keepalive 和 timeout
2. Redis 内存 - 根据对话数量规划，建议至少 512MB
3. API 配额 - 智谱/阿里云 API 有速率限制，注意监控
4. 日志轮转 - 配置 logrotate 防止日志文件过大