HelloGitHub-Team/HelloDjango-blog-tutorial

HelloDjango-blog-tutorial
完全免费、开源的 HelloDjango 系列教程之博客开发。
基于 django 2.2，带你从零开始一步步创建属于自己的博客网站。

特别说明：本项目不仅仅是教程用的演示项目！我们的目标是开发一个功能完善、测试充分、可用于生产环境的开源博客系统。和其他开源博客系统不同点在于，我们以教程的形式详细记录项目从 0 到 1 的开发过程。

分支说明

master 分支为项目的主分支，每一步关键功能的开发都对应一篇详细的教程，并和历史提交以及标签一一对应。例如第一篇教程对应第一个 commit，对应标签为 step1，依次类推。

资源列表

成品在线预览
教程首发 HelloGitHub 微信公众号和追梦人物的博客，在线学习地址：HelloDjango - Django博客教程（第二版）
项目源码仓库
项目前端模板源码仓库

本地运行

可以使用 Virtualenv、Pipenv、Docker 等在本地运行项目，每种方式都只需运行简单的几条命令就可以了。

注意：

因为博客全文搜索功能依赖 Elasticsearch 服务，如果使用 Virtualenv 或者 Pipenv 启动项目而不想搭建 Elasticsearch 服务的话，请先设置环境变量 ENABLE_HAYSTACK_REALTIME_SIGNAL_PROCESSOR=no 以关闭实时索引，否则无法创建博客文章。如果关闭实时索引，全文搜索功能将不可用。

Windows 设置环境变量的方式：set ENABLE_HAYSTACK_REALTIME_SIGNAL_PROCESSOR=no

Linux 或者 macOS：export ENABLE_HAYSTACK_REALTIME_SIGNAL_PROCESSOR=no

使用 Docker 启动则无需设置，因为会自动启动一个包含 Elasticsearch 服务的 Docker 容器。

无论采用何种方式，先克隆代码到本地：

$ git clone https://github.com/HelloGitHub-Team/HelloDjango-blog-tutorial.git

Virtualenv

创建虚拟环境并激活虚拟环境，具体方法可参考：开始进入 django 开发之旅：使用虚拟环境

安装项目依赖

$ cd HelloDjango-blog-tutorial
$ pip install -r requirements.txt

迁移数据库
```
$ python manage.py migrate
```
创建后台管理员账户
```
$ python manage.py createsuperuser
```
具体请参阅创作后台开启，请开始你的表演。
运行开发服务器
```
$ python manage.py runserver
```
浏览器访问 http://127.0.0.1:8000/admin，使用第 4 步创建的管理员账户登录后台发布文章，如何发布文章可参考：创作后台开启，请开始你的表演。

或者执行 fake 脚本批量生成测试数据：
```
$ python -m scripts.fake
```
批量脚本会清除全部已有数据，包括第 4 步创建的后台管理员账户。脚本会再默认生成一个管理员账户，用户名和密码都是 admin。
浏览器访问：http://127.0.0.1:8000，可进入到博客首页

Pipenv

安装 Pipenv（已安装可跳过）
```
$ pip install pipenv
```
安装项目依赖
```
$ cd HelloDjango-blog-tutorial
$ pipenv install --dev
```
关于如何使用 Pipenv，参阅：开始进入 django 开发之旅的 Pipenv 创建和管理虚拟环境部分。
迁移数据库

在项目根目录运行如下命令迁移数据库：
```
$ pipenv run python manage.py migrate
```
创建后台管理员账户

在项目根目录运行如下命令创建后台管理员账户
```
$ pipenv run python manage.py createsuperuser
```
具体请参阅创作后台开启，请开始你的表演。
运行开发服务器

在项目根目录运行如下命令开启开发服务器：
```
$ pipenv run python manage.py runserver
```
浏览器访问 http://127.0.0.1:8000/admin，使用第 4 步创建的管理员账户登录后台发布文章，如何发布文章可参考：创作后台开启，请开始你的表演。

或者执行 fake 脚本批量生成测试数据：
```
$ pipenv run python -m scripts.fake
```
批量脚本会清除全部已有数据，包括第 4 步创建的后台管理员账户。脚本会再默认生成一个管理员账户，用户名和密码都是 admin。
在浏览器访问：http://127.0.0.1:8000/，可进入到博客首页。

Docker

安装 Docker 和 Docker Compose

构建和启动容器

$ docker-compose -f local.yml build
$ docker-compose -f local.yml up

创建后台管理员账户
```
$ docker exec -it hellodjango_blog_tutorial_local python manage.py createsuperuser
```
其中 hellodjango_blog_tutorial_local 为项目预定义容器名。
浏览器访问 http://127.0.0.1:8000/admin，使用第 3 步创建的管理员账户登录后台发布文章，如何发布文章可参考：创作后台开启，请开始你的表演。

或者执行 fake 脚本批量生成测试数据：
```
$ docker exec -it hellodjango_blog_tutorial_local python -m scripts.fake
```
批量脚本会清除全部已有数据，包括第 3 步创建的后台管理员账户。脚本会再默认生成一个管理员账户，用户名和密码都是 admin。
为 fake 脚本生成的博客文章创建索引，这样就可以使用 Elasticsearch 服务搜索文章
```
$ docker exec -it hellodjango_blog_tutorial_local python manage.py rebuild_index
```
通过 admin 后台添加的文章会自动创建索引。
在浏览器访问：http://127.0.0.1:8000/，可进入到博客首页。

线上部署

线上部署的详细文档请参考下方教程目录索引中的 部署篇 部分，如果不想了解细节或已了解细节，使用 Docker 仅需以下几个简单步骤就可以上线运行：

小贴士：

国内服务器请设置好镜像加速，否则 Docker 构建容器的过程会非常缓慢！具体可参考 部署篇 Docker 部署 django 中线上部署部分的内容。

克隆代码到服务器

$ git clone https://github.com/HelloGitHub-Team/HelloDjango-blog-tutorial.git

创建环境变量文件用于存放项目敏感信息

$ cd HelloDjango-blog-tutorial
$ mkdir .envs
$ touch .envs/.production

在 .production 文件写入下面的内容并保存

# django 用于签名和加密等功能的密钥，泄露会严重降低网站的安全性
# 推荐使用这个工具生成：https://miniwebtool.com/django-secret-key-generator/
DJANGO_SECRET_KEY=0p72%e@r3qr$bq%%&bxj#_bem+na2t^0(#((fom6eewrg)gyb^

# 设置 django 启动时加载的配置文件
DJANGO_SETTINGS_MODULE=blogproject.settings.production

修改 Nginx 配置：复制 compose/nginx/hellodjango-blog-tutorial.conf-tmpl 到同一目录，并重命名为 hellodjango-blog-tutorial.conf，修改第 6 行的 server_name 为自己的域名（如果没有域名就改为服务器的公网 ip 地址）

启动容器

$ docker-compose -f production.yml up --build -d

执行 docker ps 检查容器启动状况，看到如下的 3 个容器说明启动成功：
- hellodjango_blog_tutorial_nginx
- hellodjango_blog_tutorial_elasticsearch
- hellodjango_blog_tutorial
配置 HTTPS 证书（没有配置域名无法配置，只能通过服务器 ip 以 HTTP 协议访问）
```
$ docker exec -it hellodjango_blog_tutorial_nginx certbot --nginx -n --agree-tos --redirect --email email@hellodjango.com -d hellodjango-blog-tutorial-demo.zmrenwu.com
```
解释一下各参数的含义：
- --nginx，使用 Nginx 插件
- -n 非交互式，否则会弹出询问框
- --redirect，自动配置 Nginx，将所有 http 请求都重定向到 https
- --email xxx@xxx.com，替换为自己的 email，用于接收通知
- -d 域名列表，开启 https 的域名，替换为自己的域名，多个域名用逗号分隔
浏览器访问域名或者服务器 ip 即可进入博客首页