---
name: nginx-config
version: 2.0.0
description: "配置 Nginx 作为 Hyperf + Vue 3 的反向代理和静态文件服务。当需要 SSL、负载均衡或 Nginx 优化时使用。"
---

# 🔧 Nginx Config (Hyperf + Vue 3 SPA)

## 触发条件

用户需要配置 Nginx 作为 Hyperf API + Vue 3 SPA 前端的反向代理、SSL 终端、静态文件服务器或负载均衡器。

## Phase 0：场景确认

| 场景 | 对应配置 |
|------|---------|
| 开发环境反向代理 | 基础 proxy_pass |
| 生产环境单机部署 | proxy_pass + SSL + 安全头 |
| 多实例负载均衡 | upstream + health check |
| 前端 SPA 静态资源 | try_files + 长期缓存 |
| WebSocket 支持 | upgrade + connection 头 |
| API 反向代理 | /api -> Hyperf 9501 |

---

## Phase 1：基础架构配置 (Hyperf + Vue 3 SPA)

```nginx
# /etc/nginx/sites-available/myapp.conf

# ── 后端 Upstream ─────────────────────────
upstream hyperf_backend {
    server 127.0.0.1:9501;
    keepalive 32;
}

upstream hyperf_websocket {
    server 127.0.0.1:9502;
}

# ── HTTP -> HTTPS 重定向 ──────────────────
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$server_name$request_uri;
}

# ── 主配置 ────────────────────────────────
server {
    listen 443 ssl http2;
    server_name example.com www.example.com;

    # ── SSL 证书 ──────────────────────────
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;

    # ── 安全头 ────────────────────────────
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options     nosniff always;
    add_header X-Frame-Options            DENY always;
    add_header X-XSS-Protection           "1; mode=block" always;
    add_header Referrer-Policy            "strict-origin-when-cross-origin" always;

    # ── 文件上传限制 ──────────────────────
    client_max_body_size 20M;

    # ── Gzip 压缩 ────────────────────────
    gzip on;
    gzip_min_length 1k;
    gzip_comp_level 6;
    gzip_vary on;
    gzip_types
        text/plain
        text/css
        application/json
        application/typescript
        text/xml
        application/xml
        image/svg+xml;

    # ── Vue 3 SPA 前端 ───────────────────
    root /var/www/myapp/Case-Database-Frontend-user/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # ── Vite 产物静态资源（带 hash 长期缓存）──
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    location /favicon.ico {
        expires 30d;
        access_log off;
    }

    # ── Hyperf API 反向代理 ──────────────
    location /admin/ {
        proxy_pass http://hyperf_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        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;

        proxy_connect_timeout 60s;
        proxy_send_timeout    60s;
        proxy_read_timeout    60s;
    }

    # ── WebSocket 代理 ───────────────────
    location /ws {
        proxy_pass http://hyperf_websocket;
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_connect_timeout 3600s;
        proxy_send_timeout    3600s;
        proxy_read_timeout    3600s;
    }

    # ── 文件上传/下载 ────────────────────
    location /admin/upload {
        proxy_pass http://hyperf_backend;
        client_max_body_size 50M;
        proxy_request_buffering off;
    }

    # ── 拒绝隐藏文件 ────────────────────
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }
}
```

---

## Phase 2：负载均衡配置

```nginx
# 多 Hyperf 实例
upstream hyperf_backend {
    least_conn;
    server 10.0.0.1:9501 weight=3;
    server 10.0.0.2:9501 weight=3;
    server 10.0.0.3:9501 backup;
    keepalive 64;
}

# 健康检查（需要 nginx-upstream-check 模块或商业版）
# 替代方案：K8s Ingress + Pod 健康检查
```

---

## Phase 3：Let's Encrypt SSL

```bash
# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

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

# 自动续期（Certbot 自动添加 cron）
sudo certbot renew --dry-run
```

---

## Phase 4：Docker Compose 中的 Nginx

```yaml
# docker-compose.yml 中 Nginx 服务
services:
  nginx:
    image: nginx:1.25-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./Case-Database-Frontend-user/dist:/var/www/myapp/Case-Database-Frontend-user/dist:ro
      - ./certbot/conf:/etc/letsencrypt:ro
    depends_on:
      - hyperf
    restart: unless-stopped
```

---

## 验证

1. [ ] `nginx -t` 配置语法检查通过
2. [ ] HTTPS 证书有效
3. [ ] SPA 路由刷新正常 (try_files -> /index.html)
4. [ ] API 代理 `/admin/*` 正常
5. [ ] WebSocket `/ws` 连接正常
6. [ ] 静态资源 `/assets/*` 带 Cache-Control
7. [ ] 安全头通过 securityheaders.com 检查
8. [ ] Gzip 压缩生效