# 工具部署Nginx

工具类型: shell 脚本

文档更新: 2026-01-23 11:28:06

适用场景: 非云化产品的的私有化部署(自建环境)

# 免责申明和使用须知

1.工具定位声明
- 本工具为辅助部署工具，旨在帮助快速搭建云原生环境所依赖的中间件（包含并不仅限于Kubernetes、Nacos、Kafka等），便于项目组快速部署微服务应用。
- 不承诺提供中间件的长期完整维护、支持或安全保障。
2.开源组件免责声明
- 本工具使用的 Kubernetes、etcd、calico、Nacos、Kafka等组件均为开源软件，受各自开源许可证保护。
- 本工具不修改、不篡改任何开源组件，仅作为安装和部署的辅助工具。
- 使用本工具即表示您已阅读并同意相关开源组件的使用许可协议。
3.安全与责任声明
- 本工具不承担因使用过程中出现的安全问题、系统崩溃、数据丢失等后果的责任。
- 建议用户自行评估部署环境的安全性，并根据自身需求选择合适的版本和配置。
4.不提供长期维护
- 本工具仅为临时部署工具，不承诺对中间件进行持续更新、补丁修复、安全处置和兼容性支持。
- 用户应自行关注官方更新，并根据实际需要决定是否升级或更换工具。
5.商业使用提醒
- 若您将本工具用于商业环境，请确保所有使用组件符合其开源许可证，并遵守相关法律法规。
- 本工具不提供任何形式的商业支持或担保。
6.用户自主决策
- 本工具仅供参考和学习使用，最终部署方案由用户自行决定。
- 在使用前，请确保您具备足够的技术能力，并了解Kubernetes、Nacos、Kafka等等云原生组件的运行机制和配置方法。

# 相关下载

安装工具-单机编译版: https://pan.baidu.com/s/1uY5lQ0miwaFJSJjE76_AzA?pwd=f2dg

安装工具-高可用编译版: https://pan.baidu.com/s/1qajcicpDHYeQGQkQDBmZNQ?pwd=ayzc

# 工具安装

# 设置足够大的句柄

至少设置open files为65535，避免生产上线时遭遇 too many open files 异常：

通过 vim /etc/security/limits.conf 命令编辑此文件添加以下内容

# open files  (-n)
* soft nofile 65535
* hard nofile 65535
# max user processes  (-u)
* soft nproc 65535
* hard nproc 65535

# 设置当前会话中立刻生效
ulimit -n 65535  # 设置最大打开文件数量
ulimit -u 65535  # 设置最大进程数
以上配置完成后，执行 ulimit -a 命令检查open files是否变成65535

# 上传工具和相关模块包

# 准备一个存放脚本和模块包的目录
mkdir -p /seeyon/scripts/nginx

将multi-install-nginx.sh、Nginx二进制包及相关依赖模块全部上传到同一个目录下，sh工具安装时会自动读取目录下的文件：

# 配置工具参数

vim multi-install-nginx.sh

按需修改multi-install-nginx.sh中的参数，首次安装可以全部保持默认。

# 执行工具脚本安装

bash multi-install-nginx.sh

初始安装，如检测到命令缺失，需参考工具输出找到与当前系统相匹配的安装命令，进行手动安装。安装完成后，再重新执行 bash multi-install-nginx.sh

如命令无缺失，会看到持续日志输出显示安装过程，二进制编译安装需要一定时间，耐心等待编译完成：

看到如下信息，则表示安装成功：

# 日常维护

记录工具部署最后的输出日志，参考日志做后续日常维护即可：

请按需手动配置参数文件: /apps/nginx/conf/nginx.conf
当前默认不加载配置目录: /apps/nginx/conf.d/{http,stream}
如果需要记得取消行注释: /apps/nginx/conf/nginx.conf 中的 include 行

服务管理
启动服务: systemctl start nginx
重启服务: systemctl restart nginx
关闭服务: systemctl stop nginx
重载配置: systemctl reload nginx
服务状态: systemctl status nginx

相关命令
检查配置: /apps/nginx/sbin/nginx -t
启动服务: /apps/nginx/sbin/nginx -c /apps/nginx/conf/nginx.conf
关闭服务: /apps/nginx/sbin/nginx -s stop
重载配置: /apps/nginx/sbin/nginx -s reload
查看版本: /apps/nginx/sbin/nginx -v

# 预编译纯静态的 nginx 二进制文件

当前，预编译有 amd64 和 arm64 以及 loong64 三个架构的 nginx 纯静态的最新版二进制文件给有需要的同事使用。

当前分别有 nginx/tengine/angie + openssl/libressl/tongsuo 的组合，在文件名中体现，可按需下载使用。

涉及国密的只提供 angie/tengine + tongsuo 的包，不支持 nginx + tongsuo。

更新时间: 20260208

在压缩包的doc目录下的version.info文件保存了所包含的模块插件和版本信息

nginx-static 的版本信息：

nginx: 1.28.2 zlib: 1.3.1 openssl: 3.0.19 pcre2: 10.47 ngx_http_proxy_connect_module: 0.0.7 nginx_upstream_check_module: 2025-03-19 nginx_sticky_module: 08a395c66e42+patch nginx-module-vts: 0.2.5 ngx_brotli: 1.2.0

编译时，默认安装路径为：/apps/nginx。

部署时，安装目录不是 /apps/nginx 这个路径，则需使用 -p 参数按需调整为实际安装路径。

编译时开启了 nginx 所有核心模块，还开启/支持以下功能模块：

ssl/http2/http3
nginx-sticky-module-ng
ngx_http_proxy_connect_module

# 使用方法

下载对应硬件平台的 tgz 包

amd64/x86_64 平台下载：nginx-static-1.28.1-amd64.tgz

arm64/aarch64 平台下载：nginx-static-1.28.1-arm64.tgz

# 升级已有

解压 tgz 包相对路径下的 sbin/nginx 这个文件替换原有同名文件即可。

# 全新安装

1、解压 tgz 包到对应目录下，如：/apps，不需要再添加nginx。解压后会自动在 /apps 下创建 nginx 目录。效果如：/apps/nginx。

注：/apps/nginx 为实际安装目录

# 创建安装根目录
mkdir -p /apps

# 创建运行nginx的默认用户和组(默认nobody)
grep -q "^nobody:" /etc/group || groupadd nobody
grep -q "^nobody:" /etc/passwd || useradd -r -s /usr/sbin/nologin -g nobody nobody

# amd64/x86_64 架构
tar -xf nginx-1.28.1-amd64.tgz -C /apps

# arm64/aarch64 架构
tar -xf nginx-1.28.1-arm64.tgz -C /apps

2、使用命令创建服务控制文件

注：/apps/nginx 为实际安装目录可自行调整。例如：/home/yfc/nginx

ngxPrefix=/apps/nginx
cat > /etc/systemd/system/nginx.service << EOF
[Unit]
Description=Nginx Server
After=network.target nss-lookup.target
Wants=network-online.target

[Service]
Type=forking
ExecStartPre=${ngxPrefix}/sbin/nginx -p ${ngxPrefix} -t
ExecStart=${ngxPrefix}/sbin/nginx -p ${ngxPrefix}
ExecReload=${ngxPrefix}/sbin/nginx -p ${ngxPrefix} -s reload
# User=nobody
# Group=nobody
Restart=on-failure
RestartSec=5s
KillSignal=SIGQUIT
TimeoutStopSec=10s
# PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF

3、一些服务管理命令

systemctl daemon-reload
systemctl restart nginx
systemctl status nginx

4、当实际部署路径和编译时路径不一样时的手动管理命令(以 /home/yfc/nginx 为例)

ngxPrefix=/home/yfc/nginx
# 测试
${ngxPrefix}/sbin/nginx -p ${ngxPrefix} -t
# 启动
${ngxPrefix}/sbin/nginx -p ${ngxPrefix}
# 重载
${ngxPrefix}/sbin/nginx -p ${ngxPrefix} -s reload
# 关闭
${ngxPrefix}/sbin/nginx -p ${ngxPrefix} -s stop

# 预编译纯静态的 tengine 二进制文件

tengine 官方网址：http://tengine.taobao.org

当前，预编译有 amd64 和 arm64 两个架构的 tengine 纯静态的最新版二进制文件给有需要的同事使用。

更新时间: 20260202

tengine-static 的版本信息：

tengine: 3.1.0 zlib: 1.3.1 openssl: 3.0.19 pcre2: 10.47

编译时，默认安装路径为：/apps/nginx。

部署时，安装目录不是 /apps/nginx 这个路径，则需使用 -p 参数按需调整为实际安装路径。

编译时开启了 tengine 所有核心模块，tengine 内置支持以下功能模块（sticky 模块已内置）：

ssl/http2/http3
ngx_http_proxy_connect_module

安装和升级参考nginx的操作即可。部署方式和nginx的基本相同。

使用 tengine 时需要注意：

nginx 调用 sticky 模块时使用 sticky

tengine 调用 sticky 模块时使用 session_sticky

# 预编译纯静态的 angie 二进制文件

angie 官方网址：https://cn.angie.software

angie 支持铜锁和国密功能相关文档参考链接：https://www.tongsuo.net/docs/features/angie/

当前，预编译有 amd64 和 arm64 两个架构的 angie纯静态的最新版二进制文件给有需要的同事使用。

更新时间: 20260202

angie-static 的版本信息：

angie: 1.11.2 zlib: 1.3.1 tongsuo: 8.4.0 pcre2: 10.47 nginx-module-vts: 0.2.5

编译时，默认安装路径为：/apps/angie。

部署时，安装目录不是 /apps/angie 这个路径，则需使用 -p 参数按需调整为实际安装路径。

编译时开启了 angie 所有核心模块，还开启/支持以下功能模块（sticky 模块已内置）：

ssl/http2/http3
ngx_http_proxy_connect_module

安装和升级参考nginx的操作即可。注意把 nginx 改为 angie 即可。

# 免编译二进制版全量包

在免编译二进制版全量包中，实现了二进制解压自动部署。

包含且支持 nginx/tengine/angie 三个不同软件服务在 amd64 和 arm64 两个硬件平台下的单机部署和高可用部署。

部署前，按需调整部分脚本参数和 nginx.hosts 配置。

部署后，按需调整 nginx/tengine/angie 的相关配置，以满足业务实际需求。

# 解压
tar -xf multi-install-nginx-1.28.1-amd64.tgz

# 安装
# 只传参 i 时 默认安装 nginx
bash multi-install-nginx.sh i

# 传参 i nginx 时 安装 nginx
bash multi-install-nginx.sh i nginx
# 传参 i tengine 时 安装 tengine
bash multi-install-nginx.sh i tengine
# 只传参 i angie 时 安装 angie
bash multi-install-nginx.sh i angie

# 关于监控

模块及功能一般依赖到以下三个项目（当前使用vts）： https://github.com/vozlt/nginx-module-vts https://github.com/sysulq/nginx-vts-exporter https://github.com/nginx/nginx-prometheus-exporter

vts官方发布的二进制文件需要 glibc 2.32 以上才能运行。

为了方便大家，使用官方源码自行构建了 amd64 和 arm64 两个架构的纯静态二进制文件，经验证，支持在 glibc 2.17 及以上的操作系统运行。可在网盘下载。

# 使用vts时

编译nginx时，需要安装额外模块。采集的数据比较多。

确保已经取消以下注释：

http {
    ......
    vhost_traffic_status_zone;
    vhost_traffic_status_filter_by_host on;
    ......
    server {
        ......
        location /vts_status/json {
            vhost_traffic_status_display;
            vhost_traffic_status_display_format json;
        }
        ......
}

# 使用stub时

编译nginx时，无需安装额外模块。但是采集的数据很少很基础。

确保已经取消以下注释：

        location /stub_status {
            stub_status on;
            access_log off;
            # 注意调整授权IP或网段
            #allow 192.168.100.240;
            #deny all;
        }

# 关于容器镜像

由于官方发布的镜像在编译时没有添加以下模块：

nginx_upstream_check_module ngx_http_proxy_connect_module nginx_sticky_module nginx-module-vts

如果需要，可以使用网盘里的极致精简容器镜像，基于纯静态二进制构建。

nginx：包含 ngx_http_proxy_connect_module、nginx_upstream_check_module、nginx_sticky_module、nginx-module-vts

tengine：内置了绝大多数监控数据采集，所以不需要以上模块。

angie：包含 nginx-module-vts

docker-compose 示例文件

# 先临时启动一个容器
docker run --rm -it -p 80:80 nginx:1.28.1
# 获取挂载卷可能会用到的相关信息
docker exec -it $(docker ps | grep nginx:1.28.1 | awk '{print $1}') /apps/nginx/sbin/nginx -V

services:
  nginx:
    image: nginx:1.28.1
    container_name: nginx
    ports:
      - "80:80"    # 端口映射：宿主机80 → 容器80
      - "443:443"  # 若需HTTPS，添加443端口映射
    volumes:
      # 1. 挂载主配置目录（核心：覆盖/修改nginx.conf）
      - ./nginx/conf:/apps/nginx/conf
      # 2. 挂载子配置目录（推荐：虚拟主机配置单独放，不修改主配置）
      - ./nginx/conf.d:/apps/nginx/conf.d
      # 3. 挂载网页根目录（业务静态文件：html、css、js等）
      - ./nginx/html:/apps/nginx/html
      # 4. 挂载日志目录（容器日志持久化到宿主机，便于排查问题）
      - ./nginx/logs:/apps/nginx/logs
      # 可选：挂载SSL证书目录（若配置HTTPS，需添加）
      # - ./nginx/ssl:/apps/nginx/ssl
    restart: always  # 容器异常退出时自动重启，保证服务可用性
    network_mode: bridge  # 默认网络模式，按需修改（如host/自定义网络）

如果涉及铜锁（tongsuo）国密相关生态工具，请参考： https://www.tongsuo.net/docs/release-note

# 提醒

在使用基于 musl libc 构建的 Nginx、Tengine、Angie、Redis 等纯静态二进制程序时，由于 musl 在 DNS 解析及 IPv6 连接回退策略 上的实现特性，在 IPv6 半可用或链路质量不稳定 的环境中，可能出现连接延迟或超时问题。

为规避上述风险，建议通过 应用层配置 + 系统层策略 双层显式限制仅使用 IPv4（单层可生效，双层约束更稳定），包括绑定 IPv4 地址、禁用 IPv6 监听，以及限定仅进行 IPv4 域名解析。

# 1. 应用软件层面

# 1.1 Redis 配置示例

# redis.conf
# 仅监听 IPv4 地址，避免启用双栈监听
bind 0.0.0.0
# 如存在以下配置需删除或注释
# bind ::
# bind * -::*

说明： Redis 默认支持双栈监听，显式移除 IPv6 监听可避免 musl 在连接阶段进入 IPv6 分支；容器化或物理机启动时可注入环境变量强化：export RES_OPTIONS="inet4"。

# 1.2 Nginx / Tengine / Angie 配置示例

# nginx.conf
http {
    # HTTP层强制仅IPv4解析
    resolver 223.5.5.5 8.8.8.8 ipv4=on;
    server {
        listen 0.0.0.0:80;
        # listen [::]:80;  # 禁用 IPv6 监听
    }
    server {
        listen 0.0.0.0:443 ssl;
        # listen [::]:443 ssl;  # 禁用 IPv6 监听
        # SSL相关配置...
    }
}

说明： resolver ipv4=on 强制仅解析 A 记录（IPv4），避免 musl 尝试 AAAA（IPv6）解析；使用 upstream 域名时，此配置可有效规避解析层延迟。

# 2. 网络 / 操作系统层面

# 2.1 基于 Kubernetes 的配置示例

# 方式一：通过 sysctl（推荐，前提是集群允许开启 sysctl 配置）

spec:
  securityContext:
    sysctls:
    - name: net.ipv6.conf.all.disable_ipv6
      value: "1"
    - name: net.ipv6.conf.default.disable_ipv6
      value: "1"
  containers:
  - name: 应用名称
    image: 应用镜像:版本
    env:
    - name: RES_OPTIONS
      value: "inet4"

说明：使用 sysctls 比特权容器更安全，也符合 Kubernetes 最佳实践；需确保集群已配置 sysctl_node_allow_list 包含上述配置项。

# 方式二：特权容器方式（不推荐，仅作兜底）

spec:
  containers:
  - name: 应用名称
    image: 应用镜像:版本
    securityContext:
      privileged: true
    command: ["/bin/sh", "-c"]
    args:
    - sysctl -w net.ipv6.conf.all.disable_ipv6=1 && export RES_OPTIONS="inet4" && 应用启动命令

# 2.2 物理机 / 虚拟机配置示例

# 1. 写入配置文件永久生效
echo "net.ipv6.conf.all.disable_ipv6 = 1" >> /etc/sysctl.conf
echo "net.ipv6.conf.default.disable_ipv6 = 1" >> /etc/sysctl.conf
echo "net.ipv6.conf.lo.disable_ipv6 = 1" >> /etc/sysctl.conf
# 2. 重载配置立即生效
sysctl -p
# 3. 全局注入环境变量强化IPv4解析（可选）
echo "export RES_OPTIONS=\"inet4\"" >> /etc/profile
source /etc/profile

# 3. 验证配置是否生效

# 1. 验证系统 IPv6 是否禁用（输出 1 即为生效）
sysctl net.ipv6.conf.all.disable_ipv6
# 2. 验证应用是否仅监听 IPv4（无 tcp6/inet6 输出即为生效）
ss -tulnp | grep -E "nginx|redis-server"
# 3. 验证 musl 解析是否仅返回 IPv4（无 IPv6 地址输出即为生效）
getent ahostsv6 目标域名 || echo "IPv6解析已禁用"

编撰人：yangfc、het

← 手动部署Nacos 手动部署Nginx →