NGINX Unit

安装§

系统要求§

NGINX Unit 在以下操作系统进行了编译和运行测试:

  • Linux 2.6 及以上版本

  • FreeBSD 9 及以上版本

  • MacOS X
  • Solaris 11

CPU架构:

  • i386
  • amd64
  • powerpc
  • arm

支持以下编程语言和版本:

  • Go 1.6 及以上版本

  • Java 8 or later
  • Node.js 8.11 or later
  • PHP 5, 7
  • Perl 5.12 及以上版本

  • Python 2.6, 2.7, 3
  • Ruby 2.0 及以上版本

安装在同个操作系统的,同种编程语言的不同版本可以同时运行。

Docker 镜像§

通过我们的 Docker 镜像仓库来安装运行 Unit:

# docker pull nginx/unit
# docker run -d nginx/unit

缺省将使用 :latest 镜像标签,对应最新 Unit 版本的 -full 全部配置。另外支持的标签如下:

标签

描述

<version>-full

所有支持的语言模块配置

<version>-minimal

不含语言模块配置

<version>-<language>

仅支持指定语言模块配置,例如,1.3-ruby2.31.2-python2.7

更多详细信息,请查阅 镜像仓库网页

预编译的安装包§

Unit 预编译的二进制安装包适用于以下操作系统:

  • CentOS 6, 7
  • RHEL 6, 7
  • Amazon Linux
  • Ubuntu 16.04, 18.04, 18.10
  • Debian 8, 9

CentOS 安装包§

  1. 创建文件 /etc/yum.repos.d/unit.repo 并在里面添加如下内容:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/centos/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. 安装 Unit 基础包

    # yum install unit
    
  3. 安装一些附加模块,例如:

    # yum install unit-php unit-python unit-go unit-perl unit-devel \
                  unit-jsc-common unit-jsc8
    

注解

控制 socket 文件路径为:/var/run/control.unit.sock

RHEL 安装包§

  1. 创建文件 /etc/yum.repos.d/unit.repo 并在里面添加如下内容:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/rhel/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. 安装 Unit 基础包

    # yum install unit
    
  3. 安装一些附加模块,例如:

    使用 RHEL 6:

    # yum install unit-php unit-python unit-perl unit-devel \
                  unit-jsc-common unit-jsc8 unit-jsc11
    

    For RHEL 7:

    # yum install unit-php unit-python unit-go unit-perl unit-devel \
                  unit-jsc-common unit-jsc8 unit-jsc11
    

注解

控制 socket 文件路径为:/var/run/control.unit.sock

Amazon Linux 安装包§

  1. 创建文件 /etc/yum.repos.d/unit.repo 并在里面添加如下内容:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/amzn/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    

    使用 Amazon Linux 2 LTS:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/amzn2/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. 安装 Unit 基础包

    # yum install unit
    
  3. 安装一些附加模块,例如:

    # yum install unit-php unit-python27 unit-python34 unit-python35 \
          unit-python36 unit-go unit-perl unit-devel unit-jsc-common \
          unit-jsc8 unit-jsc11
    

    使用 Amazon Linux 2 LTS:

    # yum install unit-php unit-python unit-go unit-perl unit-devel \
                  unit-jsc-common unit-jsc8 unit-jsc11
    

注解

控制 socket 文件路径为:/var/run/control.unit.sock

Ubuntu 安装包§

  1. 下载 NGINX, Inc. 仓库和安装包的 密钥

  2. 将密钥添加到 apt 的钥匙串中:

    # apt-key add nginx_signing.key
    

    程序可以验证 NGINX 仓库的签名,这样可以消除掉安装 Unit 时提示丢失 PGP 密钥的警告。

  3. 创建文件 /etc/apt/sources.list.d/unit.list 并在里面添加如下内容:

    使用 Ubuntu 16.04:

    deb https://packages.nginx.org/unit/ubuntu/ xenial unit
    deb-src https://packages.nginx.org/unit/ubuntu/ xenial unit
    

    使用 Ubuntu 18.04:

    deb https://packages.nginx.org/unit/ubuntu/ bionic unit
    deb-src https://packages.nginx.org/unit/ubuntu/ bionic unit
    

    For Ubuntu 18.10:

    deb https://packages.nginx.org/unit/ubuntu/ cosmic unit
    deb-src https://packages.nginx.org/unit/ubuntu/ cosmic unit
    
  4. 安装 Unit 基础包

    # apt-get update
    # apt-get install unit
    
  5. 安装一些附加模块,例如:

    使用 Ubuntu 16.04:

    # apt-get install unit-php unit-python2.7 unit-python3.5 unit-go \
          unit-perl unit-ruby unit-dev unit-jsc-common unit-jsc8
    

    使用 Ubuntu 18.04:

    # apt-get install unit-php unit-python2.7 unit-python3.6 unit-go1.9 \
          unit-go1.10 unit-perl unit-ruby unit-dev unit-jsc-common unit-jsc8 \
          unit-jsc10
    

    For Ubuntu 18.10:

    # apt-get install unit-php unit-python2.7 unit-python3.6 unit-python3.7 \
          unit-go1.9 unit-go1.10 unit-perl unit-ruby unit-dev \
          unit-jsc-common unit-jsc8 unit-jsc11
    

注解

控制 socket 文件路径为:/var/run/control.unit.sock

Debian 安装包§

  1. 下载 NGINX, Inc. 仓库和安装包的 密钥

  2. 将密钥添加到 apt 的钥匙串中:

    # apt-key add nginx_signing.key
    

    程序可以验证 NGINX 仓库的签名,这样可以消除掉安装 Unit 时提示丢失 PGP 密钥的警告。

  3. 创建文件 /etc/apt/sources.list.d/unit.list 并在里面添加如下内容:

    使用 Debian 8:

    deb https://packages.nginx.org/unit/debian/ jessie unit
    deb-src https://packages.nginx.org/unit/debian/ jessie unit
    

    使用 Debian 9:

    deb https://packages.nginx.org/unit/debian/ stretch unit
    deb-src https://packages.nginx.org/unit/debian/ stretch unit
    
  4. 安装 Unit 基础包

    # apt-get update
    # apt-get install unit
    
  5. 安装一些附加模块,例如:

    使用 Debian 8:

    # apt-get install unit-php unit-python2.7 unit-python3.4 unit-perl \
          unit-ruby unit-dev
    

    使用 Debian 9:

    # apt-get install unit-php unit-python2.7 unit-python3.5 unit-go1.7 \
          unit-go1.8 unit-perl unit-ruby unit-dev
    

注解

控制 socket 文件路径为:/var/run/control.unit.sock

启动和关闭§

安装预编译安装包后,开启开机自启动 Unit:

# systemctl enable unit.service

立即手动启动或重启 Unit:

# systemctl restart unit.service

立即手动关闭 Unit:

# systemctl stop unit.service

停用 Unit 开机自启动:

# systemctl disable unit.service

社区仓库§

警告

以下列出的分发版本由各自社区进行维护,NGINX 没有控制权并不对这些资源负责,使用前请谨慎考虑。

Alpine Linux§

使用 Alpine Linux 安装包 安装 Unit 核心执行文件:

# apk update
# apk upgrade
# apk add unit

安装服务管理器和指定的语言模块:

# apk add unit-openrc unit-perl unit-php7 unit-python3 unit-ruby

注解

控制 socket 文件路径为:/run/control.unit.sock

Arch Linux§

使用 Arch 用户仓库 (AUR) 安装 Unit:

$ sudo pacman -S git
$ git clone https://aur.archlinux.org/nginx-unit.git
$ cd nginx-unit

警告

请验证 PKGBUILD 和附带文件是否是恶意或不可信的。AUR 安装包安全是用户生成提供的,无需预先审核,因此使用他们需你自行承担风险。

$ makepkg -si

注解

控制 socket 文件路径为:/run/nginx-unit.control.sock

FreeBSD§

使用 FreeBSD 安装包 安装 Unit:

# pkg install -y unit

注解

控制 socket 文件路径为:/var/run/unit/control.unit.sock

使用 FreeBSD ports 安装 Unit前,需要先更新。

For portsnap:

# portsnap fetch update

For svn:

# svn update /usr/ports

接下来,进入 port 路径,进行编译构建和安装:

# cd /usr/ports/www/unit
# make
# make install

警告: 这里的 make 命令是 port 配置的。如要使用 make 命令来编译官方仓库源代码,请参阅 Building and Installing Unit.

注解

控制 socket 文件路径为:/var/run/unit/control.unit.sock

Gentoo§

使用 Portage 安装 Unit 前需要更新仓库,然后再安装 Unit 安装包:

# emerge --sync
# emerge www-servers/nginx-unit

注解

控制 socket 文件路径为:/run/nginx-unit.sock

Remi’s RPM 仓库§

Remi’s RPM 仓库 里有着最新版本 PHP 安装包,支持 CentOS、Fedora 以及 RHEL,也还有 Unit 安装包以及 PHP 模块。

使用 Remi’s 版本的 Unit 安装包前,需要先配置 Remi’s RPM 仓库 。Remi’s PHP 语言模块也可以跟 官方仓库的预编译安装包 一起工作。

接下来,安装 Unit 和你想用的 PHP 模块:

# yum install --enablerepo=remi unit php54-unit-php php55-unit-php php56-unit-php \
      php70-unit-php php71-unit-php php72-unit-php php73-unit-php

注解

控制 socket 文件路径为:/var/run/unit/control.sock

Node.js 安装包§

Unit 的 Node.js 安装包被称为 unit-http。使用了 Unit 的 libunit 库; 你需要在你的 Node.js 应用中引入 require 对应包才能运行 Unit。你可以通过 NPM 仓库 安装 Unit。

安装 libunit 可以从 unit-dev/unit-devel 预编译安装包 安装,或是通过 源代码编译 安装。然后全局安装 unit-http

# npm install -g --unsafe-perm unit-http

警告

出于性能优化的原因, unit-http 包是平台和架构相关的。不能在不同系统间进行 node-modules 目录下的文件移动(例如应用迁移时的移动),全局安装避免了这种情况的产生,只需要 重新链接迁移的应用程序

这应该能够满足绝大部分需求。Use the package in your Unit-hosted application as you would use the built-in http package in common Node.js web applications.

如果要更新 Unit 版本,请确保更新 NPM 安装包:

# npm update -g --unsafe-perm unit-http

注解

你也可以通过 手动安装 来编译和安装 unit-http

源代码§

这一部分将说明如何用源代码进行编译安装。

获取源代码§

有三种方式来获取 Unit 的源代码,分别是:NGINX, Inc. 的 Mercurial 仓库、GitHub 以及压缩包。

源代码都在 unit 子目录中。

Mercurial 仓库§

  1. 如果没有 Mercurial 软件,需要先下载安装。例如,在 Ubuntu 系统可以使用如下命令:

    # apt-get install mercurial
    
  2. 下载 Unit 源代码:

    # hg clone https://hg.nginx.org/unit
    

GitHub 仓库§

  1. 如果没有 Git 软件,需要先下载安装,参见 GitHub 文档

  2. 下载 Unit 源代码:

    # git clone https://github.com/nginx/unit
    

压缩包§

可以在如下网址下载 Unit 源代码压缩包: https://unit.nginx.org/download/

安装依赖软件§

Before configuring and compiling Unit, install the required build tools plus the library files for available languages (Go, Node.js, PHP, Perl, Python, and Ruby) and the other features you want Unit to support.

下面的命令假设你配置 Unit 支持所有语言模块和功能,如果不需要,可以跳过相关包。

Debian, Ubuntu§

# apt-get install build-essential
# apt-get install golang
# curl -sL https://deb.nodesource.com/setup_<Node.js version>.x | bash -; apt-get install nodejs
# apt-get install php-dev libphp-embed
# apt-get install libperl-dev
# apt-get install python-dev
# apt-get install ruby-dev
# apt-get install openjdk-8-jdk
# apt-get install libssl-dev

Amazon Linux, CentOS, RHEL§

# yum install gcc make
# yum install golang
# curl -sL https://rpm.nodesource.com/setup_<Node.js version>.x | bash -; yum install nodejs
# yum install php-devel php-embedded
# yum install perl-devel perl-libs
# yum install python-devel
# yum install ruby-devel
# yum install java-1.8.0-openjdk-devel
# yum install openssl-devel

配置源代码§

首先,进行系统检查并创建 Makefile 以备语言模块配置使用:

# ./configure <command-line options>

通用 ./configure 选项:

--help

显示 ./configure 通常选项简介。

查看指定语言的更多信息,运行命令 ./configure <language> --help 查看,或者参阅 below

以下选项与编译过程相关:

--cc=pathname

指定 C 编译器路径名。

缺省值为 cc

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

附加 C 编译器和连接器选项。

缺省值为空字符串。

以下选项对应控制 Unit 运行环境特权:

--group=name, --user=name
 

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

缺失值分别是 <user> 的主要组名和 nobody

以下标识符用来启用或禁用一些功能:

--debug

启用 调试日志

--no-ipv6

禁用 IPv6 支持。

--no-unix-sockets
 

禁用 Unix 域套接字支持。

--openssl

启用 OpenSSL 支持。确保 OpenSSL (1.0.1 或更高版本) 的头文件和库在编译器搜索路径中。

To customize the path, provide the --cc-opt and --ld-opt options; alternatively, set CFLAGS and LDFLAGS environment variables before running ./configure.

For details, see SSL/TLS and Certificates.

The last option group customizes Unit’s runtime directory structure:

--prefix=prefix
 

Destination directory prefix for so-called path options: --bindir, --sbindir, --libdir, --incdir, --modules, --state, --pid, --log, and --control. Their relative settings are prefix-based.

The default value is an empty string.

--bindir=directory, --sbindir=directory
 

Directory paths for end-user and sysadmin executables.

The default values are bin and sbin, respectively.

--control=socket
 

Address of the control API socket; Unix sockets (starting with unix:), IPv4, and IPv6 sockets are valid here.

The default value is unix:control.unit.sock, created as root with 600 permissions.

警告

For security reasons, avoid opening sockets on public interfaces in production.

--incdir=directory, --libdir=directory
 

Directory paths for libunit header files and libraries.

The default values are include and lib, respectively.

--log=pathname

Pathname for Unit’s log.

The default value is unit.log.

--modules=directory
 

Directory path for Unit’s language modules.

The default value is modules.

--pid=pathname

Pathname for the PID file of Unit’s daemon process.

The default value is unit.pid.

--state=directory
 

Directory path for Unit’s state storage.

警告

Unit state includes its runtime configuration, certificates, and other private records. It can be copied as is when you migrate your Unit installation; however, mind that it contains sensitive data and must be available only to root with 700 permissions.

The default value is state.

Directory Structure§

To customize Unit installation and runtime directories, you can both:

  • Set the --prefix and path options during configuration to set up the runtime file structure: Unit will use these settings to locate its modules, state, and other files.
  • Set the DESTDIR variable during installation. Unit file structure will be placed at the specified directory, which can be either the final installation target or an intermediate staging location.

Coordinate these two options as necessary to customize the directory structure. One common scenario is installation based on absolute paths.

  1. Set absolute runtime paths with --prefix and path options:

    # ./configure --state=/var/lib/unit --log=/var/log/unit.log \
                  --control=unix:/run/control.unit.sock --prefix=/usr/local/
    

    This configuration will access its state, log, and control socket at custom locations; other files will be accessed by default prefix-based paths: /usr/local/sbin/, /usr/local/modules/, and so on.

  2. If you’re building Unit on the system where you intend to run it, omit DESTDIR during installation; the files will be placed at the specified paths. If you’re building Unit for further packaging or containerization, specify DESTDIR to place the files in a staging location, preserving their relative structure.

An alternative scenario is a build that you can move around the filesystem.

  1. Set relative runtime paths with --prefix and path options:

    # ./configure --state=config --log=log/unit.log \
                  --control=unix:control/control.unit.sock --prefix=movable
    

    This configuration will access its files by prefix-based paths (both default and custom): <working directory>/movable/sbin/, <working directory>/movable/config/, and so on.

  2. Specify DESTDIR during installation to place the build where needed. You can move it around your system or across compatible systems; however, make sure to relocate the entire file structure and start Unit binaries from the base directory so that the relative paths remain valid:

    # cd <DESTDIR>
    # movable/sbin/unitd <command-line options>
    

You can also combine these two approaches as you see fit; nevertheless, always take care to understand how your settings actually work together.

Configuring Modules§

Next, configure a module for each language you want to use with Unit. The ./configure <language> commands set up individual language modules and place module-specific instructions in the Makefile.

注解

Unit can run applications in several versions of a supported language side by side: you need to configure, build, and install a separate module for each version.

Configuring Go§

When you run ./configure go, Unit sets up the Go package that your applications will use to run in Unit. To use the package, install it in your Go environment. Available configuration options:

--go=pathname

Specific Go executable pathname. Also used for build and install commands.

The default value is go.

--go-path=directory
 

Custom directory path for Go package installation.

The default value is $GOPATH.

注解

The ./configure script doesn’t alter the GOPATH environment variable. Make sure these two paths, the configuration-time --go-path and compile-time GOPATH, are coherent so that Go can import and use the Unit package.

Configuring Java§

When you run ./configure java, the script configures a module to support running Java Web Applications in Unit. Available command options:

--home=directory
 

Directory path for Java utilities and header files (required to build the module).

The default value is the java.home setting.

--jars=directory
 

Directory path for Unit’s custom .jar files.

The default value is the Java module path.

--lib-path=directory
 

Directory path for the libjvm.so library.

The default value is derived from JDK settings.

--local-repo=directory
 

Directory path for local .jar repository.

The default value is $HOME/.m2/repository/.

--repo=directory
 

URL path for remote Maven repository.

The default value is http://central.maven.org/maven2/.

--module=filename
 

Target name for the Java module that Unit will build (<module>.unit.so). Also used for build and install commands.

The default value is java.

To configure a module called java11.unit.so with OpenJDK 11.0.1:

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

Configuring Node.js§

When you run ./configure nodejs, Unit sets up the unit-http package that your applications will use to run in Unit. Available configuration options:

--local=directory
 

Local directory path for Node.js package installation.

By default, the package is installed globally (recommended).

--node=pathname
 

Specific Node.js executable pathname. Also used for build and install commands.

The default value is node.

--npm=pathname

Specific NPM executable pathname.

The default value is npm.

--node-gyp=pathname
 

Specific node-gyp executable pathname.

The default value is node-gyp.

Configuring Perl§

When you run ./configure perl, the script configures a module to support running Perl scripts as applications in Unit. Available command options:

--include=directory
 

Directory path to Perl headers (required to build the module).

The default is Perl’s $Config{archlib}/CORE directory.

--perl=pathname
 

Specific Perl executable pathname.

The default value is perl.

--module=filename
 

Target name for the Perl module that Unit will build (<module>.unit.so). Also used for build and install commands.

The default value is the filename of the <perl> executable.

To configure a module called perl-5.20.unit.so for Perl 5.20.2:

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

Configuring PHP§

When you run ./configure php, the script configures a module to support running PHP applications in Unit via PHP’s embed SAPI. Available command options:

--config=pathname
 

Pathname of the php-config script invoked to configure the PHP module.

The default value is php-config.

--lib-path=directory
 Directory path of PHP’s embed SAPI library file (libphp<version>.so or libphp<version>.a).
--lib-static Enables linking with the static embed SAPI library (libphp<version>.a). If this option is specified, --lib-path is also required.
--module=filename
 

Target name for the PHP module that Unit will build (<module>.unit.so). Also used for build and install commands.

The default value is <config>‘s filename without the -config suffix (thus, /usr/bin/php7-config yields php7).

To configure a module called php70.unit.so for PHP 7.0:

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

Configuring Python§

When you run ./configure python, the script configures a module to support running Python scripts as applications in Unit. Available command options:

--config=pathname
 

Pathname of the python-config script invoked to configure the Python module.

The default value is python-config.

--lib-path=directory
 Custom directory path of the Python runtime library to use with Unit.
--module=filename
 

Target name for the Python module that Unit will build (<module>.unit.so). Also used for build and install commands.

The default value is <config>‘s filename without the -config suffix (thus, /usr/bin/python3-config yields python3).

To configure a module called py33.unit.so for Python 3.3:

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

Configuring Ruby§

When you run ./configure ruby, the script configures a module to support running Ruby scripts as applications in Unit. Available command options:

--module=filename
 

Target name for the Ruby module that Unit will build (<module>.unit.so). Also used for build and install commands.

The default value is the filename of the <ruby> executable.

--ruby=pathname
 

Specific Ruby executable pathname.

The default value is ruby.

To configure a module called ru23.unit.so for Ruby 2.3:

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

Building and Installing Unit§

To build Unit executables and language modules that you have ./configure‘d earlier and install them:

# make
# make install

You can also build and install language modules individually; the specific method depends on whether the language module is embedded in Unit or packaged externally.

Embedded Language Modules§

To build and install Unit modules for Java, PHP, Perl, Python, or Ruby after configuration, run make <module> and make <module>-install, for example:

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

External Language Packages§

To build and install Unit packages for Go and Node.js after configuration, run make <go>-install and make <node>-install, for example:

# make go-install
# make node-install

注解

To install the Node.js package locally, run make <node>-local-install:

# make node-local-install

If you haven’t specified the <local> directory with ./configure nodejs earlier, provide it here: DESTDIR=/your/project/directory. If both options are specified, DESTDIR prefixes the <local> value. However, the recommended method is global installation.

If you customize the executable pathname with --go or --node, use the following pattern:

# ./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

Startup§

We advise installing Unit from preconfigured packages; in this case, startup is configured automatically.

Even if you install Unit otherwise, manual startup is not recommended. Instead, configure a service manager such as OpenRC or systemd or create an rc.d script to launch the Unit daemon using the options below; refer to your system guides for detailed instructions.

To start the daemon, run unitd as root from the sbin installation subdirectory. Usually, there’s no need to override compile-time settings; use the --help command-line option to review their values. For details and security notes, refer to 配置源代码.

General options:

--help, -h Displays a brief summary of Unit’s command-line options and their default values that were configured at compile time.
--no-daemon Runs Unit in non-daemon mode.
--version Displays Unit version and ./configure settings it was built with.

The following options override compile-time settings:

--control <socket>
 Address of the control API socket. IPv4, IPv6, and Unix domain sockets are supported.
--group=name, --user=name
 Group name and user name used to run Unit’s non-privileged processes.
--log <pathname>
 Pathname for the Unit log.
--modules <directory>
 Directory path for Unit language modules (<module>.unit.so files).
--pid <pathname>
 Pathname for the PID file of Unit’s main process.
--state <directory>
 Directory path for Unit state storage.