Nginx 安装与使用指南

本文介绍如何在 Debian / Ubuntu 系统上安装 Nginx，并完成基础配置、站点管理、反向代理、静态站点、HTTPS 与常见问题排查。目标是让它成为一份可以直接执行的实用文档，而不是只写“装个 nginx 然后改配置”的简略笔记。

适用场景

部署静态网站
作为反向代理入口
代理 Go / Python / Node / PHP 等后端服务
统一做 HTTPS、压缩、缓存和访问控制
作为 Web 网关承接多个站点

Nginx 是什么

Nginx 是一个高性能的 HTTP 服务器、反向代理和负载均衡器，也可以用于 TCP / UDP 代理。对于 Debian 上的大多数 Web 场景，它最常见的角色是：

静态文件服务器
反向代理入口
TLS 终止层
多站点虚拟主机管理器

安装前准备

先更新软件包索引：

sudo apt update

确认你有 sudo 权限，并且 80/443 端口没有被其他服务占用。

安装 Nginx

Debian 上直接使用系统仓库安装即可：

sudo apt install -y nginx

安装后检查版本：

nginx -v

如果你需要官方 NGINX 仓库的稳定版或主线版，也可以使用 nginx.org 提供的 Debian 仓库；但大多数场景下，Debian 仓库已经足够。

启动服务并设置开机自启

安装完成后，启动 Nginx 并设置开机自启：

sudo systemctl enable nginx
sudo systemctl start nginx

查看状态：

sudo systemctl status nginx

正常情况下应看到 active (running)。

目录结构

Debian 默认的 Nginx 目录结构通常是：

/etc/nginx/nginx.conf
/etc/nginx/sites-available/
/etc/nginx/sites-enabled/
/etc/nginx/snippets/
/var/www/html/
/var/log/nginx/

常见约定：

sites-available 放站点配置源文件
sites-enabled 放启用中的站点软链接
nginx.conf 是主配置入口

这种拆分方式适合多站点管理，也方便回滚。

先做一次配置检查

修改任何配置前后，都建议先测试语法：

sudo nginx -t

如果输出包含 syntax is ok 和 test is successful，说明当前配置语法正确。

默认站点

Debian 安装后通常会带一个默认站点配置，路径一般是：

/etc/nginx/sites-available/default

它通常会通过 sites-enabled 被启用。你可以先保留默认站点，确认 Nginx 正常工作后再替换成自己的站点。

默认页面目录通常是：

/var/www/html/

你可以在这里放一个简单的 index.html 验证静态服务能力。

基础验证

创建一个测试页：

echo "nginx ok" | sudo tee /var/www/html/index.html

然后访问服务器 IP 或域名，如果看到 nginx ok，说明基础静态服务已经正常。

常见站点配置方法

建议给每个站点单独建一个配置文件，例如：

sudo nano /etc/nginx/sites-available/example.com

然后创建软链接启用：

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com

修改完成后重新加载：

sudo nginx -t
sudo systemctl reload nginx

静态站点示例

下面是一个最小可用的静态站点配置：

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

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

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

准备目录：

sudo mkdir -p /var/www/example.com
echo "hello nginx" | sudo tee /var/www/example.com/index.html

反向代理示例

Nginx 最常见的用途之一是把外部请求转发到内部服务。

假设后端服务运行在 127.0.0.1:8080：

server {
    listen 80;
    listen [::]:80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

为什么要设置这些头

Host：后端知道用户访问的是哪个域名
X-Real-IP：后端知道真实客户端 IP
X-Forwarded-For：保留代理链路
X-Forwarded-Proto：后端知道原始协议是 HTTP 还是 HTTPS

如果你的后端需要 WebSocket，还要补充：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

HTTPS 配置

生产环境中，Nginx 通常会承担 TLS 终止。证书可以来自 Let’s Encrypt 或你自己的证书体系。

一个常见结构是：

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    return 301 https://example.com$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name example.com www.example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

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

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

HTTPS 落地原则

HTTP 全站跳转到 HTTPS
证书要覆盖实际访问域名
不要让 www 和非 www 同时返回不同内容，除非你有明确业务设计

负载均衡基础

如果你有多个后端实例，可以在 upstream 中定义：

upstream app_backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
}

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

    location / {
        proxy_pass http://app_backend;
    }
}

如果你使用负载均衡，建议进一步明确：

健康检查策略
超时策略
会话保持是否需要
后端是否支持无状态扩容

常用配置项

以下是经常会用到的指令：

listen：监听端口
server_name：域名匹配
root：站点根目录
index：默认首页
location：路径匹配
try_files：文件存在性检查与回退
proxy_pass：反向代理
proxy_set_header：透传请求头
client_max_body_size：上传大小限制
access_log / error_log：访问和错误日志

上传限制示例

如果你需要允许大文件上传，可以在 server 或 location 中设置：

client_max_body_size 50m;

配置检查与重载

修改配置后，先检查语法：

sudo nginx -t

如果检查通过，再热加载配置：

sudo systemctl reload nginx

如果你想完全重启：

sudo systemctl restart nginx

区别：

reload：平滑加载配置，不中断已有连接
restart：重启服务，会更粗暴

常用管理命令

# 启动
sudo systemctl start nginx

# 停止
sudo systemctl stop nginx

# 重启
sudo systemctl restart nginx

# 查看状态
sudo systemctl status nginx

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

日志查看

默认日志通常在：

/var/log/nginx/access.log
/var/log/nginx/error.log

实时查看：

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

如果站点单独配置了日志文件，也应按站点路径单独查看。

常见问题

1. `nginx -t` 报语法错误

处理顺序：

看报错文件和行号
检查少写的分号或大括号
检查 include 的文件路径是否正确
再执行 nginx -t

2. 80 端口被占用

先看是谁占用了端口：

sudo ss -ltnp | grep ':80'

如果是 Apache、Caddy 或其他服务占用，需要先停掉冲突服务，或者修改 Nginx 监听端口。

3. 访问不到站点

按顺序检查：

DNS 是否指向正确 IP
server_name 是否匹配访问域名
防火墙是否放行 80/443
是否启用了对应站点配置
是否执行了 nginx -t 和 reload

4. 反向代理返回 502

通常说明 Nginx 能收到请求，但后端服务不可用。检查：

后端进程是否在运行
端口是否正确
proxy_pass 地址是否写错
后端是否拒绝了请求
后端应用日志是否有错误

5. 上传失败或返回 413

这通常是 client_max_body_size 太小。增大限制后再重载配置。

6. 改了配置但没生效

先执行：

sudo nginx -t
sudo systemctl reload nginx

如果依然没有生效，检查你修改的文件是否真的被 include 进主配置。

最小可用流程

如果你只是想快速跑通一次，按这个顺序即可：

sudo apt update
sudo apt install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx
sudo nginx -t
sudo mkdir -p /var/www/example.com
echo "hello nginx" | sudo tee /var/www/example.com/index.html
sudo nano /etc/nginx/sites-available/example.com
sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com
sudo nginx -t
sudo systemctl reload nginx

总结

在 Debian 上使用 Nginx 的核心方法是：

直接安装系统仓库的 nginx
用 sites-available 和 sites-enabled 管理站点
修改配置后先 nginx -t
通过 reload 平滑生效
反向代理时正确传递请求头
HTTPS、日志、上传限制和错误排查要一开始就规划好