xiaoshuai
516 lines
11 KiB
Markdown
516 lines
11 KiB
Markdown
---
|
||
name: nginx
|
||
description: Nginx Web 服务器管理 — 站点配置、SSL 证书管理、反向代理、负载均衡、热重载、 Let's Encrypt 自动续期
|
||
---
|
||
|
||
# Nginx 管理助手
|
||
|
||
## 功能概述
|
||
|
||
本 Skill 提供完整的 Nginx 操作能力，包括站点管理、SSL/HTTPS 配置、反向代理、负载均衡、Let's Encrypt 证书管理等。支持直接编辑配置文件并热重载生效。
|
||
|
||
## 系统环境（用户环境）
|
||
|
||
```
|
||
系统：Ubuntu Linux
|
||
Nginx 版本：1.24.0
|
||
配置目录：/etc/nginx/
|
||
主配置：/etc/nginx/nginx.conf
|
||
站点配置：/etc/nginx/sites-available/ (可用) / sites-enabled/ (启用)
|
||
额外配置：/etc/nginx/conf.d/
|
||
SSL 模板：/etc/letsencrypt/options-ssl-nginx.conf
|
||
DH 参数：/etc/letsencrypt/ssl-dhparams.pem
|
||
日志路径：/var/log/nginx/error.log, /var/log/nginx/access.log
|
||
```
|
||
|
||
## 一、基础操作
|
||
|
||
### 查看 Nginx 状态
|
||
|
||
```bash
|
||
# 查看运行状态
|
||
sudo systemctl status nginx
|
||
|
||
# 测试配置语法
|
||
sudo nginx -t
|
||
|
||
# 查看已加载的配置
|
||
sudo nginx -T
|
||
|
||
# 查看版本和编译参数
|
||
nginx -V
|
||
```
|
||
|
||
### 启停管理
|
||
|
||
```bash
|
||
# 启动
|
||
sudo systemctl start nginx
|
||
|
||
# 停止
|
||
sudo systemctl stop nginx
|
||
|
||
# 重启（完全停止再启动）
|
||
sudo systemctl restart nginx
|
||
|
||
# 热重载（加载新配置，不中断连接）
|
||
sudo systemctl reload nginx
|
||
|
||
# 禁用/启用开机自启
|
||
sudo systemctl disable nginx
|
||
sudo systemctl enable nginx
|
||
```
|
||
|
||
## 二、站点管理
|
||
|
||
### 创建新站点
|
||
|
||
**步骤：**
|
||
1. 在 `/etc/nginx/sites-available/` 创建配置文件
|
||
2. 在 `/etc/nginx/sites-enabled/` 创建软链接
|
||
3. 测试配置：`sudo nginx -t`
|
||
4. 重载生效：`sudo systemctl reload nginx`
|
||
|
||
**示例 — 静态网站：**
|
||
```nginx
|
||
server {
|
||
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;
|
||
}
|
||
}
|
||
```
|
||
|
||
**示例 — HTTP 跳转到 HTTPS：**
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name example.com www.example.com;
|
||
return 301 https://$host$request_uri;
|
||
}
|
||
```
|
||
|
||
### 反向代理配置
|
||
|
||
```nginx
|
||
server {
|
||
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;
|
||
|
||
# WebSocket 支持
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
|
||
# 超时设置
|
||
proxy_connect_timeout 60s;
|
||
proxy_send_timeout 60s;
|
||
proxy_read_timeout 60s;
|
||
}
|
||
}
|
||
```
|
||
|
||
### HTTPS + SSL 配置
|
||
|
||
```nginx
|
||
server {
|
||
listen 443 ssl http2;
|
||
server_name example.com www.example.com;
|
||
|
||
# SSL 证书路径（Let's Encrypt）
|
||
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
|
||
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
|
||
|
||
# 使用 Certbot 提供的安全 SSL 配置模板
|
||
include /etc/letsencrypt/options-ssl-nginx.conf;
|
||
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
|
||
|
||
root /var/www/example.com;
|
||
index index.html;
|
||
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 负载均衡
|
||
|
||
```nginx
|
||
upstream backend {
|
||
least_conn; # 最少连接优先
|
||
server 10.0.0.2:8080 weight=3;
|
||
server 10.0.0.3:8080 weight=2;
|
||
server 10.0.0.4:8080 backup; # 备用服务器
|
||
}
|
||
|
||
server {
|
||
listen 80;
|
||
server_name example.com;
|
||
|
||
location / {
|
||
proxy_pass http://backend;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 启用/禁用站点
|
||
|
||
```bash
|
||
# 启用站点（创建软链接）
|
||
sudo ln -s /etc/nginx/sites-available/mysite /etc/nginx/sites-enabled/mysite
|
||
|
||
# 禁用站点（删除软链接）
|
||
sudo rm /etc/nginx/sites-enabled/mysite
|
||
|
||
# 测试并重载
|
||
sudo nginx -t && sudo systemctl reload nginx
|
||
```
|
||
|
||
### 删除站点
|
||
|
||
```bash
|
||
# 1. 禁用站点
|
||
sudo rm /etc/nginx/sites-enabled/mysite
|
||
|
||
# 2. 删除配置文件（可选，保留备份）
|
||
sudo rm /etc/nginx/sites-available/mysite
|
||
|
||
# 3. 重载
|
||
sudo systemctl reload nginx
|
||
```
|
||
|
||
## 三、SSL / HTTPS 管理
|
||
|
||
### 查看已有证书
|
||
|
||
```bash
|
||
# Let's Encrypt 证书目录
|
||
ls /etc/letsencrypt/live/
|
||
|
||
# 查看证书到期时间
|
||
sudo certbot certificates
|
||
|
||
# 或者手动查看
|
||
openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem -noout -dates
|
||
```
|
||
|
||
### 申请 Let's Encrypt 证书（Certbot）
|
||
|
||
```bash
|
||
# 安装 certbot（如未安装）
|
||
sudo apt install certbot python3-certbot-nginx
|
||
|
||
# 为单个域名申请证书
|
||
sudo certbot --nginx -d example.com -d www.example.com
|
||
|
||
# 自动配置 Nginx（Certbot 会修改配置文件）
|
||
# 或使用 --nginx 参数让它自动配置 SSL
|
||
|
||
# 仅获取证书，不修改 Nginx 配置
|
||
sudo certbot certonly --nginx -d example.com
|
||
```
|
||
|
||
### 手动配置 SSL（已有证书）
|
||
|
||
在站点配置中加入：
|
||
```nginx
|
||
listen 443 ssl http2;
|
||
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
|
||
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
|
||
include /etc/letsencrypt/options-ssl-nginx.conf;
|
||
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
|
||
```
|
||
|
||
### 强制 HTTPS 跳转
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name example.com www.example.com;
|
||
return 301 https://$host$request_uri;
|
||
}
|
||
```
|
||
|
||
### 证书自动续期
|
||
|
||
Let's Encrypt 证书有效期 90 天，Certbot 安装后自动配置定时任务：
|
||
|
||
```bash
|
||
# 查看自动续期配置
|
||
sudo certbot renew --dry-run
|
||
|
||
# 手动触发续期
|
||
sudo certbot renew
|
||
|
||
# 查看续期定时任务
|
||
sudo systemctl list-timers | grep certbot
|
||
```
|
||
|
||
### SSL 证书检查
|
||
|
||
```bash
|
||
# 检查 SSL 配置是否正确
|
||
openssl s_client -connect example.com:443 -servername example.com
|
||
|
||
# 查看证书信息
|
||
openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -text -noout | grep -E "Issuer|Subject|Validity"
|
||
```
|
||
|
||
## 四、反向代理和 upstream 进阶
|
||
|
||
### 长连接 upstream
|
||
|
||
```nginx
|
||
upstream api_backend {
|
||
keepalive 32; # 保持长连接数
|
||
|
||
server 127.0.0.1:8001;
|
||
server 127.0.0.1:8002;
|
||
}
|
||
|
||
server {
|
||
location /api/ {
|
||
proxy_pass http://api_backend;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Connection "";
|
||
}
|
||
}
|
||
```
|
||
|
||
### 路径重写
|
||
|
||
```nginx
|
||
location /api/v1/ {
|
||
rewrite ^/api/v1/(.*)$ /api/$1 break;
|
||
proxy_pass http://127.0.0.1:8080;
|
||
}
|
||
```
|
||
|
||
### WebSocket 代理
|
||
|
||
```nginx
|
||
location /ws/ {
|
||
proxy_pass http://127.0.0.1:9000;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
proxy_read_timeout 86400;
|
||
}
|
||
```
|
||
|
||
### 限制访问（IP 白名单）
|
||
|
||
```nginx
|
||
location /admin/ {
|
||
allow 192.168.1.0/24;
|
||
allow 10.0.0.0/8;
|
||
deny all;
|
||
|
||
proxy_pass http://127.0.0.1:8080;
|
||
}
|
||
```
|
||
|
||
## 五、日志和调试
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# 错误日志
|
||
sudo tail -20 /var/log/nginx/error.log
|
||
|
||
# 访问日志
|
||
sudo tail -20 /var/log/nginx/access.log
|
||
|
||
# 实时查看访问日志
|
||
sudo tail -f /var/log/nginx/access.log
|
||
|
||
# 实时查看错误日志
|
||
sudo tail -f /var/log/nginx/error.log
|
||
```
|
||
|
||
### 查看连接数
|
||
|
||
```bash
|
||
# 查看 Nginx 进程连接数
|
||
sudo ss -s
|
||
|
||
# 查看连接状态
|
||
sudo netstat -anp | grep nginx
|
||
```
|
||
|
||
### 常用调试命令
|
||
|
||
```bash
|
||
# 完整测试并显示配置
|
||
sudo nginx -T
|
||
|
||
# 检查配置语法（不检查合法性）
|
||
sudo nginx -t
|
||
|
||
# 查看已启用的站点
|
||
ls /etc/nginx/sites-enabled/
|
||
|
||
# 查看默认 SSL 配置
|
||
cat /etc/letsencrypt/options-ssl-nginx.conf
|
||
```
|
||
|
||
## 六、工作流程
|
||
|
||
### 创建新站点（完整流程）
|
||
|
||
1. **创建目录**：`sudo mkdir -p /var/www/example.com`
|
||
2. **编写配置**：在 `/etc/nginx/sites-available/example.com` 创建配置
|
||
3. **创建软链接**：`sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com`
|
||
4. **测试**：`sudo nginx -t`
|
||
5. **重载**：`sudo systemctl reload nginx`
|
||
6. **如需 HTTPS**：执行 `sudo certbot --nginx -d example.com -d www.example.com`
|
||
|
||
### 修改站点配置（完整流程）
|
||
|
||
1. **编辑配置**：`sudo nano /etc/nginx/sites-available/example.com`
|
||
2. **测试**：`sudo nginx -t`
|
||
3. **重载**：`sudo systemctl reload nginx`
|
||
4. **验证**：检查 `sudo systemctl status nginx`
|
||
|
||
### 启用 HTTPS（已有站点）
|
||
|
||
1. **申请证书**：`sudo certbot --nginx -d example.com -d www.example.com`
|
||
2. **Certbot 自动**：修改配置文件，添加 HTTPS server 块，自动配置重定向
|
||
3. **验证**：`sudo systemctl reload nginx && openssl s_client -connect example.com:443`
|
||
|
||
## 七、安全最佳实践
|
||
|
||
1. **使用 TLS 1.2+**：ssl_protocols 仅启用 TLSv1.2 TLSv1.3
|
||
2. **使用 Certbot 配置模板**：`include /etc/letsencrypt/options-ssl-nginx.conf`
|
||
3. **启用 HSTS**（可选）：`add_header Strict-Transport-Security "max-age=31536000" always;`
|
||
4. **禁止显示 Nginx 版本**：`server_tokens off;`（在主配置 http 块中）
|
||
5. **定期更新证书**：配置自动续期后无需手动操作
|
||
6. **限制请求方法**：仅允许 GET/POST/HEAD
|
||
```nginx
|
||
if ($request_method !~ ^(GET|POST|HEAD)$) {
|
||
return 405;
|
||
}
|
||
```
|
||
|
||
## 八、故障排查
|
||
|
||
### 反向代理常见错误
|
||
|
||
#### "URL 拼写可能存在错误"
|
||
|
||
这个错误**不是 Nginx 本身返回的**，而是后端服务（如 Spring Boot、Node.js、Vite 等）返回的。
|
||
|
||
**排查步骤：**
|
||
```bash
|
||
# 第1步：直接测试后端服务（排除 Nginx 影响）
|
||
curl -v http://127.0.0.1:1234/
|
||
|
||
# 如果直接访问也报错 → 问题在后端，与 Nginx 无关
|
||
# 如果直接访问正常 → 问题在 Nginx 配置
|
||
```
|
||
|
||
#### proxy_pass 路径陷阱
|
||
|
||
```nginx
|
||
# ❌ 错误：末尾多了斜杠，会把 /app/ 替换成 /
|
||
location /app/ {
|
||
proxy_pass http://127.0.0.1:8080/;
|
||
}
|
||
|
||
# ✅ 正确：末尾无斜杠，保持原路径
|
||
location /app/ {
|
||
proxy_pass http://127.0.0.1:8080; # 不加 /
|
||
}
|
||
|
||
# 特殊情况：需要去掉前缀时
|
||
location /api/ {
|
||
# rewrite + proxy_pass 末尾斜杠 = 去掉 /api 前缀
|
||
rewrite ^/api/(.*)$ /$1 break;
|
||
proxy_pass http://127.0.0.1:8080/; # 这里需要斜杠
|
||
}
|
||
```
|
||
|
||
#### 必备的代理请求头
|
||
|
||
```nginx
|
||
location / {
|
||
proxy_pass http://127.0.0.1:1234;
|
||
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;
|
||
}
|
||
```
|
||
|
||
### 配置测试失败
|
||
|
||
```bash
|
||
# 查看详细错误
|
||
sudo nginx -t 2>&1
|
||
|
||
# 查看错误日志
|
||
sudo tail -30 /var/log/nginx/error.log
|
||
```
|
||
|
||
### 服务启动失败
|
||
|
||
```bash
|
||
# 查看 systemctl 日志
|
||
sudo journalctl -xe --no-pager | tail -50
|
||
|
||
# 查看端口占用
|
||
sudo lsof -i :80
|
||
sudo lsof -i :443
|
||
```
|
||
|
||
### 502 Bad Gateway
|
||
|
||
1. 检查后端服务是否运行：`curl -I http://127.0.0.1:8080`
|
||
2. 检查 upstream 配置
|
||
3. 查看错误日志确认原因
|
||
|
||
### 证书过期
|
||
|
||
```bash
|
||
# 强制续期
|
||
sudo certbot renew --force-renewal
|
||
|
||
# 或者重新申请
|
||
sudo certbot certonly --nginx -d example.com
|
||
```
|
||
|
||
### 快速诊断命令
|
||
|
||
```bash
|
||
# 1. 检查 Nginx 和后端端口
|
||
sudo lsof -i :1234
|
||
sudo netstat -tlnp | grep nginx
|
||
|
||
# 2. 直接测试后端
|
||
curl -v http://127.0.0.1:1234/
|
||
|
||
# 3. 测试 Nginx 配置
|
||
sudo nginx -t
|
||
|
||
# 4. 查看实时日志
|
||
sudo tail -f /var/log/nginx/access.log
|
||
sudo tail -f /var/log/nginx/error.log
|
||
|
||
# 5. 查看完整的已加载配置
|
||
sudo nginx -T
|
||
``` |