# djangotutorial

**Repository Path**: aiden61/djangotutorial

## Basic Information

- **Project Name**: djangotutorial
- **Description**: 一个可部署的个人主页与个人博客系统：前台用于展示个人资料、项目与内容页（Markdown），后台用于维护数据与权限；支持统一登录、用户/管理员分权访问与 API 鉴权。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 个人主页 / 个人博客系统

一个可部署的个人主页与个人博客系统：前台用于展示个人资料、项目与内容页（Markdown），后台用于维护数据与权限；支持统一登录、用户/管理员分权访问与 API 鉴权。


## 功能概览
- **统一登录**：未登录访问根路径 `/` 自动跳转 `/login`，登录后按角色进入对应面板。
- **角色与权限隔离**：
  - 普通用户：`/dashboard/user`
  - 管理员：`/dashboard/admin`
  - 越权访问返回 403，并清除会话。
- **内容可维护**：个人资料/项目/技能等由后台维护，前台展示不写死（支持 Markdown 字段）。
- **安全配置**：生产环境通过环境变量配置 `ALLOWED_HOSTS` 与 CORS 白名单，避免 `*` 放开带来的风险。

## 技术栈
- 后端：Django + Django REST framework
- 鉴权：Session + JWT（SimpleJWT）
- 前端：React + Vite
- 部署：Gunicorn + Nginx + Systemd（CentOS 方案）

## 数据库配置（MySQL）
本项目默认使用 MySQL 数据库，并且不提供表数据迁移，部署时会直接导入预置的空表结构（`djangotutorial.sql`），从而保证每个人部署完毕后拥有独立的、干净的个人博客系统。在启动项目前，请确保：
1. **安装 MySQL**：推荐 MySQL 5.7 或 8.0+。
2. **初始化数据库**：
   在 MySQL 控制台执行以下命令创建数据库：
   ```sql
   CREATE DATABASE IF NOT EXISTS djangotutorial CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```
3. **导入结构**：
   ```bash
   mysql -u root -p djangotutorial < djangotutorial.sql
   ```
4. **配置环境变量**：
   项目通过以下环境变量连接 MySQL。如未设置，将使用默认值（仅限本地开发使用）：
   - `MYSQL_DATABASE`：数据库名（默认 `djangotutorial`）
   - `MYSQL_USER`：数据库用户名（默认 `root`）
   - `MYSQL_PASSWORD`：数据库密码（默认 `123456`）
   - `MYSQL_HOST`：数据库主机地址（默认 `127.0.0.1`）
   - `MYSQL_PORT`：数据库端口（默认 `3306`）

**默认管理员凭据与安全提示**：
数据库导入后，将自动创建一个超级管理员账户：
- 用户名：`admin`
- 密码：`admin`

⚠️ **警告**：首次使用上述默认凭据登录后，请**务必立刻进入后台的「账户设置」修改密码**，以免造成数据安全隐患！

**回滚方案 (SQLite)**：
如在部署时 MySQL 环境不可用或出现错误需要回退至 SQLite：
1. 在 `djangotutorial/settings.py` 中移除 `pymysql` 相关代码。
2. 将 `DATABASES` 配置恢复为：
   ```python
   DATABASES = {
       'default': {
           'ENGINE': 'django.db.backends.sqlite3',
           'NAME': BASE_DIR / 'db.sqlite3',
       }
   }
   ```
3. 重新运行 `py manage.py migrate` 即可恢复基于 SQLite 的运行状态。

## 配置说明

### 博客基础信息配置
你可以通过后台「信息总览」/「个人资料」配置博客首页显示的信息，或者通过调用 API：
- **头像 (`avatar_url`)**：显示在左上角
- **名称 (`display_name`)**：作为主标题显示
- **副标题 (`headline`)**：位于主标题下方的一句话介绍
- **个人简介 (`summary`)**：位于右侧边栏（关于我）

以上字段在系统预留的 `Profile` 数据表中存储，无需改动数据库。

### UI 组件与颜色方案
- **莫兰迪配色 (Morandi Colors)**：系统全局颜色通过 `index.css` 的 `:root` 变量驱动（例如 `--color-primary`, `--color-bg`, `--color-surface`）。如果需要更改主题色，仅需调整 `index.css` 即可。
- **深色模式**：默认支持，可通过右上角的开关按钮在 Light/Dark 间切换，CSS 变量会自动对应 `.dark`。
- **GlassCard (磨砂玻璃卡片)**：通过 `<GlassCard>` 封装。如果浏览器不支持 `backdrop-filter`，会自动降级为纯色。
- **登录背景动画**：提供基于 Canvas 的极简粒子动效，CPU 消耗小，右下角提供一键降级纯 CSS 的开关。

## 编辑器与数据持久化
管理后台集成了 `Vditor` (MIT协议) 作为 Markdown 核心编辑器：
- **功能支持**：实时预览、代码高亮、TOC。
- **自动草稿保存**：内容实时写入 `localStorage`，防浏览器意外关闭。
- **兼容性**：为了实现数据库**零改动**的最小化升级要求，文章仅将 Markdown 源码存入现有 `content_md` 字段，并在前台页面（`ReactMarkdown`）动态渲染。旧有文章 100% 兼容直接展示，无需运行迁移脚本。
- **图片上传**：支持通过后端 API（带有鉴权、5MB 限制、后缀限制白名单验证）安全上传。

## 部署与启动说明

本项目提供了两个分离的脚本用于不同阶段的操作，避免误触发删库操作。

1. **初次部署：`deploy.sh`**
   仅在首次配置服务器环境时使用。它会执行：
   - 检查虚拟环境和依赖安装
   - 检测目标 MySQL 数据库。**如果检测到为空库**，会自动执行重建表结构 (`djangotutorial.sql`)。**如果检测到已存在业务表**，它会安全地跳过删表导入动作，仅执行增量迁移 (`python manage.py migrate`)，保护生产环境数据安全。

2. **日常维护与启动：`start.sh`**
   日常代码更新、服务重启时请使用此脚本。它仅负责：
   - 从远端拉取最新代码
   - 执行安全的增量表迁移
   - 收集静态文件
   - 以后台守护进程模式启动（或热重载） Gunicorn 进程

## 本地开发

### 1) 后端（使用自带的智能启动脚本）
项目提供了一个智能的 `start_server.py` 脚本，它会自动寻找并使用项目目录下的虚拟环境（`.venv`），并具备端口冲突自动重试、后台运行等特性。

```powershell
# 1. 创建虚拟环境并安装依赖
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# 2. 导入预置表结构（默认密码 admin / admin）
mysql -u root -p djangotutorial < djangotutorial.sql

# 3. 一键启动后端（自动寻找可用端口，默认从 8000 开始）
# Windows 环境下将在后台运行，并输出日志到 server_8000.log
.\.venv\Scripts\python.exe start_server.py
```

**启动脚本高级用法**：
- **指定端口**：`$env:DJANGO_PORT="8080"; .\.venv\Scripts\python.exe start_server.py`
- **查看日志**：`Get-Content server_8000.log -Wait` (Windows) 或 `tail -f server_8000.log` (Mac/Linux)
- **停止服务**：脚本启动成功后会输出对应的 `taskkill` 或 `kill` 命令，直接复制执行即可。

访问：
- http://127.0.0.1:8000/login
- 未登录访问根路径会被重定向到 `/login`

### 2) 前端（使用 Vite 开发服务器）
```bash
cd frontend
npm install
npm run dev
```

## 首次部署（生成默认账号）
项目提供一次性初始化命令，会明文打印随机强密码（仅用于首次初始化），请登录后立即修改：
```bash
py manage.py init_default_accounts
```
- 普通用户：`user`
- 超级管理员：`admin`

## 登录与路由
- 登录页：`/login`
  - 默认展示「用户登录」
  - 点击「切换至管理员登录」无刷新切换表单与接口
- 登录成功跳转：
  - 用户 → `/dashboard/user`
  - 管理员 → `/dashboard/admin`

## 后端接口（节选）
- 用户登录：`POST /api/user/login/`
- 管理员登录：`POST /api/admin/login/`
- 当前用户：`GET /api/auth/me/`
- 退出登录：`POST /api/auth/logout/`

## 生产环境配置（环境变量）
建议在 Systemd service 或服务器环境中设置：
- `DJANGO_DEBUG`：`True|False`（生产必须 `False`）
- `DJANGO_ALLOWED_HOSTS`：例如 `yourdomain.com,www.yourdomain.com`
- `DJANGO_CORS_ALLOWED_ORIGINS`：例如 `https://yourdomain.com`

## CentOS 生产环境部署（Gunicorn + Nginx）
项目根目录提供自动化部署脚本 [`deploy.sh`](file:///D:/Work/Django/djangotutorial/deploy.sh)，覆盖：
- 创建虚拟环境并安装依赖
- 前端构建
- 数据库迁移与静态文件收集
- 重启 Systemd 服务与 Nginx

### 1) 环境准备
```bash
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs python3 python3-devel gcc git
sudo yum install -y epel-release
sudo yum install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx
```

### 2) 配置 Systemd（示例）
创建 `/etc/systemd/system/djangotutorial.service`：
```ini
[Unit]
Description=Gunicorn daemon for personal site
After=network.target

[Service]
User=root
Group=root
WorkingDirectory=/var/www/djangotutorial
ExecStart=/var/www/djangotutorial/.venv/bin/gunicorn --workers 3 --bind unix:/var/www/djangotutorial/djangotutorial.sock djangotutorial.wsgi:application

[Install]
WantedBy=multi-user.target
```

### 3) 配置 Nginx（示例）
在 `/etc/nginx/conf.d/djangotutorial.conf` 添加：
```nginx
server {
    listen 80;
    server_name your_domain_or_ip;

    location /static/ {
        alias /var/www/djangotutorial/static/;
    }

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://unix:/var/www/djangotutorial/djangotutorial.sock;
    }
}
```

### 4) 一键部署
```bash
cd /var/www/djangotutorial
chmod +x deploy.sh
./deploy.sh
```

## 测试
后端：
```bash
py manage.py test
```
前端：
```bash
cd frontend
npm test
```