预计阅读时间：10 分钟

DjangoBlog

当前博客使用 https://github.com/liangliangyy/DjangoBlog.git 开源项目部署，通过本项目的学习，了解服务器渲染和django

🚀 快速开始

1. 环境准备

确保您的系统中已安装 Python 3.10+ 和 MySQL。

2. 克隆与安装

# 克隆项目到本地
git clone https://github.com/liangliangyy/DjangoBlog.git
cd DjangoBlog

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows PowerShell
.\venv\Scripts\Activate.ps1
# Linux/Mac
source venv/bin/activate

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

# 安装前端项目依赖
cd frontend
npm install

3. 项目配置

• 数据库配置： 打开 djangoblog/settings.py 文件，找到 DATABASES 配置项，修改为您的 MySQL 连接信息。

python DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', 'NAME': 'djangoblog', 'USER': 'root', 'PASSWORD': 'your_password', 'HOST': '127.0.0.1', 'PORT': 3306, 'OPTIONS': { 'charset': 'utf8mb4' }, } } 在 MySQL 中创建数据库: sql CREATE DATABASE `djangoblog` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

• 基本配置： 根据需要修改 djangoblog/settings.py 中的其他配置项，如网站名称、邮箱设置等。

4. 初始化数据库

# 生成数据库迁移文件
python manage.py makemigrations

# 执行数据库迁移
python manage.py migrate

# 创建超级管理员账户
python manage.py createsuperuser

5. 开发模式

在开发环境中，推荐同时运行 Django 后端和 Vite 前端开发服务器，以获得最佳的开发体验（热更新、实时预览）：

1. 启动后端开发服务器

# (1) 激活虚拟环境（如果尚未激活）
# Windows PowerShell
.\venv\Scripts\Activate.ps1
# Linux/Mac
# source venv/bin/activate

# (2) 启动 Django 开发服务器
python manage.py runserver

2. 启动前端开发服务器

打开另一个终端窗口，执行以下命令：

# (1) 进入 frontend 目录
cd frontend

# (2) 启动 Vite 开发服务器
npm run dev

3. 开发流程说明

• 后端服务：运行在 http://127.0.0.1:8000/，提供 API 接口和管理后台
• 前端服务：运行在 http://localhost:5173/，提供热更新的前端资源
• 访问地址：通过 http://127.0.0.1:8000/ 访问完整的博客应用
• 热更新：修改前端代码后，页面会自动刷新，无需手动重新加载
• 管理后台：通过 http://127.0.0.1:8000/admin/ 访问，使用超级管理员账户登录

4. 开发注意事项

• 确保两个服务同时运行，才能获得完整的开发体验
• 前端代码修改会实时反映到浏览器中
• 后端代码修改会触发 Django 开发服务器的自动重启
• 数据库模型更改后，需要重新执行 makemigrations 和 migrate 命令

这种开发模式结合了 Django 的强大后端能力和 Vite 的现代前端开发体验，让您可以高效地开发和调试代码。

快速启动开发环境（推荐）

为了方便快速启动开发环境，项目中提供了三种启动脚本，您可以选择适合您操作系统的脚本：

1. Windows 批处理脚本（.bat）

# 直接双击运行或在命令行中执行
./start_dev.bat

2. Windows PowerShell 脚本（.ps1）

# 在 PowerShell 中执行
.\start_dev.ps1

3. 跨平台 Makefile（推荐）

# 启动开发环境
make dev

# 安装所有依赖
make install

# 仅安装前端依赖
make install-frontend

# 仅安装后端依赖
make install-backend

这些脚本会自动： - 检查虚拟环境是否存在 - 在新的终端窗口中启动前端 Vite 开发服务器 - 激活虚拟环境并启动后端 Django 开发服务器 - 显示访问地址和其他有用信息

使用这些脚本可以大大简化开发环境的启动过程，提高开发效率！

6. 生产环境部署

本人使用的是腾讯云轻量级服务器+1panel面板

1、部署配置

1、安装mysql、OpenResty 2、点击文件菜单，新建目录通过拉取项目 3、创建虚拟环境，项目目录为拉取的项目根目录

# 启动命令先配置为tail -f /dev/null，因为要先启动容器进行一些项目的前置操作

# 点击环境变量，添加以下内容
DJANGO_DEBUG：False # 关闭debug模式
DJANGO_DB_HOST：xxx # mysql容器的地址
DJANGO_DB_NAME：xxx # 数据库名
DJANGO_DB_USER：xxx # 用户名
DJANGO_DB_PASSWORD：xxx # 用户密码

4、启动运行环境

# 输入python --version检查下是否正常

# 创建虚拟环境
python -m venv venv

# 进入虚拟环境
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt # 注意：生产环境启动django使用gunicorn，requirements.txt中没有，要单独安装

# 打包前端项目
cd frontend
npm i # 先在容器中安装node
npm run build
cd ..

# 数据库迁移,和开发环境操作一致

# 收集静态文件
python manage.py collectstatic --noinput

# (可选) 压缩静态文件
python manage.py compress --force

5、点击编辑，配置启动命令和端口映射

# 前置操作完成了，重新配置启动命令
source venv/bin/activate && pip install -r requirements.txt && gunicorn djangoblog.wsgi:application --bind 0.0.0.0:8000

# 端口配置，外部访问使用，当前项目绑定的8000端口，外部访问容器映射配置

6、创建网站，配置OpenResty 1. 创建网站，选择运行环境 2. 类型python，运行环境框选择刚才新建的 3. 域名填入自己的域名，没域名填写公网IP 4. 点击侧边栏容器，点击openresty项的更多-编辑，点击挂载，配置收集的静态资源目录和openresty的映射 5. 点击侧边栏网站-名称-配置文件，配置映射的静态文件

7、 启动项目，登录之前创建的超级用户账号配置网站、发布文章等等

2、遇到的问题和解决方案

1、创建运行环境配置的启动命令是和项目一起启动，虚拟环境和必要的启动库gunicorn没有安装，导致启动失败 配置启动命令为tail -f /dev/null，然后才能打开容器终端进行前置操作

2、静态文件无法访问，网站样式布局错乱 项目收集的静态文件，openresty容器无法访问到的，要先通挂载映射，然后配置nginx静态资源访问容器映射的目录才行

3、main.js和client文件请求地址不对，请求的是vite服务和开发环境服务器 最开始是通过开发环境收集静态文件，然后上传到云服务器项目根目录中，经排查发现\blog\templatetags\vite_tags.py中配置了引用映射文件为'blog/static/blog/dist/.vite/manifest.json'，经检查发现缺少此文件，上传对应文件解决

📦 插件系统

插件系统是 DjangoBlog 的核心特色之一。它允许您在不修改核心代码的情况下，通过编写独立的插件来扩展博客功能。

内置插件

项目已内置以下实用插件：

• view_count - 文章浏览计数统计
• seo_optimizer - SEO 优化增强
• article_copyright - 文章版权声明（现代化样式）
• article_recommendation - 智能文章推荐（响应式卡片布局）
• external_links - 外部链接处理（自动添加图标）
• image_lazy_loading - 图片懒加载优化（淡入动画）
• reading_time - 文章阅读时间估算
• cloudflare_cache - Cloudflare 缓存管理

开发自定义插件

只需在 plugins 目录下创建一个新的文件夹，并编写您的 plugin.py 文件即可开发自定义插件。每个插件可以包含：

• 钩子函数：用于在特定事件触发时执行代码
• 模板标签：用于在模板中使用插件功能
• 静态资源：插件所需的 CSS、JavaScript 文件
• 配置选项：插件的可配置参数

详细的插件开发文档请参考 docs/plugin_development.md。

📄 许可证

本项目基于 MIT License 开源。

本文由 hhg 原创，转载请注明出处。