Table of Contents

文件说明
支持配置文件格式
SSL
listeners监听器
db_clients数据库客户端
threads_num线程数
session会话
document_root根目录
upload_path上传文件路径
client_max_body_size请求体最大值
client_max_memory_body_size请求体内存分配最大值
file_types文件类型
mime 注册新的MIME类型
connections连接数控制
log日志选项
应用控制
use_sendfile发送文件
use_gzip压缩传输
static_files_cache_time文件缓存时间
simple_controllers_map简单控制器映射
idle_connection_timeout空闲连接超时控制
dynamic_views动态视图加载
server_header_field头字段
keepalive_requests长连接请求数
Pipelining请求数

11 drogon_ctl 命令

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

English | 简体中文

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

使用配置文件而不是源码，可以在运行期而不是编译期决定应用的行为，这无疑是更方便和灵活的方式；
可以保持main文件的简洁；

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

配置文件的加载很简单，在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++的注释符号/**/和//把不需要的配置项注释掉。

注释掉配置项后，框架会使用默认值初始化，对应项的默认值在配置文件中都有说明，

支持配置文件格式

json
yaml 需要安装yaml-cpp以提供yaml文件解析

下面以json格式分项详述。

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": ""
    }
  ]
```
其中：
- address: 字符串类型，表示监听的IP地址，如果没有该项，则采用默认值"0.0.0.0"
- port: 整数类型，表示监听的端口，必须是合法的端口号，没有默认值，必填项。
- https: 布尔类型，表示是否采用https，默认值是false，表示使用http。
- cert和key: 字符串类型，在https为true时有效，表示https的证书和私钥，默认值是空字符串，表示采用全局的ssl配置的证书和私钥文件；
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": ""
    }
  ]
```
其中：
- name：字符串，客户端名字，默认是"default"，name是应用开发者从框架获取数据库客户端的标记，如果有多项客户端，name字段必须不同，否则，框架不会正常工作；
- rdbms：字符串，表示数据库服务端类型，目前支持"postgresql"，"mysql"和“sqlite3”，大小写不敏感。
- host：字符串，数据库服务端地址，localhost是默认值；
- port：整数，数据库服务端的端口号；
- dbname：字符串，数据库名字；
- user：字符串，用户名；
- passwd：字符串，密码；
- is_fast：bool，默认false，表明该客户端是否是FastDbClient；
- connection_number：到数据库服务端的连接数，至少是1，默认值也是1，影响数据读写的并发量；如果is_fast为真，该数值表示每个事件循环的连接数，否则表示总的连接数；
- filename: sqlite3 数据库的文件名；
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,
```
其中：
- enable_session：布尔值，表示是否采用会话，默认值是false，如果客户端不支持cookie，请设为false，因为框架会为每个不带会话cookie 的请求创建新的会话，如果客户端不支持cookie 而又有大量请求，则服务端会生成大量的无用 session对象，这是完全没必要的资源和性能损失；
- session_timeout：整数值，表示会话的超时时间，单位是秒，默认值是0，只有enable_session为true时才发挥作用。0表示永久有效。
document_root根目录

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

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

app项的子项，字符串，用来限制请求体的大小。你可以使用后缀 k, m, g, 来指定千字节，兆字节或者吉字节 (byte * 1024)，在 64 位的系统上，你也可以使用 t 来表示一个太字节。后缀可以是小写或者大写。
```
"client_max_body_size": "10M",
```
client_max_memory_body_size请求体内存分配最大值

app项的子项，字符串，用来限制对请求体进行缓存分配内存的大小。你可以使用后缀 k, m, g, 来指定千字节，兆字节或者吉字节 (byte * 1024)，在 64 位的系统上，你也可以使用 t 来表示一个太字节。后缀可以是小写或者大写。
```
"client_max_memory_body_size": "50K"
```

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,
```
其中：
- max_connections：整数，默认值是 100000，表示同时并发的最大连接数；当服务端维持的连接达到这个数量时，新的TCP连接请求将被直接拒绝。
- max_connections_per_ip：整数，默认值是0，表示单个IP的最大连接数，0表示没有限制。
log日志选项

app项的子项，同时也是个JSON对象，控制日志输出的行为，如下：
```
"log": {
      "log_path": "./",
      "logfile_base_name": "",
      "log_size_limit": 100000000,
      "log_level": "TRACE"
    },
```
其中：
- log_path：字符串，默认值是空串，表示文件存放的路径，如果是空串，则所有日志输出到标准输出；
- logfile_base_name：字符串，表示日志文件的basename，默认值是空串，这时basename将为drogon；
- log_size_limit：整数，单位是字节，默认值是100000000(100M)，当日志文件的大小达到这个数值时，日志文件会切换。
- log_level：字符串，默认值是"DEBUG"，表示日志输出的最低级别，可选值从低到高为："TRACE","DEBUG","INFO","WARN"，其中的TRACE级别只有在DEBUG编译的情况下才有效。
注意： Drogon的文件日志采用了非阻塞输出结构，大概可以达到每秒百万行的日志输出能力，可以放心使用。
应用控制

也是app子项，有两个控制项，如下：
```
    "run_as_daemon": false,
    "relaunch_on_error": false,
```
其中：
- run_as_daemon：布尔值，默认值是false，当为true时，应用程序将以daemon的形式变成1号进程的子进程运行于系统后台。
- relaunch_on_error：布尔值，默认值时false，当为true时，应用程序将fork一次，子进程执行真正的工作，父进程什么都不干，只负责在子进程崩溃或因其它原因退出时重启子进程，这是一种简单的服务保护机制。
use_sendfile发送文件

app子选项，布尔值，表示在发送文件时是否采用linux系统调用sendfile，默认值时true，使用sendfile 可以提高发送效率，减少大文件的内存占用。如下：
```
"use_sendfile": true,
```
注意：即使该项为true，sendfile系统调用也不一定会采用，因为小文件使用sendfile并不一定划算，框架会根据自己的优化策略决定是否采用。
use_gzip压缩传输

app子选项，布尔值，默认值是true，表示 Http响应的Body是否采用压缩传输。当该项为true时，下面的情况采用压缩传输：
- 客户端支持gzip压缩；
- body是文本类型；
- body的长度大于一定值；
配置例子如下：
```
"use_gzip": true,
```
static_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"]
      }
    ],
```
其中：
- path：字符串，Http路径；
- controller：字符串，HttpSimpleController的名字；
- http_methods：字符串数组，支持的Http方法，这个列表之外的会被过滤掉，返回405错误；
- filters：字符串数组，路径上的filter列表，参见中间件和过滤器；
idle_connection_timeout空闲连接超时控制

app子选项，整数值，单位秒，默认值是60，当一个连接超过这个数值的时间没有任何读写的时候，该连接将会被强制断开。如下：
```
"idle_connection_timeout":60
```
dynamic_views动态视图加载

app的子选项，控制动态视图的使能和路径，有两个选项，如下：
```
"load_dynamic_views":true,
"dynamic_views_path":["./views"],
```
其中：
- dynamic_views_path：布尔值，默认值是false，当为true时，框架会在视图路径中搜索视图文件，并动态编译成so文件，然后加载进应用，当任何视图文件发生变化时，也会引起自动编译和重新加载；
- dynamic_views_path：字符串数组，每一项表示动态视图的搜索路径，如果路径值不是/,./或../开始的，并且这个值也不是.或..，则这个路径是前面document_root项的相对路径，否则就是一个绝对路径或者当前目录的相对路径。
参见视图。
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
```

文件说明

支持配置文件格式

SSL

listeners监听器

db_clients数据库客户端

threads_num线程数

session会话

document_root根目录

upload_path上传文件路径

client_max_body_size请求体最大值

client_max_memory_body_size请求体内存分配最大值

file_types文件类型

mime 注册新的MIME类型

connections连接数控制

log日志选项

应用控制

use_sendfile发送文件

use_gzip压缩传输

static_files_cache_time文件缓存时间

simple_controllers_map简单控制器映射

idle_connection_timeout空闲连接超时控制

dynamic_views动态视图加载

server_header_field头字段

keepalive_requests长连接请求数

Pipelining请求数

11 drogon_ctl 命令

Document

Tutorial

中文文档

教程