Graphite是一个开源项目，可以作为时间序列数据库（TSDB）使用，当你需要存储随着时间变化的数值时，应当考虑使用时间序列数据库。

除了数据的存储、查询外，Graphite还提供数据可视化（UI层）功能，它可以很好的在廉价的硬件上运行。你可以使用Graphite来监控网站、应用程序、网络服务器等的性能数据（Metrics），轻松实现基于时间维的分析。

Graphite本身不负责性能数据的采集，但是它提供了简单易用的接口，公共这些接口你可以把基于数字的性能数据存储到Graphite中。

Graphite由三个组件构成：

1. Carbon：一个基于Twisted（Python事件驱动网络框架）的守护程序，负责监听外部的时间序列数据
2. Whisper：一个简单的存储时间序列数据的数据库，设计上和RRDtool类似 
3. Graphite-Web：一个基于Django（Python Web框架）的Web应用，使用Cairo（一个2D图形库）来渲染性能数据的图表，使用ExtJS作为基础UI框架

下面是Graphite的架构图：

一旦你把数据送给Carbon，它就立刻可以在Webapp的图表中显示，因为数据在被写入文件系统之前，会驻留在缓存中。

除了使用Graphite Webapp，你也可以通过URL API，将图表嵌入到自己的应用程序中去。如何使用Graphite

使用Graphite来监控你的性能数据，你需要完成以下工作：

1. 理解Graphite组件的职责和相互关系
2. 安装Graphite及其依赖
3. 基础的配置，让Graphite能运行起来
4. 设计Metrics路径
5. 配置Metrics的驻留规则、聚合规则等
6. 向Graphite发送Metrics
7. 从Graphite获取Metrics并展示

Metrics路径由点号分隔的字符串构成，类似于Python的包名称。路径是Metrics的标识。

你应当仔细的设计此路径的命名空间，以反映出所有Metrics之间的层次关系。例如servers.zircon.cpu，这个三级路径设计中，第一级表示设备类别，第二级表示设备名称，第三级表示监测点类型。

Carbon由一系列的守护进程组成，这些守护进程共同组成Graphite的存储后端。在最小化的安装下，只有一个守护进程carbon-cache.py。根据需要你可以启用carbon-relay.py、carbon-aggregator.py以便实现Metrics分发、定制聚合规则。各Carbon守护进程简介如下：

Whisper是一个固定大小（fixed-size）的数据库，其设计和用途与RRD（round-robin-database）类似。它能提供快速、可靠的数值数据的存储。

Whisper能够对最近的数据进行高分辨率的存储，而对久远的历史数据，自动降低其存储精度（减少样本数量）。

在大多数场景下，Whisper有足够好的性能。它比RRDtool慢，主要原因是Whisper基于Python编写，这个性能差异很小，通常不需要考虑。

Whisper数据库以文件方式存放在磁盘上，扩展名.wsp。Carbon会为每个Metrics创建一个.wsp文件，路径的最后一节作为文件的basename，路径的其它部分形成目录层次。

在Whisper中存储的每一个数值，称为数据点（Data Points）。

在磁盘上，数据点以大端、双精度浮点数存储。每个数据还附带一个时间戳信息，时间戳为1970-01-01到数据采集时间的秒数。

一个Whisper数据库文件可以包含一个或者多个“归档”，归档是数据文件中的逻辑段。

每个归档具有不同的数据分辨率（一定时间段内，数据点数量越多，则分辨率越高）。归档以最高分辨率（最小驻留时间） —— 最低分辨率（最长驻留时间）的顺序，在数据库文件中顺序排列。

为了精确的从高分辨率向低分辨率的归档聚合，高分辨率归档和它之后的低分辨率归档，其分辨率应当具有整除关系。例如，第一个归档分辨率为60秒/数据点，那么第二个归档可以是300秒/数据点，第三个归档可以是3600秒/数据点。

一个数据库的总计驻留时间（存放的数据点跨越的时间），由最长驻留时间的（最后一个）归档确定。因为之前的那些归档，时间区间都是它的子区间。

把数据点转移到低分辨率归档时，面临着如何把多个数据点转变为单个数据点的问题。Whisper支持average、sum、last、max、min等聚合函数。

注意，这里的聚合和Carbon提供的前置聚合不是一回事。

当Whisper向一个多归档数据写入Metrics时，数据点将被同时写入到所有的归档中。这意味着聚合动作随时可能发生。

当从Whisper中获取数据时，第一个能完整覆盖所需区间的归档被使用。

Whisper的磁盘利用效率不高，因为：

1. 每个数据点要附加一个时间戳信息
2. 由于归档的时间区间有重叠，因此数据存在冗余
3. 归档中的时间槽位（time-slots）总是占据着磁盘空间，不管有没有值存储在其中

这些特征是故意的，主要出于性能方面的考虑。

1. RRD不能去填充以前的时间槽位。这意味着每一条数据都必须是更新的，不会“补录”
2. RRD不能很好的支持不规则的数据更新。如果RRD接收到一条数据，但是后续数据没有到来，则前一条数据可能丢失

git clone https://github.com/graphite-project/graphite-web.git
graphite-web/check-dependencies.py
# 根据输出的提示来判断缺少哪些依赖，然后安装

yum -y install python-devel     # Carbon 依赖于 Python Development Headers

yum install pycairo             # Cairo库的Python绑定

pip install django              # Web框架
pip install django-tagging

pip install pytz

yum install fontconfig

yum install -y memcached        # 可选，缓存支持
pip install python-memcached    
                                # 可选，RDDTool
yum install cairo-devel libxml2-devel pango-devel pango libpng-devel freetype freetype-devel libart_lgpl-devel rrdtool-devel

pip install python-rrdtool      # 可选，RRD支持

pip install whitenoise          # 用于Web静态文件处理

yum install pyOpenSSL           # OpenSSL的Python绑定
pip install service_identity    # SSL相关

pip install https://github.com/graphite-project/ceres/tarball/master
pip install whisper
pip install carbon
pip install graphite-web

sudo groupadd graphite
sudo usermod -a -G graphite root
sudo usermod -a -G graphite apache
sudo chgrp -R graphite /opt/graphite/storage
sudo chmod -R 770 /opt/graphite/storage

Whisper被安装到Python全局site-packages目录，另外两个Graphite组件安装到

/opt/graphite

$GRAPHITE_ROOT

$STORAGE_DIR

你需要让Graphite-web的底层框架Django执行数据库的初始化。此数据库被用来存放用户设置、仪表盘，以及支持事件功能。

默认情况下，Graphite-web使用位于$STORAGE_DIR/graphite.db的SQLite数据库。如果要运行多个Graphite-web实例，则必须使用MySQL等数据库以便多个实例可以共享数据。 

执行下面的命令初始化SQLite数据库：

PYTHONPATH=/opt/graphite/webapp django-admin.py migrate --settings=graphite.settings --run-syncdb
# 完毕后 $STORAGE_DIR/graphite.db自动创建

Django应用需要在Web服务器中运行，Web服务器需要对SQLite数据文件有读写权限。假设你使用Apache2，运行Apache2的用户为apache，则需要执行：

sudo chgrp graphite /opt/graphite/storage/graphite.db

Graphite不建议修改settings.py，所有定制化的配置，都应该在此文件中进行。常用的设置项如下表：

rrdtool flushcached

DEFAULT_CACHE_POLICY = [
    (0, 60), # 默认缓存60秒
    (7200, 120) # >= 2小时以上时间范围的查询，缓存2分钟
] 

# 如果报Unknown command: 'collectstatic' 说明INSTALLED_APPS中缺少
# django.contrib.staticfiles	
PYTHONPATH=/opt/graphite/webapp django-admin.py collectstatic 
    --noinput --settings=graphite.settings

Alias /static/ "/opt/graphite/static"

我们的配置如下：

# 如果不设置，会导致报错：AttributeError: 'Settings' object has no attribute 'URL_PREFIX
URL_PREFIX = '/'

多种Web服务器可以用于运行基于Django的Web应用，这里我们选择Apache2。在CentOS下安装Apache2：

yum install httpd

要让Apache2能够运行Python Web应用，需要安装模块mod_wsgi。参考Django学习笔记完成mod_wsgi的构建与安装。

在/opt/graphite/examples/目录下，example-graphite-vhost.conf可以作为Apache虚拟主机的模板，复制该文件到/etc/httpd/conf.d/目录下，然后修改：

<IfModule !wsgi_module.c>
    LoadModule wsgi_module modules/mod_wsgi.so
</IfModule>
WSGISocketPrefix run/wsgi
<VirtualHost *:7767>
        ServerName xcentos7.local
        DocumentRoot "/opt/graphite/webapp"
        ErrorLog /opt/graphite/storage/log/webapp/error.log
        CustomLog /opt/graphite/storage/log/webapp/access.log common
        WSGIDaemonProcess graphite processes=5 threads=5 display-name='%{GROUP}' inactivity-timeout=120
        WSGIProcessGroup graphite
        WSGIApplicationGroup %{GLOBAL}
        WSGIImportScript /opt/graphite/conf/graphite.wsgi process-group=graphite application-group=%{GLOBAL}
        WSGIScriptAlias / /opt/graphite/conf/graphite.wsgi
        Alias /content/ /opt/graphite/webapp/content/
        <Directory /opt/graphite/webapp/content/>
            Require all granted
        </Directory>
        <Directory /opt/graphite/conf/>
            Require all granted
        </Directory>
</VirtualHost>

如果配置没有问题，启动Web服务器后访问：

http://GRAPHITE_HOST:GRAPHITE_PORT/render

所有Carbon守护进程可以基于多种通信协议，监听时间序列数据，并且对数据进行不同的处理。

Carbon的配置文件位于/opt/graphite/conf/目录，默认情况下没有预置的配置文件，但是Graphite提供了若干配置文件样例。你可以复制这些配置文件并定制：

pushd /opt/graphite/conf
cp carbon.conf.example carbon.conf
cp storage-schemas.conf.example storage-schemas.conf

这是主配置文件，为每个Carbon守护进程定义配置项。该配置文件按段区分不同守护进程的配置：

这个配置文件用于定义Metrics的驻留率（ retention rates）——即Metrics的数据点（datapoints）以什么频率保存，保存多长时间。关于该配置文件，需要注意：

1. 该配置文件可以由多个段（Section）组成。每个段定义一个存储规则
2. 这些规则按照从上到下的顺序对Metrics进行匹配，第一个匹配的规则对Metrics生效
3. 匹配Metrics时，采用的是正则表达式
4. 对于一个Metrics，其存储规则在接收到第一个数据时固化。因而修改此配置文件不会影响到既有的.wsp文件。要应用到既有的.wsp可以调用whisper-resize.py

每个规则由三个部分组成：

# 段名称（规则名称），主要是文档用途。在匹配段的Metrics被创建时，日志creates.log中会显示此名称
[rulename]
# 匹配Metrics路径（Metrics的全限定名称，点号分隔）的正则式
# 举例：^servers\.www.*\.workers\.busyWorkers$
pattern=regex
# 驻留率表达式，数据点间隔:存留天数，时间后缀s,m,h,d,y分别表示秒、分、小时、天、年
# 举例：10s:14d 表示每个数据点表示10秒（相当于每10秒采集数据一次），并且存储14天的数据
retentions=retention rate

注意，你可以指定多重驻留率表达式（retention rate），逗号分隔每个表达式。一般从最高精度:最短存留时间开始指定，直到最低精度:最长存留时间。例如：

15s:7d,1m:21d,15m:5y

设置多重驻留率表达式，可以在保存足够长时间的历史数据的前提下，尽量减少磁盘I/O和消耗的存储空间。当跨越驻留表达式的时间区间（上例中7天，21天）后，whisper会自动降低采样率（downsamples），默认算法是取平均值，可以通过storage-aggregation.conf定制聚合方式

这个配置文件定义如何在降低采样率（转换为低精度存储时） 如何对数据进行聚合。该文件的格式与storage-schemas.conf类似：

[rulename]
pattern = rexexp
# 0-1之间的浮点数，默认0.5。聚合区间内的值，至少多少比例为非空，聚合后的值才是非空
xFilesFactor = 0.5
# 数据聚合方式，默认average
aggregationMethod = average | sum | min | max | last

同样的，修改此文件不会影响已经生成的.wsp文件， 要应用到既有的.wsp文件，可以调用whisper-set-aggregation-method.py。

这个配置文件指定中继规则——即需要把何种Metrics转发给何种后端。中继由Carbon的中继进程负责执行。该文件格式如下：

[rulename]
pattern = regex
servers = ip:port,ip:port,...

该配置文件定义聚合出来的Metrics——由几个Metrics聚合而成的新的Metrics。聚合由Carbon的聚合进程负责执行。

注意：这里的聚合storage-aggregation.conf提及的聚合不同。后者用于单一Metrics的降低采样，而前者用于生成新的Metrics。

与其它配置文件不同，该文件一旦更改，立即生效。

该文件的格式如下：

# 捕获任何匹配input_pattern的Metrics，使用method聚合成新的Metrics：output_template
# frequency：每隔多久执行一次聚合
# method：可选sum/avg
output_template (frequency) = method input_pattern

举例，假设你的Metrics的命名规则是：

<env>.applications.<app>.<server>.<metric>

这是你可以配置如下聚合规则，来计算所有应用程序的请求的总数：

<env>.applications.<app>.all.requests (60) = sum <env>.applications.<app>.*.requests

在此规则下，下面的Metrics：

test.applications.pems.221.request
test.applications.pems.6.request
test.applications.pems.5.request
test.applications.pems.201.request

会每个60秒求和并生成 

test.applications.pems.all.request

该配置文件定义Metrics名称的改写规则。 与其它配置文件不同，该文件一旦更改，立即生效。该文件的格式如下：

[pre]
# pre段的规则，在接收到数据后立即执行改写
[post]
# post段的规则，在聚合完毕后执行改写
regex-pattern = replacement-text

 举例：

# \1表示第一个捕获，即[a-z0-9]+
^collectd\.([a-z0-9]+)\. = \1.system.
# collectd.prod.cpu-0.idle-time 会被改写为 prod.system.cpu-0.idle-item

Carbon提供黑白名单功能。白名单：仅仅接受其中列出的Metrics；黑名单：拒绝其中列出Metrics。

要启用黑白名单功能，需要修改carbon.conf，设置

USE_WHITELIST = True

如何启动Graphite Webapp依赖于其运行的Web服务软件，以Apache为例：

# CentOS 7
systemctl restart httpd

Carbon组件需要执行下面的命令来启动：

/opt/graphite/bin/carbon-cache.py start

SQLite是一个“文件数据库”，不需要启动。如果Graphite Webapp使用其它数据库，例如MySQL，则需要启动之。 

你可以通过多种方式向Graphite（的Carbon组件）发送Metrics数据点。主要的三种数据格式是：Plaintext、Pickle、AMQP 

这种方式非常简单，你可以用如下格式来发送一条Metrics数据点：

<metric path> <metric value> <metric timestamp>
# 举例：
servers.zircon.cpu 85 1470303923

出于测试目的，你可以直接通过命令向Carbon发送Metrics数据：

PORT=2003
SERVER=127.0.0.1
echo "servers.zircon.cpu 85 `date +%s`" | nc ${SERVER} ${PORT}

Pickle是Python下的对象串行化框架，Pickle协议即它的串行化格式协议。使用该协议，你可以一次发送多个Metrics，并且串行化后的数据比较紧凑，因此Pickle协议性能更好。

下面是构建Pickle报文的示例代码：

listOfMetricTuples = [
    (path, (timestamp, value)),
    ...
]
payload = pickle.dumps(listOfMetricTuples, protocol=2)
header = struct.pack("!L", len(payload))
message = header + payload
# 然后通过Socket把message发送出去即可

import pickle
import socket
import struct
import sys
import time
from time import sleep

import psutil


def get_cpu_load():
    load = psutil.cpu_percent()
    print load
    return load


if __name__ == '__main__':
    CARBON_HOST = '172.16.87.132'
    CARBON_PORT = 2004
    s = socket.socket()
    try:
        s.connect((CARBON_HOST, CARBON_PORT))
        while True:
            data = [
                ('servers.zircon.cpu', (time.time(), get_cpu_load()))
            ]
            pkg = pickle.dumps(data, 1)
            s.sendall(struct.pack('!L', len(pkg)))
            s.sendall(pkg)
            sleep(5)
    except socket.error:
        raise SystemExit("Failed to connect to %(host)s:%(port)" % {'host': CARBON_HOST, 'port': CARBON_PORT})
    except KeyboardInterrupt:
        sys.stderr.write("\nExiting on CTRL-C\n")
        sys.exit(0) 

要从Graphite获取数据用于展示，可以使用Graphite Webapp暴露的Render URL API（RUA）。你可以通过

http://GRAPHITE_HOST:GRAPHITE_PORT/render

访问此API。要向RUA传递参数，可以使用URL请求参数方式：

&name=value

下面列出几个RUA的URL示例：

# Zircon的CPU负载图，获取800x600的图片
http://graphite/render?target=servers.zircon.cpu&height=800&width=600
# 最近12小时，所有服务器的CPU负载平均值
http://graphite/render?target=averageSeries(servers.*.load)&from=-12hours
# 获取原始数据而不是图片，JSON格式
http://graphite/render?target=servers.zircon.cpu&format=json

该参数用来指定从何处获取数据，你可以指定：

1. 单个Metrics路径
2. 带有通配符的的Metrics路径，匹配多个Metrics
3. 函数调用，针对作为入参的Metrics进行各种转换、合并操作

你可以在路径中使用三种风格的通配符：

1. *

    可以匹配0-N个字符，例如

   servers.dev-*.cpu

    ，可以匹配所有开发服务器的CPU负载Metrics。

2. [...]

    可以匹配列表中枚举的单个字符，例如

   servers.dev-[a-z0-9].cpu

    ，可以匹配dev-0、dev-1等服务器的CPU负载Metrics。

3. {...}

    可以匹配列表中枚举的单个字符串，例如

   servers.{dev-0,dev-1}.cpu

    ，匹配dev-0、dev-2的CPU负载Metrics。

注意：所有通配符都不能跨越点号。 

你可以指定target为template函数调用，从而在Metrics路径中使用变量，例如：

# $varname 用来声明变量占位符
# template[varname]参数用来传递变量值
&target=template(servers.$servername.cpu)&template[servername]=zircon

# 可以使用数字代替变量名
&target=template(servers.$1.cpu)&template[1]=zircon

# template可以内嵌其它函数
&target=template(constantLine($number))&template[number]=123

可用的函数较多，这里不一一列举说明，参见官方文档。

这两个可选参数用来指定相对或者绝对的时间区间（time period）。from表示区间起点，如果忽略，默认值是24小时之前；until表示区间终点，如果或略，默认值是当前时间点。

如果要使用相对时间，需要加上

-

你可以指定

HH:MM_YYYYMMDD

YYYYMMDD

 MM/DD/YY

该参数用来指定要获取的数据的格式。 支持以下取值：

<target name>,<start timestamp>,<end timestamp>,<series step>|[data]*

entries,1311836008,1311836013,1|1.0,2.0,3.0,5.0,6.0

entries,2011-07-28 01:53:28,1.0
entries,2011-07-28 01:53:29,2.0
entries,2011-07-28 01:53:30,3.0
entries,2011-07-28 01:53:31,5.0
entries,2011-07-28 01:53:32,6.0

[{
  "target": "entries",
  "datapoints": [
    [1.0, 1311836008],
    [2.0, 1311836009],
    [3.0, 1311836010],
    [5.0, 1311836011],
    [6.0, 1311836012]
  ]
}]

{
  "labels" : [
    "Time",
    "entries"
  ],
  "data" : [
    [1468791890000, 0.0],
    [1468791900000, 0.0]
  ]
}

[{
  "target": "entries",
  "datapoints": [{
    "y": 0.0,
    "x": 1468791890
  }, {
    "y": 0.0,
    "x": 1468791900
  }]
}]

[
  {
    'name' : 'summarize(test.data, "30min", "sum")',
    'start': 1335398400,
    'end'  : 1335425400,
    'step' : 1800,
    'values' : [None, None, 1.0, None],
  }
]

你可以指定多个参数，来控制生成的图形的样式：

# 颜色名称
&bgcolor=blue
# HEX代码
&bgcolor=2222FF
# HEX代码，包含透明度
&bgcolor=5522FF60

上一章内容我们讨论了如何获取Graphite数据。通过Render URL API，我们不但可以获得文本数据，还可以直接获得渲染好的图片。这意味着通过Render URL API本身就可以实现Metrics的渲染，你只需要把生成的图片嵌入到自己的应用程序中即可。

Graphite Webapp本身提供了基于ExtJS的一个管理界面，你可以通过

http://GRAPHITE_HOST:GRAPHITE_PORT/admin

Graphite生成的Metrics曲线的图片，不是非常美观，而静态图片也缺乏交互性。因此，实际项目中常常结合使用第三方基于JavaScript的Charts库来做展示，例如：

1. Grafana：UI比较绚丽，支持设计仪表盘、时间区间联动。参见：使用Grafana展示时间序列数据
2. Graphene：一个较为简单的，基于D3.js和Backbone.js的Graphite仪表盘工具

除了简单的，基于Key/Value的Metrics数据，Graphite还可以存储、展示随机出现的数据——事件。

事件不适合存储在Whisper中，因此它被存储在Graphite的Webapp的数据库中（默认使用SQLite）。

通过向

http://GRAPHITE_HOST:GRAPHITE_PORT/events/

{ 
    "what": "事件类型", 
    "tags": "标签",
    "data": "事件相关的数据" 
}

指定target为

event(*tags)

/render

[
   {
      "target" : "events(mytag)",
      "datapoints" : [
         [
            1,
            1388966651
         ],
         [
            3,
            1388966652
         ]
      ]
   }
]

你也可以通过

/render/events/get_data

[
   {
      "when" : 1392046352,
      "tags" : "mytag",
      "data" : "...",
      "id" : 2,
      "what" : "Event - deploy"
   }
] 

Django的request对象曾经有一个属性REQUEST，用来获得通过GET或者POST请求传递的请求参数，在1.9版本中此属性已经移除。

Graphite代码没有即时更新，存在不兼容的问题，修改一下即可：

def parseOptions(request):
   queryParams = request.GET # request.REQUEST已经被移除

还有很多其它views.py存在同样的问题，最好搜索一下一并修改。如果觉得麻烦可以安装兼容版本的Django：

pip install django==1.8.14

The post Graphite学习笔记 appeared first on 绿色记忆.

Django是一个Python的Web开发框架，它是一个WSGI规范的框架端实现。使用该框架可以把你从Web开发的很多重复劳动中解放出来而专注于业务逻辑。

Django运行速度非常快、并且是可扩容的，安全性方面也做的很好，可以避免一些常见的安全性错误。

最新的1.9版本，要求Python版本为2.7、3.4或者3.5。具体安装步骤本文不赘述，可以参考Python知识集锦。

Django内置了一个简单的开发用Web服务器，可以用于开发和测试，要启动此服务器，只需要：

# 先进入工程根目录
cd librarymgr
# 启动开发服务器
python manage.py runserver

这个开发服务器会自动重新载入最新的Python代码，便于开发调试。

在生产环境下你应当使用可靠的Web服务器，例如Apache、Nginx等。

这个组合可以作为Django的Web容器。Apache是广泛使用的、模块化的Web服务器；而mod_wsgi模块则是一个Apache模块，同时也是WSGI规范的服务器端实现，安装此模块后Apache可以和任何支持WSGI的Python Web应用通信，例如基于Django的应用。

mod_wsgi有两种运行模式：

1. 嵌入式模式：类似于mod_perl，Python被嵌入在Apache中，Python代码在Apache启动时加载到Apache进程空间并驻留直到Apache进程结束。这种方式具有较高的性能
2. 守护模式：mod_wsgi产生独立进程，由该进程来处理请求。此进程的运行用户可以不同于Apache进程。此进程可以独立于Apache重启，因而在开发期间可以更无缝的更新代码

手工构建mod_wsgi的步骤如下：

wget https://github.com/GrahamDumpleton/mod_wsgi/archive/4.5.3.tar.gz
tar xzf 4.5.3.tar.gz 
cd mod_wsgi-4.5.3/
./configure
# 在Linux上，Apache2默认使用的MPM（多处理模块）是prefork，下面安装开发支持
# 如果是CentOS，安装 yum install httpd-devel
sudo apt-get install apache2-prefork-dev
make && sudo make install 
# 构建好的模块默认被安装到：
# Ubuntu 14 /usr/lib/apache2/modules/mod_wsgi.so
# CentOS 7  /usr/lib64/httpd/modules/mod_wsgi.so

然后，你需要让Apache加载mod_wsgi模块。你可以使用a2enmod命令或者修改配置文件： 

LoadModule wsgi_module /usr/lib/apache2/modules/mod_wsgi.so

如果要使用Django的数据库API，你需要安装数据库服务器。Django支持多种数据库后端，官方支持包括：PostgreSQL、MySQL、Oracle和SQLite，其它主流数据库有第三方支持。开发一个简单的项目，不需要在生成环境部署时，你可以使用SQLite，它不需要独立的服务器，也不需要安装第三方Python模块。

除了后端以外，你还需要安装对应的Python database bindings：

# MySQL
sudo pip install mysqlclient
# PostgreSQL
sudo pip install  psycopg2

如果你想用Django的

manage.py migrate

你可以通过pip安装：

# 安装Release
sudo pip install django
# 安装开发版本
git clone git://github.com/django/django.git
sudo pip install -e django/

本章通过一个简单的图书馆管理系统，来了解Django的开发流程和基本的API。

开始编程之前，你需要创建一个Django工程：

cd ~/Python/projects/pycharm
django-admin startproject librarymgr

上面的命令会在当前目录下创建一个librarymgr目录，这是新工程的根目录，其结构如下：

└── librarymgr               # 工程容器目录
    ├── manage.py            # 一个命令行工具，通过它你可以和Django工程互动
    └── librarymgr           # 当前工程对应的Python包
        ├── __init__.py      # 空白文件，仅仅用于识别当前目录为一个包
        ├── settings.py      # 当前Django工程的设置/配置
        ├── urls.py          # 当前工程的URL映射声明
        └── wsgi.py          # WSGI兼容的Web服务器的入口点，部署工程时用到此文件

一个Django实例的全部设置：  数据库配置、Django选项、应用程序选项，都存放在工程目录下。

你可以直接把工程容器目录作为PyCharm工程打开，PyCharm会自动识别并启用Django支持。

执行下面的命令，可以启动开发服务器：

# 默认监听127.0.0.1:8000
python manage.py runserver   
# 监听所有网络接口
python manage.py runserver 0.0.0.0:8000

注意此服务器会自动Reload最新的Python代码，因而你不需要在修改代码后重启服务器。但是某些时候，例如添加了新文件，可能不会自动载入，这时你需要手工重启。 

使用PyCharm时，用于启动开发服务器的Run Configuration会自动创建，点击工具栏按钮即可启动。 

到目前为止，开发环境已经搭建完毕，可以实现功能了。

在一个工程中，可以包含多个Django应用，有时你可能觉得称之为模块更合适。而每个应用也可以归属于多个工程。工程中的应用共享工程的配置——例如数据库连接。每个Django应用由一个Python包组成，这个包包含一些约定俗成的内容。

你可以把Django应用放置在PYTHONPATH中的任意目录，在这里，我们把它们放置在工程根目录下。执行下面的命令，创建一个应用：

python manage.py startapp bookmgr

命令执行完毕后，工程结构如下：

├── bookmgr
│   ├── admin.py
│   ├── apps.py                 # 包含当前应用的定义及配置
│   ├── __init__.py
│   ├── migrations
│   │   └── __init__.py
│   ├── models.py               # 在这里定义模型类
│   ├── tests.py
|   ├── urls.py                 # 在这里定义URLconf，即URL和视图的映射关系
│   └── views.py                # 在这里创建新的视图
├── librarymgr
│   ├── __init__.py
│   ├── __init__.pyc
│   ├── settings.py
│   ├── settings.pyc
│   ├── urls.py
│   └── wsgi.py
└── manage.py

我们为图书管理模块添加一个最简单的视图，在响应中简单的输出欢迎文字：

from django.http.response import HttpResponse

def index(request):
    return HttpResponse("Welcome to Book Management module.") 

要调用视图，必须将其映射到某个URL，因而我们需要

URLconf

urls.py

from django.conf.urls import url

from . import views

# 该固定名称的变量定义一系列的URL映射规则
urlpatterns = [
    # url函数定义URL到视图的映射，注意URL的base部分可能已经被父URLconf脱去。该函数接受4个参数
    # regex 匹配URL的正则式，注意此正则式不搜索GET/POST参数或者网址的域名部分，例如对于
    #       https://librarymgr.gmem.cc/bookmgr/?id=1，进行匹配判断的仅仅时bookmgr/
    # view  匹配后，需要调用的视图函数，并把HttpRequest作为第一个入参，正则式中捕获的分组依次作为后续位置参数
    #       如果使用正则式的命名分组，则捕获的分组作为关键字参数传入
    # kwargs 所谓关键字参数
    # name  为URL命名，以便从Django的其它地方——例如模板中——无歧义的引用之
    url(r'^$', views.index, name = 'index')
]

完成URL到视图的映射后，必须把URLconf包含到工程的根URLconf中去： 

from django.conf.urls import url, include
from django.contrib import admin

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    # 使用include函数引用其它URLconf
    # 在处理请求时，前缀匹配部分bookmgr/会自动去除，把剩余的部分传递给子URLconf，进行匹配
    url(r'^bookmgr/', include('bookmgr.urls'))
]

现在启动开发服务器，输入网址http://127.0.0.1:8000/bookmgr/，你应该可以看到之前编写的欢迎文字。 

传统的增删改查应用是离不开数据库的，我们可以为工程中所有模块配置共享的数据源。

librarymgr/settings.py

默认情况下，配置文件包含了SQLite的配置：

# 工程使用的所有数据源
DATABASES = {
    # 单个数据源
    'default': {
        # 引擎（数据库后端），其它可选引擎包括：
        # django.db.backends.postgresql、django.db.backends.mysql、django.db.backends.oracle等
        'ENGINE': 'django.db.backends.sqlite3',
        # 数据库的名称，如果使用SQLite，则指定数据库文件的绝对路径
        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
    }
}

不使用SQLite时，你需要提供额外的配置项。本章使用MySQL数据库：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'test',
        'USER': 'root',
        'PASSWORD': 'root',
        'HOST': '127.0.0.1',
        'PORT': '3306',
    }
}

由于默认激活的那些应用程序必须使用表，因此必须初始化数据库，即创建表结构、初始化表数据，执行下面的命令：

# 根据DATABASES设置，以及应用的INSTALLED_APPS的database migrations，完成表创建和数据插入
python manage.py migrate

配置完数据库后，顺便设置一下时区：

TIME_ZONE = 'Asia/Shanghai'

包含该实例激活的Django应用程序的名称，默认激活以下通用应用：

图书管理模块涉及的模型包括书籍类目、书籍、书籍实例等，我们需要将它们建模为Python类。

每个模型类都应该是django.db.models.Model的子类型，这是Django提供的充血模型基类。我们创建以下三个类：

from django.db import models

from django.utils.encoding import python_2_unicode_compatible
@python_2_unicode_compatible  # 如果需要支持Python2
class Category(models.Model):
    # 每个模型会定义若干个Field子类型的变量，这些变量对应数据库的字段，二者默认名字一致
    # 字符串类型的字段
    # 第一个可选参数是人类友好的字段名称
    name = models.CharField('Category name', max_length = 128)
    # 对其它模型的引用，自引用必须用引号包围的类名或者'self'
    # Django支持o2m、m2o、m2m等常见数据库关系
    # blank=True表示表单验证时允许为空，null=True表示数据库字段可以为空
    parent_category = models.ForeignKey('self', blank=True, null=True )
    # 下面这个函数定义模型的字符串展示
    def __str__(self):
        return self.name

class Book(models.Model):
    name = models.CharField(max_length = 128)
    category = models.ForeignKey(Category)
    isbn = models.BigIntegerField()
    pub_date = models.DateTimeField()


class BookInstance(models.Model):
    no = models.IntegerField()
    book = models.ForeignKey(Book)
    # 枚举值和枚举字段
    STATUS_LEND_OUT = 1
    STATUS_RETURNED = 0
    status = models.SmallIntegerField(
        choices = ((STATUS_LEND_OUT, 'Lend out'), (STATUS_RETURNED, 'Returned')),
        # 字段可以提供默认值
        default = STATUS_RETURNED
    )

Django根据上面一小片模型代码，可以自动生成Schema（表结构）。首先，你需要安装bookmgr这个应用：

INSTALLED_APPS = [
    # 在开始处添加下面的内容，BookmgrConfig类以及自动在apps.py中定义
    'bookmgr.apps.BookmgrConfig'
]

然后执行下面的命令，生成一个“迁移”：

# 运行makemigrations命令，告知Django你对模型执行了修改（这里是添加了新模型）
# 并且你想把这个改变保存到一个迁移（migration）中
python manage.py makemigrations bookmgr
# 输出如下：
# Migrations for 'bookmgr':
#   0001_initial.py:
#     - Create model Book
#     - Create model BookInstance
#     - Create model Category
#     - Add field category to book

所谓迁移，只是磁盘上的文件，Django用它来记录模型（以及对应的数据库Schema）的变化。

你可以到应用的migrations目录查看新生成的迁移0001_initial.py，它同样是一段标准的Python代码。

使用命令

python manage.py sqlmigrate bookmgr 0001

BEGIN;
--
-- Create model Book
--
CREATE TABLE `bookmgr_book` (
    `id` integer AUTO_INCREMENT NOT NULL PRIMARY KEY, `name` varchar(128) NOT NULL,
    `isbn` bigint NOT NULL, `pub_date` datetime NOT NULL
);
--
-- Create model BookInstance
--
CREATE TABLE `bookmgr_bookinstance` (
    `id` integer AUTO_INCREMENT NOT NULL PRIMARY KEY, `no` integer NOT NULL, 
    `status` smallint NOT NULL, `book_id` integer NOT NULL)
;
--
-- Create model Category
--
CREATE TABLE `bookmgr_category` (
    `id` integer AUTO_INCREMENT NOT NULL PRIMARY KEY, 
    `name` varchar(128) NOT NULL, `parent_category_id` integer NOT NULL
);
--
-- Add field category to book
--
ALTER TABLE `bookmgr_book` ADD COLUMN `category_id` integer NOT NULL;
ALTER TABLE `bookmgr_book` ALTER COLUMN `category_id` DROP DEFAULT;
ALTER TABLE `bookmgr_bookinstance` ADD CONSTRAINT `bookmgr_bookinstance_book_id_73e96047_fk_bookmgr_book_id` 
    FOREIGN KEY (`book_id`) REFERENCES `bookmgr_book` (`id`);
ALTER TABLE `bookmgr_category` ADD CONSTRAINT `bookmgr_categ_parent_category_id_736b2e01_fk_bookmgr_category_id` 
    FOREIGN KEY (`parent_category_id`) REFERENCES `bookmgr_category` (`id`);
CREATE INDEX `bookmgr_book_b583a629` ON `bookmgr_book` (`category_id`);
ALTER TABLE `bookmgr_book` ADD CONSTRAINT `bookmgr_book_category_id_e3c50876_fk_bookmgr_category_id` 
    FOREIGN KEY (`category_id`) REFERENCES `bookmgr_category` (`id`);

COMMIT;

关于上述脚本，你需要了解：

1. 我们没有定义主键字段id，但是父类Model定义了，因此继承而来。你也可以覆盖默认定义
2. 主键的生成规则依据数据库的不同，自动设置
3. 表名称默认为：应用名称_模型类名，模型类名自动转为小写
4. 外键字段的名称为：引用字段名称_id

sqlmigrate命令只是打印SQL，并不会执行数据库迁移。后者通过下面的命令完成：

# 把所有尚未执行的迁移应用到数据库中
python manage.py migrate

注意，你可以在执行迁移之前执行check命令，确保工程中没有错误：

python manage.py check

Django的迁移功能很强大，它在django_migrations表中记录数据库的当前状态，因而可以跟踪迁移的进度。每次执行migrate命令时，Django总是把尚未执行的迁移应用到数据库中。迁移功能还能在升级数据库的同时避免数据丢失。

当你修改模型后，记住以下执行三个步骤：

1. 在models.py中修改模型类
2. 创建迁移文件：

   python manage.py makemigrations

    
3. 执行数据库迁移：

   python manage.py migrate

    

本节我们尝试通过交互式的Python控制台来试验Django的API，首先执行下面的命令启动控制台：

python manage.py shell

现在可以可以编写代码试验功能了：

# 导入模型类
from bookmgr.models import Category, Book, BookInstance
# 查询所有类目
Category.objects.all()
# 输出：[]  因为当前是空表
# 新建一个类目，你可以使用关键字参数传递各字段的值，这是Model类的行为
c = Category(name='social science')
# 必须调用save()，才能持久化到数据库中
c.save()
# 根据主键get，亦可入参id=1
c_sc = Category.objects.get(pk=1)
# 外键字段赋值，使用模型对象，而不是其ID
c = Category(name='economics',parent_category=c_sc)
c.save()
c = Category(name='politics',parent_category=c_sc)
c.save()
# 自动产生的双向关联，使用对方模型名称_set访问
c_sc.category_set.all()    # [<Category: Category object>, <Category: Category object>]
# 通过双向关联创建新对象
c_sc.category_set.create(name='law')
c_sc.category_set.create(name='pedagogy')

执行下面的命令，来创建超级用户

python manage.py createsuperuser

现在通过http://127.0.0.1:8000/admin登陆，默认情况下你可以管理用户和组。

要允许Admin应用管理模型对象，你需要进行注册：

from django.contrib import admin

from .models import Category, Book, BookInstance

admin.site.register(Category)
admin.site.register(Book)
admin.site.register(BookInstance)

重启服务后，你就可以在Web界面中添加、修改、删除模型了。 依据模型字段类型的不同，Admin应用会呈现不同的表单元素。

本节我们开发几个视图，用来展示Book模型。 

为了可维护性的考虑，不应当把HTML片段硬编码在视图函数中，我们可以使用Django提供的模板子系统来分离Python代码和HTML代码。依据Django的默认设置：

TEMPLATES = [
    {
        # 使用何种模板引擎
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        # 在应用的根目录下寻找templates目录  
        'APP_DIRS': True,
    },
]

你需要在应用（bookmgr）的根目录下创建一个

templates

任何网站都需要图片、脚本、样式表等静态资源。在Django框架中应用

django.contrib.staticfiles

你需要设置静态文件的URL前缀以及静态文件搜索目录：

# URL前缀
STATIC_URL = '/static/'
# 静态文件搜索目录，这里工程根目录下的static目录
STATICFILES_DIRS = (
    os.path.join(BASE_DIR, 'static'),
)

在Django模板中，你可以类似

/static/css/default.css

{% load static from staticfiles %}
<link rel="stylesheet" href="{% static "css/default.css" %}">

要能够正常访问default.css，你必须将其存放到

librarymgr/static/css/default.css

现在我们编写Book模块的首页，它展示欢迎信息和最新出版的10本图书。视图函数如下：

def book_index(request):
    # 上下文对象
    context = {
        'books': Book.objects.order_by('-pub_date')[:10]
    }

    # 加载模板
    template = loader.get_template('book/index.html')
    # 调用模板的render()方法，可以把上下文变量合并入模板，并生成字符串
    return HttpResponse(template.render(context, request))

    # 亦可使用下面的捷径：
    from django.shortcuts import render
    return render(request, 'book/index.html', context)

URL映射定义如下：

url(r'^book/index', views.book_index, name = 'book_index')

模板代码如下：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Book Index</title>
    {% load static from staticfiles %}
    <link rel="stylesheet" href="{% static 'css/default.css' %}">
</head>
<body>

{% if books %}
    <div><span>Recently 10 published books:</span></div>
    <table>
        <thead>
        <tr>
            <th>Book name</th>
            <th>Publish date</th>
            <th>Action</th>
        </tr>
        </thead>
        <tbody>
        {% for book in books %}
            <tr>
                <td><a href="{% url 'book_view' book.id %}">{{ book.name }}</a></td>
                <td>{{ book.pub_date }}</td>
                <td><a href="{% url 'book_edit' book.id %}"><img src="{% static 'images/edit.png' %}"/></a></td>
            </tr>
        {% endfor %}
        </tbody>
    </table>
{% else %}
    No book available.
{% endif %}
</body>
</html>

这里可以大概了解一下Django模板的语法风格：

1. 使用

   {% %}

    语法声明流程控制指令
2. 使用

   {{ }}

    语法声明占位符
3. 使用点号导航语法来访问对象属性

打开：http://127.0.0.1:8000/bookmgr/book/index，可以看到如下页面：

在上一节的模板中，我们有如下一段代码：

<td><a href="/bookmgr/book/{{ book.id }}">{{ book.name }}</a></td>

上面的href属性中，硬编码了工程名称和应用名称，这会导致部署时修改URL困难。你随时可以url标签避免硬编码：

<td><a href="{% url 'book_view' book.id %}">{{ book.name }}</a></td>

其中book_view就是URLConf中映射条目的name字段：

urlpatterns = [
    url(r'^book/(?P<book_id>[0-9]+)', views.book_view, name = 'book_view')
]

上一节我们开发的视图展示了最近10条书籍信息，其中书籍名称具有链接，很明星，此链接点击后应该显示单本书籍的详细信息。

注意详细信息视图的URL设计：http://127.0.0.1:8000/bookmgr/book/view/4，仍然是RESTful风格的URL，最后的数字是书籍的主键。 我们可以这样映射URL：

url(r'^book/view/(?P<book_id>[0-9]+)', views.book_view, name = 'book_view')

其中

(?P<group_name>...)

视图函数如下：

# book_id这个入参名称必须和分组的命名一致
def book_view(request, book_id):
    try:
        book = Book.objects.get(pk = book_id)
    except Book.DoesNotExist:
        # 触发异常，Django会自动将其转换为404响应
        raise Http404('No such book:%i' % book_id)

    # 上面的try-except块也可以使用快捷方式代替：
    book = get_object_or_404(Book, pk = book_id)

    return render(request, 'book/view.html', {'book': book})

模板代码如下：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>View Book</title>
    {% load static from staticfiles %}
    <link rel="stylesheet" href="{% static 'css/default.css' %}">
</head>
<body>
<div><span>Detail information of: {{ book.name }}</span></div>
<table>
    <tr>
        <th>Book name:</th>
        <td>{{ book.name }}</td>
    </tr>
    <tr>
        <th>Category:</th>
        <td>{{ book.category.name }}</td>
    </tr>
    <tr>
        <th>ISBN:</th>
        <td>{{ book.isbn }}</td>
    </tr>
    <tr>
        <th>Publish date:</th>
        <td>{{ book.pub_date }}</td>
    </tr>
</table>
</body>
</html>

打开：http://127.0.0.1:8000/bookmgr/book/view/1，可以看到如下页面：

本节我们了解一下Django中的表单处理。 

添加视图函数：

def book_edit(request, book_id, messages=[]):
    categories = Category.objects.all()
    try:
        book = Book.objects.get(pk=book_id)
    except Book.DoesNotExist:
        raise Http404('No such book:%i' % book_id)
    return render(request, 'book/edit.html', {'book': book, 'categories': categories, 'messages': messages})

URL映射如下：

url(r'^book/edit/(?P<book_id>[0-9]+)', views.book_edit, name='book_edit')

模板代码如下，注意其中的for和if控制结构：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Edit Book</title>
    {% load static from staticfiles %}
    <link rel="stylesheet" href="{% static "css/default.css" %}">
</head>
<body>
<div><span>Edit: {{ book.name }}</span></div>
{% if messages %}
    {% for msg in messages %}
        <div class="{% if msg.ok %}ok{% else %}error{% endif %}">{{ msg.message }}</div>
    {% endfor %}
{% endif %}
<form action="{% url 'book_commit' %}" method="post">
    <table>
        <tr>
            <th>Book name:</th>
            <td>
                {% csrf_token %} {% comment %} 必须，否则报错：CSRF verification failed. Request aborted. {% endcomment %}
                <input type="hidden" name="id" value="{{ book.id }}"/>
                <input type="text" name="name" value="{{ book.name }}"/></td>
        </tr>
        <tr>
            <th>Category:</th>
            <td>
                <select name="category">
                    {% for c in categories %}
                        <option value="{{ c.id }}"
                                {% if c.id == book.category.id %}selected="selected"{% endif %}>{{ c.name }}</option>
                    {% endfor %}
                </select>
            </td>
        </tr>
        <tr>
            <th>ISBN:</th>
            <td>
                <input type="number" name="isbn" value="{{ book.isbn }}"/>
            </td>
        </tr>
        <tr>
            <th>Publish date:</th>
            <td>
                <input type="date" name="pub_date" value="{{ book.pub_date.isoformat }}"/>
            </td>
        </tr>
    </table>
    <input class="submit-btn" type="submit" value="Submit"/>
</form>
</body>
</html>

点击首页的Action列的按钮 ，即可看到此编辑Book的页面：

点击上面的Submit按钮后，需要有服务器程序来处理表单数据，并返回处理结果。这些工作由book_commit视图函数完成： 

def book_commit(request):
    # 类似于字典的、存放所有POST请求参数的对象。类似的 request.GET 用于访问GET请求参数
    data = request.POST
    messages = []
    categories = Category.objects.all()
    try:
        book_id = int(data['id'])
        category_id = int(data['category'])
        book = Book.objects.get(pk=book_id)
        category = Category.objects.get(pk=category_id)
        book.name = data['name']
        book.category = category
        book.isbn = int(data['isbn'])
        from dateutil.parser import parse
        book.pub_date = parse(data['pub_date'])
        messages.append({'ok': True, 'message': 'Book updated: %i' % book_id})
    except Book.DoesNotExist:
        messages.append({'ok': False, 'message': 'No such book: %i' % book_id})
    except Category.DoesNotExist:
        messages.append({'ok': False, 'message': 'No such category: %i' % category_id})
    except BaseException as e:
        print e.message
        messages.append({'ok': False, 'message': 'Failed to update book, %s' % e.message})
    return book_edit(request, book_id, messages)

注意最后的return语句调用了其它视图函数，这类似于Java Servlet中的请求转发。另外一种处理方式是301重定向：

# reverse用于避免硬编码URL
return HttpResponseRedirect(reverse('book_edit', args=(book.id,)))

这样也可以把用户带回到编辑页面。区别有两点：

1. 重定向方式下，不能方便的传递模板上下文变量。例如messages变量
2. 重定向方式下，实际上就是让浏览器重新定位到book_edit这个URL，因此浏览器地址是/bookmgr/book/edit/3。前一种方式的浏览器地址是/bookmgr/book/commit

完成开发后，我们需要把工程部署到生产环境的服务器上。

最简单的配置：

# /librarymgr/为URL前缀。匹配的URL将由wsgi.py处理
WSGIScriptAlias /librarymgr/ /home/alex/Python/projects/pycharm/librarymgr/librarymgr/wsgi.py
# PYTHONPATH，指定为工程根目录
WSGIPythonPath /home/alex/Python/projects/pycharm/librarymgr

<Directory /home/alex/Python/projects/pycharm/librarymgr/librarymgr>
<Files wsgi.py>
    Require all granted
</Files>
</Directory>

Alias /static/ /home/alex/Python/projects/pycharm/librarymgr/static/
<Directory /home/alex/Python/projects/pycharm/librarymgr/static/>
    Require all granted
</Directory>

虚拟主机方式：

WSGIPythonPath /home/alex/Python/projects/pycharm/librarymgr
<VirtualHost 127.0.0.1:80>
    WSGIScriptAlias / /home/alex/Python/projects/pycharm/librarymgr/librarymgr/wsgi.py

    <Directory /home/alex/Python/projects/pycharm/librarymgr/librarymgr>
    <Files wsgi.py>
        Require all granted
    </Files>
    </Directory>

    Alias /static/ /home/alex/Python/projects/pycharm/librarymgr/static/
    <Directory /home/alex/Python/projects/pycharm/librarymgr/static/>
        Require all granted
    </Directory>
</VirtualHost>

The post Django学习笔记 appeared first on 绿色记忆.