6.6 KiB

Raw Permalink Blame History

运行项目与错误修复设计方案

项目概述

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 并发运行前后端

项目启动流程设计

启动顺序架构

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 数据库文件不存在或权限问题

flowchart LR
    A[数据库连接失败] --> B{检查文件权限}
    B -->|权限正常| C[创建数据库目录]
    B -->|权限异常| D[修复文件权限]
    C --> E[执行 schema.sql]
    D --> E
    E --> F[验证表结构]

解决策略:

确保 backend/database 目录存在且可写
自动创建数据库文件
执行 schema.sql 初始化表结构
验证示例数据插入

端口冲突错误

错误场景: 3000 或 5173 端口被占用

graph TD
    A[启动失败] --> B{检查端口占用}
    B -->|端口被占用| C[终止占用进程]
    B -->|端口正常| D[检查其他配置]
    C --> E[重新启动服务]
    D --> F[排查网络配置]

解决策略:

检测端口占用情况
提供端口配置选项
实现优雅的端口切换

LLM API 配置错误

错误模式:

API_KEY 未配置或无效
网络连接问题
请求频率限制

修复流程:

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

前端构建错误

常见问题:

依赖版本冲突
样式预处理器错误
TypeScript 类型检查错误

解决方案架构:

依赖冲突: 使用 pnpm 的严格依赖解析
样式错误: 验证 SCSS 变量文件路径
类型错误: 配置 unplugin-auto-import

服务启动验证策略

后端健康检查

graph LR
    A[GET /] --> B{响应状态}
    B -->|200| C[服务正常]
    B -->|非200| D[服务异常]
    
    E[GET /api] --> F{API状态}
    F -->|可访问| G[API正常]
    F -->|不可访问| H[API异常]

前端资源加载验证

验证点:

静态资源加载 (CSS, JS)
Vue 应用挂载成功
Element Plus 组件正常渲染
路由导航功能

前后端通信验证

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: 验证代理设置

功能验证测试方案

核心功能测试架构

graph TD
    A[页面加载测试] --> B[创建新对话]
    B --> C[发送消息测试]
    C --> D[接收响应测试]
    D --> E[对话历史测试]
    E --> F[UI交互测试]

测试用例设计

测试项	验证内容	期望结果
页面访问	http://localhost:5173	页面正常加载
新建对话	点击新建对话按钮	创建空白对话界面
消息发送	输入测试消息并发送	消息显示在界面
API通信	后端接收并处理请求	返回预期响应
历史记录	查看对话历史	正确显示历史对话

错误监控与日志策略

日志架构设计

graph LR
    A[请求日志] --> D[Morgan中间件]
    B[错误日志] --> E[自定义ErrorHandler]
    C[应用日志] --> F[Console Logger]
    
    D --> G[请求统计]
    E --> H[错误追踪]
    F --> I[调试信息]

监控指标

性能指标: 响应时间、内存使用、CPU占用
错误指标: 错误率、异常类型、失败请求
业务指标: API调用次数、用户会话数

部署前置条件检查

环境依赖验证

flowchart TD
    A[Node.js 版本] -->|>=16.0.0| B[pnpm 安装]
    B --> C[workspace 配置]
    C --> D[依赖安装状态]
    D --> E[环境变量配置]
    E --> F[网络连接测试]
    F --> G[启动准备就绪]

配置文件验证

package.json: 验证脚本配置和依赖版本
pnpm-workspace.yaml: 确认 workspace 配置格式
vite.config.js: 验证构建和代理配置
.env: 检查必要环境变量

故障排除指南

常见问题快速诊断

问题类型	症状	诊断步骤	解决方案
依赖问题	模块找不到	检查 node_modules	重新安装依赖
端口冲突	EADDRINUSE	检查端口占用	更换端口或终止进程
数据库错误	连接失败	检查文件权限	重新初始化数据库
API调用失败	网络错误	检查配置和网络	修复配置或网络问题
前端白屏	页面不显示	检查控制台错误	修复组件或路由错误

调试工具配置

graph LR
    A[后端调试] --> B[nodemon + console.log]
    C[前端调试] --> D[Vue DevTools]
    E[网络调试] --> F[浏览器 Network 面板]
    G[数据库调试] --> H[SQLite 命令行工具]

6.6 KiB Raw Permalink Blame History