CHN 10 配置文件 - an-tao/drogon Wiki

Original URL: https://github.com/an-tao/drogon/wiki/CHN-10-配置文件

你可以通过DrogonAppFramework实例的多个接口配置各种参数来控制Http服务端的某些行为。不过,使用配置文件是更好的方式,原因如下:

所有的配置接口都有对应的配置文件选项支持,基于上面这些额外的好处,建议应用开发者使用配置文件配置应用的各种参数。

配置文件的加载很简单,在DrogonAppFramework实例调用run接口之前,调用loadConfigFile接口即可,参数是配置文件的路径和文件名,比如:

int main()
{
    drogon::app().loadConfigFile("config.json");
    drogon::app().run();
}

这段程序,加载配置文件config.json,然后运行。具体的监听端口、日志输出、数据库配置等等行为都可以由配置文件配置,事实上,这段程序基本就可以是整个webapp应用的主函数的全部代码了。

文件说明

配置文件的例子在源码目录的顶层config.example.json,如果你使用drogon_ctl create project命令创建工程,那么,在工程目录里也可以找到内容一致的文件config.json。所以,你基本上不需要重写,而是对这个文件进行适当的修改,就可以完成对webapp的配置。

文件是json格式,支持注释,你可以用c++的注释符号/**///把不需要的配置项注释掉。

注释掉配置项后,框架会使用默认值初始化,对应项的默认值在配置文件中都有说明,下面分项详述。

SSL

ssl项是为了配置https服务的加密配置文件,如下:

  "ssl": {
    "cert": "../../trantor/trantor/tests/server.pem",
    "key": "../../trantor/trantor/tests/server.pem",
    "conf":[
      ["Options", "Compression"],
      ["min_protocol", "TLSv1.2"]
    ]
  }

其中,cert是证书文件路径,key是私钥文件路径,如果一个文件既包含证书也包含私钥,则两个路径可以配制成相同的。文件的编码格式为PEM;conf则是可选的SSL选项。他们会直接被传入SSL_CONF_cmd里,用来定制化SSL连接。这些选项必须是一个或是两个元素的字串数组。

listeners监听器

顾名思义,listeners项是为了配置webapp的监听器,它是一个JSON数组类型,每一个JSON对象都表示一个监听,具体的配置如下:

"listeners": [
    {
      "address": "0.0.0.0",
      "port": 80,
      "https": false
    },
    {
      "address": "0.0.0.0",
      "port": 443,
      "https": true,
      "cert": "",
      "key": ""
    }
  ]

其中:

db_clients

用于配置数据库客户端,它是一个JSON数组类型,每一个JSON对象都表示一个单独的数据库客户端,具体的配置如下:

  "db_clients":[
    {
      "name":"",
      "rdbms": "postgresql",
      "host": "127.0.0.1",
      "port": 5432,
      "dbname": "test",
      "user": "",
      "passwd": "",
      "is_fast": false,
      "connection_number":1,
      "filename": ""
    }
  ]

其中:

threads_num线程数

属于app选项的子项,整数,默认值是1,表示框架IO线程数,对网络并发有明确的影响,这个数字并不是越大越好,了解non-blocking I/O原理的应该知道,这个数值应该和你期望网络IO占用的CPU核心数一致。如果这个参数设为0,那么IO线程数将设置为全部CPU核心数。比如:

"threads_num": 16,

表示,网络IO占用16个线程,在高负荷情况下,最多可以跑满16个CPU核心(线程核心)。

session会话

会话相关的选项也是app的子项,控制是否采用session和session的超时时间。如:

"enable_session": true,
"session_timeout": 1200,

其中:

document_root根目录

app项的子项,字符串,表示Http根目录对应的文档路径,是静态文件下载的根路径,默认值是"./",表示程序运行的当前路径。比如:

"document_root": "./",

upload_path上传文件路径

app项的子项,字符串,表示上传文件的默认路径,默认值是"uploads",如果这个值不是/,./../开始的,并且这个值也不是...,则这个路径是前面document_root项的相对路径,否则就是一个绝对路径或者当前目录的相对路径。如:

"upload_path":"uploads",

file_types文件类型

app项的子项,字符串数组,默认值如下,表示框架支持的静态文件下载类型,如果请求的静态文件扩展名在这些类型之外的,框架将返回404错误。

"file_types": [
      "gif",
      "png",
      "jpg",
      "js",
      "css",
      "html",
      "ico",
      "swf",
      "xap",
      "apk",
      "cur",
      "xml"
    ],

mime註冊新mime類型

app项的子项、字符串字典。声明发送与静态文件時如何将文件扩展映射到新的 MIME 类型(即。默认情况下未识别的)。注意,此选项仅注册 MIME。如果扩展不在上述file_types中,则框架仍发送 404。

"mime" : {
  "text/markdown": "md",
  "text/gemini": ["gmi", "gemini"]
}

connections连接数控制

app项的子项,有两个选项,如下:

 "max_connections": 100000,
 "max_connections_per_ip": 0,

其中:

log日志选项

app项的子项,同时也是个JSON对象,控制日志输出的行为,如下:

 "log": {
      "log_path": "./",
      "logfile_base_name": "",
      "log_size_limit": 100000000,
      "log_level": "TRACE"
    },

其中:

注意: Drogon的文件日志采用了非阻塞输出结构,大概可以达到每秒百万行的日志输出能力,可以放心使用。

应用控制

也是app子项,有两个控制项,如下:

    "run_as_daemon": false,
    "relaunch_on_error": false,

其中:

use_sendfile发送文件

app子选项,布尔值,表示在发送文件时是否采用linux系统调用sendfile,默认值时true,使用sendfile可以提高发送效率,减少大文件的内存占用。如下:

"use_sendfile": true,

注意:即使该项为true,sendfile系统调用也不一定会采用,因为小文件使用sendfile并不一定划算,框架会根据自己的优化策略决定是否采用。

use_gzip压缩传输

app子选项,布尔值,默认值是true,表示Http响应的Body是否采用压缩传输。当该项为true时,下面的情况采用压缩传输:

配置例子如下:

"use_gzip": true,

files_cache_time文件缓存时间

app子选项,整数值,单位秒,表示静态文件在框架内部的缓存时间,即,在这段时间内对该文件的请求,框架会直接从内存返回响应而不会读取文件系统,这对提高静态文件性能有一定好处,当然,代价是更新实时性有n秒的延时。默认值是5秒,0表示永远缓存(只会读文件系统一次,慎用),负数表示没有缓存。如下:

 "static_files_cache_time": 5,

simple_controllers_map

app子选项,JSON对象数组,每一项表示一个从Http路径到HttpSimpleController的映射,这种配置只是一个可选途径,并不是必须配置在这里,请参阅HttpSimpleController。 具体的配置如下:

"simple_controllers_map": [
      {
        "path": "/path/name",
        "controller": "controllerClassName",
        "http_methods": ["get","post"],
        "filters": ["FilterClassName"]
      }
    ],

其中:

idle_connection_timeout空闲连接超时控制

app子选项,整数值,单位秒,默认值是60,当一个连接超过这个数值的时间没有任何读写的时候,该连接将会被强制断开。如下:

"idle_connection_timeout":60

dynamic_views动态视图加载

app的子选项,控制动态视图的使能和路径,有两个选项,如下:

"load_dynamic_views":true,
"dynamic_views_path":["./views"],

其中:

参见视图

server_header_field头字段

app的子选项,配置由框架发送的所有response的Server头字段,默认值是空串,当该选项为空时,框架会自动生成形如Server: drogon/version string的头字段。如下:

"server_header_field": ""

keepalive_requests长连接请求数

keepalive_requests 选项设置客户端在一个keepalive长连接上可以发送的最大请求数。当达到这个请求数时,长连接将被关闭。默认值0代表没有限制。如下:

"keepalive_requests": 0

Pipelining请求数

pipelining_requests选项用于设置长连接上已接收但未必处理的最大的请求数。当这个数字达到时,长连接将被关闭。默认值0代表没有限制。关于pipelining的详细描述,请参阅标准文档rfc2616-8.1.1.2。配置如下所示:

"pipelining_requests": 0

11 drogon_ctl命令