Nginx 安装与使用教程

适用于 Ubuntu/Debian 系统，涵盖安装、配置、虚拟主机、反向代理、HTTPS、性能优化等核心场景。

目录

1. Nginx 简介
2. 安装 Nginx
3. 目录结构
4. 基本命令
5. 配置文件详解
6. 静态网站托管
7. 虚拟主机（多站点）
8. 反向代理
9. 负载均衡
10. HTTPS 配置
11. 日志管理
12. 性能优化
13. 常见问题排查

1. Nginx 简介

Nginx（读作 "Engine-X"）是一款高性能的开源软件，主要用途：

核心优势：

• 🚀 高并发：单机轻松支撑数万并发连接
• 💾 低内存：事件驱动架构，每个连接仅几KB内存
• ⚡ 高性能：静态文件处理速度极快
• 🔧 模块化：丰富的官方和第三方模块

2. 安装 Nginx

2.1 方式一：apt 直接安装（最简单）

# 更新软件源
sudo apt update

# 安装 Nginx
sudo apt install nginx -y

# 验证安装
nginx -v
# 输出：nginx version: nginx/1.x.x

# 检查运行状态
sudo systemctl status nginx

⚠️ apt 安装的版本通常不是最新版，但对大多数场景足够用。

2.2 方式二：官方源安装（推荐，获取最新版）

# 安装依赖
sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring -y

# 导入官方签名密钥
curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
  | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

# 添加稳定版源
echo"deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
  http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
  | sudo tee /etc/apt/sources.list.d/nginx.list

# 更新并安装
sudo apt update
sudo apt install nginx -y

# 验证
nginx -v

2.3 方式三：源码编译安装（自定义模块）

# 安装编译依赖
sudo apt install build-essential libpcre3 libpcre3-dev zlib1g-dev \
  libssl-dev libgd-dev libgeoip-dev -y

# 下载源码（以 1.26.2 为例）
cd /usr/local/src
curl -O https://nginx.org/download/nginx-1.26.2.tar.gz
tar xzf nginx-1.26.2.tar.gz
cd nginx-1.26.2

# 配置编译选项
./configure \
  --prefix=/usr/local/nginx \
  --with-http_ssl_module \
  --with-http_v2_module \
  --with-http_realip_module \
  --with-http_gzip_static_module \
  --with-http_stub_status_module \
  --with-stream

# 编译安装
make
sudo make install

# 创建 systemd 服务文件
sudo tee /etc/systemd/system/nginx.service << 'EOF'
[Unit]
Description=Nginx HTTP Server
After=network.target

[Service]
Type=forking
ExecStartPre=/usr/local/nginx/sbin/nginx -t
ExecStart=/usr/local/nginx/sbin/nginx
ExecReload=/usr/local/nginx/sbin/nginx -s reload
ExecStop=/usr/local/nginx/sbin/nginx -s quit
PIDFile=/usr/local/nginx/logs/nginx.pid
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable nginx
sudo systemctl start nginx

2.4 防火墙放行

# UFW 防火墙
sudo ufw allow 80/tcp     # HTTP
sudo ufw allow 443/tcp    # HTTPS

# 或 iptables
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

2.5 验证安装成功

# 方法1：浏览器访问
# 打开 http://你的服务器IP，看到 "Welcome to nginx!" 即成功

# 方法2：命令行验证
curl -I http://localhost
# 应返回 HTTP/1.1 200 OK

3. 目录结构

安装后主要文件位置（apt 安装方式）：

/etc/nginx/
├── nginx.conf              # 主配置文件
├── sites-available/        # 可用站点配置（存放配置文件）
├── sites-enabled/          # 已启用站点（符号链接指向 available）
├── conf.d/                 # 额外配置片段（.conf 结尾自动加载）
├── snippets/               # 可复用的配置片段
├── modules-available/      # 可用模块
└── modules-enabled/        # 已启用模块

/var/log/nginx/
├── access.log              # 访问日志
└── error.log               # 错误日志

/var/www/html/              # 默认网站根目录
/usr/sbin/nginx             # 可执行文件
/lib/systemd/system/nginx.service  # systemd 服务文件

📌 源码安装的路径不同：配置在 /usr/local/nginx/conf/，日志在 /usr/local/nginx/logs/

4. 基本命令

# 启动
sudo systemctl start nginx

# 停止（立即中断所有连接）
sudo systemctl stop nginx

# 优雅停止（处理完当前请求后停止）
sudo nginx -s quit

# 重启（完全停止再启动，会短暂中断服务）
sudo systemctl restart nginx

# 重新加载配置（不中断服务，生产环境首选）
sudo systemctl reload nginx
# 或
sudo nginx -s reload

# 开机自启
sudo systemctl enable nginx

# 取消开机自启
sudo systemctl disable nginx

# 检查配置文件语法（重要！修改配置后务必先检查）
sudo nginx -t

# 查看版本及编译参数
nginx -V

# 查看运行状态
sudo systemctl status nginx

💡 最佳实践：每次修改配置后，先 nginx -t 检查语法，再 nginx -s reload 平滑重载。

5. 配置文件详解

5.1 主配置文件 nginx.conf

# /etc/nginx/nginx.conf

# ===== 全局块 =====
user www-data;              # 运行用户
worker_processes auto;      # 工作进程数（auto = CPU核心数）
error_log /var/log/nginx/error.log warn;  # 错误日志级别
pid /run/nginx.pid;

# 事件块
events {
    worker_connections 1024;    # 单个进程最大连接数
    multi_accept on;            # 一次接受所有新连接
    use epoll;                  # Linux 下使用 epoll 模型
}

# HTTP 块
http {
    # ---------- 基础设置 ----------
    include       mime.types;               # MIME 类型映射
    default_type  application/octet-stream;  # 默认类型

    # ---------- 日志格式 ----------
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';

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

    # ---------- 性能优化 ----------
    sendfile        on;       # 零拷贝传输（静态文件提速）
    tcp_nopush      on;       # 优化数据包发送
    tcp_nodelay     on;       # 禁用 Nagle 算法（低延迟）
    keepalive_timeout 65;     # 长连接超时（秒）
    types_hash_max_size 2048;

    # ---------- Gzip 压缩 ----------
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;         # 小于 1KB 不压缩
    gzip_comp_level 6;            # 压缩级别 1-9
    gzip_types
        text/plain
        text/css
        text/javascript
        application/javascript
        application/json
        application/xml
        image/svg+xml;

    # ---------- 虚拟主机 ----------
    include /etc/nginx/sites-enabled/*;   # 加载站点配置
    include /etc/nginx/conf.d/*.conf;     # 加载额外配置
}

5.2 配置结构层次

全局块（main）        → 影响 Nginx 整体运行
  └─ events 块       → 影响网络连接
  └─ http 块         → HTTP 服务器所有配置
       └─ server 块  → 单个虚拟主机/站点
            └─ location 块 → 特定 URL 路径的规则
  └─ stream 块       → TCP/UDP 代理（四层）

5.3 常用变量速查

6. 静态网站托管

6.1 最简配置

# /etc/nginx/sites-available/mysite

server {
    listen 80;                          # 监听端口
    server_name mysite.com;             # 绑定域名
    root /var/www/mysite;               # 网站根目录
    index index.html index.htm;         # 默认首页

    location / {
        try_files $uri $uri/ =404;      # 找不到文件返回 404
    }
}

6.2 启用站点

# 创建符号链接启用站点
sudo ln -s /etc/nginx/sites-available/mysite /etc/nginx/sites-enabled/

# 检查并重载
sudo nginx -t && sudo nginx -s reload

6.3 创建测试页面

sudo mkdir -p /var/www/mysite

sudo tee /var/www/mysite/index.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
    <title>My Nginx Site</title>
    <style>
        body { font-family: sans-serif; text-align: center; padding: 50px; }
        h1 { color: #009639; }
    </style>
</head>
<body>
    <h1>🎉 Nginx 运行成功！</h1>
    <p>这是你的第一个 Nginx 站点</p>
</body>
</html>
EOF

6.4 SPA 应用支持（Vue/React）

server {
    listen 80;
    server_name app.example.com;
    root /var/www/app/dist;
    index index.html;

    # 所有路径都回退到 index.html（前端路由）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源长缓存
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

7. 虚拟主机（多站点）

Nginx 支持在同一台服务器上托管多个网站。

7.1 基于域名的虚拟主机

# 站点 A
server {
    listen 80;
    server_name site-a.com www.site-a.com;
    root /var/www/site-a;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

# 站点 B
server {
    listen 80;
    server_name site-b.com www.site-b.com;
    root /var/www/site-b;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

7.2 基于端口的虚拟主机

# 端口 8080 的站点
server {
    listen 8080;
    server_name localhost;
    root /var/www/app1;
}

# 端口 9090 的站点
server {
    listen 9090;
    server_name localhost;
    root /var/www/app2;
}

7.3 默认服务器（兜底处理）

# 匹配不到任何 server_name 时的兜底
server {
    listen 80 default_server;
    server_name _;

    return 444;  # 直接关闭连接（拒绝未知域名的访问）
}

8. 反向代理

反向代理是 Nginx 最常用的功能之一，将客户端请求转发给后端服务。

8.1 基础反向代理

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;    # 后端服务地址
        proxy_set_header Host $host;          # 传递原始域名
        proxy_set_header X-Real-IP $remote_addr;        # 传递真实 IP
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;     # 传递协议
    }
}

8.2 不同路径代理到不同服务

server {
    listen 80;
    server_name example.com;

    # /api/ → 后端 API 服务
    location /api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # /admin/ → 后台管理服务
    location /admin/ {
        proxy_pass http://127.0.0.1:9090/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 其他 → 前端静态文件
    location / {
        root /var/www/frontend;
        try_files $uri $uri/ /index.html;
    }
}

8.3 WebSocket 代理

location /ws/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;    # WebSocket 长连接超时
}

8.4 代理超时设置

location /api/ {
    proxy_pass http://127.0.0.1:8080;

    # 连接后端超时
    proxy_connect_timeout 5s;
    # 读取后端响应超时
    proxy_read_timeout 60s;
    # 发送请求到后端超时
    proxy_send_timeout 60s;

    # 后端响应缓冲
    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;
}

8.5 常见后端框架代理示例

# -------- Flask (Gunicorn) --------
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

# -------- Node.js (Express) --------
location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

# -------- Java (Spring Boot) --------
location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Spring Boot 需要的头部
    proxy_set_header X-Forwarded-Port $server_port;
}

# -------- PHP-FPM --------
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

9. 负载均衡

9.1 基础负载均衡

# 定义后端服务器组
upstream backend {
    server 192.168.1.101:8080;
    server 192.168.1.102:8080;
    server 192.168.1.103:8080;
}

server {
    listen 80;
    server_name lb.example.com;

    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

9.2 负载均衡策略

# 加权轮询 — 性能强的机器分配更多请求
upstream backend {
    server 192.168.1.101:8080 weight=5;   # 50% 请求
    server 192.168.1.102:8080 weight=3;   # 30% 请求
    server 192.168.1.103:8080 weight=2;   # 20% 请求
}

# 最少连接 — 适合长连接场景
upstream backend {
    least_conn;
    server 192.168.1.101:8080;
    server 192.168.1.102:8080;
}

# IP 哈希 — 会话保持
upstream backend {
    ip_hash;
    server 192.168.1.101:8080;
    server 192.168.1.102:8080;
}

9.3 健康检查与容错

upstream backend {
    server 192.168.1.101:8080 max_fails=3 fail_timeout=30s;
    server 192.168.1.102:8080 max_fails=3 fail_timeout=30s;
    server 192.168.1.103:8080 backup;   # 备用服务器，其他全挂才启用
}

• max_fails=3：30秒内失败3次标记为不可用
• fail_timeout=30s：标记不可用后30秒再尝试
• backup：备用服务器

10. HTTPS 配置

10.1 使用 Let's Encrypt 免费证书（推荐）

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx -y

# 自动获取证书并配置 Nginx
sudo certbot --nginx -d example.com -d www.example.com

# 自动续期（Certbot 会自动创建定时任务）
sudo certbot renew --dry-run    # 测试续期

10.2 手动配置 HTTPS

server {
    # 监听 443 并启用 HTTP/2
    listen 443 ssl http2;
    server_name example.com;

    # 证书路径
    ssl_certificate     /etc/nginx/ssl/example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;

    # SSL 优化配置
    ssl_protocols TLSv1.2 TLSv1.3;           # 仅允许安全协议
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:
                ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;

    # SSL 会话缓存（减少握手开销）
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # OCSP Stapling（加速证书验证）
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;

    root /var/www/example;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

# HTTP 自动跳转 HTTPS
server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

10.3 自签名证书（测试用）

# 生成自签名证书
sudo mkdir -p /etc/nginx/ssl

sudo openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout /etc/nginx/ssl/selfsigned.key \
  -out /etc/nginx/ssl/selfsigned.crt \
  -subj "/C=CN/ST=Guizhou/L=Anshun/O=MyOrg/CN=localhost"

11. 日志管理

11.1 自定义日志格式

http {
    # 详细日志格式
    log_format detailed '$remote_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent" '
                        'rt=$request_time '
                        'upstream=$upstream_addr '
                        'upstream_time=$upstream_response_time';

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

11.2 按站点分离日志

server {
    server_name site-a.com;
    access_log /var/log/nginx/site-a.access.log;
    error_log  /var/log/nginx/site-a.error.log;
    # ...
}

server {
    server_name site-b.com;
    access_log /var/log/nginx/site-b.access.log;
    error_log  /var/log/nginx/site-b.error.log;
    # ...
}

11.3 日志轮转（logrotate）

Nginx 安装后通常会自动配置 logrotate，配置文件位于：

cat /etc/logrotate.d/nginx

内容类似：

/var/log/nginx/*.log {
    daily                # 每天轮转
    missingok            # 日志文件不存在不报错
    rotate 14            # 保留14天
    compress             # 旧日志压缩
    delaycompress        # 延迟一次再压缩
    notifempty           # 空文件不轮转
    create 0640 www-data adm
    sharedscripts
    postrotate
        [ -f /var/run/nginx.pid ] && kill -USR1 $(cat /var/run/nginx.pid)
    endpostrotate
}

11.4 实时查看日志

# 实时跟踪访问日志
sudo tail -f /var/log/nginx/access.log

# 实时跟踪错误日志
sudo tail -f /var/log/nginx/error.log

# 统计访问量 TOP 10 的 IP
awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -10

# 统计状态码分布
awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -rn

# 统计请求量最多的 URL
awk '{print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -20

12. 性能优化

12.1 Worker 进程优化

# nginx.conf 全局块
worker_processes auto;              # 自动匹配 CPU 核心数
worker_rlimit_nofile 65535;         # 提高文件描述符上限

系统层面也需调整：

# 查看当前限制
ulimit -n

# 临时提高限制
ulimit -n 65535

# 永久修改（添加到 /etc/security/limits.conf）
# *  soft  nofile  65535
# *  hard  nofile  65535

12.2 静态文件缓存

server {
    # 图片缓存 30 天
    location ~* \.(jpg|jpeg|png|gif|ico|svg|webp)$ {
        expires 30d;
        add_header Cache-Control "public, no-transform";
        access_log off;    # 静态资源不打访问日志
    }

    # CSS/JS 缓存 7 天
    location ~* \.(css|js)$ {
        expires 7d;
        add_header Cache-Control "public";
        access_log off;
    }

    # 字体缓存 1 年
    location ~* \.(woff|woff2|ttf|otf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
}

12.3 开启 Brotli 压缩（比 Gzip 更好）

# 安装 Brotli 模块
sudo apt install libnginx-mod-http-brotli-filter libnginx-mod-http-brotli-static -y

http {
    # Brotli 压缩
    brotli on;
    brotli_comp_level 6;
    brotli_types text/plain text/css application/javascript
                 application/json image/svg+xml;
}

12.4 安全头部

server {
    # 防止 MIME 类型嗅探
    add_header X-Content-Type-Options "nosniff" always;

    # 防止点击劫持
    add_header X-Frame-Options "SAMEORIGIN" always;

    # XSS 防护
    add_header X-XSS-Protection "1; mode=block" always;

    # HSTS（强制 HTTPS，仅 HTTPS 站点使用）
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # CSP（内容安全策略）
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'" always;
}

12.5 内核参数优化

# /etc/sysctl.conf 添加以下参数

# 允许TIME_WAIT sockets复用
net.ipv4.tcp_tw_reuse = 1

# 减少FIN_WAIT2超时
net.ipv4.tcp_fin_timeout = 15

# SYN队列长度
net.ipv4.tcp_max_syn_backlog = 65535

# 全连接队列长度
net.core.somaxconn = 65535

# TCP keepalive 时间
net.ipv4.tcp_keepalive_time = 600

# 应用生效
sudo sysctl -p

13. 常见问题排查

13.1 端口被占用

# 查看 80 端口占用
sudo lsof -i :80
# 或
sudo ss -tlnp | grep :80

# 杀死占用进程
sudo kill -9 <PID>

13.2 权限问题

# 确保网站目录权限正确
sudo chown -R www-data:www-data /var/www/mysite
sudo chmod -R 755 /var/www/mysite

# 确保 Nginx 可读证书
sudo chmod 600 /etc/nginx/ssl/*.key
sudo chmod 644 /etc/nginx/ssl/*.crt

13.3 配置语法错误

# 检查语法并显示详细信息
sudo nginx -t

# 常见错误：
# nginx: [emerg] duplicate location "/"  → 重复的 location 块
# nginx: [emerg] unknown directive "xxx"  → 拼写错误或模块未加载
# nginx: [emerg] no port in upstream      → upstream 地址格式错误

13.4 413 Request Entity Too Large

# 增大请求体限制（默认 1MB）
server {
    client_max_body_size 50m;    # 允许上传 50MB 文件
}

13.5 502 Bad Gateway

常见原因：

1. 后端服务未启动 → 检查后端进程是否运行
2. 后端服务崩溃 → 查看后端日志
3. 端口不匹配 → 确认 proxy_pass 地址与后端实际端口一致
4. 防火墙阻挡 → 检查 iptables/安全组规则

# 检查后端服务是否运行
curl http://127.0.0.1:8080/

# 查看错误日志
sudo tail -20 /var/log/nginx/error.log

13.6 504 Gateway Timeout

# 增大后端超时时间
location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_connect_timeout 300s;
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
}

13.7 location 匹配规则速查

优先级从高到低：

1. =      精确匹配        location = /api { ... }
2. ^~     前缀匹配优先    location ^~ /images/ { ... }
3. ~      区分大小写正则   location ~ \.php$ { ... }
4. ~*     不区分大小写正则 location ~* \.(jpg|png)$ { ... }
5. /      普通前缀匹配    location /static/ { ... }

# 精确匹配 —— 最高优先级
location = / {
    # 只匹配 /，不匹配 /index.html
}

# 正则匹配 —— 适合文件扩展名
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    expires 30d;
}

# 前缀匹配 —— 适合目录
location /static/ {
    alias /var/www/static/;
}

# 通用兜底
location / {
    try_files $uri $uri/ /index.html;
}

📌 速查清单