Ansible 角色: Nginx

注意: 请考虑使用 NGINX, Inc. 官方的 NGINX Ansible 角色。

在 RedHat/CentOS、Debian/Ubuntu、Archlinux、FreeBSD 或 OpenBSD 服务器上安装 Nginx。

此角色从 Nginx yum 仓库（在基于 RedHat 的系统上）、apt（在基于 Debian 的系统上）、pacman（Archlinux）、pkgng（在 FreeBSD 系统上）或 pkg_add（在 OpenBSD 系统上）安装和配置最新版本的 Nginx。安装 Nginx 后，您可能需要进行额外的设置，例如在 /etc/nginx/conf.d/ 中添加您自己的 [virtualhost].conf 文件，以描述您特定网站的路径和选项。

要求

无。

角色变量

以下是可用变量及其默认值（请参见 defaults/main.yml）：

nginx_listen_ipv6: true

是否在 IPv6 上监听（适用于此角色管理的所有虚拟主机）。

nginx_selfsigned_certificate_directory: /etc/nginx/ssl
nginx_selfsigned_certificate_privkey: "{{ nginx_selfsigned_certificate_directory }}/privkey.pem"
nginx_selfsigned_certificate_fullchain: "{{ nginx_selfsigned_certificate_directory }}/fullchain.pem"
nginx_selfsigned_certificate_csr: "{{ nginx_selfsigned_certificate_directory }}/cert.csr"

自签名证书应创建的位置。这将在 catchall-vhost 中使用，并替代 nginx-vhost 配置中缺失的证书。

nginx_copy_missing_certs: yes

定义角色是否应为虚拟主机复制自签名证书。

nginx_vhosts: []

Nginx 虚拟主机的虚拟主机定义（服务器块）列表。每个条目将创建一个以 name 命名的单独配置文件。如果留空，您需要提供自己的虚拟主机配置。有关可用服务器选项，请参见 defaults/main.yml 中的示例。如果需要对服务器定义进行大量自定义，更好的做法是自己管理虚拟主机配置文件，将此变量保留为 []。因为我主要使用 Django 编码，所以我创建了 django-vhost.j2 模板，可以通过片段机制进行扩展。

nginx_vhosts:
  - name: localhost-django
    server_names:
      - "localhost"
    upstreams:
      - name: local
        server: localhost:8000
    template: django-vhost.j2
    extra_static_roots:
      - location: "/www/"
        root: /var/
    snippets:
      - location: "~* /static/(.*\\.)(js|css)"
        expiries: 365d
        alias: "/var/www/static/$1$2"
        template: cache.j2
      - location: "/"
        upstream: "local"
        template: "proxy.j2"
    enable_https: true
    static_root: /var/www/static/
    media_root: /var/www/media/
    certificate: /etc/letsencrypt/live/localhost/fullchain.pem
    private_key: /etc/letsencrypt/live/localhost/privkey.pem

在这个示例中，如果上述路径下缺少证书，它将从 nginx_selfsigned_certificate_directory 复制。它将确保 Nginx 正常启动，但您应该提供有效的证书。

nginx_remove_default_vhost: false

是否删除 Nginx 提供的“默认”虚拟主机配置。如果您希望基本的 / URL 定向到为您自己配置的单独 .conf 文件中的一个虚拟主机，则很有用。

nginx_upstreams: []

如果您将 Nginx 配置为负载均衡器，可以使用此变量定义一个或多个上游集。除了定义至少一个上游外，您还需要配置一个服务器块，通过定义的上游代理请求（例如 proxy_pass http://myapp1;）。有关更多信息，请参阅 defaults/main.yml 中的示例。

nginx_user: "nginx"

Nginx 运行时的用户。RedHat 的默认值为 nginx，Debian 为 www-data，FreeBSD 和 OpenBSD 为 www。

nginx_worker_processes: "{{ ansible_processor_vcpus|default(ansible_processor_count) }}"
nginx_worker_connections: "1024"
nginx_multi_accept: "off"

nginx_worker_processes 应设置为您机器上的核心数量（如果默认值不正确，可以使用 grep processor /proc/cpuinfo | wc -l 找到该数字）。nginx_worker_connections 是每个进程的连接数。设置更高以处理更多的同时连接（并且请记住，连接将在每个客户端的 keepalive 超时持续期间内使用！）。如果希望 Nginx 立即接受所有连接，可以将 nginx_multi_accept 设置为 on。

nginx_error_log: "/var/log/nginx/error.log warn"
nginx_access_log: "/var/log/nginx/access.log main buffer=16k"

默认错误和访问日志的配置。设置为 off 以完全禁用日志。

nginx_sendfile: "on"
nginx_tcp_nopush: "on"
nginx_tcp_nodelay: "on"

TCP 连接选项。有关这些指令的更多信息，请参见 这篇博客文章。

nginx_keepalive_timeout: "65"
nginx_keepalive_requests: "100"

Nginx keepalive 设置。如果您有更多的轮询式流量（尤其是 AJAX 驱动的网站），则超时应设置得更高（10s+）；如果大多数用户访问几个页面而不发送进一步请求，则应设置得更低（<10s）。

nginx_server_tokens: "on"

Nginx server_tokens 设置。控制 Nginx 是否在 HTTP 标头中响应其版本。设置为 "off" 以禁用。

nginx_client_max_body_size: "64m"

此值决定了可以上传的最大文件，因上传在击中 php-fpm 等后端之前会经过 Nginx。如果您收到 client intended to send too large body 的错误，则表示此值设置过低。

nginx_server_names_hash_bucket_size: "64"

如果您有很多服务器名称或有非常长的服务器名称，您可能会在启动时遇到 Nginx 错误，需要增加此值。

nginx_proxy_cache_path: ""

在 nginx.conf 文件中设置为 proxy_cache_path 指令。默认情况下，如果保留为空字符串，则不会配置，但如果您希望使用 Nginx 作为反向代理，可以将其设置为有效值（例如 "/var/cache/nginx keys_zone=cache:32m"），以利用 Nginx 的缓存（更多的代理配置可以在单独的服务器配置中完成）。

nginx_extra_http_options: ""

在 nginx.conf 的顶层 http 块中插入额外的行。值应按字面定义（如同直接插入到 nginx.conf 中，遵循 Nginx 配置语法 - 如以 ; 结尾等），例如：

nginx_extra_http_options: |
  proxy_buffering    off;
  proxy_set_header   X-Real-IP $remote_addr;
  proxy_set_header   X-Scheme $scheme;
  proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header   Host $http_host;

有关放置的更多细节，请参见 templates/nginx.conf.j2 中的模板。

nginx_extra_conf_options: ""

在 nginx.conf 顶部插入额外的行。值应按字面定义（如同直接插入到 nginx.conf 中，遵循 Nginx 配置语法 - 如以 ; 结尾等），例如：

nginx_extra_conf_options: |
  worker_rlimit_nofile 8192;

有关放置的更多细节，请参见 templates/nginx.conf.j2 中的模板。

nginx_log_format: |-
  '$remote_addr - $remote_user [$time_local] "$request" '
  '$status $body_bytes_sent "$http_referer" '
  '"$http_user_agent" "$http_x_forwarded_for"'

配置 Nginx 的 log_format 选项。

nginx_default_release: ""

（仅适用于 Debian/Ubuntu）允许您为 Nginx 的安装设置不同的仓库。例如，如果您正在运行 Debian 的 wheezy 版本，并希望获取更新版本的 Nginx，您可以安装 wheezy-backports 仓库并在此处设置该值，Ansible 将在安装 Nginx 时使用此值作为 -t 选项。

nginx_ppa_use: false
nginx_ppa_version: stable

（仅适用于 Ubuntu）允许您使用官方的 Nginx PPA，而不是系统的包。您可以将版本设置为 stable 或 development。

nginx_yum_repo_enabled: true

（仅适用于 RedHat/CentOS）将此设置为 false 以禁用 nginx yum 仓库的安装。如果您希望使用默认的 OS 稳定包，或者使用 Satellite，请必要时这样设置。

nginx_service_state: started
nginx_service_enabled: yes

默认情况下，此角色将确保 Nginx 正在运行并在配置后开机启动。您可以使用这些变量覆盖此行为，特别是在容器中安装或需要进一步控制服务状态时。

重写配置模板

如果由于未公开选项而无法通过变量进行自定义，您可以重写用于生成虚拟主机配置文件或 nginx.conf 文件的模板。

nginx_conf_template: "nginx.conf.j2"
nginx_catchall_template: "default-catchall.j2"
nginx_vhost_template: "vhost.j2"

如果需要，您还可以按虚拟主机逐个设置模板。

nginx_vhosts:
  - listen: "80 default_server"
    server_name: "site1.example.com"
    root: "/var/www/site1.example.com"
    index: "index.php index.html index.htm"
    template: "{{ playbook_dir }}/templates/site1.example.com.vhost.j2"
  - server_name: "site2.example.com"
    root: "/var/www/site2.example.com"
    index: "index.php index.html index.htm"
    template: "{{ playbook_dir }}/templates/site2.example.com.vhost.j2"

您可以复制和修改提供的模板，或者使用 Jinja2 模板继承 来扩展它，并覆盖您需要更改的特定模板块。

示例: 在 Nginx 配置中配置 gzip

将 nginx_conf_template 设置为指向您 playbook 目录中的模板文件。

nginx_conf_template: "{{ playbook_dir }}/templates/nginx.conf.j2"

在您上面配置的路径中创建子模板，并扩展相对于您的 playbook.yml 的 nekeal.nginx 模板文件。

{% extends 'roles/nekeal.nginx/templates/nginx.conf.j2' %}

{% block http_gzip %}
    gzip on;
    gzip_proxied any;
    gzip_static on;
    gzip_http_version 1.0;
    gzip_disable "MSIE [1-6]\.";
    gzip_vary on;
    gzip_comp_level 6;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/x-javascript
        application/json
        application/xml
        application/xml+rss
        application/xhtml+xml
        application/x-font-ttf
        application/x-font-opentype
        image/svg+xml
        image/x-icon;
    gzip_buffers 16 8k;
    gzip_min_length 512;
{% endblock %}

依赖关系

无。

示例 Playbook

- hosts: server
  roles:
    - { role: nekeal.nginx }

许可证

MIT / BSD

作者信息

此角色由 Jeff Geerling 于 2014 年创建，他是 Ansible for DevOps 一书的作者。