入门指南

快速开始

本章节带你在 10 分钟内完成 EduBuddy 的完整本地部署，并创建你的第一个账号开始使用。

EduBuddy 后端依赖 better-sqlite3，需要在本地编译原生 C++ 模块。请确保系统已安装 build-essential 和 python3，否则 npm install 会失败。

第一步：安装系统依赖

根据你的 Linux 发行版，执行以下命令安装编译工具：

Ubuntu / Debian

sudo apt update
sudo apt install -y build-essential python3 node-gyp

CentOS / RHEL / Fedora

sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y python3

Arch Linux

sudo pacman -S --needed base-devel python

第二步：克隆项目

git clone https://github.ibm.com/xzwangdl/EduBuddy.git
cd EduBuddy

第三步：安装依赖

分别进入后端和前端目录安装 npm 依赖：

# 安装后端依赖
cd backend
npm install

# 安装前端依赖
cd ../frontend
npm install

如果 better-sqlite3 编译失败，请参考常见问题排查章节。

第四步：配置环境变量

复制示例配置文件，并填写你的 AI API 密钥：

cp backend/.env.example backend/.env

编辑 backend/.env，最少需要配置以下三个字段：

# AI API 配置（必填）
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o

# 服务端口（可选，默认 3001）
PORT=3001

# JWT 密钥（可选，建议生产环境修改）
JWT_SECRET=your-secret-key-change-in-production

支持的 AI 服务商

服务商	OPENAI_BASE_URL	推荐模型
OpenAI	`https://api.openai.com/v1`	gpt-4o
DeepSeek	`https://api.deepseek.com/v1`	deepseek-chat
阿里通义千问	`https://dashscope.aliyuncs.com/compatible-mode/v1`	qwen-plus
月之暗面 Kimi	`https://api.moonshot.cn/v1`	moonshot-v1-8k

第五步：启动服务

打开两个终端窗口，分别启动后端和前端：

终端 1：启动后端（端口 3001）

cd backend
npm run dev

看到以下输出表示后端启动成功：

🚀 AI学生帮手后端服务启动成功
📡 服务地址: http://localhost:3001
🔍 健康检查: http://localhost:3001/health
📚 环境: development

终端 2：启动前端（端口 5173）

cd frontend
npm start

第六步：访问应用

打开浏览器，访问：

http://localhost:5173

首次使用，点击 「注册新账号」 创建账号，填写以下信息：

用户名：唯一标识，用于登录
邮箱：用于账号管理
密码：至少 6 位
显示名称：界面中显示的名字
角色：学生 / 教师（可选）
年级：用于 AI 个性化推荐（可选）

可以通过 http://localhost:3001/health 验证后端是否正常运行，正常会返回 {"status":"ok",...}。

目录结构说明

EduBuddy/
├── backend/               # 后端服务（Node.js + Express）
│   ├── src/
│   │   ├── server.ts      # 应用入口，中间件注册
│   │   ├── database/      # 数据库初始化与 Schema
│   │   ├── routes/        # API 路由处理器
│   │   ├── services/      # AI 服务封装
│   │   ├── middleware/    # 认证等中间件
│   │   └── utils/         # JWT、日志等工具
│   ├── .env.example       # 环境变量模板
│   └── package.json
├── frontend/              # 前端应用（React + Vite）
│   ├── src/
│   │   ├── App.tsx        # 路由配置
│   │   ├── pages/         # 各功能页面
│   │   ├── components/    # 公共组件
│   │   ├── services/      # API 调用封装
│   │   └── store/         # Zustand 全局状态
│   └── package.json
└── docs/                  # 帮助文档（当前文件）