Beginner’s Guide（开始者向导）

This guide gives a basic introduction to nginx and describes some simple tasks that can be done with it.

这个向导给了对Nginx的基本介绍和如何用nginx工作的一些简单任务。

It is supposed that nginx is already installed on the reader’s machine.

它被支持当nginx已经安装到机器上

If it is not, see the Installing nginx page.

如果没有安装，查看安装nginx页面

This guide describes how to start and stop nginx, and reload its configuration,

这个向导描述怎么样启动和冬至Ngin,以及重新加载它的配置文件

explains the structure of the configuration file and describes how to set up nginx to serve out static content,

解释配置文件的结构和描述如何安装nginx到发送静态内容

how to configure nginx as a proxy server, and how to connect it with a FastCGI application.

如何配置nginx作为一个代理服务器，以及如何连接一个快速图形化界面应用

nginx has one master process and several worker processes.

nginx有一个主进程和多个工作进程

The main purpose of the master process is to read and evaluate configuration, and maintain worker processes.

主进程的主要目的是读取和评价配置文件，以及保持工作进程

Worker processes do actual processing of requests.

工作进程做实际请求的进程

nginx employs event-based model and OS-dependent mechanisms to efficiently distribute requests among worker processes.

nginx雇佣了多个事件基础示范和操作依赖机制为了有效分配工作进程之间的请求

The number of worker processes is defined in the configuration file and may be fixed for a given configuration or automatically adjusted to the number of available CPU cores (see worker_processes).

工作进程的数被定义在配置文件中以及被制定到给定的配置文件或者自动适应有效CPU核数的数量

The way nginx and its modules work is determined in the configuration file. By default, the configuration file is named nginx.conf and placed in the directory /usr/local/nginx/conf, /etc/nginx, or /usr/local/etc/nginx.

这种nginx的方式和它的模型工作在配置文件中被确定。默认情况下，配置文件被命名为nginx.conf并且放在/usr/local/nginx/conf,/etc/nginx,/usr/local/etc/nginx目录中

Starting, Stopping, and Reloading Configuration

开始、停止、重新启动配置文件

To start nginx, run the executable file. Once nginx is started, it can be controlled by invoking the executable with the -s parameter. Use the following syntax:

为了开始nginx，运行可执行文件。一旦nginx被启动，他可以被一个调用可执行的-s参数控制，使用下边的变量： nginx -s signal

nginx -s signal

Where signal may be one of the following: 这个signal可能是下边中的一个.

• stop — fast shutdown停止-快速关闭
• quit — graceful shutdown 退出-优雅的关闭
• reload — reloading the configuration file重启--重启启动配置文件
• reopen — reopening the log files 重打开--重新打开逻辑日志

For example, to stop nginx processes with waiting for the worker processes to finish serving current requests, the following command can be executed:

例如，为了停止正在等待工作的进程以完成当前的请求，几个当前命令，如下的命令被执行。

nginx -s quit

This command should be executed under the same user that started nginx.

这个命令应该在开始的nginx的同一个用户下被执行

Changes made in the configuration file will not be applied   改变的配置文件将不会被应用

until the command to reload configuration is sent to nginx or it is restarted. To reload configuration, execute:

直到命令重新启动配置文件，为了重新启动配置文件，执行如下：

nginx -s reload

Once the master process receives the signal to reload configuration

一旦主进程接手到信号或者重新启动配置文件

, it checks the syntax validity of the new configuration file and tries to apply the configuration provided in it.

它选择新的配置文件中有效的语法，然后适找应用在配置文件中提到的内容

If this is a success,如果这是一个成功

the master process starts new worker processes and sends messages to old worker processes

主进程开始一个新进程并且发送消息给老的工作进程

, requesting them to shut down.

请求他们关闭

Otherwise, the master process rolls back the changes and continues to work with the old configuration. Old worker processes,

否则，这个主线程回滚改变并且继续用老的配置文件工作。老的工作进程，

receiving a command to shut down, stop accepting new connections and continue to service current requests until all such requests are serviced.

接手到命令关闭，停止接手新的连接并且继续服务当前请求知道所有请求被服务

After that, the old worker processes exit.

在那以后，老的工作进程退出

A signal may also be sent to nginx processes with the help of Unix tools such as the kill utility.

一个信号被发送到nginx进程带着Uninx工具比如关闭单元的进程

In this case a signal is sent directly to a process with a given process ID. The process ID of the nginx master process is written, by default, to the nginx.pid in the directory /usr/local/nginx/logs or /var/run. For example, if the master process ID is 1628, to send the QUIT signal resulting in nginx’s graceful shutdown, execute:

在这样的情况下一个信号被直接发送一个带有进程ID号的进程。这个主进程的进程被写，默认，在目录/usr/local/nginx/logs或者/var/run目录下的nginx.pid里面。例如，如果主进程ID为1628，为了发送优雅关闭的退出信号结果，执行如下： kill -s quit 1628

kill -s QUIT 1628

For getting the list of all running nginx processes, the ps utility may be used, for example, in the following way:

为了获得正在运行的nginx进程的列表，PS小勇可能被用，例如，下边的方式  ps -ax |grep nginx

ps -ax | grep nginx

For more information on sending signals to nginx, see Controlling nginx.

为了更多发送信号到nginx的信息，请查看控制nginx

Configuration File’s Structure

配置文件的结构

nginx consists of modules which are controlled by directives specified in the configuration file.

nginx的模块构成被在配置文件的命令指定

Directives are divided into simple directives and block directives.

命令被分为简单命令和模块命令

A simple directive consists of the name and parameters separated by spaces and ends with a semicolon (;).

一个简单命由一个空间和一个分好结束的参数和名词的构成

A block directive has the same structure as a simple directive,

一个模块命令有相同简单指令的结构

but instead of the semicolon it ends with a set of additional instructions surrounded by braces ({ and }).

这个模块命令由{}替代分号

If a block directive can have other directives inside braces, it is called a context (examples: events, http, server, and location).

如果一个模块指令能够有其他内部指令，他被叫做内容例如：时间、http、服务和位置

Directives placed in the configuration file outside of any contexts are considered to be in the main context.

在配置文件任何内容外边的特定指令被看作是主内容

The events and http directives reside in the main context, server in http, and location in server.

特定事件和http指令居住在主要内容、服务器和服务位置

The rest of a line after the # sign is considered a comment.

在#后边的代码被看着是注释

Serving Static Content

服务静态内容

An important web server task is serving out files (such as images or static HTML pages).

一个重要的web服务任务正在服务文件

You will implement an example where,

你需要集成实施这样的例子在这里

depending on the request, files will be served from different local directories: /data/www (which may contain HTML files) and /data/images (containing images).

依赖请求，文件被不同的目录所服务：/data/www(他可能包含Html 文件) 和/data/images图片文件

This will require editing of the configuration file and setting up of a server block inside the http block with two location blocks.

这些要求编辑配置文件和在http块里面设置带有2个位置快的服务器块

First, create the /data/www directory and put an index.html file with any text content into it and create the /data/images directory and place some images in it.

首先，创建/data/www目录并且放一个含有任何内容的index.html文件在里面并且创建目录/data/images并且放一些图片在里面

Next, open the configuration file. The default configuration file already includes several examples of the server block, mostly commented out. For now comment out all such blocks and start a new server block:

下一步，打开配置文件，默认的配置文件是包含"服务器（server）"块的服务例子，大部分被注释掉。现在注释掉所有块并且开启一个服务器块

http {
    server {
    }
}

Generally, the configuration file may include several server blocks distinguished by ports on which they listen to and by server names.

一般地，配置文件可以包括几个“服务器server”块，区别于他们收听和服务器名称的端口

Once nginx decides which server processes a request,

一旦nginx决定选择哪个请求服务进程，它就

it tests the URI specified in the request’s header 它就连接在请求头部被特定设置的URL

against the parameters of the location directives defined inside the server block.

针对服务器块中定义的位置指令的参数

Add the following location block to the server block:

location / {
    root /data/www;
}

This location block specifies the “/” prefix compared with the URI from the request.

这个位置特定的"/"指令，区别于请求的URL?   和 请求的URL在一起

For matching requests, 为了匹配这些请求

the URI will be added to the path specified in the root directive,

这个URL被添加到根指令下的指定路径

that is, to /data/www, to form the path to the requested file on the local file system.

即/数据/ WWW、形成路径所要求的文件在本地文件系统。

If there are several matching location blocks nginx selects the one with the longest prefix.

 如果有多个匹配定位块nginx的选择具有最长前缀。  

The location block above provides the shortest prefix, of length one, and so only if all other location blocks fail to provide a match, this block will be used.

上面的位置块提供了最短的前缀，长度一个，所以只有当所有其他位置块未能提供一个匹配，这个块将被使用。

Next, add the second location block:

接下来，添加第二个位置块

location /images/ {
    root /data;
}

It will be a match for requests starting with /images/ (location / also matches such requests, but has shorter prefix).

他将匹配以/images/开头的一个请求（位置 / 当然也匹配这样的请求，但是有更短的前缀）

The resulting configuration of the server block should look like this:

结果配置文件的服务器块可能像这样

server {
    location / {
        root /data/www;
    }

    location /images/ {
        root /data;
    }
}

This is already a working configuration of a server that listens on the standard port 80 and is accessible on the local machine at http://localhost/.

这个已经正在工作的服务器配置江亭标准的80端口，并且在当前机器上通过 http://localhost访问

In response to requests with URIs starting with /images/, the server will send files from the /data/images directory.

当URL以"/images/"开始请求，则服务器会发送/data/images目录下的所有文件

For example, in response to the http://localhost/images/example.png request nginx will send the /data/images/example.png file.

比如，当在URL上输入http://localhost/imaes/example.png,neginx的请求被发送到/data/images/example.png文件

If such file does not exist, nginx will send a response indicating the 404 error.

如果这样的文件不存在，nginx将发送一个含有404错误的响应

Requests with URIs not starting with /images/ will be mapped onto the /data/www directory.

没有以/images/要求开头的url请讲江北映射到 /data/www目录

For example, in response to the http://localhost/some/example.html request nginx will send the /data/www/some/example.html file.

比如，在回应URL请求“http://localhost/some/example.htm”，请求nginx会发送/data/www/some/example.html文件

To apply the new configuration, start nginx if it is not yet started or send the reload signal to the nginx’s master process, by executing:

为了应用新的配置，开始nginx如果还未开始或者未发送重新启动新号到主进程，会执行

nginx -s reload

In case something does not work as expected, you may try to find out the reason in access.log and error.log files in the directory /usr/local/nginx/logs or /var/log/nginx.

一旦有些功能没有按照预期工作，你可以试着找出原因在access.log和error.log，文件目录在/user/local/nginx/logs 或者/var/log/nginx

Setting Up a Simple Proxy Server

设置一个简单的代理服务器

One of the frequent uses of nginx is setting it up as a proxy server,

nginx一个频繁的使用上作为一个代理服务器

which means a server that receives requests,

他的意思服务器接受、请求、通过他们制定的代理服务器，接受请求从他们，然后发送请求到客户端。

passes them to the proxied servers, retrieves responses from them, and sends them to the clients.

We will configure a basic proxy server,

我们将配置基本的代理服务器

which serves requests of images with files from the local directory and sends all other requests to a proxied server.

服务器请求图片文件从当前的目录并且诶发送所有请求到代理服务器

In this example, both servers will be defined on a single nginx instance.

在这个例子中，两个服务都被顶一个为一个单独nginx实例

First, define the proxied server by adding one more server block to the nginx’s configuration file with the following contents:

首先，定义一个代理服务通过添加一个多个节点到nginx的配置文件类似下边的内容

server {
    listen 8080;
    root /data/up1;

    location / {
    }
}

This will be a simple server that listens on the port 8080 (previously, the listen directive has not been specified since the standard port 80 was used) and maps all requests to the /data/up1 directory on the local file system.

这将是一个简单的服务器监听8080端口（明显的，这个监听指令没有被制定知道标准的80端口被用）并且映射所有的请求到 /data/up1 目录到当前文件系统

Create this directory and put the index.html file into it.

创建这个目录并且防止index.html到该目录下。

Note that the root directive is placed in the server context.

注意根指令在服务器内容被设置

Such root directive is used when the location block selected for serving a request does not include own root directive.

比如根指令被使用当位置块选择用于服务请求，该请求不包括我们根指令

Next, use the server configuration from the previous section and modify it to make it a proxy server configuration.

接下来，使用服务器指令从以前的节点并且修改他们成代理服务器配置

In the first location block, put the proxy_pass directive with the protocol, name and port of the proxied server specified in the parameter (in our case, it is http://localhost:8080):

在这个第一个位置块，设置代理通过指令，附带有协议、名称和指定代理端口

server {
    location / {
        proxy_pass http://localhost:8080;
    }

    location /images/ {
        root /data;
    }
}

We will modify the second location block,

我们修改第二个位置块，

which currently maps requests with the /images/ prefix to the files under the /data/images directory,

他当前映射请求带有 /images/ 设定到在/data/images目录下的文件

to make it match the requests of images with typical file extensions. The modified location block looks like this:

为了设定请求的图片的典型文件扩展名，修改位置块如下：

location ~ \.(gif|jpg|png)$ {
    root /data/images;
}

这个参数是匹配所有url以.gif,.jpg,.png结尾的正则表达式。一般正则表但是应该以“~”开头，这个请求将匹配到/data/images目录

The parameter is a regular expression matching all URIs ending with .gif, .jpg, or .png. A regular expression should be preceded with ~. The corresponding requests will be mapped to the /data/images directory.

当nginx选择一个位置块为了服务一个请求他首先确定了

When nginx selects a location block to serve a request

当选定一个特定的服务器请求块指令

it first checks location directives that specify prefixes, remembering location with the longest prefix, and then checks regular expressions.

他首先验证位置指令，该指令制定前缀，记得最长指令，并且验证正则表达式

If there is a match with a regular expression, nginx picks this location or, otherwise, it picks the one remembered earlier.

如果这里有一个正则表达式匹配，nginx选择位置，否则它选择一个前期记住的正则表达式

The resulting configuration of a proxy server will look like this:

配置代理服务器的配置文件结果像这样：

server {
    location / {
        proxy_pass http://localhost:8080/;
    }

    location ~ \.(gif|jpg|png)$ {
        root /data/images;
    }
}

This server will filter requests ending with .gif, .jpg, or .png

这个服务器将筛选以".gif,.jpg,.png"结尾的请求

and map them to the /data/images directory (by adding URI to the root directive’s parameter)

并且匹配他们到/data/images目录（添加URL到根指令参数）

and pass all other requests to the proxied server configured above.

并且通过所有上边代理的服务器指令的其他请求

To apply new configuration, send the reload signal to nginx as described in the previous sections.

为了应用一个新配置，发送重启信号到nginx就像在前边节点的描述

There are many more directives that may be used to further configure a proxy connection.

这里可能有更多指令，他们可以被作为将来代理连接的配置

Setting Up FastCGI Proxying

建立快速的公共网管代理

nginx can be used to route requests to FastCGI servers which run applications built with various frameworks and programming languages such as PHP.

nginx可以被用着配置路由请求到快速网管服务器，他可以运行各种各样的框架和使用例如Php这样的语音

The most basic nginx configuration to work with a FastCGI server includes using the fastcgi_pass directive instead of the proxy_pass directive,

最基础的nginx配置用于快速网管接口服务的工作包括使用快速网管通知指令代替代理通过指令

and fastcgi_param directives to set parameters passed to a FastCGI server.

和fastcgi_param指令集通过FastCGI服务器参数。

Suppose the FastCGI server is accessible on localhost:9000.

支持快速网关服务在 localhost:9000

Taking the proxy configuration from the previous section as a basis,

设置代理指令从以前的节点例如一个基础的，替代通过指令用快速接口通过指令和参数localhost:9000.

replace the proxy_pass directive with the fastcgi_pass directive and change the parameter to localhost:9000.

In PHP, the SCRIPT_FILENAME parameter is used for determining the script name,

在php中，这个script文件名参数被用着确定script名称

and the QUERY_STRING parameter is used to pass request parameters. The resulting configuration would be:

并且脚本参数被用着通过请求参数。配置结果如下：

server {
    location / {
        fastcgi_pass  localhost:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param QUERY_STRING    $query_string;
    }

    location ~ \.(gif|jpg|png)$ {
        root /data/images;
    }
}

This will set up a server that will route all requests except for requests for static images to the proxied server operating on localhost:9000 through the FastCGI protocol.

这些将建立一个服务，该服务将路由一个请求除了请求动态的图片到代理服务器通过快速关口写在9000端口上