一、 技术栈分析

1.1 后端 (Backend)

后端架构特点：

• SSE (Server-Sent Events) 流式输出，StreamingResponse + text/event-stream
• 三层路由：/api/chat、/api/conversations、/api/roles
• 数据库自动初始化 + 种子数据（seed_roles）
• 会话管理：自动创建/复用会话，消息历史轮次限制

1.2 前端 (Frontend)

前端架构特点： - Vite 代理 /api → http://127.0.0.1:8000，SSE 响应头防缓冲处理 - 微信风格 UI：绿色气泡、左滑删除、打字指示器 - 自定义 Markdown 渲染：代码块保护 → 行内代码 → HTML 转义 → 格式替换 → 段落包裹 - 触摸 + 鼠标双端滑动事件支持

1.3 数据流

用户输入 → Pinia Store → XMLHttpRequest SSE POST /api/chat/stream
                                    ↓
                        Vite Proxy (5173 → 8000)
                                    ↓
                        FastAPI StreamingResponse
                                    ↓
                        chat_service → doubao_service
                                    ↓
                        httpx → 豆包 API (SSE 流式)
                                    ↓
                        delta/done/error 事件逐行返回
                                    ↓
                        XHR onprogress → appendStreamDelta → Vue 响应式更新

项目的 AI 调用层已经兼容 OpenAI Chat Completions 格式（/chat/completions + Authorization: Bearer + choices[0].delta.content），所以切换到任何兼容此格式的 API 只需修改 .env 配置。

二、 AI 接口配置

编辑 backend/.env 文件，修改以下三个关键字段：

配置项说明

1. 切换到 OpenAI

DOUBAO_API_KEY=sk-你的OpenAI密钥
DOUBAO_API_URL=https://api.openai.com/v1/chat/completions
DOUBAO_MODEL=gpt-4o
DOUBAO_ENDPOINT_ID=

2. 切换到 DeepSeek

DOUBAO_API_KEY=sk-你的DeepSeek密钥
DOUBAO_API_URL=https://api.deepseek.com/v1/chat/completions
DOUBAO_MODEL=deepseek-chat
DOUBAO_ENDPOINT_ID=

3. 切换到其他兼容 API（如通义千问、Kimi、本地 Ollama 等）

# 通义千问
DOUBAO_API_KEY=sk-你的密钥
DOUBAO_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
DOUBAO_MODEL=qwen-plus
DOUBAO_ENDPOINT_ID=

# Kimi (Moonshot)
DOUBAO_API_KEY=sk-你的密钥
DOUBAO_API_URL=https://api.moonshot.cn/v1/chat/completions
DOUBAO_MODEL=moonshot-v1-8k
DOUBAO_ENDPOINT_ID=

# 本地 Ollama
DOUBAO_API_KEY=ollama
DOUBAO_API_URL=http://127.0.0.1:11434/v1/chat/completions
DOUBAO_MODEL=llama3
DOUBAO_ENDPOINT_ID=

修改 .env 后重启后端即可生效（uvicorn --reload 模式下修改 .env 不会自动重载，需手动重启）。

三、 Linux 云服务器部署流程

1. 服务器准备

sudo apt update && sudo apt install -y python3 python3-pip python3-venv nodejs npm nginx git

# Python 3.11+（如果系统版本低）
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install -y python3.11 python3.11-venv python3.11-dev

2. 上传项目

cd /opt
git clone <你的仓库地址> uniapp

3. 后端部署

cd /opt/uniapp/backend

python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cp .env .env.production
vim .env.production

# 修改 DOUBAO_API_KEY、DOUBAO_MODEL 等

# 测试启动
uvicorn main:app --host 127.0.0.1 --port 8000

4. 前端构建

cd /opt/uniapp/uniapp-im
npm install
npm run build:h5

构建产物在 dist/build/h5/，纯静态文件，由 Nginx 托管。

5. Nginx 配置

# /etc/nginx/sites-available/uniapp-im
server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /opt/uniapp/uniapp-im/dist/build/h5;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # SSE 关键配置
        proxy_http_version 1.1;
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }
}

sudo ln -s /etc/nginx/sites-available/uniapp-im /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

6. 后端进程管理（Systemd + Uvicorn）

SSE 流式输出依赖 ASGI 协议，必须使用 Uvicorn 而非 WSGI 服务器。

# /etc/systemd/system/uniapp-backend.service
[Unit]
Description=UniApp IM Chat Backend
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/uniapp/backend
EnvironmentFile=/opt/uniapp/backend/.env.production
ExecStart=/opt/uniapp/backend/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 --workers 2
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable uniapp-backend
sudo systemctl start uniapp-backend

# 查看状态 / 日志
sudo systemctl status uniapp-backend
sudo journalctl -u uniapp-backend -f

Uvicorn 多进程说明： --workers N 启动 N 个工作进程，每个进程独立持有 SQLite 连接。如果并发高需换 PostgreSQL，SQLite 写锁会限制多 worker 写入性能。

7. HTTPS（可选但推荐）

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
sudo certbot renew --dry-run

8. 防火墙

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

四、整体架构

用户浏览器
    ↓ HTTPS (443)
  Nginx
    ├── /          → 静态文件 (dist/build/h5)
    └── /api/*     → proxy_pass → Uvicorn ASGI (127.0.0.1:8000)
                                      ↓
                                   豆包/OpenAI API

五、关键注意事项

• SSE 必须用 ASGI：Uvicorn 原生支持异步长连接，WSGI（如 Gunicorn sync worker）会阻塞 SSE 流式输出
• Nginx 必须关闭缓冲：proxy_buffering off + proxy_cache off + proxy_http_version 1.1 + Connection ''，否则流式输出被缓冲成一次性返回
• proxy_read_timeout 300s：AI 响应可能较慢，避免 Nginx 超时断开
• 生产环境不要用 --reload：仅开发用，生产用 --workers 2 多进程
• SQLite 适合小规模：多 worker 并发写入受限，高并发换 PostgreSQL，改 DATABASE_URL 即可

六、截目截图