# studyield

**Repository Path**: hongawen/studyield

## Basic Information

- **Project Name**: studyield
- **Description**: 二次改造studyield
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Studyield

AI 驱动的学习平台，前后端分离架构。

- **后端**：NestJS 10（TypeScript）+ PostgreSQL / Redis / Qdrant（向量库）/ ClickHouse（分析）
- **前端**：React 19 + Vite + TailwindCSS + Radix UI
- **端口**：后端 API `3010`（前缀 `/api/v1`），前端 `5189`

---

## 一、环境要求

| 依赖 | 版本 | 说明 |
| --- | --- | --- |
| Node.js | ≥ 20 | 前后端均需 |
| pnpm | ≥ 11 | `corepack enable` 或 `npm i -g pnpm` |
| Docker + Docker Compose | 最新版 | 用于跑数据库等基础设施 |

基础设施服务（PostgreSQL、Redis、Qdrant、ClickHouse）统一由 Docker 启动，无需本地单独安装。

---

## 二、两种启动方式

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

基础设施用 Docker 跑，前后端在本地以开发模式（热重载）运行：

```bash
./start.sh
```

脚本会自动完成：
1. 启动 `postgres` / `redis` / `qdrant` / `clickhouse` 四个容器并等待健康检查通过；
2. 若缺少 `backend/.env`、`frontend/.env`，自动从对应 `.env.example` 复制；
3. 安装依赖（首次）、执行数据库迁移；
4. 启动后端（`pnpm run start:dev`）和前端（`pnpm run dev`）。

> ⚠️ 首次运行前，请先编辑 `backend/.env` 填入必要密钥（至少 JWT 密钥；AI 功能需 `OPENROUTER_API_KEY` / `OPENAI_API_KEY`），详见「四、环境变量」。

启动后访问：

- 前端：http://localhost:5189
- 后端 API：http://localhost:3010/api/v1
- Qdrant 面板：http://localhost:6333/dashboard

按 `Ctrl+C` 可停止前端；停止全部基础设施容器：`docker compose down`。

---

### 方式 B：全 Docker（一键跑整套，接近生产）

前端、后端、基础设施全部打包为容器运行：

```bash
# 后端环境变量：首次需从示例复制并按需填写
cp backend/.env.example backend/.env

# 启动整套（含前后端镜像构建）
docker compose --env-file .env.docker up -d

# 查看日志
docker compose logs -f backend

# 停止
docker compose down
```

- 前端：http://localhost:5189
- 后端 API：http://localhost:3010/api/v1

各服务端口、默认账号密码在根目录 `.env.docker` 中定义，可按需修改。

---

### 方式 C：手动分步启动（需要精细控制时）

```bash
# 1. 启动基础设施
docker compose --env-file .env.docker up -d postgres redis qdrant clickhouse

# 2. 后端
cd backend
cp .env.example .env        # 首次，随后编辑填入密钥
pnpm install
pnpm run migrate             # 执行数据库迁移
pnpm run start:dev           # 开发模式（热重载）

# 3. 前端（新开一个终端）
cd frontend
cp .env.example .env        # 首次
pnpm install
pnpm run dev
```

---

## 三、常用命令

### 后端（`backend/`）

| 命令 | 作用 |
| --- | --- |
| `pnpm run start:dev` | 开发模式，热重载 |
| `pnpm run start:prod` | 生产模式（需先 `pnpm run build`） |
| `pnpm run build` | 编译到 `dist/` |
| `pnpm run migrate` | 执行数据库迁移 |
| `pnpm run migrate:create` | 创建新迁移文件 |
| `pnpm run test` | 单元测试 |
| `pnpm run lint` | ESLint 检查并修复 |

### 前端（`frontend/`）

| 命令 | 作用 |
| --- | --- |
| `pnpm run dev` | 开发服务器 |
| `pnpm run build` | 生产构建（含类型检查） |
| `pnpm run preview` | 本地预览构建产物 |
| `pnpm run lint` | ESLint 检查 |

---

## 四、环境变量

三份配置文件，各有示例模板：

| 文件 | 用途 | 模板 |
| --- | --- | --- |
| `.env.docker` | Docker Compose 基础设施与端口默认值 | 已提供，开箱即用 |
| `backend/.env` | 后端应用配置（数据库、JWT、AI 等） | `backend/.env.example` |
| `frontend/.env` | 前端配置（API 地址等） | `frontend/.env.example` |

**最小可运行**只需在 `backend/.env` 中设置：

- `JWT_ACCESS_SECRET` / `JWT_REFRESH_SECRET`（各至少 32 位，可用 `openssl rand -hex 32` 生成）
- 数据库 / Redis / Qdrant / ClickHouse 连接信息（默认值已对齐 `.env.docker`）

**可选功能**按需填写对应密钥：

- AI 对话与向量嵌入：`OPENROUTER_API_KEY`、`OPENAI_API_KEY`
- 文件存储（Cloudflare R2）、Web 搜索（Tavily / Serper）等

---

## 五、服务端口速查

| 服务 | 端口 | 地址 |
| --- | --- | --- |
| 前端 | 5189 | http://localhost:5189 |
| 后端 API | 3010 | http://localhost:3010/api/v1 |
| PostgreSQL | 5432 | localhost:5432 |
| Redis | 6379 | localhost:6379 |
| Qdrant | 6333 | http://localhost:6333/dashboard |
| ClickHouse | 8123 | localhost:8123 |

---

## 六、常见问题

- **`start.sh` 报「Docker is not running」**：先启动 Docker Desktop。
- **端口被占用**：修改 `.env.docker` 中对应的 `*_PORT`，或释放占用端口。
- **后端连不上数据库**：确认基础设施容器已 `healthy`（`docker compose ps`），并检查 `backend/.env` 的连接配置与 `.env.docker` 一致。
- **迁移失败**：确保 PostgreSQL 容器已就绪后再执行 `pnpm run migrate`。