入门指南

环境配置

EduBuddy 通过 backend/.env 文件管理所有运行时配置。本页列出所有可用的环境变量及其说明。

完整配置示例

# ===== AI 服务配置 =====
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o

# ===== 服务器配置 =====
PORT=3001
NODE_ENV=development

# ===== 安全配置 =====
JWT_SECRET=change-this-to-a-random-secret-in-production
JWT_EXPIRES_IN=7d

# ===== 数据库配置 =====
DB_PATH=./data/edubuddy.db

# ===== 文件上传配置 =====
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760

# ===== 速率限制配置 =====
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=200

变量详解

AI 服务配置

变量名	必填	默认值	说明
`OPENAI_API_KEY`	✅ 是	—	AI 服务的 API 密钥
`OPENAI_BASE_URL`	否	`https://api.openai.com/v1`	AI 服务的 Base URL，用于切换国内兼容服务
`OPENAI_MODEL`	否	`gpt-4o`	使用的模型名称，需与服务商支持的模型对应

图片 OCR 功能（POST /api/upload/image）需要模型支持 Vision 能力，如 gpt-4o、gpt-4-vision-preview。语音转文字功能调用 Whisper API（whisper-1），需要 OpenAI 官方 API Key 或兼容接口。

服务器配置

变量名	必填	默认值	说明
`PORT`	否	`3001`	后端服务监听端口
`NODE_ENV`	否	`development`	运行环境；生产环境设为 `production` 以隐藏错误详情

安全配置

变量名	必填	默认值	说明
`JWT_SECRET`	否	`edubuddy-secret-key`	JWT 签名密钥，生产环境务必修改为随机字符串
`JWT_EXPIRES_IN`	否	`7d`	JWT Token 有效期，支持 `1h`、`7d`、`30d` 等格式

数据库配置

变量名	必填	默认值	说明
`DB_PATH`	否	`./data/edubuddy.db`	SQLite 数据库文件路径，首次运行自动创建

文件上传配置

变量名	必填	默认值	说明
`UPLOAD_DIR`	否	`./uploads`	上传文件存储目录，自动创建
`MAX_FILE_SIZE`	否	`10485760`（10 MB）	单文件最大字节数

速率限制配置

变量名	必填	默认值	说明
`RATE_LIMIT_WINDOW_MS`	否	`900000`（15 分钟）	速率限制滑动窗口时长（毫秒）
`RATE_LIMIT_MAX`	否	`200`	窗口内最大请求数（全局 API）

AI 相关接口（生成题目、AI 解题、AI 分析、生成学习路线）有独立的速率限制：每分钟最多 20 次，该值目前为硬编码，如需调整请修改 backend/src/server.ts 中 aiLimiter 的 max 值。

前端环境变量

前端通过 Vite 的 .env 机制配置，在 frontend/ 目录下创建 .env.local 文件：

# 后端 API 地址（默认 http://localhost:3001/api）
VITE_API_URL=http://localhost:3001/api

生产环境部署时，将 VITE_API_URL 改为实际的后端域名：

VITE_API_URL=https://api.yourdomain.com/api

生成安全的 JWT 密钥

可使用以下命令生成一个随机的高强度密钥：

# 方法一：openssl
openssl rand -base64 64

# 方法二：Node.js
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"