Rocket 的目标是提供一个高弹性和高可用性的组态配置系统,开发者或是系统管理员可以很轻易地对每一个别的设置项目使用环境变量、设置档或是代码来进行设置。

以设置优先等级来说,写死在代码内的设置值的优先权是最高的。其次是环境变量,最后才是写在设置档中的设置值。这篇文章会先从优先权最低的设置方式开始说明。

不过在开始说明设置方式之前,先来了解一下 Rocket 框架到底有哪些项目可以设置吧!

Rocket 框架的组态配置

启动 Rocket 框架时,Rocket 会于标准输出(stdout)中列出启动该 Rocket 应用程序时所使用的组态配置。如下图所示:

启动 Rocket 时列出的组态配置

Rocket 框架的主要可设置项目如下表:

项目名称 类型 默认值(预设会用编译模式来区分 Profile:debug/release) 功用
address 字符串(IP 地址) 127.0.0.1 Rocket 框架启动时要监听的网络界面(IP 地址)。
port 整数(16 比特的无号整数) 8000 Rocket 框架启动时要监听的 TCP 连接端口。
workers 整数(无号整数) CPU 逻辑内核的数量 运行异步函数的线程数量。
max_blocking 整数(无号整数) 512 运行阻塞任务的最大线程数量。
ident 字符串、false Rocket 在 HTTP 回应中,于 Server 标头字段中要夹带的值。如果设为 false,则不回应 Server 标头。
ip_header 字符串、false X-Real-IP 在 HTTP 请求中,要把哪个标头字段中的值当作是客户端的真实 IP。如果设为 false,则不使用这个方式来取得客户端的真实 IP。
limits 表格(字段的值皆为表示字节大小的字符串) { bytes = "8KiB", data-form = "2MiB", file = "1MiB", form = "32KiB", json = "1MiB", msgpack = "1MiB", string = "8KiB" } 针对不同的请求类型,来限制 Rocket 框架在读取每个请求时,最大能读取前面的几个字节。
temp_dir 字符串(目录路径) 运行环境的暂存目录 暂存盘所存放的目录之路径。
keep_alive 整数(32 比特的无号整数,表示秒数) 5 HTTP 连接的 keep-alive 时间,0 为不打开;超过 0 表示要 keep-alive 的秒数。
tls 表格(certs、key 值分别为 SSL 证书和密钥的路径) 无 使 Rocket 框架能够提供 HTTPS 服务。如果不设置的话就只会使用 HTTP。Rocket 框架所提供的 HTTPS 功能不建议使用在正式环境中,应使用 Nginx 等反向代理服务器。
secret_key 字符串(256 比特或是 512 比特的 Base64 数据) 由 Rocket 框架于启动时随机产生。 用来作为基于 Cookie 的会话(Cookie-based Session)等需加密时的场合所使用的密钥。在使用 release 运行环境时,这个项目的值必须由系统管理员手动设置,确保每个应用程序实体都是使用一样的密钥。这个字段只会在激活 rocket 的 secrets 特色时才会有作用。
shutdown 表格
(ctrlc 为布尔值,设置是否能用 Ctrl + c 来触发 shutdown;
force 为布尔值,设置是否强制关闭异步运行环境;
signals 为 Set 集合,设置哪些中断信号可以触发 shutdown,Unix 环境才有效;
grace 和 mercy 为 32 比特无号整数,前者为强制关闭 HTTP 回应等服务器 I/O 前的等待时间秒数,后者为强制关闭连接 I/O 前的等待时间秒数)
{ ctrlc = true, force = true, signals = [SIGTERM], grace = 2, mercy = 3 } 设置如何「优雅的关机」(Graceful Shutdown)。
log_level 字符串(off、critical、normal、debug) normal/critical 设置 Log 的输出层级。愈靠近 debug 层级的话,输出的 Log 愈多。
cli_colors 布尔 true 是否在 Log 中使用颜色和 Emoji。

关于 secret_key 的产生,可以直接使用 OpenSSL 指令来完成。指令如下:

openssl rand -base64 32

以 openssl 产生 secret_key

设置 Rocket 框架

用设置档设置 Rocket 框架

Rocket 框架在启动的时候,预设会去读取工作目录中的 Rocket.toml 文件,如果这个文件不存在,就会不断地往上层目录中寻找 Rocket.toml 文件来用。

Rocket.toml 设置档的撰写方式很简单,如下:

[default]
address = "0.0.0.0"
port = 9958
keep_alive = 0
workers = 32
log_level = "debug"
secret_key = "nPu3M2/h4UOA8kVEpPqH+4KUzLaJKwhM78BAMBH+AEM="
limits = { form = "10MiB" }

套用设置档后的 Rocket 组态

default 区块会覆写掉字段的默认值。如果想要针对某个 Profile 来设置的话,可以直接把 Profile 的名称作为区块名称,写进 Rocket.toml 设置档中。

例如:

[default]
workers = 16
limits = { form = "32KiB" }

[debug]
address = "127.0.0.1"
port = 8000
keep_alive = 5
log_level = "normal"

[release]
address = "0.0.0.0"
port = 80
keep_alive = 10
log_level = "off"
secret_key = "nPu3M2/h4UOA8kVEpPqH+4KUzLaJKwhM78BAMBH+AEM="

如果要加入自定义的 Profile 也是可以,也是一样将 Profile 名称作为区块名称来撰写即可,如下:

[my_profile]
port = 12345
secret_key = "nPu3M2/h4UOA8kVEpPqH+4KUzLaJKwhM78BAMBH+AEM="

使用自定义的 Profile 时,未定义到的项目默认值会依编译模式使用 debug 或 release 的默认值,请见上表(但 secret_key 必须要手动设置)。至于要如何让 Rocket 套用为这个 Profile,会在下一个小节说明。

用环境变量设置 Rocket 框架

Rocket 的设置项目,都可以使用 ROCKET_项目名称(大写) 这样的环境变量命名方式来设置。

例如:

ROCKET_ADDRESS=0.0.0.0
ROCKET_PORT=9958
ROCKET_WORKERS=16
ROCKET_KEEP_ALIVE=0
ROCKET_LOG_LEVEL=debug
ROCKET_SECRET_KEY='nPu3M2/h4UOA8kVEpPqH+4KUzLaJKwhM78BAMBH+AEM='
ROCKET_LIMITS='{form = "10MiB"}'

以环境变量设置的 Rocket 组态

如果想要更改 Profile,则要用 ROCKET_PROFILE 这个环境变量。

例如以下指令,可以让 Rocket 应用程序以 my_profile 环境来运行:

ROCKET_PROFILE=my_profile cargo run

以 my_profile 运行的 Rocket

用代码来设置 Rocket 框架

如果我们想要用代码来设置 Rocket 框架的话,程序可以写成如以下这样:

#[macro_use]
extern crate rocket;

use rocket::{
    config::{Config, LogLevel},
    data::{Limits, ToByteUnit},
};

#[get("/")]
fn index() -> &'static str {
    "Hello, world!"
}

#[launch]
fn rocket() -> _ {
    let figment = Config::figment()
        .merge(("address", "0.0.0.0"))
        .merge(("port", 9958))
        .merge(("keep_alive", 0))
        .merge(("workers", 16))
        .merge((
            "log_level",
            if cfg!(debug_assertions) { LogLevel::Debug } else { LogLevel::Critical },
        ))
        .merge(("secret_key", "nPu3M2/h4UOA8kVEpPqH+4KUzLaJKwhM78BAMBH+AEM="))
        .merge(("limits", Limits::new().limit("form", 10.mebibytes())));

    rocket::custom(figment).mount("/", routes![index])
}

自订的项目名称

Rocket 框架的设置档并不是只能撰写上述提到的设置项目,如果我们有其它设置值想要透过 Rocket 框架的设置档来传入的话,也是同样可以用环境变量、设置档或是代码的方式将我们自订的项目名称以及设置值传给 Rocket 框架。

例如:

[default]
custom = 16384

[release]
custom = 4096
ROCKET_CUSTOM=16384
let figment = Config::figment()
    .merge(("custom", if cfg!(debug_assertions) { 16384 } else { 4096 }));

let rocket = rocket::custom(figment);

...

把设置值传给 Rocket 框架之后呢?要怎么在框架内取得?这个就先留到后面的章节再来介绍啦!现阶段我们可以用 Figment 结构实体提供的 extract_inner 方法来取得指定的设置字段,如以下程序:

#[macro_use]
extern crate rocket;

#[get("/")]
fn index() -> &'static str {
    "Hello, world!"
}

#[launch]
fn rocket() -> _ {
    let figment = rocket::Config::figment()
        .merge(("custom", if cfg!(debug_assertions) { 16384 } else { 4096 }));

    println!("custom = {:?}", figment.extract_inner::<u32>("custom"));

    rocket::custom(figment).mount("/", routes![index])
}

总结

在这个章节中,我们了解了 Rocket 框架的设置方式。直至目前为止,我们所学的 Rocket 知识已经足够完成 Web 应用程序的开发和部署了。不过,Rocket 框架的功能远远不只有这些。在下一个章节中,我们要来学习 Rocket 框架提供的错误捕获者机制。

下一章:错误捕获者(Error Catcher)。