NGINX Unit

从源代码构建§

获取 Unit 的 源代码 后，对其进行配置和编译，以微调和运行自定义 Unit 构建。

安装必需软件§

在配置和编译 Unit 之前，请安装必需的构建工具和 必需语言 的库文件，以及您希望在 Unit 中使用的所有其他功能，例如 TLS 或正则表达式。

以下命令假设您正在使用所有受支持的语言和功能配置 Unit（X、Y 和 Z 分别表示主版本号、次版本号和修订号）；省略您不会使用的软件包。

# apt install build-essential
# apt install golang
# apt install curl && \
      curl -sL https://deb.nodesource.com/setup_VERSION.x | bash - && \
      apt install nodejs
# npm install -g node-gyp
# apt install php-dev libphp-embed
# apt install libperl-dev
# apt install pythonX-dev
# apt install ruby-dev ruby-rack
# apt install openjdk-X-jdk
# apt install libssl-dev
# apt install libpcre2-dev

# yum install gcc make
# yum install golang
# yum install curl && \
      curl -sL https://rpm.nodesource.com/setup_VERSION.x | bash - && \
      yum install nodejs
# npm install -g node-gyp
# yum install php-devel php-embedded
# yum install perl-devel perl-libs
# yum install pythonX-devel
# yum install ruby-devel rubygem-rack
# yum install java-X.Y.Z-openjdk-devel
# yum install openssl-devel
# yum install pcre2-devel

端口

# cd /usr/ports/lang/go/ && make install clean
# cd /usr/ports/www/node/ && make install clean
# cd /usr/ports/www/npm/ && make install clean && npm i -g node-gyp
# cd /usr/ports/lang/phpXY/ && make install clean
# cd /usr/ports/lang/perlX.Y/ && make install clean
# cd /usr/ports/lang/python/ && make install clean
# cd /usr/ports/lang/rubyXY/ && make install clean
# cd /usr/ports/java/openjdkX/ && make install clean
# cd /usr/ports/security/openssl/ && make install clean
# cd /usr/ports/devel/pcre2/ && make install clean

软件包

# pkg install go
# pkg install node && pkg install npm && npm i -g node-gyp
# pkg install phpXY
# pkg install perlX
# pkg install python
# pkg install rubyXY
# pkg install openjdkX
# pkg install openssl
# pkg install pcre2

# pkg install gcc
# pkg install golang
# pkg install php-XY
# pkg install ruby
# pkg install jdk-X
# pkg install openssl
# pkg install pcre

另外，在 Solaris 上构建和安装 Unit 时，请使用 gmake 代替 make。

Enabling njs

To build Unit with njs support, download the njs code to the same parent directory as the Unit code.

0.8.2 is the latest version of njs that Unit supports. Make sure you are in the correct branch before configuring the binaries.

$ git clone https://github.com/nginx/njs.git
$ cd njs
$ git checkout -b 0.8.2 0.8.2

Next, configure and build the njs binaries. Make sure to use the --no-zlib and --no-libxml2 options to avoid conflicts with Unit’s dependencies:

$ ./configure --no-zlib --no-libxml2 && make

Point to the resulting source and build directories when configuring the Unit code.

Enabling WebAssembly

To build Unit with support for the WebAssembly Component Model, you need rust version 1.76.0+, cargo and the developer package for clang as mentioned in the Required Software Section.

Next please refer to Configuring Modules - WebAssembly for further instructions.

Warning

The unit-wasm module is deprecated. We recommend using wasm-wasi-component instead, available in Unit 1.32.0 and later, which supports WebAssembly Components using standard WASI 0.2 interfaces.

To build Unit with the WebAssembly language module, you need the Wasmtime runtime. Download the C API files suitable for your OS and architecture to the same parent directory as the Unit code, for example:

$ cd ..
$ wget -O- https://github.com/bytecodealliance/wasmtime/releases/download/v12.0.0/wasmtime-v12.0.0-x86_64-linux-c-api.tar.xz \
      | tar Jxf -  # Unpacks to the current directory

Point to the resulting include and lib directories when configuring the Unit code.

To build WebAssembly apps that run on Unit, you need the wasi-sysroot SDK:

$ wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-20/wasi-sysroot-20.0.tar.gz | tar zxf -

When building the apps, add the following environment variable:

WASI_SYSROOT=/path/to/wasi-sysroot-dir/

配置源§

要运行系统兼容性检查并为 Unit 生成包含核心构建指令的 Makefile

$ ./configure COMPILE-TIME OPTIONS

在继续之前，通过配置所需的语言模块来完成最终的 Makefile。

控制编译、运行时权限或对某些功能的支持的常规选项和设置

--help

显示常见 ./configure 选项的摘要。

有关特定语言的详细信息，请运行 ./configure <language> --help 或参见下方。

--cc=pathname

自定义 C 编译器路径名。

默认值为 cc。

--cc-opt=options, --ld-opt=options

C 编译器和链接器的额外选项。

--group=name, --user=name

运行 Unit 的非特权进程的组名和用户名。

默认值分别是 --user 的主组和 nobody。

--debug

打开调试日志。

--no-ipv6

关闭 IPv6 支持。

--no-unix-sockets

关闭用于控制和路由的 UNIX 域套接字支持。

--openssl

打开 OpenSSL 支持。确保 OpenSSL（1.0.1+）头文件和库位于编译器的路径中；可以使用 --cc-opt 和 --ld-opt 选项或 CFLAGS 和 LDFLAGS 环境变量在运行 ./configure 时设置。

有关 Unit 中 TLS 配置的详细信息，请参见SSL/TLS 证书。

默认情况下，Unit 依赖于本地安装的 PCRE 库版本以支持路由中的正则表达式；如果两个主要版本都存在，则 Unit 选择 PCRE2。另外两个选项会改变此行为

--no-regex

关闭 regex 支持；任何尝试在 Unit 配置中使用 regex 都会导致错误。

--no-pcre2

忽略 PCRE2；而是使用较旧的 PCRE 8.x 库。

Unit 还支持在配置中使用 njs 脚本；要启用此功能，请使用相应选项

--njs

开启 njs 支持；需要 --openssl。

当启用 --njs 时，--cc-opt 和 --ld-opt 选项值应指向 njs 源代码的 src/ 和 build/ 子目录。例如，如果您在 Unit 仓库旁边克隆了 njs 仓库

$ ./configure --njs --openssl \
              --cc-opt="-I../njs/src/ -I../njs/build/"  \
              --ld-opt="-L../njs/build/"  \
              ...

下一个选项组自定义 Unit 的运行时 目录结构

--prefix=PREFIX

用于 路径选项 的目标目录前缀：--bindir、--sbindir、--includedir、--libdir、--modulesdir、--datarootdir、--mandir、--localstatedir、--libstatedir、--runstatedir、--logdir、--tmpdir、--control、--pid、--log。

默认值为 /usr/local。

--exec-prefix=EXEC_PREFIX

仅针对可执行目录的目标目录前缀。

默认值为 PREFIX 值。

--bindir=BINDIR, --sbindir=SBINDIR

客户端和服务器可执行文件的目录路径。

默认值为 EXEC_PREFIX/bin 和 EXEC_PREFIX/sbin。

--includedir=INCLUDEDIR, --libdir=LIBDIR

libunit 头文件和库的目录路径。

默认值为 PREFIX/include 和 EXEC_PREFIX/lib。

--modulesdir=MODULESDIR

Unit 语言 模块 的目录路径。

默认值为 LIBDIR/unit/modules。

--datarootdir=DATAROOTDIR, --mandir=MANDIR

unitd(8) 数据存储的目录路径及其安装 man 页的子目录。

默认值为 PREFIX/share 和 DATAROOTDIR/man。

--localstatedir=LOCALSTATEDIR

Unit 存储其运行时状态、PID 文件、控制套接字和日志的目录路径。

默认值为 PREFIX/var。

--libstatedir=LIBSTATEDIR

Unit 的运行时状态（配置、证书、其他资源）在运行之间存储的目录路径。如果您迁移安装，请复制整个目录。

警告

该目录很敏感，必须由 root 拥有，权限为 700。不要在外部更改其内容；使用配置 API 以确保完整性。

默认值为 LOCALSTATEDIR/run/unit。

--logdir=LOGDIR, --log=LOGFILE

Unit 的 日志 的目录路径和文件名。

默认值为 LOCALSTATEDIR/log/unit 和 LOGDIR/unit.log。

--runstatedir=RUNSTATEDIR

Unit 存储其 PID 文件和控制套接字的目录路径。

默认值为 LOCALSTATEDIR/run/unit。

--pid=pathname

Unit 的 main 进程 的 PID 文件的路径名。

默认值为 RUNSTATEDIR/unit.pid。

--control=SOCKET

控制 API 套接字地址，采用 IPv4、IPv6 或 UNIX 域格式

$ ./configure --control=127.0.0.1:8080
$ ./configure --control=[::1]:8080
$ ./configure --control=unix:/path/to/control.unit.sock  # Note the unix: prefix

警告

避免在公共网络中公开不受保护的控制套接字。使用 NGINX 或 SSH 等其他解决方案来确保安全性和身份验证。

默认值为 unix:RUNSTATEDIR/control.unit.sock，以 root 创建，权限为 600。

--tmpdir=TMPDIR

定义临时文件存储位置（用于转储大型请求主体）。

默认值为 /tmp。

目录结构§

默认情况下，make install 在以下路径名安装 Unit

目录

默认路径

bin 目录

/usr/local/bin/

sbin 目录

/usr/local/sbin/

lib 目录

/usr/local/lib/

include 目录

/usr/local/include/

tmp 目录

/tmp/

手册页

/usr/local/share/man/

语言模块

/usr/local/lib/unit/modules/

运行时状态

/usr/local/var/lib/unit/

PID 文件

/usr/local/var/run/unit/unit.pid

日志文件

/usr/local/var/log/unit/unit.log

控制 API 套接字

unix:/usr/local/var/run/unit/control.unit.sock

默认值旨在适用于大多数情况；要自定义此布局，请在配置期间设置--prefix及其相关选项，定义结果文件结构。

配置模块§

接下来，为要与 Unit 一起使用的每种语言配置一个模块。./configure <language> 命令设置各个语言模块，并将特定于模块的说明放入 Makefile 中。

注意

要在多种语言版本中运行应用程序，请为每个版本构建并安装一个模块。要打包自定义模块，请参阅模块操作方法。

运行 ./configure go 时，Unit 会设置 Go 程序包，该程序包允许你的应用程序在 Unit 上运行。要使用该程序包，请在 Go 环境中安装它。可用的配置选项

--go=pathname

特定的 Go 可执行文件路径名，也用于 make 目标。

默认值为 go。

--go-path=目录

用于安装 Go 软件包的自定义目录路径。

默认值为 $GOPATH。

注意

运行 ./configure go 不会更改 GOPATH 环境变量，因此配置时 --go-path 和编译时 $GOPATH 必须一致，以便 Go 找到结果软件包。

$ GOPATH=<Go package installation path> GO111MODULE=auto go build -o app app.go

运行 ./configure java 时，该脚本会配置一个模块以支持在 Unit 上运行 Java Web 应用程序。可用的命令选项

--home=目录

用于构建模块的 Java 实用程序和头文件的目录路径。

默认值为 java.home 设置。

--jars=目录

用于 Unit 的自定义 .jar 文件的目录路径。

默认值为 Java 模块路径。

--lib-path=目录

用于 libjvm.so 库的目录路径。

默认值基于 JDK 设置。

--local-repo=目录

用于本地 .jar 存储库的目录路径。

默认值为 $HOME/.m2/repository/。

--repo=目录

用于远程 Maven 存储库的 URL 路径。

默认值为 http://central.maven.org/maven2/。

--module=基本名称

结果模块的名称 (<基本名称>.unit.so)，也用于 make 目标。

默认值为 java。

要使用 OpenJDK 11.0.1 配置名为 java11.unit.so 的模块

$ ./configure java --module=java11  \
                   --home=/Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home

当您运行 ./configure nodejs 时，Unit 会设置 unit-http 模块，让您的应用程序 在 Unit 上运行。可用的配置选项

--local=directory

安装生成的模块的本地目录路径。

默认情况下，模块全局安装 (推荐)。

--node=pathname

特定的 Node.js 可执行路径名，也用于 make 目标。

默认值为 node。

--npm=pathname

特定的 npm 可执行路径名。

默认值为 npm。

--node-gyp=pathname

特定的 node-gyp 可执行路径名。

默认值为 node-gyp。

当您运行 ./configure perl 时，该脚本会配置一个模块以支持在 Unit 上将 Perl 脚本作为应用程序运行。可用的命令选项

--perl=pathname

特定的 Perl 可执行路径名。

默认值为 perl。

--module=基本名称

结果模块的名称 (<基本名称>.unit.so)，也用于 make 目标。

默认值为 --perl 可执行文件的名称。

为 Perl 5.20.2 配置名为 perl-5.20.unit.so 的模块

$ ./configure perl --module=perl-5.20  \
                   --perl=perl5.20.2

当您运行 ./configure php 时，该脚本会配置一个自定义 SAPI 模块，该模块与 libphp 库链接，以支持在 Unit 上运行 PHP 应用程序。可用的命令选项

--config=pathname

用于设置生成模块的 php-config 脚本的路径名。

默认值为 php-config。

--lib-path=目录

libphp 库文件（libphp*.so 或 libphp*.a）的目录路径，通常可以使用 --enable-embed PHP 构建获得

$ php-config --php-sapis

      ... embed ...

--lib-static

链接静态 libphp 库（libphp*.a），而不是动态库（libphp*.so）；需要 --lib-path。

--module=基本名称

结果模块的名称 (<基本名称>.unit.so)，也用于 make 目标。

默认值为 --config 的文件名，减去 -config 后缀；因此，--config=/path/php7-config 会生成 php7.unit.so。

为 PHP 7.0 配置名为 php70.unit.so 的模块

$ ./configure php --module=php70  \
                  --config=/usr/lib64/php7.0/bin/php-config  \
                  --lib-path=/usr/lib64/php7.0/lib64

运行 ./configure python 时，脚本会配置一个模块，以支持在 Unit 上将 Python 脚本作为应用程序运行。可用的命令选项

--config=pathname

用于设置生成模块的 python-config 脚本的路径名。

默认值为 python-config。

--lib-path=目录

与 Unit 一起使用的 Python 运行时库的自定义目录路径。

--module=基本名称

结果模块的名称 (<基本名称>.unit.so)，也用于 make 目标。

默认值为 --config 的文件名，减去 -config 后缀；因此，/path/python3-config 会变为 python3。

注意

由 python-config 设置的 Python 解释器必须使用 --enable-shared 选项进行编译。

为 Python 3.3 配置名为 py33.unit.so 的模块

$ ./configure python --module=py33  \
                     --config=python-config-3.3

运行 ./configure ruby 时，脚本会配置一个模块，以支持在 Unit 上将 Ruby 脚本作为应用程序运行。可用的命令选项

--module=基本名称

结果模块的名称 (<基本名称>.unit.so)，也用于 make 目标。

默认值为 --ruby 可执行文件的 filename。

--ruby=pathname

特定的 Ruby 可执行文件路径名。

默认值为 ruby。

为 Ruby 2.3 配置名为 ru23.unit.so 的模块

$ ./configure ruby --module=ru23  \
                   --ruby=ruby23

运行 ./configure wasm-wasi-component 时，脚本会配置一个模块，以支持在 Unit 上运行 WebAssembly 组件。

该模块不接受任何额外的配置参数。该模块的基本名称为 wasm-wasi-component。

警告

Unit 1.32.0 及更高版本支持 WebAssembly 组件模型和 WASI 0.2 API。我们建议使用新实现。

运行 ./configure wasm 时，脚本会配置一个模块，以支持在 Unit 上运行 WebAssembly 应用程序。可用的命令选项

--module=基本名称

结果模块的名称 (<基本名称>.unit.so)，也用于 make 目标。

--runtime=basename

要使用的 WebAssembly 运行时。

默认值为 wasmtime。

--include-path=path

运行时头文件的目录路径。

--lib-path=路径

运行时库文件的目录路径。

--rpath=<路径>

指定运行时库搜索路径的目录路径。

如果未指定值，则假定为--lib-path值。

要配置名为wasm.unit.so的模块

$ ./configure wasm --include-path=/path/to/wasmtime/include  \
                   --lib-path=/path/to/wasmtime/lib \
                   --rpath

构建和安装单元§

要构建和安装您之前已使用./configure配置的单元的可执行文件和语言模块

$ make
# make install

请注意，make install需要首先使用./configure设置单元的目录结构。

要在不安装的情况下从构建目录树运行单元

$ ./configure --prefix=./build
$ make
$ ./build/sbin/unitd

您还可以单独构建和安装语言模块；具体方法取决于语言模块是嵌入到单元中（Java、Perl、PHP、Python、Ruby）还是外部打包（Go、Node.js）。

注意

有关单元语言模块的更多详细信息，请参阅使用语言模块。

嵌入式语言模块§

要在配置后构建和安装 Java、PHP、Perl、Python 或 Ruby 的模块，请运行make <模块基名>和make <模块基名>-install，例如

$ make perl-5.20
# make perl-5.20-install

外部语言模块§

要在配置后全局构建和安装 Go 和 Node.js 的模块，请运行make <go>-install和make <node>-install，例如

# make go-install
# make node-install

注意

要本地安装 Node.js 模块，请运行make <node>-local-install

# make node-local-install

如果您之前未使用./configure nodejs指定--local目录，请在此处提供

# DESTDIR=/your/project/directory/ make node-local-install

如果指定了这两个选项，则DESTDIR为./configure nodejs设置的--local值添加前缀。

最后，请注意，对于 Node.js 模块，首选全局安装。

如果您使用--go或--node自定义了可执行文件路径名，请使用以下模式

$ ./configure nodejs --node=/usr/local/bin/node8.12
# make /usr/local/bin/node8.12-install

$ ./configure go --go=/usr/local/bin/go1.7
# make /usr/local/bin/go1.7-install

启动和关闭§

警告

我们建议从预编译包安装单元；在这种情况下，启动会自动配置。

即使您以其他方式安装单元，也请避免手动启动。相反，配置服务管理器（OpenRC、systemd等）或创建rc.d脚本，使用以下选项启动单元守护进程。

启动命令取决于您使用./configure设置的目录，但它们的默认值将unitd二进制文件放在众所周知的位置，因此

# unitd RUNTIME OPTIONS

运行 unitd -h 或 unitd --version 以列出 Unit 的编译时设置。通常，默认值不需要覆盖；但仍有以下运行时选项可用。有关其编译时对应项，请参见 此处。

--help, -h

显示命令行选项及其默认值的摘要。

--version

显示 Unit 的版本和构建时使用的 ./configure 设置。

--no-daemon

以非守护程序模式运行 Unit。

--control socket

IPv4、IPv6 或 UNIX 域格式的控制 API 套接字地址

# unitd --control 127.0.0.1:8080
# unitd --control [::1]:8080
# unitd --control unix:/path/to/control.unit.sock

--control-mode

设置 UNIX 域控制套接字的权限。默认值：0600

--control-user

设置 UNIX 域控制套接字的所有者。

--control-group

设置 UNIX 域控制套接字的组。

--group name, --user name

用于运行 Unit 的非特权 进程 的组名和用户名。

--log pathname

Unit 的 日志 的路径名。

--modules directory

Unit 的语言 模块（*.unit.so 文件）的目录路径。

--pid pathname

Unit 的 main 进程 的 PID 文件的路径名。

--state directory

Unit 的状态存储的目录路径。

--tmp directory

Unit 的临时文件存储的目录路径。

最后，要停止正在运行的 Unit

# pkill unitd

此命令向所有 Unit 的进程发出以正常方式终止的信号。

编辑此页面