LOCAL_DEV_GUIDE.md

CourseLink 本地开发快速启动指南

快速开始（推荐）

Windows 用户

直接双击运行：

init_local_dev.bat

Mac/Linux 用户

运行：

python init_local_dev.py

手动初始化步骤

如果自动脚本失败，可以手动执行：

1. 进入 backend 目录

cd backend

2. 删除旧数据库（可选）

# Windows
del db.sqlite3

# Mac/Linux
rm db.sqlite3

3. 清理旧的 migrations（可选）

# Windows PowerShell
Remove-Item chatbot\migrations\*.py -Exclude __init__.py
Remove-Item extension\migrations\*.py -Exclude __init__.py
Remove-Item accounts\migrations\*.py -Exclude __init__.py

# Mac/Linux
find . -path "*/migrations/*.py" -not -name "__init__.py" -delete

4. 创建新的 migrations

python manage.py makemigrations

5. 初始化数据库

python manage.py migrate

6. 创建超级用户

python manage.py createsuperuser

按提示输入：

• 用户名（建议：admin）
• 邮箱（可选）
• 密码（至少 8 位）

7. 启动开发服务器

python manage.py runserver

访问地址

• API 服务: http://127.0.0.1:8000/
• 管理后台: http://127.0.0.1:8000/admin/
• API 文档: http://127.0.0.1:8000/api/

数据库说明

本地开发（默认）

• 数据库: SQLite3
• 文件位置: backend/db.sqlite3
• 优点: 无需安装额外软件，开箱即用
• 适用: 本地开发、测试

生产环境

如需使用 MySQL/PostgreSQL，在 .env 文件中配置：

DB_ENGINE=django.db.backends.mysql
DB_NAME=courselink_db
DB_USER=root
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=3306

环境变量配置

本项目后端启动依赖环境变量（至少需要 DJANGO_SECRET_KEY）。推荐直接使用仓库自带模板：

# 在项目根目录（本地开发推荐 SQLite 模板）
cp backend/.env.local.example backend/.env

然后编辑 backend/.env，最小必需配置建议包含：

• DJANGO_SECRET_KEY: Django 密钥（必需，否则后端无法启动）
• DASHSCOPE_API_KEY: Dashscope API Key（需要实际调用 LLM 时必需）
• SERVER_MASTER_KEY: 加密主密钥（建议本地也配置）

本地开发常用（可选）：

• DJANGO_DEBUG=True
• DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost
• CORS_ALLOWED_ORIGINS=http://localhost:5173

常见问题

Q1: 端口被占用

# 使用其他端口
python manage.py runserver 8001

Q2: migrations 冲突

# 清理所有 migrations 并重新创建
python init_local_dev.py  # 自动处理

Q3: 数据库连接失败

确认 .env 文件存在且 DB_ENGINE 未设置（默认使用 SQLite）

依赖安装

首次使用需要安装依赖：

# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Mac/Linux:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

下一步

1. 初始化数据库
2. 创建超级用户
3. 启动开发服务器
4. 开始开发！

注意事项

• .env 文件包含敏感信息，请勿提交到 Git
• db.sqlite3 仅用于开发，生产环境请使用 PostgreSQL/MySQL
• 定期备份数据库文件

需要帮助？

• 查看 Django 文档: https://docs.djangoproject.com/
• 项目 Issues: [GitHub Issues 链接]