fquiz/README.md

fquiz

基于 Next.js + Python（FastAPI）的全栈 Monorepo 初始化工程。

目录结构

.
├── web/                 # Next.js 16 + TypeScript + App Router
├── api/                 # FastAPI 服务
├── scripts/dev.sh       # 前后端一键并行启动脚本
├── .env.example         # 根环境变量模板
└── package.json         # Monorepo 根脚本

技术栈

• 前端：Next.js 16、React 19、TypeScript
• 后端：FastAPI、Uvicorn、Pydantic Settings
• 协议：REST（默认 /health、/api/v1/ping）

环境要求

• Node.js >= 20
• Python >= 3.10
• Python 需要可用的 venv 和 pip（Debian/Ubuntu 可安装 python3-venv）

快速开始

1. 克隆仓库并进入目录。

2. 安装前端依赖：

   npm --prefix web install
   

3. 配置环境变量：

   cp .env.example .env
   cp web/.env.local.example web/.env.local
   

4. 准备 Python 环境并安装依赖（示例）：

   python3 -m venv .venv
   source .venv/bin/activate
   python -m pip install -r api/requirements.txt
   

5. 一键启动前后端：

   npm run dev
   

常用命令

# 启动前端
npm run dev:web

# 仅启动后端
npm run dev:api

# 构建前端
npm run build:web

# 前端 lint
npm run lint:web

Docker Compose 部署

1. 准备环境变量：

   cp .env.example .env
   

2. 构建并启动容器：

   docker compose up --build -d
   

3. 查看运行状态和日志：

   docker compose ps
   docker compose logs -f
   

4. 访问服务：

• 前端：http://localhost:3000
• 后端：http://localhost:8000/health

5. 停止并清理：

   docker compose down
   

说明：

• NEXT_PUBLIC_API_BASE_URL 在 Next.js 中是构建期注入；如果修改该值，需要重新执行 docker compose up --build。