256 lines
6.6 KiB
Markdown
256 lines
6.6 KiB
Markdown
# 运行项目与错误修复设计方案
|
|
|
|
## 项目概述
|
|
|
|
LLM Chat Website 是一个基于 Node.js 后端和 Vue.js 前端的全栈聊天应用，使用 pnpm workspace 进行依赖管理。项目采用现代化技术栈，包含完整的聊天功能和大语言模型集成。
|
|
|
|
## 技术架构分析
|
|
|
|
### 后端架构 (Node.js + Express)
|
|
- **框架**: Express.js 4.18.2
|
|
- **数据库**: SQLite3 5.1.6
|
|
- **缓存**: LRU Cache 10.0.1
|
|
- **HTTP客户端**: Axios 1.6.2
|
|
- **开发工具**: Nodemon 3.0.2
|
|
- **端口**: 3000 (默认)
|
|
|
|
### 前端架构 (Vue 3)
|
|
- **框架**: Vue 3.3.8
|
|
- **构建工具**: Vite 5.0.0
|
|
- **UI框架**: Element Plus 2.4.4
|
|
- **状态管理**: Pinia 2.1.7
|
|
- **路由**: Vue Router 4.2.5
|
|
- **端口**: 5173 (默认)
|
|
|
|
### 依赖管理
|
|
- **包管理器**: pnpm (workspace 模式)
|
|
- **配置文件**: pnpm-workspace.yaml
|
|
- **根目录脚本**: concurrently 并发运行前后端
|
|
|
|
## 项目启动流程设计
|
|
|
|
### 启动顺序架构
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[检查 pnpm 安装] --> B[验证 workspace 配置]
|
|
B --> C[检查依赖安装状态]
|
|
C --> D[启动后端服务]
|
|
D --> E[初始化数据库]
|
|
E --> F[启动前端服务]
|
|
F --> G[验证服务通信]
|
|
G --> H[功能验证测试]
|
|
```
|
|
|
|
### 环境变量配置架构
|
|
|
|
| 变量名 | 默认值 | 说明 |
|
|
|--------|--------|------|
|
|
| PORT | 3000 | 后端服务端口 |
|
|
| NODE_ENV | development | 运行环境 |
|
|
| LLM_API_KEY | - | 大语言模型API密钥 |
|
|
| LLM_API_BASE_URL | https://api.openai.com/v1 | API基础地址 |
|
|
| LLM_MODEL | gpt-3.5-turbo | 使用的模型 |
|
|
| CORS_ORIGIN | http://localhost:5173 | 跨域设置 |
|
|
|
|
## 潜在错误分析与解决方案
|
|
|
|
### 数据库初始化错误
|
|
|
|
**错误场景**: SQLite 数据库文件不存在或权限问题
|
|
```mermaid
|
|
flowchart LR
|
|
A[数据库连接失败] --> B{检查文件权限}
|
|
B -->|权限正常| C[创建数据库目录]
|
|
B -->|权限异常| D[修复文件权限]
|
|
C --> E[执行 schema.sql]
|
|
D --> E
|
|
E --> F[验证表结构]
|
|
```
|
|
|
|
**解决策略**:
|
|
1. 确保 backend/database 目录存在且可写
|
|
2. 自动创建数据库文件
|
|
3. 执行 schema.sql 初始化表结构
|
|
4. 验证示例数据插入
|
|
|
|
### 端口冲突错误
|
|
|
|
**错误场景**: 3000 或 5173 端口被占用
|
|
```mermaid
|
|
graph TD
|
|
A[启动失败] --> B{检查端口占用}
|
|
B -->|端口被占用| C[终止占用进程]
|
|
B -->|端口正常| D[检查其他配置]
|
|
C --> E[重新启动服务]
|
|
D --> F[排查网络配置]
|
|
```
|
|
|
|
**解决策略**:
|
|
1. 检测端口占用情况
|
|
2. 提供端口配置选项
|
|
3. 实现优雅的端口切换
|
|
|
|
### LLM API 配置错误
|
|
|
|
**错误模式**:
|
|
- API_KEY 未配置或无效
|
|
- 网络连接问题
|
|
- 请求频率限制
|
|
|
|
**修复流程**:
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant App as 应用
|
|
participant Config as 配置验证
|
|
participant LLM as LLM服务
|
|
|
|
App->>Config: 验证API配置
|
|
Config->>Config: 检查必要环境变量
|
|
alt 配置缺失
|
|
Config->>App: 返回警告信息
|
|
App->>App: 使用默认配置
|
|
else 配置完整
|
|
Config->>LLM: 测试连接
|
|
LLM->>Config: 返回连接状态
|
|
end
|
|
```
|
|
|
|
### 前端构建错误
|
|
|
|
**常见问题**:
|
|
1. 依赖版本冲突
|
|
2. 样式预处理器错误
|
|
3. TypeScript 类型检查错误
|
|
|
|
**解决方案架构**:
|
|
- 依赖冲突: 使用 pnpm 的严格依赖解析
|
|
- 样式错误: 验证 SCSS 变量文件路径
|
|
- 类型错误: 配置 unplugin-auto-import
|
|
|
|
## 服务启动验证策略
|
|
|
|
### 后端健康检查
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[GET /] --> B{响应状态}
|
|
B -->|200| C[服务正常]
|
|
B -->|非200| D[服务异常]
|
|
|
|
E[GET /api] --> F{API状态}
|
|
F -->|可访问| G[API正常]
|
|
F -->|不可访问| H[API异常]
|
|
```
|
|
|
|
### 前端资源加载验证
|
|
|
|
**验证点**:
|
|
1. 静态资源加载 (CSS, JS)
|
|
2. Vue 应用挂载成功
|
|
3. Element Plus 组件正常渲染
|
|
4. 路由导航功能
|
|
|
|
### 前后端通信验证
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant F as Frontend
|
|
participant P as Proxy
|
|
participant B as Backend
|
|
|
|
F->>P: 发送 /api 请求
|
|
P->>B: 转发到 localhost:3000
|
|
B->>P: 返回响应
|
|
P->>F: 返回结果
|
|
|
|
Note over F,B: 验证 CORS 配置
|
|
Note over F,B: 验证代理设置
|
|
```
|
|
|
|
## 功能验证测试方案
|
|
|
|
### 核心功能测试架构
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[页面加载测试] --> B[创建新对话]
|
|
B --> C[发送消息测试]
|
|
C --> D[接收响应测试]
|
|
D --> E[对话历史测试]
|
|
E --> F[UI交互测试]
|
|
```
|
|
|
|
### 测试用例设计
|
|
|
|
| 测试项 | 验证内容 | 期望结果 |
|
|
|--------|----------|----------|
|
|
| 页面访问 | http://localhost:5173 | 页面正常加载 |
|
|
| 新建对话 | 点击新建对话按钮 | 创建空白对话界面 |
|
|
| 消息发送 | 输入测试消息并发送 | 消息显示在界面 |
|
|
| API通信 | 后端接收并处理请求 | 返回预期响应 |
|
|
| 历史记录 | 查看对话历史 | 正确显示历史对话 |
|
|
|
|
## 错误监控与日志策略
|
|
|
|
### 日志架构设计
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[请求日志] --> D[Morgan中间件]
|
|
B[错误日志] --> E[自定义ErrorHandler]
|
|
C[应用日志] --> F[Console Logger]
|
|
|
|
D --> G[请求统计]
|
|
E --> H[错误追踪]
|
|
F --> I[调试信息]
|
|
```
|
|
|
|
### 监控指标
|
|
|
|
- **性能指标**: 响应时间、内存使用、CPU占用
|
|
- **错误指标**: 错误率、异常类型、失败请求
|
|
- **业务指标**: API调用次数、用户会话数
|
|
|
|
## 部署前置条件检查
|
|
|
|
### 环境依赖验证
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[Node.js 版本] -->|>=16.0.0| B[pnpm 安装]
|
|
B --> C[workspace 配置]
|
|
C --> D[依赖安装状态]
|
|
D --> E[环境变量配置]
|
|
E --> F[网络连接测试]
|
|
F --> G[启动准备就绪]
|
|
```
|
|
|
|
### 配置文件验证
|
|
|
|
1. **package.json**: 验证脚本配置和依赖版本
|
|
2. **pnpm-workspace.yaml**: 确认 workspace 配置格式
|
|
3. **vite.config.js**: 验证构建和代理配置
|
|
4. **.env**: 检查必要环境变量
|
|
|
|
## 故障排除指南
|
|
|
|
### 常见问题快速诊断
|
|
|
|
| 问题类型 | 症状 | 诊断步骤 | 解决方案 |
|
|
|----------|------|----------|----------|
|
|
| 依赖问题 | 模块找不到 | 检查 node_modules | 重新安装依赖 |
|
|
| 端口冲突 | EADDRINUSE | 检查端口占用 | 更换端口或终止进程 |
|
|
| 数据库错误 | 连接失败 | 检查文件权限 | 重新初始化数据库 |
|
|
| API调用失败 | 网络错误 | 检查配置和网络 | 修复配置或网络问题 |
|
|
| 前端白屏 | 页面不显示 | 检查控制台错误 | 修复组件或路由错误 |
|
|
|
|
### 调试工具配置
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[后端调试] --> B[nodemon + console.log]
|
|
C[前端调试] --> D[Vue DevTools]
|
|
E[网络调试] --> F[浏览器 Network 面板]
|
|
G[数据库调试] --> H[SQLite 命令行工具]
|
|
``` |