01-单机部署与基础认知

1. 阶段定位

第一阶段是 Nginx 七阶段学习路线的入门基础阶段，目标不是记住大量配置项，而是先建立对 Nginx 的整体认知，掌握一台单机 Nginx 从安装、启动、配置、访问、日志查看到基础排障的完整闭环。

学习这一阶段时，需要把 Nginx 当成一个运行在操作系统上的网络服务来看，而不是只把它当成一份 nginx.conf 配置文件。你需要理解：

1
2
3
4
5
6
7

用户浏览器 / curl
  -> 访问服务器 IP 或域名
  -> 请求进入服务器端口
  -> Nginx master/worker 进程接收连接
  -> 根据 nginx.conf 匹配 server/location
  -> 返回静态文件或后续阶段转发请求
  -> 写入 access.log / error.log

本阶段完成后，你应该具备下面能力：

• 能在 Linux 服务器上独立安装并启动 Nginx。
• 能说清 Nginx 是什么、适合做什么、不适合做什么。
• 能理解 Nginx 的典型目录、配置文件、日志文件和运行用户。
• 能读懂最小可运行的 nginx.conf。
• 能配置一个基础静态站点并通过浏览器或 curl 访问。
• 能使用 nginx -t、systemctl、nginx -s reload 完成基础管理。
• 能排查启动失败、配置错误、端口占用、权限不足、远程访问失败等常见问题。

2. 学习边界

第一阶段只解决“单机部署与基础认知”，不要过早扩展到复杂代理、负载均衡、HTTPS、缓存、限流和源码。

2.1 本阶段重点

• Nginx 的角色定位。
• Nginx 与 Apache、Tomcat、Spring Boot 内置 Web 容器的区别。
• 包管理器安装 Nginx。
• 源码编译安装 Nginx。
• Nginx 目录结构。
• 主配置文件结构。
• master/worker 进程模型。
• systemd 服务管理。
• 静态资源访问。
• 基础日志查看。
• 基础命令使用。
• 常见入门故障排查。

2.2 本阶段暂不深入

下面内容后续阶段再系统学习：

• server_name 的复杂匹配规则。
• location 的优先级细节。
• rewrite 和变量体系。
• proxy_pass 反向代理细节。
• upstream 负载均衡算法。
• HTTPS、HTTP/2、证书续期。
• gzip、brotli、缓存和性能调优。
• 限流、限并发、访问控制。
• 高可用、灰度发布、热升级。
• Nginx 源码和模块开发。

3. Nginx 是什么

Nginx，读作 Engine X，是一个高性能的 HTTP Server、反向代理服务器、负载均衡器和通用 TCP/UDP 代理服务器。

在常见互联网架构中，Nginx 通常位于流量入口层：

1
2
3
4
5

用户
  -> DNS
  -> 公网 IP / 负载均衡
  -> Nginx
  -> 静态资源 / 后端服务 / 应用集群

Nginx 最常见的使用场景包括：

第一阶段先重点掌握“静态资源服务器”和“单机 HTTP 服务”两个基础角色。

4. Nginx 的核心特点

4.1 高并发能力强

Nginx 采用事件驱动、异步非阻塞 IO 和 master/worker 多进程模型。相比一个连接一个线程的传统模型，Nginx 可以用较少进程处理大量并发连接。

简化理解：

1
2

传统线程模型：一个请求 -> 一个线程 -> 阻塞等待 IO
Nginx 事件模型：一个 worker -> 监听大量连接 -> 有事件就处理 -> 没事件不阻塞等待

这也是 Nginx 适合作为入口层和静态资源服务的关键原因。

4.2 配置清晰

Nginx 以配置文件为核心，典型配置结构是：

1
2
3
4
5

main
  events
  http
    server
      location

这种结构非常适合描述 HTTP 服务的层级关系。

4.3 资源占用低

Nginx 通常使用少量 worker 进程即可处理较高并发。相比传统应用服务器，它在静态资源、连接保持、请求转发等场景中资源消耗更低。

4.4 模块化能力强

Nginx 由核心框架加模块组成。常见能力如 HTTP、SSL、gzip、rewrite、proxy、stream 等都来自模块。可以通过下面命令查看当前 Nginx 编译了哪些模块：

1

nginx -V

输出中重点关注：--prefix、--conf-path、--sbin-path、--modules-path、--with-http_ssl_module、--with-http_v2_module、--with-stream、--with-pcre、--with-zlib、--with-openssl。

5. Nginx 与常见 Web 组件对比

5.1 Nginx 与 Apache

5.2 Nginx 与 Tomcat

典型架构：用户 -> Nginx -> Tomcat / Spring Boot。

5.3 Nginx 与 Spring Boot 内置 Web 容器

Spring Boot 内置 Tomcat、Jetty 或 Undertow，可以直接监听端口提供 HTTP 服务。Nginx 通常放在 Spring Boot 前面，承担统一域名入口、HTTPS 证书卸载、静态资源服务、反向代理、访问日志、超时控制以及后续负载均衡和限流职责。Spring Boot 则负责业务接口、业务逻辑、数据库访问、权限认证和事务处理。

6. 实验环境准备

6.1 推荐系统

6.2 推荐机器配置

6.3 必备命令

1
2
3
4
5

curl --version
wget --version
systemctl --version
ss --version
ps --version

7. 安装方式总览

Nginx 常见安装方式有三种：

第一阶段建议两种方式都做一遍：

1. 先用包管理器安装，快速跑起来。
2. 再用源码编译安装，理解目录、模块和编译参数。

8. 使用包管理器安装 Nginx

8.1 Ubuntu / Debian 安装

更新软件源：

1

sudo apt update

安装 Nginx：

1

sudo apt install -y nginx

查看版本：

1

nginx -v

查看编译参数：

1

nginx -V

启动服务：

1

sudo systemctl start nginx

设置开机自启：

1

sudo systemctl enable nginx

查看状态：

1

sudo systemctl status nginx

浏览器访问：

1

http://服务器IP/

或者使用 curl：

1
2

curl -I http://127.0.0.1/
curl http://127.0.0.1/

8.2 Rocky Linux / AlmaLinux / CentOS Stream 安装

安装 EPEL 或启用系统仓库后安装：

1

sudo dnf install -y nginx

如果系统使用 yum：

1

sudo yum install -y nginx

启动服务：

1
2

sudo systemctl start nginx
sudo systemctl enable nginx

查看状态：

1

sudo systemctl status nginx

查看监听端口：

1

sudo ss -lntp | grep nginx

访问测试：

1

curl -I http://127.0.0.1/

8.3 防火墙放行 HTTP

如果本机能访问 127.0.0.1，但远程浏览器访问不了服务器 IP，常见原因是防火墙或云安全组未放行。

Ubuntu 常见 ufw：

1
2
3

sudo ufw status
sudo ufw allow 80/tcp
sudo ufw reload

Rocky / CentOS 常见 firewalld：

1
2
3
4

sudo firewall-cmd --state
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --reload

云服务器还需要检查云厂商安全组：

• 入方向放行 TCP 80。
• 如果后续使用 HTTPS，放行 TCP 443。
• 如果测试自定义端口，例如 8088，也要放行对应端口。

9. 使用源码编译安装 Nginx

源码编译不是第一阶段生产必备能力，但非常适合用来理解 Nginx 的组成、模块和安装路径。

9.1 安装编译依赖

Ubuntu / Debian：

1
2

sudo apt update
sudo apt install -y build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev openssl libssl-dev wget tar

Rocky / AlmaLinux / CentOS Stream：

1
2

sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y pcre pcre-devel zlib zlib-devel openssl openssl-devel wget tar

9.2 下载源码

建议进入 /usr/local/src：

1
2
3
4

cd /usr/local/src
sudo wget https://nginx.org/download/nginx-1.26.2.tar.gz
sudo tar -zxf nginx-1.26.2.tar.gz
cd nginx-1.26.2

说明：版本号可按实际情况替换。生产环境选择版本时应优先选择官方稳定版。

9.3 配置编译参数

示例编译参数：

1
2
3
4
5
6
7
8
9
10
11
12
13

sudo ./configure \
  --prefix=/usr/local/nginx \
  --sbin-path=/usr/local/nginx/sbin/nginx \
  --conf-path=/usr/local/nginx/conf/nginx.conf \
  --pid-path=/usr/local/nginx/logs/nginx.pid \
  --lock-path=/usr/local/nginx/logs/nginx.lock \
  --error-log-path=/usr/local/nginx/logs/error.log \
  --http-log-path=/usr/local/nginx/logs/access.log \
  --with-http_ssl_module \
  --with-http_v2_module \
  --with-http_gzip_static_module \
  --with-http_stub_status_module \
  --with-stream

常见参数解释：

9.4 编译与安装

1
2

sudo make
sudo make install

查看安装目录：

1
2
3

ls -lah /usr/local/nginx
ls -lah /usr/local/nginx/conf
ls -lah /usr/local/nginx/sbin

查看版本与编译参数：

1
2

/usr/local/nginx/sbin/nginx -v
/usr/local/nginx/sbin/nginx -V

9.5 启动源码安装版 Nginx

检查配置：

1

sudo /usr/local/nginx/sbin/nginx -t

启动：

1

sudo /usr/local/nginx/sbin/nginx

查看进程：

1

ps -ef | grep nginx

访问：

1

curl -I http://127.0.0.1/

停止：

1

sudo /usr/local/nginx/sbin/nginx -s stop

优雅退出：

1

sudo /usr/local/nginx/sbin/nginx -s quit

重新加载配置：

1

sudo /usr/local/nginx/sbin/nginx -s reload

10. Nginx 典型目录结构

包管理器安装和源码安装的路径不同，但核心文件类型是一致的。

10.1 包管理器安装常见路径

Ubuntu / Debian 常见路径：

Rocky / CentOS 常见路径：

10.2 源码安装常见路径

如果使用前文参数安装：

10.3 路径差异的本质

路径不同并不影响 Nginx 的核心工作方式。真正需要掌握的是：

1
2
3
4
5
6

nginx 可执行文件在哪里
nginx.conf 主配置文件在哪里
静态资源 root 目录在哪里
access.log / error.log 在哪里
pid 文件在哪里
systemd 是否接管服务管理

使用下面命令可以快速定位当前 Nginx 的真实编译路径：

1

nginx -V 2>&1 | tr ' ' '\n' | grep -- '--.*path\|--prefix'

如果系统里存在多个 Nginx，一定要确认当前执行的是哪一个：

1
2
3

which nginx
whereis nginx
ps -ef | grep nginx

11. Nginx 主配置文件结构

一个最小化的 nginx.conf 通常包含下面结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

user nginx;
worker_processes auto;

error_log /var/log/nginx/error.log warn;
pid /run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    access_log /var/log/nginx/access.log;

    sendfile on;
    keepalive_timeout 65;

    server {
        listen 80;
        server_name localhost;

        location / {
            root /usr/share/nginx/html;
            index index.html index.htm;
        }
    }
}

11.1 main 全局块

main 不是显式写出来的块，而是配置文件最外层上下文。

11.2 events 块

events 块定义连接处理相关参数。

1
2
3

events {
    worker_connections 1024;
}

粗略最大连接能力可以这样理解：

1

理论连接上限 ≈ worker_processes × worker_connections

但真实上限还受操作系统文件描述符限制、CPU、内存、网络带宽、后端能力、keepalive、反向代理上游连接等因素影响。

11.3 http 块

http 块是 HTTP 服务的核心上下文，绝大多数 Web 配置都写在这里或其子块中。

11.4 server 块

server 块表示一个虚拟主机，可以理解成一个站点或一个监听入口。

1
2
3
4
5
6
7
8
9

server {
    listen 80;
    server_name example.com;

    location / {
        root /data/www/example;
        index index.html;
    }
}

第一阶段先掌握：一个 server 可以监听一个端口，也可以配置一个域名入口。

11.5 location 块

location 块用于匹配 URI 路径，并决定如何处理请求。

1
2
3
4

location / {
    root /usr/share/nginx/html;
    index index.html;
}

请求 GET /index.html，如果 root 是 /usr/share/nginx/html，最终查找文件就是 /usr/share/nginx/html/index.html。

第一阶段只需要掌握最基础的前缀匹配。复杂优先级留到第二阶段。

12. 基础指令详解

12.1 user

1

user nginx;

user 指定 worker 进程使用哪个系统用户运行。master 进程通常由 root 启动，worker 会切换到普通用户以降低安全风险。

查看进程用户：

1

ps -eo user,pid,ppid,cmd | grep nginx

常见现象：

1
2
3

root      1001     1 nginx: master process nginx
nginx     1002  1001 nginx: worker process
nginx     1003  1001 nginx: worker process

12.2 worker_processes

1

worker_processes auto;

入门建议使用 auto。

12.3 worker_connections

1
2
3

events {
    worker_connections 1024;
}

表示每个 worker 最大连接数。注意它不是整个 Nginx 的总连接数，而是单个 worker 的连接上限。

12.4 pid

1

pid /run/nginx.pid;

pid 文件记录 master 进程 ID。执行 reload、stop、quit 时，Nginx 会根据 pid 找到 master 进程并发送信号。

1
2

cat /run/nginx.pid
ps -p $(cat /run/nginx.pid) -o pid,ppid,cmd

12.5 error_log

1

error_log /var/log/nginx/error.log warn;

错误日志用于记录启动错误、配置问题、权限问题、连接失败、上游错误等信息。

入门阶段建议使用 warn 或 error。

12.6 access_log

1

access_log /var/log/nginx/access.log;

访问日志记录每一次 HTTP 请求的访问信息，例如客户端 IP、请求时间、URI、状态码、响应大小等。

1
2

sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

12.7 include

1

include /etc/nginx/conf.d/*.conf;

include 用于引入其他配置文件，核心作用是拆分配置，避免所有内容都堆在一个 nginx.conf 中。

1
2
3
4

/etc/nginx/nginx.conf
/etc/nginx/conf.d/default.conf
/etc/nginx/conf.d/site-a.conf
/etc/nginx/conf.d/site-b.conf

注意：被 include 的文件内容会被放入当前位置解析；子配置必须放在正确上下文中，例如 server 应该放在 http 内。

12.8 root

1
2
3

location / {
    root /data/www;
}

root 表示静态资源根目录。Nginx 会将 root 与 URI 拼接成真实文件路径。

1
2
3

root /data/www;
URI  /images/logo.png;
最终文件 /data/www/images/logo.png

12.9 index

1

index index.html index.htm;

index 表示访问目录时默认查找的首页文件。例如访问 http://example.com/，Nginx 会尝试查找 root目录/index.html 和 root目录/index.htm。

13. master/worker 进程模型

Nginx 采用 master/worker 多进程模型。

1
2
3
4

master process
  ├── worker process
  ├── worker process
  └── worker process

13.1 master 进程职责

master 进程主要负责管理，不直接处理普通 HTTP 请求。

职责包括：

• 读取和校验配置。
• 绑定监听端口。
• 创建 worker 进程。
• 接收 reload、stop、quit 等信号。
• 管理 worker 生命周期。
• 平滑重载配置。
• 处理日志重新打开。

13.2 worker 进程职责

worker 进程负责实际处理客户端连接和 HTTP 请求。

职责包括：

• 接收客户端连接。
• 读取 HTTP 请求。
• 匹配 server/location。
• 读取静态文件。
• 返回 HTTP 响应。
• 写入访问日志。
• 后续阶段还会负责代理 upstream。

13.3 查看进程

1

ps -ef | grep nginx

常见输出：

1
2
3

root       1001      1  0 10:00 ?  00:00:00 nginx: master process /usr/sbin/nginx
nginx      1002   1001  0 10:00 ?  00:00:00 nginx: worker process
nginx      1003   1001  0 10:00 ?  00:00:00 nginx: worker process

更清晰的树形查看：

1

pstree -p | grep nginx

如果没有 pstree，可以安装：

1
2
3

sudo apt install -y psmisc
# 或
sudo dnf install -y psmisc

13.4 reload 时发生了什么

执行：

1

sudo nginx -s reload

或：

1

sudo systemctl reload nginx

大致过程：

1
2
3
4
5
6

1. master 收到 reload 信号
2. master 检查新配置语法
3. 如果配置错误，继续使用旧配置
4. 如果配置正确，启动新的 worker
5. 新 worker 使用新配置接收新请求
6. 旧 worker 处理完已有连接后退出

这就是 Nginx reload 通常不会中断已有请求的原因。

注意：

• reload 不是 restart。
• reload 不会强制杀死正在处理请求的旧 worker。
• 如果配置错误，reload 会失败，但旧 worker 通常继续工作。
• 修改监听端口、证书、日志路径等配置后，都应先 nginx -t 再 reload。

14. systemd 管理 Nginx

多数现代 Linux 发行版使用 systemd 管理服务。

14.1 常用命令

14.2 reload 与 restart 区别

生产环境修改配置通常流程：

1
2
3

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl status nginx

不要养成“改完配置直接 restart”的习惯。

14.3 journalctl 查看服务日志

查看最近日志：

1

sudo journalctl -u nginx -n 50

持续跟踪：

1

sudo journalctl -u nginx -f

查看本次启动后的日志：

1

sudo journalctl -u nginx -b

15. nginx 命令行用法

15.1 查看版本

1

nginx -v

输出示例：

1

nginx version: nginx/1.26.2

15.2 查看编译参数

1

nginx -V

这个命令非常重要，能确认当前 Nginx 的模块和路径。

建议学习时重点观察：

1
2
3
4
5
6
7
8
9
10

configure arguments:
--prefix=...
--sbin-path=...
--conf-path=...
--error-log-path=...
--http-log-path=...
--pid-path=...
--with-http_ssl_module
--with-http_v2_module
--with-stream

15.3 检查配置

1

sudo nginx -t

配置正确时：

1
2

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

配置错误时，Nginx 会指出错误文件和行号，例如：

1
2

nginx: [emerg] unexpected "}" in /etc/nginx/conf.d/test.conf:12
nginx: configuration file /etc/nginx/nginx.conf test failed

15.4 指定配置文件检查

1

sudo nginx -t -c /etc/nginx/nginx.conf

源码安装版：

1

sudo /usr/local/nginx/sbin/nginx -t -c /usr/local/nginx/conf/nginx.conf

15.5 发送信号

1
2
3
4

sudo nginx -s reload
sudo nginx -s stop
sudo nginx -s quit
sudo nginx -s reopen

15.6 打印配置文件内容

部分版本支持：

1

sudo nginx -T

nginx -T 会测试配置，并输出完整配置，包括 include 后的内容。它很适合排查“实际加载了哪些配置”。

注意：输出中可能包含证书路径、内部域名等敏感信息，生产环境复制给他人前要脱敏。

16. 第一个静态站点实验

16.1 创建站点目录

1

sudo mkdir -p /data/www/stage01

创建首页：

1
2
3
4
5
6
7
8
9
10
11
12
13

cat <<'EOF' | sudo tee /data/www/stage01/index.html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>Nginx Stage 01</title>
</head>
<body>
  <h1>Nginx Stage 01 OK</h1>
  <p>单机部署与基础认知实验成功。</p>
</body>
</html>
EOF

设置权限：

1

sudo chmod -R 755 /data/www/stage01

如果 worker 用户是 nginx 或 www-data，需要确保它能读取该目录。检查目录权限：

1

namei -l /data/www/stage01/index.html

16.2 新增 server 配置

创建配置文件：

1

sudo vi /etc/nginx/conf.d/stage01.conf

写入：

1
2
3
4
5
6
7
8
9
10
11
12

server {
    listen 8088;
    server_name _;

    access_log /var/log/nginx/stage01.access.log;
    error_log  /var/log/nginx/stage01.error.log warn;

    location / {
        root /data/www/stage01;
        index index.html;
    }
}

16.3 检查并加载配置

1
2

sudo nginx -t
sudo systemctl reload nginx

如果是源码安装版：

1
2

sudo /usr/local/nginx/sbin/nginx -t
sudo /usr/local/nginx/sbin/nginx -s reload

16.4 本机访问验证

1
2

curl -I http://127.0.0.1:8088/
curl http://127.0.0.1:8088/

预期状态码：HTTP/1.1 200 OK，预期正文包含 Nginx Stage 01 OK。

16.5 远程访问验证

从宿主机或另一台机器访问：

1

curl -I http://服务器IP:8088/

如果访问失败，按顺序检查：Nginx 是否启动、是否监听 8088、服务器防火墙是否放行、云安全组是否放行、服务器 IP 是否正确、是否存在 SELinux 权限限制。

查看监听端口：

1

sudo ss -lntp | grep 8088

17. 默认站点与自定义站点

包管理器安装后通常会有默认站点。常见默认配置可能在：

1
2

/etc/nginx/conf.d/default.conf
/etc/nginx/sites-enabled/default

默认首页可能在：

1
2

/usr/share/nginx/html/index.html
/var/www/html/index.nginx-debian.html

17.1 修改默认首页

1
2

echo 'Hello Nginx' | sudo tee /usr/share/nginx/html/index.html
curl http://127.0.0.1/

17.2 不建议直接删除默认配置

学习阶段可以保留默认配置，然后新增自己的 stage01.conf。这样便于对比默认 80 端口站点和自定义 8088 端口站点。

如果需要禁用默认站点，建议先备份：

1
2
3
4

sudo cp /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bak
sudo mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.disabled
sudo nginx -t
sudo systemctl reload nginx

Debian 系如果使用 sites-enabled：

1
2
3

sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

18. 日志基础

Nginx 最重要的两个日志是：

1
2

access.log 访问日志
error.log  错误日志

18.1 access.log

访问日志示例：

1

192.168.1.10 - - [11/Jul/2026:10:20:30 +0800] "GET / HTTP/1.1" 200 220 "-" "curl/8.0.1"

实时观察访问日志：

1

sudo tail -f /var/log/nginx/access.log

发起请求：

1

curl http://127.0.0.1/

观察日志是否新增。

18.2 error.log

错误日志用于排查问题。常见错误包括：

查看错误日志：

1
2

sudo tail -n 100 /var/log/nginx/error.log
sudo tail -f /var/log/nginx/error.log

18.3 为站点单独配置日志

1
2
3
4
5
6
7
8
9
10
11
12

server {
    listen 8088;
    server_name _;

    access_log /var/log/nginx/stage01.access.log;
    error_log  /var/log/nginx/stage01.error.log warn;

    location / {
        root /data/www/stage01;
        index index.html;
    }
}

这样不同站点日志更清晰，便于排查。

19. HTTP 基础认知

Nginx 是 HTTP Server，因此需要掌握最基础的 HTTP 概念。

19.1 请求报文

一个 HTTP 请求大致包含请求行、请求头、空行和请求体。

1
2
3
4

GET /index.html HTTP/1.1
Host: example.com
User-Agent: curl/8.0.1
Accept: */*

19.2 响应报文

一个 HTTP 响应大致包含状态行、响应头、空行和响应体。

1
2
3
4

HTTP/1.1 200 OK
Server: nginx
Content-Type: text/html
Content-Length: 220

19.3 常见状态码

第一阶段重点排查：200、403、404。

19.4 curl 常用方法

1
2
3
4
5

curl -I http://127.0.0.1/
curl -v http://127.0.0.1/
curl -H 'Host: example.com' http://127.0.0.1/
curl http://127.0.0.1:8088/
curl -o index.html http://127.0.0.1/

20. 配置文件拆分建议

第一阶段可以采用简单清晰的拆分方式。

主配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# /etc/nginx/nginx.conf
user nginx;
worker_processes auto;

error_log /var/log/nginx/error.log warn;
pid /run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    access_log /var/log/nginx/access.log;

    sendfile on;
    keepalive_timeout 65;

    include /etc/nginx/conf.d/*.conf;
}

站点配置：

1
2
3
4
5
6
7
8
9
10

# /etc/nginx/conf.d/stage01.conf
server {
    listen 8088;
    server_name _;

    location / {
        root /data/www/stage01;
        index index.html;
    }
}

建议：nginx.conf 保留全局配置；每个站点单独一个 conf.d/*.conf 文件；文件名要能表达用途；修改前先备份；修改后必须执行 nginx -t。

21. 基础排障方法论

排查 Nginx 问题不要靠猜，按链路逐层确认。

21.1 总体排查链路

1
2
3
4
5
6
7
8
9
10

服务是否运行
  -> 配置是否正确
  -> 端口是否监听
  -> 本机是否能访问
  -> 远程网络是否通
  -> 防火墙/安全组是否放行
  -> URI 是否匹配正确
  -> 文件是否存在
  -> 权限是否允许
  -> error.log 是否有明确错误

21.2 服务启动失败

查看状态：

1

sudo systemctl status nginx

检查配置：

1

sudo nginx -t

查看系统日志：

1

sudo journalctl -u nginx -n 100

查看错误日志：

1

sudo tail -n 100 /var/log/nginx/error.log

21.3 端口占用

1
2

sudo ss -lntp | grep ':80'
sudo ss -lntp | grep ':8088'

如果端口被占用，可以停止占用端口的服务、修改 Nginx listen 端口，或确认是否启动了两个不同路径的 Nginx。源码安装版和包管理器安装版可能同时存在，导致端口冲突。

21.4 本机可访问，远程不可访问

本机测试：

1

curl -I http://127.0.0.1:8088/

服务器 IP 测试：

1

curl -I http://服务器IP:8088/

远程机器测试：

1

curl -I http://服务器IP:8088/

21.5 403 Forbidden

常见原因：访问的是目录但目录中没有 index.html、Nginx worker 用户没有读取权限、上级目录没有执行权限、SELinux 阻止访问，或配置了 deny 访问控制。

排查命令：

1
2
3

sudo tail -n 50 /var/log/nginx/error.log
ls -lah /data/www/stage01
namei -l /data/www/stage01/index.html

修复示例：

1

sudo chmod -R 755 /data/www/stage01

如果是 SELinux 环境，可以先查看状态：

1

getenforce

学习阶段如果确认是 SELinux 导致，可临时验证：

1

sudo setenforce 0

注意：生产环境不要简单粗暴关闭 SELinux，应配置正确上下文。

21.6 404 Not Found

常见原因：URI 对应文件不存在、root 配置错误、文件名大小写不一致、配置未 reload，或请求进入了另一个 server。

排查方法：

1
2
3

sudo nginx -T | grep -n "stage01\|root\|listen"
ls -lah /data/www/stage01
curl -v http://127.0.0.1:8088/

理解 root 拼接规则非常重要：

1
2
3

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

请求 /index.html 时查找：

1

/data/www/stage01/index.html

21.7 配置改了不生效

排查顺序：是否修改了正确文件、是否执行 nginx -t、是否执行 reload、reload 是否成功、是否有多个 Nginx 实例、请求是否进入目标 server、浏览器是否有缓存。

1
2
3
4
5

which nginx
nginx -V
sudo nginx -T | less
ps -ef | grep nginx
sudo systemctl status nginx

21.8 日志没有写入

常见原因：请求没有进入该 server、配置了单独日志但看错文件、日志目录不存在、worker 用户没有写权限、日志文件被删除后未执行 reopen 或 reload。

1
2
3

sudo nginx -T | grep -n "access_log\|error_log"
sudo ls -lah /var/log/nginx
sudo nginx -s reopen

22. 常见错误配置示例

22.1 少写分号

错误：

1

worker_processes auto

正确：

1

worker_processes auto;

Nginx 指令通常以分号结尾，块结构以 {} 包裹。

22.2 server 写在错误位置

错误：

1
2
3

server {
    listen 80;
}

如果它写在 main 最外层，就会报错。

正确：

1
2
3
4
5

http {
    server {
        listen 80;
    }
}

如果 nginx.conf 中已经有：

1
2
3

http {
    include /etc/nginx/conf.d/*.conf;
}

则 conf.d/*.conf 中可以直接写 server。

22.3 root 路径理解错误

配置：

1
2
3

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

请求：

1

/static/app.js

实际文件路径：

1

/data/www/static/app.js

很多新手误以为是 /data/www/app.js，这个差异在后续学习 alias 时会更重要。

22.4 修改配置后直接 restart

不推荐：

1

sudo systemctl restart nginx

推荐：

1
2

sudo nginx -t
sudo systemctl reload nginx

22.5 没看 error.log

很多问题 curl 只能看到状态码，真正原因在 error.log。

1

sudo tail -n 100 /var/log/nginx/error.log

23. 第一阶段必做实验清单

实验 1：包管理器安装 Nginx

目标：快速安装并启动 Nginx。

1
2
3
4
5

sudo apt update
sudo apt install -y nginx
sudo systemctl start nginx
sudo systemctl enable nginx
curl -I http://127.0.0.1/

验收：systemctl status nginx 显示 running；curl -I 返回 200 或默认欢迎页相关状态；能找到 nginx.conf、access.log、error.log。

实验 2：查看编译参数

目标：理解当前 Nginx 的安装路径和模块。

1
2

nginx -v
nginx -V

验收：能找到 --conf-path、--error-log-path，并能说明是否启用了 http_ssl_module。

实验 3：源码编译安装 Nginx

目标：理解源码安装流程和目录。

1
2
3
4
5
6
7
8

cd /usr/local/src
sudo wget https://nginx.org/download/nginx-1.26.2.tar.gz
sudo tar -zxf nginx-1.26.2.tar.gz
cd nginx-1.26.2
sudo ./configure --prefix=/usr/local/nginx --with-http_ssl_module --with-http_stub_status_module
sudo make
sudo make install
sudo /usr/local/nginx/sbin/nginx -V

验收：/usr/local/nginx 目录存在；能启动源码安装版 Nginx；能说明源码安装版和包管理器安装版路径差异。

实验 4：配置自定义静态站点

目标：新增一个监听 8088 的静态站点。

1
2
3
4
5
6

sudo mkdir -p /data/www/stage01
echo 'Nginx Stage 01 OK' | sudo tee /data/www/stage01/index.html
sudo vi /etc/nginx/conf.d/stage01.conf
sudo nginx -t
sudo systemctl reload nginx
curl http://127.0.0.1:8088/

配置：

1
2
3
4
5
6
7
8
9

server {
    listen 8088;
    server_name _;

    location / {
        root /data/www/stage01;
        index index.html;
    }
}

验收：curl http://127.0.0.1:8088/ 返回 Nginx Stage 01 OK；ss -lntp 能看到 8088 监听；access.log 有访问记录。

实验 5：故意写错配置并排查

目标：熟悉 nginx -t 报错。

1
2
3
4

server {
    listen 8089
    server_name _;
}

执行：

1

sudo nginx -t

验收：能根据报错找到具体文件和行号，并能修复错误后通过 nginx -t。

实验 6：观察 reload 前后 worker 变化

目标：理解平滑重载。

1
2
3
4

ps -ef | grep nginx
sudo nginx -t
sudo systemctl reload nginx
ps -ef | grep nginx

验收：能识别 master 进程、worker 进程，并能说明 reload 会生成新 worker，旧 worker 平滑退出。

实验 7：排查远程访问失败

目标：掌握基础网络排查。

1
2
3
4
5

curl -I http://127.0.0.1:8088/
sudo ss -lntp | grep 8088
sudo firewall-cmd --list-all
# 或
sudo ufw status

验收：能判断是 Nginx 未监听、系统防火墙、云安全组还是访问地址错误。

24. 第一阶段命令速查表

25. 第一阶段知识检查

完成学习后，尝试回答下面问题。

25.1 基础概念

1. Nginx 是什么？常见使用场景有哪些？
2. Nginx 和 Tomcat 的定位有什么区别？
3. 为什么 Nginx 适合作为静态资源服务器？
4. 为什么 Nginx 能处理较高并发？
5. Nginx 在典型 Web 架构中通常放在哪一层？

25.2 安装与目录

1. 包管理器安装和源码安装有什么区别？
2. 如何查看当前 Nginx 的配置文件路径？
3. /etc/nginx/nginx.conf 的作用是什么？
4. /var/log/nginx/access.log 和 /var/log/nginx/error.log 分别记录什么？
5. 如何判断系统中是否有多个 Nginx？

25.3 配置结构

1. main、events、http、server、location 分别是什么？
2. worker_processes 和 worker_connections 有什么区别？
3. include 的作用是什么？
4. root 如何和 URI 拼接成文件路径？
5. 修改配置后为什么要先执行 nginx -t？

25.4 进程与管理

1. master 进程负责什么？
2. worker 进程负责什么？
3. reload 和 restart 有什么区别？
4. stop 和 quit 有什么区别？
5. nginx -s reopen 常用于什么场景？

25.5 排障能力

1. Nginx 启动失败应该先看什么？
2. 端口占用如何排查？
3. 本机能访问，远程不能访问，可能是什么原因？
4. 403 常见原因有哪些？
5. 404 常见原因有哪些？

26. 第一阶段过关标准

达到下面标准，才算真正完成第一阶段。

26.1 操作能力

• 能独立使用包管理器安装 Nginx。
• 能独立源码编译安装 Nginx。
• 能启动、停止、重载 Nginx。
• 能设置 Nginx 开机自启。
• 能配置一个自定义端口的静态站点。
• 能通过浏览器和 curl 验证访问结果。

26.2 配置理解

• 能说明 nginx.conf 的基本层级结构。
• 能解释 events、http、server、location 的作用。
• 能解释 user、worker_processes、worker_connections、pid 的作用。
• 能解释 access_log、error_log 的作用。
• 能理解 include 如何拆分配置。

26.3 进程理解

• 能区分 master 和 worker。
• 能通过 ps 查看 Nginx 进程。
• 能解释 reload 的基本过程。
• 能判断 Nginx 是否正常监听端口。

26.4 排障能力

• 能根据 nginx -t 修复语法错误。
• 能根据 systemctl status 和 journalctl 判断服务状态。
• 能根据 ss 判断端口监听和占用。
• 能根据 access.log 和 error.log 定位基础访问问题。
• 能排查 403、404、端口占用、防火墙和权限问题。

27. 推荐练习顺序

建议严格按照下面顺序练习：

1
2
3
4
5
6
7
8
9
10
11
12

认识 Nginx 定位
  -> 包管理器安装
  -> 查看目录和配置
  -> 启停和 systemd 管理
  -> 修改默认首页
  -> 新增自定义静态站点
  -> 查看 access.log / error.log
  -> 故意制造配置错误
  -> 故意制造 403 / 404
  -> 源码编译安装
  -> 对比两种安装方式
  -> 总结排障流程

不要一边学第一阶段，一边跳到反向代理和 HTTPS。基础命令、目录、配置结构和日志排查熟练后，后续阶段会轻松很多。

28. 学习笔记模板

建议每次实验按下面格式记录：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

## 实验名称

### 实验目标

### 环境信息

- 操作系统：
- Nginx 版本：
- 安装方式：
- 配置文件路径：

### 操作步骤

### 关键配置

### 验证命令

### 现象与结果

### 遇到的问题

### 排查过程

### 最终结论

这样可以把零散命令沉淀为自己的经验库。

29. 本阶段常见误区

• 只会执行 apt install nginx，不知道配置文件在哪里。
• 修改配置后不执行 nginx -t。
• 把 reload 和 restart 混为一谈。
• 不看 error.log，只看浏览器报错页面。
• 看到 403 就以为 Nginx 坏了，忽略文件权限和 index 文件。
• 看到 404 就以为服务没启动，忽略 root 路径拼接。
• 不区分包管理器安装和源码安装路径。
• 同时启动两个 Nginx，导致端口冲突。
• 云服务器远程访问失败时，只检查 Nginx，不检查安全组。
• 使用 root 用户随意运行服务，不关注 worker 运行用户。

30. 阶段总结

第一阶段的核心是“跑起来、看得懂、会排查”。真正掌握本阶段后，你应该能清楚说明：

1
2
3
4
5
6
7
8
9

Nginx 是什么
Nginx 装在哪里
Nginx 配置在哪里
Nginx 日志在哪里
Nginx 如何启动和重载
Nginx 如何监听端口
Nginx 如何返回静态文件
Nginx master/worker 如何分工
Nginx 访问失败时该看哪些证据

完成本阶段后，再进入第二阶段“配置体系与请求匹配”，重点学习配置上下文、指令继承、server 匹配、location 优先级、rewrite 和变量体系。那时你会从“能跑起来”进入“能写正确配置”的阶段。