Welcome to DeerU’s documentation!¶

Deeru¶

DeerU是一个开源博客系统，它基于django开发

github : https://github.com/gojuukaze/DeerU
docs : https://deeru.readthedocs.io
demo : https://www.ikaze.cn

依赖¶

python 3.6+

django 2.2.x

安装¶

安装前先确保你已经安装了以下程序：

Python 3.6+
pip 10+
git
libjpeg，zlib – pillow包的依赖
- ubuntu: apt-get install libjpeg8-dev zlib1g-dev libfreetype6-dev
- centos: yum -y install python-devel zlib-devel libjpeg-turbo-devel

另外安装之前建议配置虚拟环境

python3 -m venv deeru_env
source deeru_env/bin/activate
# in windows, run this:
# deeru_env/Scripts/activate

使用pip安装¶

pip install deeru
deeru-admin install DeerU

从git仓库安装(不推荐)¶

git clone https://github.com/gojuukaze/DeerU.git
cd DeerU
pip install -r requirements.txt

从git安装需要手动创建两个文件：

deeru/urls_local.py ，内容如下:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('app.urls')),
]

deeru/settings_local.py ，内容如下:

# v2版本开始需要配置
SECRET_KEY = 'xxx'

DEBUG = True

ALLOWED_HOSTS = ['*']

CUSTOM_EXPRESSION = []

CUSTOM_APPS = []

CUSTOM_CONFIG_HANDLER = []

v2版本需要设置你自己的 SECRET_KEY ，可以使用命令 python manage.py gen_secret_key 生成

升级¶

你可以用升级命令进行升级，然后重启DeerU项目:

# 建议升级前更新deeru命令主体
pip install -U deeru
deeru-admin upgrade

upgrade命令参考：升级命令

DeerU采用git仓库进行升级，因此改动源码可能导致升级失败，需要手动解决冲突。项目中 deeru/settings_local.py , deeru/urls_local.py 可以任意修改

1.0升级到2.0指南¶

2.0版本对配置进行了可视化升级，所有需要而外多一些步骤。另外建议先把博客备份到本地，先在本地尝试升级，

备份:

# 备份工程
cp -r deeru deeru.bk
# 备份数据库，也可以使用数据库自带的备份命令
cd deeru
python manage.py dumpdata > ../deeru-v1bk.json

升级:

pip install -U deeru
deeru-admin upgrade

在 settings_local.py 中添加你自己的SECRET_KEY，可以使用命令 gen_secret_key 随机生成:
```
python manage.py gen_secret_key
```
同步数据库修改:
```
python manage.py init_deeru
```

这步最后会把v1配置升级到v2，如果v1的配置不符合规范或者其他原因有可能会失败。

如果失败建议，把v1的配置回复到初始的状态再升级。或者也可以尝试修改 tool/version_upgrade/v1_config_to_v2.py 脚本

使用指南¶

快速入门¶

你阅读以下文档，帮你快速熟悉DeerU，部署你的博客

第一步：安装与运行

安装：安装deeru

初始化：配置并运行deeru

第二步：发布文章与配置

现在你可以登录后台管理页面（http://127.0.0.1:8000/admin）发布文章

配置简介： v2版对配置进行了可视化化改造，现在配置更简单，你可以在这里查看配置的说明

现在你已经学会如何自定义你的博客了，接下来就把你的博客部署放到网上吧

第三步：部署

部署DeerU | 使用Gunicorn部署项目：参考这两篇部署项目，或者按你的喜好自行部署

其他

Settings ：项目的一些配置项，数据库默认使用sqlite如果你想改用mysql，参考里面的说明

备份和恢复：如果你需要备份博客，参考这篇文章

从wordprees导入

sitemap

富文本编辑器：关于富文本编辑器的说明

运行DeerU¶

安装完成后下面我们测试一下DeerU是否能正常运行

初始化¶

运行下面命令初始化项目，注意：如果你更改了数据库的配置，或者修改了主题的静态文件则需要再次运行初始化

cd DeerU # 如果你没进入工程目录先进入
python manage.py init_deeru

2. 在 deeru/urls_local.py 中修改后台管理的url，这一步可以跳过，但使用默认url会把你的登录界面暴露在网络中，造成一些安全隐患

urlpatterns = [
    path('admin123/', admin.site.urls),
]

debug模式运行¶

在正式部署前，先用debug模式运行看看

python manage.py runserver 0.0.0.0:8000

警告

不要生产环境中使用 python manage.py runserver 运行项目，这是不安全的。在生产环境中部署参考部署DeerU

如果一切正常你可以打开浏览器访问 http://127.0.0.1:8000 ,正常情况下你将看到如下页面。

如果你使用的是服务器ip访问，某些服务商默认的防火墙规则里可能不允许8000端口，你需要修改一下

配置¶

你可以在 http://127.0.0.1:8000/admin/app/config/ 中查看修改配置

v1版本中DeerU的所有配置都采用json格式进行配置，v2版使用 json-editor 对配置进行了可视化改造。

如图：

v2版本一共有4大配置：

博客配置

顶部导航栏配置

顶部图标栏配置

通用配置

博客配置¶

博客域名或ip ：指向博客首页的地址
title ：一般就是博客名，会写到html的title标签中
博客名
昵称
主题：使用的主题
百度自动推送：百度的js推送，帮助优化搜索
邮箱配置：开启后，但评论有回复时会发邮件通知评论者

顶部导航栏配置¶

导航栏位置如图：

点击 + 可增加导航项，每个导航有4个可子项：

名字

url

其中分类链接，tag链接填写的是分类/tag的id或名称，最终会生成跳转到分类/tag目录的url

img

图片id，图片名：为上传到相册中的图片

fontawesome图标：使用的是 fontawesome 图标， base_theme使用的是fontawesome5版本，你可以在其官网中获取需要的图标

svg图片

属性： html标签得到属，最终会添加到html标签内。如：style=width:50;height:50 | id=1 对应的html代码为 <img style="width:50;height:50" id="1"/>

二级导航

顶部图标栏配置¶

图标栏分类左右两部分，可分别配置

通用配置¶

这是key-value的配置，通用给开发者方便的增加配置项

部署DeerU¶

部署DeerU和部署Django项目一样，你可以自选查阅网上的Django部署文档。这里提供一个部署方法。

部署一共有3步：

修改settings

部署静态、媒体文件

部署项目

修改settings¶

把 derru/settings_local.py 中的 DEBUG 改为 False ，ALLOWED_HOSTS 改为你的ip或域名

DEBUG = False
ALLOWED_HOSTS = ['www.xxx.com','111.xx.xx.xx']

部署静态、媒体文件¶

django 非debug模式下并不会返回静态、媒体文件，你可以用下面两个方法部署他们文件：

使用nginx/apache 代理，这里给出nginx的配置示例：
location ~ ^/(static|media)/ { root /home/xxx/project/DeerU; # 静态文件返回需要增加跨域头，以便支持http访问https add_header Access-Control-Allow-Origin *; expires 864000; }
注解

如果你没修改过静态文件，媒体文件配置，

则默认的静态文件url是 /static/ ,保存在工程目录下的 static/ 文件夹，

默认的媒体文件url是 /media/ ,保存在工程目录下的 media/ 文件夹，

关于静态文件，媒体文件配置参考Setting中的 STATIC_URL , MEDIA_URL
你也可以选择把静态、媒体文件上传到七牛或其他cdn服务商，然后修改 STATIC_URL , MEDIA_URL 为对应的url
推荐有两个插件自动上传到七牛的插件：
- deeru-qiniu :
- django-qiniu-storage :

注解

什么是静态文件、媒体文件？

静态文件 : 前端的js、css等文件

媒体文件 : 你上传的图片、视频、音频文件

部署项目¶

你可以使用下面三种方法部署项目：

Apache + mod_wsgi 部署

Nginx + uWSGI 部署

Gunicorn

django官方推荐使用Apache + mod_wsgi的方式部署，因为个人喜好的原因这里介绍的是使用Gunicorn部署的方法，详见：使用Gunicorn部署项目

Settings¶

下面只是列举了一些常见配置，以及DeerU的特殊配置，完整配置参考django文档 https://docs.djangoproject.com/en/2.2/ref/settings

DeerU所有的配置请在 deeru/settings_local.py 中添加或修改

数据库配置¶

DeerU默认使用sqlite，如果你需要使用mysql，需要安装mysql连接库 mysqlclient ，并在 settings_local.py 中添加
# settings_local.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'OPTIONS': {
           'charset': 'utf8mb4', # 使用mysql必须设置此项
           'read_default_file': '/path/to/my.cnf',
        },
    }
}


# my.cnf 文件
[client]
host = 127.xx.xx.xx
port = 3306
database = NAME
user = USER
password = PASSWORD
注意：如果你使用mysql，需要手动创建mysql database，并指定字符集为utf8mb4，否则无法初始化。

如果你更改了数据库配置需要再次初始化项目

其他说明以及数据库支持参考

https://docs.djangoproject.com/en/2.2/ref/settings/#databases

https://docs.djangoproject.com/en/3.0/ref/databases

mac上旧版的mysql无法安装 mysqlclient ，需要修改 mysql_config ，具体参考：https://pypi.org/project/mysqlclient/1.4.5/

SECRET_KEY¶

SECRET_KEY，v2版本开始需要在 settings_local.py 中配置（使用deeru-admin命令安装时会随机生成）

CACHES¶

默认使用文件缓存，
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': '/var/tmp/django_cache',
    }
}
你也可以使用内存、数据库、redis等作为缓存，参考 https://docs.djangoproject.com/zh-hans/2.0/ref/settings/#caches

FLATPAGE_URL¶

默认: /p/

单页面url前缀

ALLOWED_HOSTS¶

默认: [‘*’]

允许的hosts

DEBUG¶

默认：True

debug模式下会返回错误信息，不要在生产环境开启

CUSTOM_APPS¶

就是INSTALLED_APPS ，如果你添加了新的app，在 CUSTOM_APPS 中加入

CUSTOM_CONFIG_HANDLER¶

v2配置的自定义handler，用于把配置进行二次处理。

比如：配置图片时选择了图片id，配置保存时会经过handler处理，把图片id变为url。更多说明，参考: 配置handler

STATIC_URL¶

默认：/static/

静态文件的url

STATIC_ROOT¶

默认：工程目录下的 static 文件夹

静态文件保存目录，如果你更改了这一项需要再次初始化项目，或者运行 python manage.py collectstatic 收集静态文件

MEDIA_URL¶

默认：/media/

媒体文件的url

MEDIA_ROOT¶

默认：工程目录下的 media 文件夹

媒体文件保存目录

jet配置¶

jet 是django的后台管理界面扩展

相关配置有：

JET_DEFAULT_THEME : 主题

JET_INDEX_DASHBOARD : 仪表盘配置

其他配置参考： http://jet.readthedocs.io/en/latest/

DEERU_RICH_EDITOR¶

默认:
DEERU_RICH_EDITOR = {
    'filed': 'app.ex_fields.fields.MFroalaField',
    'article_kwargs': {
        ...
    },
    'flatpage_kwargs': {
        ...
    }
}
admin使用的富文本编辑器配置

filed : 富文本编辑器filed路径

article_kwargs : 文章filed的参数

flatpage_kwargs : 单页面filed的参数

froala编辑器配置¶

DeerU后台富文本编辑器使用 froala编辑器

相关配置有：

FROALA_EDITOR_PLUGINS : 插件

FROALA_EDITOR_OPTIONS : 编辑器默认选项，包括语言、上传目录等

具体说明参考： https://github.com/froala/django-froala-editor

验证码¶

评论的验证码，使用 django-simple-captcha

相关配置有：

CAPTCHA_CHALLENGE_FUNCT : 生成验证码的规则。默认使用自定义的算数验证码 tool.captcha.math_challenge

CAPTCHA_FONT_PATH : 字体文件路径。默认使用精简的阿里字体。

如果你修改了验证码的生成规则，需要注意默认字体中很可能不包含你的字符，你需要下载字体，并修改这项值。

免费的字体，精简字体的方法你可以在这里找到： https://www.ikaze.cn/article/47

其他说明参考： https://django-simple-captcha.readthedocs.io/en/latest/advanced.html#configuration-toggles

弃用配置¶

CUSTOM_EXPRESSION¶

v1配置的自定义表达式

备份和恢复¶

备份deeru你只需要备份数据库， deeru/settings_local.py , deeru/urls_local.py 以及上传的媒体文件

你可以使用django内置命令备份、恢复数据库

备份命令：

python manage.py dumpdata >mybk.json

恢复命令：

python manage.py loaddata  mybk.json

内置命令¶

所有内置命令放在 app/management/commands , deeru_cmd/management/commands 下

安装¶

install¶

下载DeerU:

deeru-admin install name [--branch master]

name:: 项目的文件夹名称
branch:: 从哪个分支下载，默认master

升级¶

upgrade¶

升级DeerU:

python manage.py upgrade

DeerU使用的是git进行升级，因此改动源码可能会导致升级失败。如改动了源码你需要手动运行 git pull origin master 升级，并解决冲突。

另外升级后你需要手动重启DeerU

创建第三方模块¶

start¶

升级DeerU:

python manage.py start type name

给开发者用的命令，创建DeerU的第三方主题或插件，使用这个命令会自动生成 setup.py , README.md , .gitignore 等必要的文件，方便开发

type:: 类型，可选项 theme、plugin
name:: 第三方模块名

初始化¶

init_deeru¶

初始化DeerU:

python manage.py init_deeru

初始化数据库，收集静态文件

从wordprees导入¶

import_wordpress¶

从wordprees的xml文件导入:

python manage.py import_wordpress xml_path [--mode (a|c|t)] [--nwp ] [--ncontent] [--cover (y|n|ask)]

xml_path:

xml文件路径

mode:

导入的内容，默认:a

a : 文章、评论、分类、标签
c : 分类
t : 标签

nwp:

xml文件中命名空间wp的内容，默认: {http://wordpress.org/export/1.2/}

ncontent:

xml文件中命名空间content的内容，默认: {http://purl.org/rss/1.0/modules/content/}

cover:

是否使用xml文件中的内容覆盖数据库中的内容，默认:ask

y : 是
n : 否
ask : 询问我

注解

1.不会导入未审核的评论，如果需要去掉get_comment()中对应的部分

2.wordprees的日期格式必须为： 2018-05-02 15:23:22

3.对评论的回复会自动在内容前添加 “回复 xx：”，如果不需要去掉save_comment()中对应部分

4.不会导入草稿

备份数据库¶

dumpdata¶

django自带的备份命令:

python manage.py dumpdata >mybk.json

恢复数据库¶

loaddata¶

django自带的恢复命令:

python manage.py loaddata  mybk.json

sitemap¶

DeerU提供了一个简单的sitemap，访问 http://127.0.0.1:8000/sitemap.xml 获取

开发指南¶

一些建议¶

开发代码时的一些建议开发建议

model说明¶

Model

配置说明¶

配置

主题开发¶

开发主题你首先要了解一下基本的东西开发主题
然后你需要知道 context 的结构 Context ，context中model的方法 Model
还有每个view里都返回了什么 url-view

v1版旧的插件开发指南¶

虽然现在放弃了插件支持，但如果需要自己开发扩展也可以读读

基础：概述
开发插件：开发插件

贡献代码¶

你发现了bug或者优化了代码并且想合并到主分支？

首先你需要fork代码到你的仓库，然后切换到dev分支，在dev分支上开发完成后再github中提交 pull request，合并到dev分支。

注解

只接受合并到dev分支的pull request

Change Log¶

2.0.1¶

替换主题中的cdn连接

修改初始文章

2.0.0¶

修复下一篇按钮的连接bug

升级js以及py包

view_class的context规范化

修改文章简介、图片的提取逻辑

配置可视化

评论支持审核

修改评论数统计规则，只统计对文章的评论

admin增加仪表盘

新回复邮件提醒功能

增加日志功能

评论增加验证码

1.1.0 -alpha¶

评论root_id,to_id规范

评论参数验证

fix bug #6

升级django版本，解决低版本安全问题 CVE-2018-14574 Detail

1.0.0¶

第一个正式版发布

0.2.0 - alpha¶

单页面

修改安装方式

重新设计表达式

添加了一些内置命令

完善文档

修改bug

0.1.0 - alpha¶

第一个测试版完成

License¶

DeerU使用 GNU General Public License v3.0 协议，你可以在遵循此协议的情况下免费使用DeerU

警告

需要注意的是，DeerU本身是免费的，但后台管理使用了富文本编辑器froala，其扩展插件并不免费，你可以在以下链接中查看收费信息：

https://github.com/froala/django-froala-editor#license

https://froala.com/wysiwyg-editor/pricing

你可以自己更换其他编辑器（参考富文本编辑器）

截图¶

首页

文章详情

admin

admin2

admin3

手机端页面

手机端页面

手机端页面

Welcome to DeerU’s documentation!¶

Deeru¶

依赖¶

安装¶

使用pip安装¶

从git仓库安装(不推荐)¶

升级¶

1.0升级到2.0指南¶

使用指南¶

快速入门¶

运行DeerU¶

初始化¶

debug模式运行¶

配置¶

博客配置¶

顶部导航栏配置¶

顶部图标栏配置¶

通用配置¶

部署DeerU¶

修改settings¶

部署静态、媒体文件¶

部署项目¶

Settings¶

数据库配置¶

SECRET_KEY¶

CACHES¶

FLATPAGE_URL¶

ALLOWED_HOSTS¶

DEBUG¶

CUSTOM_APPS¶

CUSTOM_CONFIG_HANDLER¶

STATIC_URL¶

STATIC_ROOT¶

MEDIA_URL¶

MEDIA_ROOT¶

jet配置¶

DEERU_RICH_EDITOR¶

froala编辑器配置¶

验证码¶

弃用配置¶

CUSTOM_EXPRESSION¶

备份和恢复¶

内置命令¶

安装¶

升级¶

创建第三方模块¶

初始化¶

从wordprees导入¶

备份数据库¶

恢复数据库¶

sitemap¶

开发指南¶

一些建议¶

model说明¶

配置说明¶

主题开发¶

v1版旧的插件开发指南¶

贡献代码¶

Change Log¶

2.0.1¶

2.0.0¶

1.1.0 -alpha¶

1.0.0¶

0.2.0 - alpha¶

0.1.0 - alpha¶

License¶

截图¶

Indices and tables¶