qwen-skills/nginx/SKILL.md

name, description

name	description
nginx	Nginx 全自动站点部署、SSL 证书、静态网站 SPA 配置

Nginx 管理

全自动部署流程

当用户要求"全自动配置 nginx"时，按以下顺序执行：

1. 构建并部署静态文件

从项目 run_prod.sh 读取部署目录，通常部署到 /www/<项目名>/。执行：

bash run_prod.sh

2. 创建 Nginx 配置

根据实际目录结构选择配置方式：

Debian/Ubuntu（sites-available 方式）

sudo cp <config> /etc/nginx/sites-available/<sitename>
sudo ln -sf /etc/nginx/sites-available/<sitename> /etc/nginx/sites-enabled/<sitename>
sudo nginx -t && sudo systemctl reload nginx

RHEL/CentOS/Fedora（conf.d 方式）

sudo cp <config> /etc/nginx/conf.d/<sitename>.conf
sudo nginx -t && sudo systemctl reload nginx

3. 申请 SSL 证书

sudo certbot --nginx -d www.domain.com -d domain.com --non-interactive --agree-tos --email <email>

如 certbot 未安装，先安装：

# Debian/Ubuntu
sudo apt install -y certbot python3-certbot-nginx

# RHEL/CentOS/Fedora（pip 安装）
sudo pip install certbot certbot-nginx

4. 配置自动续期

创建 systemd timer：

sudo tee /etc/systemd/system/certbot-renew.timer > /dev/null << 'EOF'
[Unit]
Description=Run certbot renew twice daily

[Timer]
OnCalendar=0/12:00,12:00
RandomizedDelaySec=3600
Persistent=true

[Install]
WantedBy=timers.target
EOF

sudo tee /etc/systemd/system/certbot-renew.service > /dev/null << 'EOF'
[Unit]
Description=Certbot renewal
After=network-online.target
W Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/bin/certbot renew --quiet --deploy-hook "systemctl reload nginx"
PrivateTmp=true
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now certbot-renew.timer

5. 验证部署

curl -I https://www.domain.com/

静态网站 SPA 配置

适用于 VitePress/Hugo 等静态站点，部署在 /www/<sitename>/：

RHEL/CentOS/Fedora 完整配置

server {
    listen 80;
    server_name www.domain.com domain.com;
    root /www/domain;
    index index.html;

    # VitePress SPA fallback
    location / {
        try_files $uri $uri.html $uri/index.html /index.html;
    }

    # 缓存静态资源
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options SAMEORIGIN;

    access_log /var/log/nginx/domain_access.log;
    error_log /var/log/nginx/domain_error.log;
}

反向代理配置

用于代理本地服务（如 Node.js）：

server {
    listen 80;
    server_name www.domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name www.domain.com;

    ssl_certificate /etc/letsencrypt/live/www.domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/www.domain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    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;
    }
}

快速命令

命令	说明
sudo nginx -t	测试配置语法
sudo systemctl reload nginx	热重载生效
sudo nginx -T	查看完整加载配置
sudo certbot certificates	查看已有证书
sudo certbot renew --dry-run	续期测试

常见问题

问题	排查
502 Bad Gateway	curl http://127.0.0.1:1234 确认后端运行
配置无效	sudo nginx -t 检查语法
nginx 未启动	sudo systemctl start nginx
SSL 申请失败	确认 DNS 已解析到服务器 IP
certbot 命令找不到	pip 安装 certbot certbot-nginx