# chat

**Repository Path**: Blue_Pepsi_Cola/chat

## Basic Information

- **Project Name**: chat
- **Description**: 做一个agent开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 豆包 AI 助手

> 仿豆包风格的 AI 对话助手，支持流式输出 · 三层记忆系统 · 多会话历史
>
> **技术栈**：Python FastAPI · 阿里云通义千问 qwen-max · MySQL 8.0 · Vue 3 · Pinia · Vite

---

## 目录

1. [功能特性](#一功能特性)
2. [架构概览](#二架构概览)
3. [启动前准备](#三启动前准备)
4. [数据库建表](#四数据库建表)
5. [本地开发启动](#五本地开发启动)
6. [生产环境部署](#六生产环境部署)
7. [目录结构](#七目录结构)
8. [API 接口一览](#八api-接口一览)
9. [记忆功能说明](#九记忆功能说明)
10. [常见问题](#十常见问题)

---

## 一、功能特性

| 功能 | 说明 |
|---|---|
| 流式输出 | SSE 逐 token 实时渲染，打字机效果 |
| 历史对话 | 左侧边栏展示所有会话，支持切换 / 重命名 / 删除 |
| 三层记忆 | 工作记忆（会话内）· 情节记忆 · 语义记忆（跨会话持久化） |
| 记忆中心 | 右侧抽屉查看、按类型筛选、删除记忆条目 |
| 自动命名 | 首轮对话后自动提取用户第一句作为会话标题 |
| Markdown | AI 回复支持代码高亮、表格、列表等富文本渲染 |

---

## 二、架构概览

```
┌─────────────────────────────────────────────────────────┐
│                      浏览器（Vue 3）                     │
│  ┌──────────┐  ┌─────────────────┐  ┌────────────────┐  │
│  │ Sidebar  │  │   ChatArea      │  │ MemoryDrawer   │  │
│  │ 历史会话  │  │ 消息列表+输入框  │  │  记忆中心抽屉   │  │
│  └──────────┘  └─────────────────┘  └────────────────┘  │
│                    Pinia Store（全局状态）                 │
└───────────────────────┬─────────────────────────────────┘
                        │ HTTP / SSE
┌───────────────────────▼─────────────────────────────────┐
│                 FastAPI 后端（Python）                    │
│  ┌──────────────────┐    ┌──────────────────────────┐   │
│  │ ConversationStore│    │     MemoryManager         │   │
│  │  sessions/msgs   │    │ working/episodic/semantic  │   │
│  └────────┬─────────┘    └────────────┬──────────────┘   │
│           │                           │                   │
│           └──────────┬────────────────┘                   │
│                      │ PyMySQL                            │
│              ┌───────▼────────┐                           │
│              │   MySQL 8.0    │                           │
│              │ sessions       │                           │
│              │ messages       │                           │
│              │ memories       │                           │
│              └────────────────┘                           │
│                                                           │
│  阿里云 DashScope ──► qwen-max（OpenAI 兼容接口）          │
└───────────────────────────────────────────────────────────┘
```

---

## 三、启动前准备

### 1. 环境依赖版本要求

| 依赖 | 最低版本 | 检查命令 |
|---|---|---|
| Python | 3.11 | `python3 --version` |
| Node.js | 18 | `node --version` |
| npm | 9 | `npm --version` |
| MySQL | 8.0 | `mysql --version` |

### 2. 获取阿里云 DashScope API Key

1. 打开 [阿里云百炼控制台](https://bailian.console.aliyun.com/)
2. 注册/登录阿里云账号，开通百炼服务
3. 左侧菜单 → **API-KEY 管理** → **创建 API-KEY**
4. 复制 Key，格式为 `sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

> 首次使用有免费额度，超额后需充值。

### 3. 安装并启动 MySQL

**方式 A：Homebrew（macOS 本地开发推荐）**

```bash
brew install mysql@8.0
brew services start mysql@8.0
# 初始化安全配置（设置 root 密码、删除匿名用户等）
mysql_secure_installation
```

**方式 B：Docker（最快，跨平台）**

```bash
docker run -d \
  --name chat-mysql \
  -e MYSQL_ROOT_PASSWORD=Chat@2024 \
  -e MYSQL_DATABASE=chat_db \
  -p 3306:3306 \
  --restart unless-stopped \
  mysql:8.0 \
  --character-set-server=utf8mb4 \
  --collation-server=utf8mb4_unicode_ci
```

验证连接是否正常：

```bash
mysql -h 127.0.0.1 -u root -p -e "SELECT VERSION();"
```

> **注意**：数据库 `chat_db` 无需手动创建，后端首次启动时会自动创建。

---

## 四、数据库建表

> **自动建表**：后端启动时会自动执行建库建表，通常**无需手动操作**。
> 以下 SQL 供手动初始化、迁移或核查表结构时使用。

### 4.1 创建数据库

```sql
-- 创建数据库，指定字符集（支持中文和 emoji）
CREATE DATABASE IF NOT EXISTS chat_db
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

USE chat_db;
```

### 4.2 sessions 表（会话元信息）

```sql
-- 会话表：存储每个对话会话的元信息
-- 列表按 updated_at DESC 排序，确保最近活跃的会话排在最上面
CREATE TABLE IF NOT EXISTS sessions (
    id         VARCHAR(36)  NOT NULL  COMMENT 'UUID 主键，全局唯一',
    title      VARCHAR(255) NOT NULL  COMMENT '会话标题，首轮对话后自动更新',
    created_at DATETIME     NOT NULL  COMMENT '会话创建时间',
    updated_at DATETIME     NOT NULL  COMMENT '最后活跃时间，列表排序依据',
    PRIMARY KEY (id)
) ENGINE=InnoDB
  DEFAULT CHARSET=utf8mb4
  COLLATE=utf8mb4_unicode_ci
  COMMENT='对话会话元信息表';
```

### 4.3 messages 表（聊天消息）

```sql
-- 消息表：存储每条聊天记录
-- session_id 关联 sessions.id，删除会话时需先删除该会话的所有消息
CREATE TABLE IF NOT EXISTS messages (
    id         VARCHAR(36) NOT NULL  COMMENT 'UUID 主键',
    session_id VARCHAR(36) NOT NULL  COMMENT '所属会话 ID，关联 sessions.id',
    role       VARCHAR(16) NOT NULL  COMMENT '发言角色：user / assistant',
    content    LONGTEXT    NOT NULL  COMMENT '消息正文，LONGTEXT 支持超长内容',
    created_at DATETIME    NOT NULL  COMMENT '消息时间，按此字段正序展示',
    PRIMARY KEY (id),
    INDEX idx_msg_session (session_id) COMMENT '按会话查消息的加速索引'
) ENGINE=InnoDB
  DEFAULT CHARSET=utf8mb4
  COLLATE=utf8mb4_unicode_ci
  COMMENT='聊天消息表';
```

### 4.4 memories 表（记忆系统）

```sql
-- 记忆表：持久化情节记忆和语义记忆（工作记忆存进程内存，不入库）
-- importance 字段用于检索时的排序权重，越高越优先召回
CREATE TABLE IF NOT EXISTS memories (
    id          VARCHAR(36)  NOT NULL             COMMENT 'UUID 主键',
    user_id     VARCHAR(64)  NOT NULL             COMMENT '用户标识，多用户隔离',
    session_id  VARCHAR(36)  NOT NULL             COMMENT '产生该记忆的来源会话 ID',
    memory_type VARCHAR(16)  NOT NULL             COMMENT '记忆类型：episodic / semantic',
    content     LONGTEXT     NOT NULL             COMMENT '记忆文本内容',
    importance  DECIMAL(4,3) NOT NULL DEFAULT 0.5 COMMENT '重要性分数 [0.000, 1.000]',
    metadata    TEXT         NOT NULL DEFAULT '{}' COMMENT '扩展元数据（JSON 字符串）',
    timestamp   DATETIME     NOT NULL             COMMENT '记忆创建时刻',
    PRIMARY KEY (id),
    INDEX idx_user    (user_id)     COMMENT '按用户隔离查询',
    INDEX idx_type    (memory_type) COMMENT '按记忆类型过滤',
    INDEX idx_session (session_id)  COMMENT '按来源会话追溯'
) ENGINE=InnoDB
  DEFAULT CHARSET=utf8mb4
  COLLATE=utf8mb4_unicode_ci
  COMMENT='AI 记忆系统持久化表';
```

### 4.5 一键执行全部建表 SQL

将以上 SQL 保存为文件后批量执行：

```bash
# 将 4.1~4.4 的 SQL 保存到文件
mysql -h 127.0.0.1 -u root -p < init.sql

# 验证建表结果
mysql -h 127.0.0.1 -u root -p chat_db -e "SHOW TABLES; SHOW TABLE STATUS\G"
```

### 4.6 重置数据库（清空所有数据）

```bash
mysql -h 127.0.0.1 -u root -p -e "DROP DATABASE IF EXISTS chat_db;"
# 重启后端后会自动重建数据库和表
```

---

## 五、本地开发启动

### 方式 A：一键脚本（推荐）

```bash
cd /Users/fanzhen/Documents/chat

# 设置必要的环境变量
export DASHSCOPE_API_KEY=sk-你的Key
export MYSQL_PASSWORD=你的MySQL密码     # root 无密码时可省略

# 执行启动脚本（首次运行会自动安装所有依赖）
./start.sh
```

脚本输出示意：

```
=== 豆包 AI 助手启动 ===

📦 MySQL 连接配置：
   Host : 127.0.0.1
   Port : 3306
   User : root
   DB   : chat_db

▶  启动后端 (http://localhost:8000)...
   后端 PID: 12345
▶  启动前端 (http://localhost:5173)...
   前端 PID: 12346

✅ 启动完成！
   前端：http://localhost:5173
   后端：http://localhost:8000
   文档：http://localhost:8000/docs
```

浏览器打开 **http://localhost:5173** 即可使用，按 `Ctrl+C` 停止。

---

### 方式 B：分步手动启动

**终端 1 — 启动后端：**

```bash
cd /Users/fanzhen/Documents/chat/backend

# 创建并激活虚拟环境（首次执行）
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖（首次执行）
pip install -r requirements.txt

# 配置环境变量
export DASHSCOPE_API_KEY=sk-你的Key
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=你的MySQL密码
export MYSQL_DB=chat_db

# 启动（开发模式，代码修改后自动重载）
python3 main.py
```

后端启动成功标志：

```
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```

**终端 2 — 启动前端：**

```bash
cd /Users/fanzhen/Documents/chat/frontend

# 安装依赖（首次执行）
npm install

# 启动开发服务器（支持热更新）
npm run dev
```

前端启动成功标志：

```
  VITE v5.x.x  ready in xxx ms
  ➜  Local:   http://localhost:5173/
```

---

### 环境变量参考

| 变量名 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
| `DASHSCOPE_API_KEY` | **必填** | — | 阿里云百炼 API Key |
| `MYSQL_HOST` | 可选 | `127.0.0.1` | MySQL 主机地址 |
| `MYSQL_PORT` | 可选 | `3306` | MySQL 端口 |
| `MYSQL_USER` | 可选 | `root` | MySQL 用户名 |
| `MYSQL_PASSWORD` | 可选 | 空字符串 | MySQL 密码 |
| `MYSQL_DB` | 可选 | `chat_db` | 数据库名（不存在时自动创建） |

写入 Shell 配置文件避免每次手动 export：

```bash
# zsh（macOS 默认）
cat >> ~/.zshrc << 'EOF'
export DASHSCOPE_API_KEY=sk-你的Key
export MYSQL_PASSWORD=你的MySQL密码
EOF
source ~/.zshrc
```

---

## 六、生产环境部署

生产部署推荐方案：**Nginx 反向代理 + Gunicorn 运行后端 + 前端静态文件托管**

```
用户浏览器
    │
    ▼
 Nginx（80/443）
    ├── /         → 前端静态文件（dist/）
    └── /api/     → 反向代理到 Gunicorn（127.0.0.1:8000）
                          │
                          ▼
                   FastAPI 应用（Gunicorn + uvicorn workers）
                          │
                          ▼
                      MySQL 8.0
```

### 6.1 服务器环境准备

```bash
# Ubuntu 22.04 示例
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3-pip nodejs npm nginx mysql-server

# 启动并设置 MySQL 开机自启
sudo systemctl start mysql
sudo systemctl enable mysql

# 安全初始化 MySQL
sudo mysql_secure_installation
```

### 6.2 创建 MySQL 生产用户（勿用 root）

```sql
-- 登录 MySQL
-- sudo mysql -u root -p

-- 创建专用数据库用户（替换 Chat@Prod2024 为强密码）
CREATE USER 'chatapp'@'localhost' IDENTIFIED BY 'Chat@Prod2024';
CREATE DATABASE IF NOT EXISTS chat_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON chat_db.* TO 'chatapp'@'localhost';
FLUSH PRIVILEGES;
```

### 6.3 部署后端

```bash
# 上传代码到服务器（示例使用 /opt/chat）
sudo mkdir -p /opt/chat
sudo chown $USER:$USER /opt/chat
git clone <your-repo-url> /opt/chat   # 或 scp/rsync 上传

cd /opt/chat/backend

# 创建虚拟环境并安装依赖
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 额外安装 Gunicorn
pip install gunicorn
```

创建 `.env` 文件存储生产环境变量（**不要提交到 Git**）：

```bash
cat > /opt/chat/backend/.env << 'EOF'
DASHSCOPE_API_KEY=sk-你的生产Key
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=chatapp
MYSQL_PASSWORD=Chat@Prod2024
MYSQL_DB=chat_db
EOF
chmod 600 /opt/chat/backend/.env   # 限制文件权限，仅 owner 可读
```

创建 systemd 服务文件（开机自启、崩溃自动重启）：

```bash
sudo tee /etc/systemd/system/chatapp.service << 'EOF'
[Unit]
Description=豆包 AI 助手后端服务
After=network.target mysql.service
Requires=mysql.service

[Service]
Type=exec
User=www-data
Group=www-data
WorkingDirectory=/opt/chat/backend
# 从 .env 文件加载环境变量
EnvironmentFile=/opt/chat/backend/.env
# Gunicorn 启动：4 个 uvicorn worker 进程，监听本地 8000 端口
ExecStart=/opt/chat/backend/.venv/bin/gunicorn \
    main:app \
    --worker-class uvicorn.workers.UvicornWorker \
    --workers 4 \
    --bind 127.0.0.1:8000 \
    --timeout 120 \
    --access-logfile /var/log/chatapp/access.log \
    --error-logfile /var/log/chatapp/error.log
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# 创建日志目录
sudo mkdir -p /var/log/chatapp
sudo chown www-data:www-data /var/log/chatapp

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable chatapp
sudo systemctl start chatapp

# 查看状态
sudo systemctl status chatapp
```

### 6.4 构建前端静态文件

```bash
cd /opt/chat/frontend

# 安装依赖
npm install

# 构建生产版本（输出到 dist/ 目录）
npm run build

# 验证构建产物
ls -lh dist/
```

### 6.5 配置 Nginx

```bash
sudo tee /etc/nginx/sites-available/chatapp << 'EOF'
server {
    listen 80;
    server_name your-domain.com;   # 替换为你的域名或服务器 IP

    # ── 前端静态文件 ──────────────────────────────────
    root /opt/chat/frontend/dist;
    index index.html;

    # Vue Router history 模式：未匹配路径一律返回 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # ── 后端 API 反向代理 ──────────────────────────────
    location /api/ {
        proxy_pass         http://127.0.0.1:8000;
        proxy_http_version 1.1;

        # SSE（流式聊天）必要配置：禁用缓冲，保证 token 实时推送
        proxy_buffering    off;
        proxy_cache        off;
        proxy_read_timeout 300s;   # 流式响应超时时间，需大于最长回复时间

        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;
        proxy_set_header Connection        '';   # SSE 长连接
    }

    # ── 静态资源缓存（JS/CSS/图片）────────────────────
    location ~* \.(js|css|png|jpg|gif|ico|woff2?)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # ── 日志 ──────────────────────────────────────────
    access_log /var/log/nginx/chatapp_access.log;
    error_log  /var/log/nginx/chatapp_error.log;
}
EOF

# 启用站点
sudo ln -sf /etc/nginx/sites-available/chatapp /etc/nginx/sites-enabled/
sudo nginx -t          # 检查配置语法
sudo systemctl reload nginx
```

### 6.6 配置 HTTPS（推荐）

```bash
# 安装 Certbot
sudo apt install -y certbot python3-certbot-nginx

# 自动申请并配置 Let's Encrypt 免费证书
sudo certbot --nginx -d your-domain.com

# 证书自动续期（Certbot 已自动配置 cron，此处验证）
sudo certbot renew --dry-run
```

### 6.7 生产运维常用命令

```bash
# 查看后端服务状态
sudo systemctl status chatapp

# 重启后端（代码更新后）
sudo systemctl restart chatapp

# 实时查看后端日志
sudo journalctl -u chatapp -f
# 或查看文件日志
sudo tail -f /var/log/chatapp/error.log

# 前端代码更新后重新构建并生效（Nginx 自动服务新文件，无需重启）
cd /opt/chat/frontend && npm run build

# 查看 Nginx 错误日志
sudo tail -f /var/log/nginx/chatapp_error.log

# 测试后端健康状态
curl http://127.0.0.1:8000/api/health
```

---

## 七、目录结构

```
chat/
├── start.sh                      # 一键本地启动脚本
├── README.md                     # 本文档
│
├── backend/                      # Python 后端
│   ├── main.py                   # FastAPI 主入口（路由 + 流式聊天）
│   ├── conversation_store.py     # 对话历史 MySQL 存储层
│   ├── requirements.txt          # Python 依赖（openai + pymysql + fastapi）
│   ├── .venv/                    # Python 虚拟环境（自动创建，勿提交 Git）
│   └── memory/                   # 记忆系统模块
│       ├── __init__.py           # 模块导出
│       ├── base.py               # MemoryItem 数据结构
│       └── manager.py            # 三层记忆管理器（MySQL 存储）
│
└── frontend/                     # Vue 3 前端
    ├── index.html                # HTML 入口
    ├── vite.config.js            # Vite 配置（开发代理 /api → 8000）
    ├── package.json              # npm 依赖声明
    └── src/
        ├── main.js               # Vue 应用挂载入口
        ├── App.vue               # 根组件（三栏布局框架）
        ├── style.css             # 全局 CSS 变量和 Markdown 样式
        ├── api.js                # HTTP 请求封装（axios + Fetch SSE）
        ├── stores/
        │   └── chat.js           # Pinia 全局状态（会话、消息、记忆）
        └── components/
            ├── Sidebar.vue       # 左侧边栏（历史会话列表 + 记忆统计）
            ├── ChatArea.vue      # 聊天主区域（消息气泡 + 输入框）
            └── MemoryDrawer.vue  # 右侧记忆中心抽屉
```

---

## 八、API 接口一览

后端运行后访问 **http://localhost:8000/docs** 查看交互式 Swagger 文档。

| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/api/sessions` | 创建新会话 |
| `GET` | `/api/sessions` | 获取所有会话列表（按最后活跃时间倒序） |
| `GET` | `/api/sessions/{id}` | 获取单个会话元信息 |
| `PUT` | `/api/sessions/{id}/title` | 重命名会话 |
| `DELETE` | `/api/sessions/{id}` | 删除会话及其所有消息 |
| `GET` | `/api/sessions/{id}/messages` | 获取会话完整消息历史 |
| `POST` | `/api/chat` | 流式聊天（SSE，返回增量文本） |
| `GET` | `/api/memories` | 获取记忆列表（`?type=episodic\|semantic`） |
| `GET` | `/api/memories/stats` | 获取三类记忆数量统计 |
| `DELETE` | `/api/memories/{id}` | 删除单条记忆 |
| `GET` | `/api/health` | 健康检查（返回服务状态和模型名） |

---

## 九、记忆功能说明

### 记忆类型对比

| 类型 | 存储位置 | 生命周期 | 典型触发内容 | 容量上限 |
|---|---|---|---|---|
| 工作记忆（working） | 进程内存 | 会话期间，重启后清除 | AI 回复摘要、当轮上下文 | 每会话 20 条 |
| 情节记忆（episodic） | MySQL | 永久，直到手动删除 | "昨天我去了北京"、"上次我说的那件事" | 无限制 |
| 语义记忆（semantic） | MySQL | 永久，直到手动删除 | "我叫小明"、"我喜欢喝咖啡" | 无限制 |

### 记忆写入流程

```
用户发送消息
    │
    ├─► _classify(content) ──► episodic / semantic / working
    │
    ├─► episodic / semantic → 写入 MySQL memories 表
    │
    └─► working → 追加到进程内存（滑动窗口，最多 20 条）
```

### 记忆检索流程

```
接收用户查询
    │
    ├─► 工作记忆：字符/词级关键词打分 → top-4
    │
    ├─► MySQL：按 importance DESC / timestamp DESC 取 50 条
    │           关键词重叠度 × importance 重排 → top-N
    │
    └─► 合并去重 → 拼接到用户消息末尾（[记忆参考] 块）→ 传给 Qwen
```

---

## 十、常见问题

### Q: 后端启动报 `Can't connect to MySQL server`？

```bash
# 检查 MySQL 是否在运行
sudo systemctl status mysql         # Linux
brew services list | grep mysql     # macOS

# 手动启动
sudo systemctl start mysql          # Linux
brew services start mysql           # macOS

# 验证能否连接
mysql -h 127.0.0.1 -u root -p -e "SELECT 1;"
```

### Q: 发消息后提示 `[错误]`？

按以下步骤逐一排查：

```bash
# 1. 确认后端运行正常
curl http://localhost:8000/api/health

# 2. 确认 API Key 已设置
echo $DASHSCOPE_API_KEY

# 3. 查看后端实时日志
# 本地：后端终端直接看输出
# 生产：sudo journalctl -u chatapp -f --since "5 min ago"
```

### Q: SSE 流式输出在生产环境不生效（回复一次性出现）？

检查 Nginx 配置是否包含以下指令：

```nginx
proxy_buffering    off;
proxy_cache        off;
proxy_read_timeout 300s;
```

### Q: 端口被占用？

```bash
lsof -i :8000    # 查找占用后端端口的进程
lsof -i :5173    # 查找占用前端端口的进程
kill -9 <PID>
```

### Q: pip install 速度慢？

```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### Q: npm install 速度慢？

```bash
npm install --registry https://registry.npmmirror.com
```

### Q: 生产环境前端请求 /api 报 404？

检查 Nginx 的 `location /api/` 是否配置了 `proxy_pass http://127.0.0.1:8000;`，以及后端 systemd 服务是否在运行：

```bash
sudo systemctl status chatapp
curl http://127.0.0.1:8000/api/health   # 直接测试后端，绕过 Nginx
```