Skip to content

QUICKSTART.md

Latest commit

 

History

History
273 lines (188 loc) · 6.47 KB

QUICKSTART.md

File metadata and controls

273 lines (188 loc) · 6.47 KB

CourseLink 快速开始指南

一分钟启动后端

Windows 用户

首次运行请先复制并配置环境变量（本地开发推荐 SQLite 模板）：

cp backend/.env.local.example backend/.env
# 进入 scripts 目录
cd CourseLink\scripts

# 一键启动(自动完成所有准备工作)
start_backend.bat

Linux/Mac 用户

首次运行请先复制并配置环境变量（本地开发推荐 SQLite 模板）：

cp backend/.env.local.example backend/.env
# 添加执行权限(首次运行)
chmod +x CourseLink/scripts/*.sh

# 进入 scripts 目录
cd CourseLink/scripts

# 一键启动(自动完成所有准备工作)
./start_backend.sh

start_backend 做了什么?

  1. 检查虚拟环境

    • 不存在 → 自动创建
    • 已存在 → 继续下一步

  2. 检查依赖

    • 未安装 → 自动安装所有依赖
    • 已安装 → 跳过安装

  3. 检查数据库

    • 不存在 → 自动初始化
    • 已存在 → 询问是否重新初始化

  4. 启动服务器

完整流程说明

首次运行

$ start_backend.bat

╔════════════════════════════════════════════════════════════╗
║          CourseLink 后端服务器启动脚本                      ║
╚════════════════════════════════════════════════════════════╝

项目根目录: C:\Users\xxx\CourseLink
后端目录: C:\Users\xxx\CourseLink\backend
操作系统: Windows 10

============================================================
检查虚拟环境
============================================================

  虚拟环境不存在,正在创建...

▶ 创建虚拟环境
  完成: 创建虚拟环境

============================================================
检查依赖
============================================================

  检测到缺少依赖,正在安装...

▶ 升级 pip
  完成: 升级 pip

▶ 安装依赖
  完成: 安装依赖

============================================================
检查数据库
============================================================

  数据库不存在,正在初始化...

▶ 创建迁移文件
  完成: 创建迁移文件

▶ 执行迁移
  完成: 执行迁移

============================================================
启动服务器
============================================================

启动后端服务器 (Uvicorn + ASGI)

服务地址: http://localhost:8000
API 端点: http://localhost:8000/api/
管理后台: http://localhost:8000/admin/

提示: 按 Ctrl+C 停止服务器

============================================================

INFO:     Will watch for changes in these directories: ['C:\\Users\\xxx\\CourseLink\\backend']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [67890]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

第二次运行(环境已就绪)

$ start_backend.bat

╔════════════════════════════════════════════════════════════╗
║          CourseLink 后端服务器启动脚本                      ║
╚════════════════════════════════════════════════════════════╝

============================================================
检查虚拟环境
============================================================

  虚拟环境已存在: C:\Users\xxx\CourseLink\venv

============================================================
检查依赖
============================================================

  依赖已安装

============================================================
检查数据库
============================================================

  数据库已存在: C:\Users\xxx\CourseLink\backend\db.sqlite3
  是否重新初始化数据库? (y/N): N

============================================================
启动服务器
============================================================

启动后端服务器 (Uvicorn + ASGI)
...

常见操作

重新初始化数据库

# 方式一: 启动时选择重新初始化
start_backend.bat
# 当提示 "是否重新初始化数据库?" 时输入 y

# 方式二: 运行初始化脚本
init_local_dev.bat  # Windows
./init_local_dev.sh # Linux/Mac

只初始化不启动

# Windows
scripts\init_local_dev.bat

# Linux/Mac
./scripts/init_local_dev.sh

创建超级用户

# 方式一: 初始化时创建
scripts\init_local_dev.bat

# 方式二: 手动创建
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac
cd backend
python manage.py createsuperuser

停止服务器

# 按 Ctrl+C

访问应用

启动成功后,可以访问:

注意事项

  1. 首次运行较慢: 需要创建虚拟环境和安装依赖,大约需要 5-10 分钟
  2. 后续运行很快: 如果环境已就绪,启动只需几秒钟
  3. 端口占用: 如果 8000 端口被占用,需要先关闭占用该端口的程序
  4. 网络问题: 安装依赖需要网络连接,国内用户建议使用镜像源

遇到问题?

Python 未安装

# 下载 Python 3.8+
https://www.python.org/downloads/

虚拟环境创建失败

# Windows
pip install virtualenv

# Linux
sudo apt install python3-venv

依赖安装失败

# 使用国内镜像
pip install -r backend/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

端口被占用

# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# Linux/Mac
lsof -i :8000
kill -9 <PID>

更多信息

提示: 如果你只需要快速启动,直接运行 scripts/start_backend.bat 即可!