运维文档

# Nginx部署维护参考手册

# 前言

本手册提供适用于致远协同V5产品线的Nginx安装部署维护方案，如V5项目需要Nginx提供负载均衡、反向代理、SSL等能力，可参考本手册操作。

由于致远协同V5产品线集群环境依赖nginx-sticky-module模块的会话粘滞能力，故本手册部署方案会包含nginx-sticky，无论协同单机还是集群都适用。

Nginx官方地址 https://nginx.org/en/download.html

免责声明：

  1. 本手册配套分发的 Nginx 为开源免费版本，遵循 BSD 开源许可协议分发，本平台仅免费提供文档与配套部署方案，本平台不收取任何费用，亦不代表开源软件无商用合规义务，商用场景请使用者自行遵守对应开源授权条款；
  2. 本平台不提供任何有偿、无偿的现场部署、线上调试、故障排查、长期售后等技术支持服务，所有方案仅供个人学习、项目环境参考；
  3. 手册文字、自研部署脚本、配套实施方案著作权归本平台作者所有；Nginx 程序本体相关知识产权、版权归原软件官方所有；
  4. 请使用者务必在隔离测试环境完整验证稳定性、安全性后，再酌情应用至生产环境；因直接上线产生的业务中断、数据丢失、安全漏洞、商业损失、知识产权侵权纠纷等全部风险与赔偿责任，均由使用者自行独立承担，与本平台无关。

# 部署方案

Nginx不同版本、不同操作系统的部署方案不同，本手册提供三个场景的部署方案供项目自行选择：

方案 适用系统 适用版本 部署方案 推荐指数
方案一 Linux、信创操作系统 Nginx1.30及更高Stable版 预编译包部署 ★★★★★
方案二 Windows Server Nginx1.30及更高Stable版 下载官方包部署 ★★
方案三 Linux、信创操作系统 Nginx1.28及更低Stable版 手动编译部署 ★★★

注：

  • 推荐使用Nginx最新Stable版本，以减少BUG和安全问题
  • 推荐使用Linux/信创环境部署Nginx，Linux 下 Nginx 性能、并发、稳定性、扩展模块自由度、运维与安全全面优于Windows 版 Nginx（功能阉割、IO 模型落后、稳定性一般）。
  • Nginx1.28及以下版本仅推荐Linux，因为1.28及以下版本官方不包含nginx-sticky模块，必须由部署人员在客户Linux或信创系统下手工将nginx-sticky模块加入并编译。
  • 自Nginx1.30版本开始，Nginx官方自带nginx-sticky模块，故Linux/信创和Windows系统均可使用sticky实现负载均衡。
  • Nginx官方规定 偶数号（如1.28、1.30）为稳定生产版（Stable） ， 而 奇数号（如1.29）为开发版（Mainline）不适合生产环境使用，故本手册未推荐1.29、1.31版本。

1783779275033.png

# 方案一Linux/信创部署Nginx1.30+版本

Linux / 信创环境部署 Nginx1.30 + 版本推荐使用预编译安装包，直接在客户环境运行使用。预编译包在 Nginx 官方原版基础上增加了 SSL 增强、gzip 压缩等高价值插件，让 Nginx 无需现场源码编译即可拥有完整企业负载均衡能力，兼容全系列信创硬件与操作系统，兼顾安全性、并发性能与运维便捷性。

# 1、预编译包下载

Nginx预编译包下载地址 https://pan.baidu.com/s/1uY5lQ0miwaFJSJjE76_AzA?pwd=f2dg

云盘提供了针对不同环境不同场景的预编译包，根据客户现场实际需求选择合适的安装包：

  • 安装包统一采用 multi-install-nginx-版本-加密库-架构.tgz 格式
  • 版本：优先下载 免编译二进制版全量包/musl 下最新Nginx版本（如本手册编时间2026-7-11最新Nginx稳定版本1.30.3）
  • 加密库：如无特殊要求默认使用 openssl 包（主流通用、兼容性最强）；如客户需要国密认证并兼容国际 TLS 标准则使用 tongsuo；如服务器内存资源有限、部署轻量边缘网关，追求更低内存占用与更少历史安全漏洞，则选用 libressl。
  • 架构：Intel/AMD x86 通用服务器选择amd64；鲲鹏、飞腾等 ARM 架构信创主机选择arm64；龙芯 LoongArch 国产处理器信创设备选择loong64。

1783781572183.png

# 2、预编译包环境要求

  • 需要 root 权限。
  • 需要 systemd 支持（用于管理 nginx.service）。
  • 本机 SSH 服务必须可达（安装包内部通过 SSH 推送部署到本机）。
  • 需要确认当前机器架构与安装包匹配。

# 3、预编译NG单机部署步骤

1、上传并解压安装包

将安装包上传到服务器，建议放到 /tmp 或 /data 目录。

# 将安装包上传到服务器，建议放到 `/tmp` 或 `/data` 目录
mkdir -p /data
mv multi-install-nginx-1.30.3-openssl-amd64.tgz /data
cd /data

# 解压到同名目录（按实际文件名替换）
tar -xf multi-install-nginx-1.30.3-openssl-amd64.tgz --one-top-level

# 进入解压目录
cd multi-install-nginx-1.30.3-openssl-amd64/

# 查看目录结构
ls -la

解压后的典型目录结构如下（部署配置只需要关注multi-install-nginx.sh和cfg/native/nginx.hosts两个文件）：

multi-install-nginx-1.30.3-openssl-amd64/
├── multi-install-nginx.sh    # 安装包内置部署脚本（核心文件）
├── bin/                      # 辅助工具（gossh、jq 等）
├── cfg/
│   └── native/
│       └── nginx.hosts       # SSH 连接配置（需编辑）
├── software/                 # Nginx 静态二进制
├── doc/                      # 文档
└── logs/                     # 运行日志

3、配置安装启用V5 Nginx模板

预编译安装包自带了自动配置V5 Nginx标准模板的功能，按如下方式设置：

V5产品线有统一的Nginx配置要求，参考文档《Nginx反向代理和负载均衡协同HTTP (opens new window)》

cd multi-install-nginx-1.30.3-openssl-amd64/

# 配置方式二选一：将createV5cfg设置为1，即安装时自动内置V5 Nginx模板
sed -i 's/^createV5cfg=""/createV5cfg="1"/' multi-install-nginx.sh

# 配置方式二选一：也可以通过vi命令直接找到 createV5cfg="" 将其修改为 createV5cfg="1"
vi multi-install-nginx.sh

1784013267179.png

3、配置 SSH 连接信息

multi-install-nginx预编译安装包的运行原理是安装包服务器 → SSH连接到Nginx服务器远程安装。如果您将安装包已经放置在Nginx服务器，也需要将当前服务器的SSH信息进行配置才能安装。

# 编辑安装包目录下的 `cfg/native/nginx.hosts` 进行ssh配置
vi cfg/native/nginx.hosts

# 修改v8-nginx那一行配置，将其改成Nginx服务器真实IP和SSH连接信息，修改后进行保存
v8-nginx host=192.168.58.132 port=22 user=root password=Seeyon123.

1783849413138.png

4、执行安装

在解压目录中执行安装包内置部署脚本：

cd multi-install-nginx-1.30.3-openssl-amd64/
bash multi-install-nginx.sh i nginx

看到如下信息表示安装完成：

1783849591057.png

预编译Nginx默认安装目录和包管理模式如下：

  • 程序目录：/apps/nginx（默认，由安装包内 instRootDir 决定）
  • 配置文件：/apps/nginx/conf 目录
  • 服务管理：systemctl 管理 nginx.service

验证安装结果：

# 查看部署摘要和常用命令（如存在）
cat doc/apps-deployment-summary.txt

# 验证版本
/apps/nginx/sbin/nginx -V
# 输出示例：nginx version: nginx/1.30.3

# 验证服务状态
systemctl status nginx

5、检查Nginx配置完整性

如按本手册操作，预编译安装包会自动生成V5的Nginx配置，只需要基于配置调整成客户真实的代理地址即可，相关配置如下：

cd /apps/nginx/conf
ls

# 主配置文件
vi nginx.conf

预编译包默认内置了主OA、移动端、数科、文档通的配置，按需开启：

1784013864368.png

# 4、预编译NG日常运维

# 1. 预编译NG启停服务

systemctl start nginx
systemctl stop nginx
systemctl restart nginx

# 2. 预编译NG重载配置（不中断连接）

/apps/nginx/sbin/nginx -s reload

# 3. 预编译NG查看状态

systemctl status nginx

# 4. 预编译NG查看版本

/apps/nginx/sbin/nginx -V

# 5. 预编译NG查看错误日志

tail -f /apps/nginx/logs/error.log

# 6. 预编译NG检查进程

ps aux | grep nginx | grep -v grep

# 7. 预编译NG检查端口

这个与nginx/conf/nginx.conf的配置有关，配置监听了哪些端口就根据实际端口检查，以下是检查80端口示例

ss -tlnp | grep :80
# 预期包含：LISTEN  0  511  0.0.0.0:80  ...  nginx

# 8. 预编译NG检查 HTTP 访问

这个与nginx/conf/nginx.conf的配置有关，以下是以默认80端口为例

# 本地测试
curl -I http://127.0.0.1
# 预期输出包含：HTTP/1.1 302 或 HTTP/1.1 200

# 外部访问（替换为服务器 IP）
curl -I http://<服务器IP>

如果后端 OA 已启动，浏览器访问 http://<服务器IP> 应跳转到 OA 登录页面。

# 9. 预编译NG修改conf

# 如按本手册操作，V5产品线的主配置存放于nginx.conf中，可根据实际情况调整配置
vi /apps/nginx/conf/nginx.conf

# 校验配置文件语法
/apps/nginx/sbin/nginx -t
# 正常输出：
# nginx: the configuration file /apps/nginx/conf/nginx.conf syntax is ok
# nginx: configuration file /apps/nginx/conf/nginx.conf test is successful

# 重启 Nginx使配置生效
systemctl restart nginx

# 验证服务状态
systemctl status nginx

# 5、预编译NG卸载步骤

预编译NG安装包sh文件提供了详细的卸载命令，执行如下命令可以查看卸载操作：

cd multi-install-nginx-1.30.3-openssl-amd64/

# 执行命令后，控制台会输入详细的卸载命令，需要参考卸载命令逐条手工执行即可完成
bash multi-install-nginx.sh r nginx

1783850085389.png

# 6、预编译NG升级版本步骤

如早期已经安装预编译NG旧版本，本次（出于安全或其它原因）需要对NG版本进行升级，通用升级方法为：备份nginx配置→卸载旧版→安装新版→还原nginx配置。

参考步骤如下：

1、备份nginx/conf文件：提前备份 /apps/nginx/conf 整个配置文件夹，避免升级后配置丢失

2、参考 [预编译NG卸载步骤] 章节，完整卸载老版本预编译NG

3、参考 [预编译包下载] 章节下载最新版本预编译NG程序

4、参考 [预编译NG单机部署步骤] 章节安装最新版本

5、将第一步旧版nginx/conf备份的文件夹还原并参考 [预编译NG修改conf] 章节重启配置生效

# 7、预编译NG实现Nginx高可用

预编译NG不仅支持单机Nginx部署，还提供了行业通用的vip+keepalived+nginx主备高可用部署脚本，由于此方案相对复杂，由技术能力的个人可参考multi-install-nginx.sh部署脚本的配置说明，结合AI进行高可用部署。

# 方案二Windows部署Nginx1.30+版本

自Nginx1.30版本开始，Nginx官方自带nginx-sticky模块，理论Windows Server环境下的Nginx也支持V5集群，如项目环境有限，要求不高，可以参考本手册部署。

建议：推荐使用Linux/信创环境部署Nginx，Linux 下 Nginx 性能、并发、稳定性、扩展模块自由度、运维与安全全面优于Windows 版 Nginx（功能阉割、IO 模型落后、稳定性一般）。如在Windows下出现NG相关限制，建议切换到Linux系统！

# 1、Win-Nginx安装包下载

通过Nginx官方地址 https://nginx.org/en/download.html 下载最新的Stable Windows安装包：

1783852619927.png

# 2、Win-Nginx单机安装部署步骤

1）解压zip安装包：

官方下载的Nginx默认为zip包，将其解压到不含中文路径的目录下，正常展示效果如下：

1783853631271.png

2）完整替代nginx.conf模板为V5产品线标准配置

安装包conf下生成的默认配置是通用配置，需要替换为V5产品线需要的 nginx.conf 模板。

将windows下conf/nginx.conf里面的内容完全删除，然后完全参考在线文档拷贝使用《Nginx反向代理和负载均衡协同HTTP (opens new window)》配置：

1783853764643.png

3）启动Windows Nginx

直接运行根目录的nginx.exe启动 或 通过命令 start nginx 启动。

# 3、Win-Nginx日常运维

1）Windows下Nginx启停： 可以通过运行nginx.exe+可视化杀掉nginx.exe来操作。 或者通过命令（在Nginx程序目录下运行）start nginx 和 .\nginx -s quit 实现。

2）Windows下修改conf配置： 跟Linux相似：修改Nginx程序目录下conf的配置（如nginx.conf），修改后需要重启Nginx使配置生效。

3）Windows下升级Nginx版本： 跟Linux相似：备份conf配置 → 停止Nginx并卸载Nginx程序 → 下载安装最新Nginx → 还原备份的conf并启动

# 方案三Linux/信创手工编译Nginx1.28低版本

Nginx1.28是NG的旧版本，该版本NG未内置nginx-sticky模块，故需要源码编译部署。

建议新项目均使用最新Nginx版本部署，仅Nginx老客户有编码编译需求才使用本手册，详细手工编译方法见《Nginx1.28旧版本源码编译部署方法 (opens new window)》

编撰人：yangfc、het

快速跳转

← 工具部署ClickHouse →