## 一、为什么需要反向代理？

### 1.1 直接暴露服务的风险

```
# 危险做法：直接绑定公网IP
python3 -m http.server 8000 --bind 0.0.0.0  # 任何IP都能访问
```

| 风险点       | 说明                         |
| ------------ | ---------------------------- |
| 端口扫描攻击 | 公网IP+开放端口易被扫描探测  |
| 无访问控制   | 任何人可直接访问，无身份验证 |
| 单点故障     | 直接暴露后端，无负载均衡能力 |
| 协议裸奔     | HTTP明文传输，无TLS加密      |

### 1.2 反向代理的核心价值

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   客户端     │────→│  Nginx代理   │────→│  真实服务    │
│ (公网用户)   │     │ (安全网关)   │     │ (内网隔离)   │
└─────────────┘     └─────────────┘     └─────────────┘
        ↑                   ↑                   ↑
    访问域名:443         监听0.0.0.0:443      监听127.0.0.1:8000
    HTTPS加密            认证/限流/日志        仅本地可访问
```

**反向代理的本质**：把"直接访问"变成"间接访问"，在中间层插入安全、性能、扩展的控制能力。

------

## 二、基础部署：单服务反向代理

### 2.1 后端服务启动（安全模式）

```
# ✅ 正确做法：仅监听本地回环
python3 -m http.server 8000 --bind 127.0.0.1 &

# 或Flask/FastAPI等框架
# app.run(host='127.0.0.1', port=8000)

# 验证：只有本地能访问
curl http://127.0.0.1:8000        # ✅ 成功
curl http://192.168.1.100:8000    # ❌ 连接拒绝（安全）
```

**绑定方式对比**：

| 绑定地址      | 安全级别 | 适用场景                             |
| ------------- | -------- | ------------------------------------ |
| `0.0.0.0`     | ⭐⭐ 中    | 内网可信环境，需同网段直接访问       |
| `127.0.0.1`   | ⭐⭐⭐⭐⭐ 高 | **生产环境标准做法**，强制走反向代理 |
| `192.168.x.x` | ⭐⭐⭐ 中高 | 多机内网通信，配合防火墙白名单       |

### 2.2 Nginx 安装与基础配置

```
# 1. 安装 Nginx 和认证工具
sudo apt update
sudo apt install nginx apache2-utils -y

# 2. 生成 Basic Auth 密码文件
sudo htpasswd -c /etc/nginx/.htpasswd admin
# 输入两次密码

# 添加更多用户（去掉 -c 参数，避免覆盖）
sudo htpasswd /etc/nginx/.htpasswd user2
```

### 2.3 核心配置文件详解

```
# /etc/nginx/sites-available/pyhttp
server {
    # 监听端口：对外暴露的入口
    listen 8001;
    
    # 服务器名：_ 表示匹配任何域名/IP
    server_name _;
    
    # 日志配置（建议开启，便于审计）
    access_log /var/log/nginx/pyhttp.access.log;
    error_log /var/log/nginx/pyhttp.error.log;

    location / {
        # ========== 认证层 ==========
        auth_basic "Restricted Access";           # 认证提示语
        auth_basic_user_file /etc/nginx/.htpasswd; # 密码文件路径
        
        # ========== 代理层 ==========
        proxy_pass http://127.0.0.1:8000;          # 后端真实服务
        
        # ========== 头部转发（关键）==========
        # 让后端知道原始域名（多域名场景必需）
        proxy_set_header Host $host;
        
        # 让后端知道真实客户端IP（日志/限流必需）
        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;
        
        # ========== 性能优化 ==========
        # 启用连接复用（减少后端TCP建立开销）
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        
        # 缓冲区设置（根据内存调整）
        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
        
        # 超时设置（防止慢客户端拖死后端）
        proxy_connect_timeout 30s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
    }
}
```

### 2.4 启用配置并验证

```
# 创建软链接启用站点
sudo ln -s /etc/nginx/sites-available/pyhttp /etc/nginx/sites-enabled/

# 语法检查（必须做，避免配置错误导致Nginx崩溃）
sudo nginx -t

# 平滑重载配置（不断开现有连接）
sudo systemctl reload nginx

# 验证：8001端口已监听
sudo ss -tlnp | grep 8001

# 测试访问（应提示输入密码）
curl -u admin:密码 http://localhost:8001
```

------

## 三、进阶场景：微服务路由分发

### 3.1 场景一：路径分发（单域名多服务）

```
用户请求                    Nginx路由                    后端服务
─────────────────────────────────────────────────────────────────────
GET /api/users/     ──→    location /api/users/    ──→   用户服务:8000
GET /api/orders/    ──→    location /api/orders/   ──→   订单服务:8001
GET /api/products/  ──→    location /api/products/ ──→   商品服务:8002
```

```
# 上游服务池定义（放在http块内，server块外）
upstream user_service {
    server 127.0.0.1:8000;
    keepalive 32;  # 连接池，提升性能
}

upstream order_service {
    server 127.0.0.1:8001;
    keepalive 32;
}

upstream product_service {
    server 127.0.0.1:8002;
    keepalive 32;
}

upstream payment_service {
    server 127.0.0.1:8003;
    keepalive 32;
}

server {
    listen 9000;
    server_name api.example.com;
    
    # 通用认证（所有location继承）
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    
    # 用户服务
    location /api/users/ {
        proxy_pass http://user_service;
        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_read_timeout 60s;
    }
    
    # 订单服务
    location /api/orders/ {
        proxy_pass http://order_service;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # 订单接口限流（防止刷单）
        limit_req_zone $binary_remote_addr zone=order_limit:10m rate=10r/s;
        limit_req zone=order_limit burst=20 nodelay;
    }
    
    # 商品服务（静态资源缓存）
    location /api/products/ {
        proxy_pass http://product_service;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # 商品列表缓存5分钟
        proxy_cache_valid 200 5m;
        proxy_cache_key "$scheme$request_method$host$request_uri";
    }
    
    # 支付服务（最高安全级别）
    location /api/payments/ {
        proxy_pass http://payment_service;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # 仅允许HTTPS（配合外层TLS）
        if ($scheme != "https") {
            return 403;
        }
        
        # 支付接口严格限流
        limit_req zone=payment_limit burst=5 nodelay;
    }
    
    # 健康检查端点（无需认证，供监控系统使用）
    location /health {
        auth_basic off;  # 关闭认证
        access_log off;  # 关闭日志
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }
}
```

### 3.2 场景二：子域名分发（多域名架构）

```
users.example.com    ──→   127.0.0.1:8000   用户中心
orders.example.com   ──→   127.0.0.1:8001   订单系统
products.example.com ──→   127.0.0.1:8002   商品服务
```

```
# 用户服务子域名
server {
    listen 9000;
    server_name users.example.com;
    
    # 日志分离（按业务拆分，便于分析）
    access_log /var/log/nginx/users.access.log;
    error_log /var/log/nginx/users.error.log;
    
    location / {
        auth_basic "User Service";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # 用户服务特定：大文件上传支持
        client_max_body_size 50M;
    }
}

# 订单服务子域名
server {
    listen 9000;
    server_name orders.example.com;
    
    access_log /var/log/nginx/orders.access.log;
    error_log /var/log/nginx/orders.error.log;
    
    location / {
        auth_basic "Order Service";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # 订单需要长连接（WebSocket支持）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# 商品服务子域名（静态资源加速）
server {
    listen 9000;
    server_name products.example.com;
    
    access_log /var/log/nginx/products.access.log;
    
    # 静态资源直接由Nginx处理，不转发后端
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
        root /var/www/products/static;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
    
    # API请求转发
    location /api/ {
        auth_basic "Product Service";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://127.0.0.1:8002;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 3.3 场景三：负载均衡（多实例高可用）

```
upstream user_service {
    # 加权轮询（weight越大，分配越多）
    server 127.0.0.1:8000 weight=3;
    server 127.0.0.1:8010 weight=2;
    server 127.0.0.1:8020 weight=2;
    
    # 备用服务器（主服务器全挂时启用）
    server 127.0.0.1:8030 backup;
    
    # 健康检查（Nginx Plus功能，开源版需第三方模块）
    # health_check interval=5 fails=3 passes=2;
    
    keepalive 64;           # 连接池
    keepalive_timeout 60s;  # 连接保活时间
    keepalive_requests 100; # 单连接最大请求数
}

upstream order_service {
    # IP哈希（保证同一用户固定到同一后端，适用于有状态服务）
    ip_hash;
    
    server 127.0.0.1:8001;
    server 127.0.0.1:8111;
    
    # 最大失败次数和冷却时间
    server 127.0.0.1:8222 max_fails=3 fail_timeout=30s;
}

upstream product_service {
    # 最少连接（适合请求处理时长不均的场景）
    least_conn;
    
    server 127.0.0.1:8002;
    server 127.0.0.1:8222;
}

server {
    listen 9000;
    
    # 全局限流配置
    limit_req_zone $binary_remote_addr zone=global_limit:10m rate=100r/s;
    limit_req zone=global_limit burst=200 nodelay;
    
    location /users/ {
        proxy_pass http://user_service;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # 连接错误时的处理
        proxy_next_upstream error timeout http_502 http_503;
        proxy_next_upstream_tries 2;
    }
    
    location /orders/ {
        proxy_pass http://order_service;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /products/ {
        proxy_pass http://product_service;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

------

## 四、安全加固：生产环境必做

### 4.1 HTTPS 强制升级

```
server {
    listen 80;
    server_name api.example.com;
    # 所有HTTP请求重定向到HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;  # http2提升性能
    server_name api.example.com;
    
    # SSL证书（Let's Encrypt免费证书）
    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    
    # SSL安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;
    
    # HSTS（强制浏览器HTTPS访问）
    add_header Strict-Transport-Security "max-age=63072000" always;
    
    location / {
        # 原有代理配置...
    }
}
```

### 4.2 IP 白名单限制

```
location /admin/ {
    # 仅允许特定IP访问管理后台
    allow 192.168.1.0/24;  # 内网网段
    allow 10.0.0.10;       # 特定IP
    deny all;              # 其他全部拒绝
    
    proxy_pass http://127.0.0.1:8000;
}
```

### 4.3 隐藏版本信息

```
# /etc/nginx/nginx.conf 主配置
http {
    server_tokens off;  # 隐藏Nginx版本号
    
    # 自定义错误页面（防止信息泄露）
    error_page 500 502 503 504 /50x.html;
    location = /50x.html {
        root /var/www/html;
        internal;
    }
}
```

------

## 五、性能优化：从能用到好用

### 5.1 启用压缩

```
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css text/xml application/json application/javascript application/rss+xml application/atom+xml image/svg+xml;
```

### 5.2 静态资源缓存

```
location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff|woff2)$ {
    expires 6M;  # 半年
    access_log off;
    add_header Cache-Control "public, immutable";
}
```

### 5.3 连接优化

```
upstream backend {
    server 127.0.0.1:8000;
    
    # 连接池关键参数
    keepalive 100;          # 保持100个空闲连接
    keepalive_requests 1000; # 单连接复用1000次
    keepalive_timeout 60s;   # 空闲连接保活60秒
}
```

------

## 六、故障排查：常见问题速查

### 6.1 502 Bad Gateway

```
# 1. 检查后端服务是否运行
curl http://127.0.0.1:8000

# 2. 检查Nginx错误日志
sudo tail -f /var/log/nginx/error.log

# 3. 常见原因
# - 后端未启动
# - 防火墙拦截
# - SELinux限制（setenforce 0 测试）
# - 后端监听地址错误（应127.0.0.1而非localhost）
```

### 6.2 认证不生效

```
# 检查密码文件权限（必须可读）
sudo chmod 644 /etc/nginx/.htpasswd
sudo chown www-data:www-data /etc/nginx/.htpasswd

# 测试密码文件格式
cat /etc/nginx/.htpasswd
# 应为：username:$apr1$xxxxx$xxxxx
```

### 6.3 配置热重载失败

```
# 先测试语法
sudo nginx -t

# 查看详细错误
sudo nginx -t 2>&1 | less

# 紧急恢复（配置错误导致Nginx无法启动）
sudo cp /etc/nginx/nginx.conf.bak /etc/nginx/nginx.conf
sudo systemctl restart nginx
```

------

## 七、完整配置模板（生产可用）

```
# /etc/nginx/sites-available/production
upstream app_backend {
    server 127.0.0.1:8000;
    keepalive 64;
}

server {
    listen 80;
    server_name _;
    return 301 https://$host$request_uri;  # 强制HTTPS
}

server {
    listen 443 ssl http2;
    server_name api.example.com;
    
    # SSL
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    # 日志
    access_log /var/log/nginx/api.access.log main;
    error_log /var/log/nginx/api.error.log warn;
    
    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    
    # 全局限流
    limit_req_zone $binary_remote_addr zone=api:10m rate=100r/s;
    limit_req zone=api burst=200 nodelay;
    
    # 认证
    auth_basic "Production API";
    auth_basic_user_file /etc/nginx/.htpasswd;
    
    location / {
        proxy_pass http://app_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;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        
        proxy_connect_timeout 30s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
        
        proxy_next_upstream error timeout http_502 http_503;
    }
    
    location /health {
        auth_basic off;
        access_log off;
        return 200 "OK\n";
        add_header Content-Type text/plain;
    }
}
```

------

## 总结

| 场景           | 推荐方案            | 关键配置                         |
| -------------- | ------------------- | -------------------------------- |
| 单服务快速上线 | 路径代理            | `location / { proxy_pass }`      |
| 多服务微服务   | upstream + location | 按路径或域名拆分                 |
| 高可用生产环境 | 负载均衡 + 健康检查 | `weight`/`ip_hash`/`least_conn`  |
| 安全敏感业务   | HTTPS + 认证 + 限流 | `auth_basic` + `limit_req` + TLS |

反向代理是**基础设施的守门员**，投入时间做好配置，能大幅提升系统的安全性、可维护性和扩展性。

nginx反向代理

## 一、反向代理的本质：什么是"反向"？

### 1.1 正向代理 vs 反向代理

```
┌─────────────────────────────────────────────────────────────────┐
│                         正向代理（Forward Proxy）                 │
│  客户端 ──→ 代理服务器 ──→ 目标服务器（Google/YouTube等）        │
│   ↑           ↑              ↑                                  │
│  我知道代理   我知道客户端     我不知道真实客户端                   │
│  我要访问外网  我要替它访问    我只看到代理IP                      │
└─────────────────────────────────────────────────────────────────┘
                              用途：翻墙、匿名、缓存加速

┌─────────────────────────────────────────────────────────────────┐
│                         反向代理（Reverse Proxy）                 │
│  客户端 ──→ 代理服务器 ──→ 后端服务器集群（Web/App/DB）          │
│   ↑           ↑              ↑                                  │
│  我只知道域名  我知道所有后端   我不知道真实用户                    │
│  访问example.com 我要分发请求   我只看到代理IP                     │
└─────────────────────────────────────────────────────────────────┘
                              用途：负载均衡、安全防护、SSL终结
```

**核心区别**：正向代理代理的是**客户端**，反向代理代理的是**服务器**。

### 1.2 反向代理的七层网络位置

```
OSI七层模型中的反向代理：

┌─────────────┐  ← 客户端（浏览器/curl）
│   应用层     │     HTTP/HTTPS请求
├─────────────┤
│   表示层     │
├─────────────┤
│   会话层     │
├─────────────┤
│   传输层     │  ← L4负载均衡（HAProxy/Envoy TCP模式）← 这里也可做代理
├─────────────┤
│   网络层     │
├─────────────┤
│  数据链路层   │
├─────────────┤
│   物理层     │
└─────────────┘  ← 反向代理服务器（Nginx/Caddy/Traefik）
       ↓
   分发到后端集群（Web服务器集群）
```

------

## 二、反向代理的核心能力矩阵

| 能力维度     | 技术实现                  | 业务价值                   |
| ------------ | ------------------------- | -------------------------- |
| **流量调度** | 轮询/加权/最少连接/IP哈希 | 水平扩展、消除单点         |
| **安全隔离** | 隐藏后端IP、WAF、限流     | 防御DDoS、SQL注入          |
| **SSL终结**  | TLS卸载、证书管理         | 后端专注业务、简化证书部署 |
| **缓存加速** | 静态缓存、边缘缓存        | 降低后端负载、提升响应速度 |
| **协议转换** | HTTP/2、gRPC、WebSocket   | 统一入口协议、后端灵活选型 |
| **可观测性** | 日志、指标、链路追踪      | 故障定位、性能优化         |

------

## 三、主流反向代理工具深度对比

### 3.1 传统三强：Nginx/Apache/HAProxy

| 工具             | 诞生年份 | 核心优势                     | 典型场景                | 性能量级  |
| ---------------- | -------- | ---------------------------- | ----------------------- | --------- |
| **Nginx**        | 2004     | 事件驱动、配置灵活、生态庞大 | Web服务器+反向代理+缓存 | 10万+并发 |
| **Apache httpd** | 1995     | 模块丰富、.htaccess灵活      | 传统LAMP、动态内容      | 1万+并发  |
| **HAProxy**      | 2000     | TCP/HTTP双栈、极致性能、稳定 | 金融级负载均衡入口      | 10万+并发 |

**性能实测对比**（相同硬件：4核8G）：

```
测试条件：100字节响应，Keep-Alive，1000并发连接

Nginx:      120,000 RPS，内存占用 150MB
HAProxy:    135,000 RPS，内存占用 80MB
Apache:     45,000 RPS，内存占用 400MB
Caddy:      95,000 RPS，内存占用 200MB（自动HTTPS开销）
```

### 3.2 云原生新贵：Traefik/Caddy/Envoy

#### Traefik：容器编排的最佳拍档

```
# Docker Compose 自动发现示例
version: '3'
services:
  traefik:
    image: traefik:v2.10
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
  
  whoami:
    image: traefik/whoami
    labels:
      - "traefik.http.routers.whoami.rule=Host(`whoami.example.com`)"
      - "traefik.http.services.whoami.loadbalancer.server.port=80"
```

**核心特性**：

- **自动服务发现**：Docker/Kubernetes标签自动注册路由
- **动态配置**：无需重启热更新
- **Let's Encrypt自动化**：一行配置自动证书
- **中间件链**：认证、限流、压缩、重试可组合

#### Caddy：配置极简主义

```
# 完整生产配置只需这几行
example.com

reverse_proxy localhost:8080

basicauth {
    admin $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
}

encode gzip
file_server /static/*
```

**一行命令启动HTTPS**：

```
# 自动申请Let's Encrypt证书，80/443端口
caddy reverse-proxy --from example.com --to localhost:8080
```

#### Envoy：服务网格的数据平面

```
# Envoy配置示例（YAML比Nginx更结构化）
static_resources:
  listeners:
    - name: listener_0
      address:
        socket_address: { address: 0.0.0.0, port_value: 10000 }
      filter_chains:
        - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                stat_prefix: ingress_http
                route_config:
                  name: local_route
                  virtual_hosts:
                    - name: backend
                      domains: ["*"]
                      routes:
                        - match: { prefix: "/" }
                          route: { cluster: service_backend }
                http_filters:
                  - name: envoy.filters.http.router
  
  clusters:
    - name: service_backend
      connect_timeout: 0.25s
      type: STATIC
      lb_policy: ROUND_ROBIN
      load_assignment:
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address: { address: 127.0.0.1, port_value: 8080 }
```

**Envoy的独特优势**：

- **xDS协议**：控制面（Istio）动态推送配置
- **可观测性内置**：Prometheus指标、分布式追踪开箱即用
- **多协议支持**：HTTP/1、HTTP/2、HTTP/3、gRPC、TCP统一代理

### 3.3 API网关层：Kong/APISIX/Gloo

| 工具       | 技术底座             | 核心能力                     | 适用规模       |
| ---------- | -------------------- | ---------------------------- | -------------- |
| **Kong**   | OpenResty(Nginx+Lua) | 插件生态丰富、企业版功能全   | 中大型企业     |
| **APISIX** | Envoy/Nginx双引擎    | 动态路由、多语言插件、国产   | 云原生中大规模 |
| **Gloo**   | Envoy                | 函数级路由、GraphQL/gRPC转换 | 微服务复杂场景 |
| **Tyk**    | Go自研               | 开源协议友好、内置Dashboard  | 中小企业       |

**Kong插件示例**（速率限制）：

```
# 安装速率限制插件
curl -X POST http://localhost:8001/plugins \
  --data "name=rate-limiting" \
  --data "config.minute=100" \
  --data "config.policy=redis" \
  --data "config.redis_host=redis"
```

------

## 四、场景化选型决策树

```
开始选型
    │
    ├── 是否需要自动服务发现（Docker/K8s）？
    │       ├── 是 → Traefik（最简单）或 APISIX（功能最强）
    │       └── 否 → 继续
    │
    ├── 是否追求配置极简（个人/小团队）？
    │       ├── 是 → Caddy（自动HTTPS神器）
    │       └── 否 → 继续
    │
    ├── 是否需要服务网格（Istio/Consul）？
    │       ├── 是 → Envoy（标准数据平面）
    │       └── 否 → 继续
    │
    ├── 性能要求是否极致（金融/高并发）？
    │       ├── 是 → HAProxy（TCP层）或 Nginx（HTTP层）
    │       └── 否 → 继续
    │
    ├── 是否需要丰富插件（认证/转换/分析）？
    │       ├── 是 → Kong 或 APISIX
    │       └── 否 → Nginx（稳定成熟）
    │
    └── 遗留系统兼容（Apache模块）？
            ├── 是 → Apache httpd + mod_proxy
            └── 否 → 上述任选
```

------

## 五、高级架构模式

### 5.1 多层代理架构（大型互联网标准）

```
用户请求
    ↓
[CDN边缘]  ← CloudFlare/阿里云CDN，静态缓存+抗DDoS
    ↓
[L4负载均衡]  ← HAProxy/硬件F5，TCP层分发，多活入口
    ↓
[L7网关集群]  ← Nginx/Kong集群，SSL终结+业务路由
    ↓
[微服务网格]  ← Envoy Sidecar，服务间mTLS+熔断
    ↓
[应用容器]  ← Pod/Container，业务代码
```

### 5.2 灰度发布实现（基于Nginx）

```
upstream backend_stable {
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
}

upstream backend_canary {
    server 10.0.0.3:8080;  # 新版本
}

split_clients "${remote_addr}AAA" $canary_version {
    95%     stable;
    5%      canary;
}

server {
    location / {
        proxy_pass http://backend_$canary_version;
    }
}
```

### 5.3 全局流量治理（Istio + Envoy）

```
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: reviews-route
spec:
  hosts:
    - reviews.prod.svc.cluster.local
  http:
    - match:
        - headers:
            end-user:
              exact: jason
      route:
        - destination:
            host: reviews.prod.svc.cluster.local
            subset: v2
    - route:
        - destination:
            host: reviews.prod.svc.cluster.local
            subset: v1
          weight: 90
        - destination:
            host: reviews.prod.svc.cluster.local
            subset: v3
          weight: 10
```

------

## 六、性能调优黄金法则

### 6.1 连接池优化

```
# Nginx upstream连接池
upstream backend {
    server 127.0.0.1:8080;
    
    keepalive 100;          # 保持100个空闲长连接
    keepalive_timeout 60s;  # 空闲连接保活时间
    keepalive_requests 1000; # 单连接最大复用次数
    
    # 健康检查（商业版或第三方模块）
    # health_check interval=5s fails=3 passes=2;
}
```

### 6.2 内核参数调优

```
# /etc/sysctl.conf
# 增大文件描述符
fs.file-max = 1000000

# TCP连接优化
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_tw_recycle = 0
net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_keepalive_time = 1200
net.ipv4.tcp_max_syn_backlog = 8192
net.ipv4.tcp_max_tw_buckets = 5000

# 端口范围
net.ipv4.ip_local_port_range = 10000 65000

# 连接跟踪（高并发时考虑关闭或增大）
net.netfilter.nf_conntrack_max = 1000000
```

### 6.3 压测验证

```
# wrk 现代HTTP压测工具
wrk -t12 -c400 -d30s http://localhost:8080/api

# 输出示例：
# Running 30s test @ http://localhost:8080/api
#   12 threads and 400 connections
#   Thread Stats   Avg      Stdev     Max   +/- Stdev
#     Latency    12.34ms   3.21ms  45.67ms   78.23%
#     Req/Sec    10.23k     1.12k   12.50k    72.45%
#   3678902 requests in 30.02s, 512.34MB read
# Requests/sec: 122545.12
# Transfer/sec:     17.07MB
```

------

## 七、未来趋势：反向代理的演进方向

| 趋势                | 技术体现                  | 影响                     |
| ------------------- | ------------------------- | ------------------------ |
| **eBPF加速**        | Cilium/Katran替代iptables | 更高性能、更低延迟       |
| **HTTP/3普及**      | QUIC协议、0-RTT连接       | 弱网环境体验提升         |
| **WebAssembly插件** | Envoy Wasm/APISIX Wasm    | 多语言编写扩展，安全沙箱 |
| **AI驱动调度**      | 基于实时延迟预测路由      | 智能流量管理             |
| **零信任架构**      | 每请求mTLS、身份感知代理  | 安全边界内移             |

------

## 总结：一张图选对工具

```
┌─────────────────────────────────────────────────────────────┐
│  个人博客/小项目 → Caddy（自动HTTPS，配置极简）               │
├─────────────────────────────────────────────────────────────┤
│  中小团队/Docker环境 → Traefik（自动发现，云原生友好）         │
├─────────────────────────────────────────────────────────────┤
│  传统架构/稳定优先 → Nginx（生态成熟，文档丰富）               │
├─────────────────────────────────────────────────────────────┤
│  金融级高并发入口 → HAProxy（TCP层极致性能）                 │
├─────────────────────────────────────────────────────────────┤
│  服务网格/Istio → Envoy（标准数据平面）                      │
├─────────────────────────────────────────────────────────────┤
│  API管理/丰富插件 → Kong/APISIX（企业级网关）                │
└─────────────────────────────────────────────────────────────┘
```

反向代理是现代架构的**流量枢纽**，选型时需平衡**性能、功能、运维复杂度**三个维度，没有银弹，只有最适合当前阶段的方案。

反向代理技术解析

## 一、Linux 防火墙技术演进史

### 1.1 三代内核框架

| 年代      | 框架         | 特点                                                | 现状               |
| --------- | ------------ | --------------------------------------------------- | ------------------ |
| **2000**  | **iptables** | 基于 netfilter 钩子，规则链遍历，O(n) 性能          | 维护模式，逐步废弃 |
| **2014**  | **nftables** | 原生集成功能，规则集优化，O(1) 性能，统一 IPv4/IPv6 | **当前内核标准**   |
| **2019+** | **bpfilter** | eBPF 驱动，用户态处理，极致性能                     | 实验阶段，未普及   |

### 1.2 用户层工具的适配

```
用户命令
    │
    ├──► ufw (Ubuntu) ──► iptables 语法 ──► iptables-nft ──► nftables 内核
    │
    ├──► firewalld (RHEL) ──► 直接生成 nftables 规则 ──► nftables 内核
    │
    └──► iptables 传统命令 ──► xtables-nft 兼容层 ──► nftables 内核
```

**关键认知**：现代 Linux 发行版（Ubuntu 22.04+、RHEL 8+、Debian 11+）**内核已没有传统 iptables**，所有 `iptables` 命令都通过 **iptables-nft** 翻译成 **nftables** 执行。

------

## 二、ufw：Ubuntu 的极简防火墙

### 2.1 架构深度解析

```
┌─────────────────────────────────────────┐
│           用户层：ufw CLI               │
│     ufw allow 22/tcp                    │
│     ufw deny from 10.0.0.100            │
└─────────────────┬───────────────────────┘
                  │ Python 解析
                  ▼
┌─────────────────────────────────────────┐
│      配置层：/lib/ufw/*.rules           │
│  -A ufw-user-input -p tcp --dport 22 -j ACCEPT
│  -A ufw-user-input -s 10.0.0.100 -j DROP
└─────────────────┬───────────────────────┘
                  │ 调用 /usr/sbin/iptables
                  ▼
┌─────────────────────────────────────────┐
│      翻译层：iptables-nft               │
│  将 iptables 语法转换为 nftables 对象：
│  add rule ip filter ufw-user-input tcp dport 22 accept
└─────────────────┬───────────────────────┘
                  │ netlink 套接字
                  ▼
┌─────────────────────────────────────────┐
│      内核层：nftables                   │
│      真正的包过滤执行引擎               │
└─────────────────────────────────────────┘
```

### 2.2 核心配置文件

| 文件                       | 作用                               | 修改建议       |
| -------------------------- | ---------------------------------- | -------------- |
| `/etc/ufw/ufw.conf`        | 全局开关、日志级别                 | 一般不动       |
| `/etc/ufw/before.rules`    | ufw 规则**之前**执行（如 NAT）     | 高级自定义     |
| `/etc/ufw/after.rules`     | ufw 规则**之后**执行（如特殊日志） | 高级自定义     |
| `/etc/ufw/user.rules`      | **用户规则主文件**（ufw 命令生成） | 手动编辑需谨慎 |
| `/etc/ufw/applications.d/` | 应用配置文件（如 OpenSSH、Nginx）  | 可自定义服务名 |

### 2.3 实战命令详解

#### 端口放行（最常用）

```
# 单行放行，立即生效（无需 reload）
sudo ufw allow 22/tcp

# 多端口逗号分隔
sudo ufw allow 80,443/tcp

# 整个区间（如被动模式 FTP）
sudo ufw allow 1:65535/udp

# 指定 IP + 端口
sudo ufw allow from 192.168.1.10 to any port 3306

# 查看生成的 nftables 规则
sudo nft list chain ip filter ufw-user-input
# 输出：
# chain ufw-user-input {
#   tcp dport 22 accept
#   tcp dport { 80, 443 } accept
#   udp dport 1-65535 accept
# }
```

#### 源 IP 控制（白名单/黑名单）

```
# 放行整个网段的所有端口（管理网）
sudo ufw allow from 192.168.5.0/24

# 仅允许特定 IP 访问数据库
sudo ufw allow from 10.0.0.50 to any port 3306 proto tcp

# 显式拒绝（优先级高于 allow，日志记录）
sudo ufw deny from 10.0.0.100

# 插入到特定位置（第 3 条规则）
sudo ufw insert 3 allow from 172.16.0.0/12
```

#### 连接速率限制（防暴力破解）

```
# SSH 防暴力：30 秒内≥6 次连接，后续 DROP
sudo ufw limit 22/tcp

# 自定义 HTTP API 限速
sudo ufw limit 8080/tcp

# 查看生成的 limit 规则
sudo nft list chain ip filter ufw-user-limit
# 输出：
# chain ufw-user-limit {
#   limit rate 6/minute burst 5 packets accept
#   log prefix "[UFW LIMIT BLOCK] " level 4
#   drop
# }
```

**原理说明**：`limit` 使用 nftables 的 **meter** 对象，基于令牌桶算法，比传统 `fail2ban` 更轻量。

#### 默认策略与开关

```
# 外网主动进入全丢弃（最安全的默认）
sudo ufw default deny incoming

# 本机出站全放行（通常如此）
sudo ufw default allow outgoing

# 转发包拒绝并回 ICMP（禁止当路由器）
sudo ufw default reject routed

# 启用防火墙（首次会提示可能断开 SSH，确认 y）
sudo ufw enable

# 开机自启
sudo systemctl enable ufw

# 完全禁用（清空所有规则）
sudo ufw disable
```

#### 规则管理

```
# 查看带编号的规则列表
sudo ufw status numbered

# 删除第 5 条规则
sudo ufw delete 5

# 删除特定规则（需完全匹配）
sudo ufw delete allow from 192.168.5.0/24

# 重置为初始状态（危险！）
sudo ufw reset
```

#### 日志管理

```
# 启用日志（默认 low，只记录被阻止的新连接）
sudo ufw logging on

# 详细日志（记录所有匹配，慎用，磁盘压力大）
sudo ufw logging high

# 关闭日志
sudo ufw logging off

# 实时查看 UFW 日志
sudo journalctl -k -f | grep UFW
# 或
sudo tail -f /var/log/ufw.log
```

### 2.4 ufw 高级技巧

#### 自定义应用配置

```
# 创建自定义服务定义
sudo tee /etc/ufw/applications.d/custom-app <<'EOF'
[CustomApp]
title=My Custom Application
description=This is a custom service running on port 8080 and 8443
ports=8080,8443/tcp
EOF

# 使用应用名放行
sudo ufw allow 'CustomApp'

# 查看所有应用
sudo ufw app list
```

#### 与 Docker 的冲突解决

Docker 默认绕过 ufw，直接操作 iptables。解决方案：

```
# 方案 1：修改 Docker 默认行为
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "iptables": false
}
EOF
sudo systemctl restart docker
# 然后手动用 ufw 放行 Docker 端口

# 方案 2：使用 ufw-docker 工具
sudo wget -O /usr/local/bin/ufw-docker https://github.com/chaifeng/ufw-docker/raw/master/ufw-docker
sudo chmod +x /usr/local/bin/ufw-docker
sudo ufw-docker install
```

------

## 三、firewalld：RHEL 生态的动态防火墙

### 3.1 架构设计理念

firewalld 与 ufw 的最大区别：**firewalld 直接生成 nftables 规则，跳过 iptables 翻译层**，且支持 **动态区域（zone）** 和 **运行时/永久配置分离**。

```
┌─────────────────────────────────────────┐
│         用户层：firewall-cmd            │
│    firewall-cmd --add-port=3000/tcp     │
│    firewall-cmd --reload                │
└─────────────────┬───────────────────────┘
                  │ D-Bus 调用
                  ▼
┌─────────────────────────────────────────┐
│      守护进程：firewalld                │
│    - 解析 XML 配置                      │
│    - 管理 zone、service、rich rules     │
│    - 直接生成 nftables 规则             │
└─────────────────┬───────────────────────┘
                  │ netlink 套接字
                  ▼
┌─────────────────────────────────────────┐
│      内核层：nftables                   │
│      真正的包过滤执行引擎               │
└─────────────────────────────────────────┘
```

### 3.2 核心概念：Zone（区域）

| Zone       | 信任度 | 默认用途                    |
| ---------- | ------ | --------------------------- |
| `drop`     | 最低   | 丢弃所有进入，无响应        |
| `block`    | 极低   | 拒绝进入，回 ICMP           |
| `public`   | 低     | 公共 Wi-Fi，仅放行 SSH/DHCP |
| `external` | 中     | 对外路由器，启用 NAT        |
| `internal` | 中高   | 内网，放行更多服务          |
| `trusted`  | 最高   | 完全信任，放行所有          |

### 3.3 实战命令详解

#### 端口放行（运行时 vs 永久）

```
# 仅运行时生效（重启丢失）
sudo firewall-cmd --add-port=3000/tcp

# 永久生效（写入 XML，需 reload）
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --reload

# 多端口
sudo firewall-cmd --permanent --add-port={8080,8443}/tcp

# 范围端口
sudo firewall-cmd --permanent --add-port=60000-61000/tcp
```

**关键区别**：`--permanent` 只修改配置文件，**必须 reload 才生效**；这是 firewalld 与 ufw 的最大 UX 差异。

#### 源 IP 控制（富规则 Rich Rules）

firewalld 的富规则比 ufw 更强大，支持 **优先级、时间限制、日志级别**：

```
# 整网段放行任何端口
sudo firewall-cmd --permanent \
  --add-rich-rule='rule family="ipv4" source address=192.168.10.0/24 accept'

# 仅允许特定 IP 访问 MySQL
sudo firewall-cmd --permanent \
  --add-rich-rule='rule family="ipv4" source address=10.0.0.50 port port=3306 protocol=tcp accept'

# 拒绝恶意 IP（带日志）
sudo firewall-cmd --permanent \
  --add-rich-rule='rule family="ipv4" source address=192.168.66.100 log prefix="DROP: " level="notice" drop'

# 时间限制（工作时间放行）
sudo firewall-cmd --permanent \
  --add-rich-rule='rule family="ipv4" source address=10.0.0.0/24 service name=ssh accept limit value="2/m"'
```

#### 连接速率限制

```
# 防暴力破解：30 秒内≥6 次连接 3000/tcp，DROP
sudo firewall-cmd --permanent \
  --add-rich-rule='rule family="ipv4" port port=3000 protocol=tcp limit value="6/m" accept'

# 查看生成的 nftables 规则
sudo nft list chain inet firewalld filter_IN_public_allow
```

#### 服务（Service）抽象

```
# 查看预定义服务
sudo firewall-cmd --get-services
# 输出：ssh dhcpv6-client http https mysql postgresql ...

# 放行服务（比端口更语义化）
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https

# 自定义服务
sudo tee /etc/firewalld/services/custom-app.xml <<'EOF'
<?xml version="1.0" encoding="utf-8"?>
<service>
  <short>Custom App</short>
  <description>My application on 8080 and 8443</description>
  <port protocol="tcp" port="8080"/>
  <port protocol="tcp" port="8443"/>
</service>
EOF
sudo firewall-cmd --reload
sudo firewall-cmd --permanent --add-service=custom-app
```

#### 默认策略与区域

```
# 查看当前生效配置
sudo firewall-cmd --list-all
# 输出解析见下方

# 修改默认区域
sudo firewall-cmd --set-default-zone=drop

# 网卡绑定到特定区域
sudo firewall-cmd --permanent --zone=internal --change-interface=eth1

# 修改区域默认动作
sudo firewall-cmd --permanent --zone=public --set-target=DROP
```

**--list-all 输出详解**：

```
public (active)                    # 当前生效的区域名称
  target: default                  # 默认动作：default/ACCEPT/DROP/REJECT
  icmp-block-inversion: no         # ICMP 是否反向阻止
  interfaces: ens18                # 绑定的网卡
  sources:                         # 源地址白名单/黑名单
  services: ssh dhcpv6-client http # 放行的服务
  ports: 3000/tcp 8080-8090/udp    # 单独放行的端口
  protocols:                       # 放行的协议（如 gre）
  forward: yes                     # 是否允许 IP 转发
  masquerade: no                   # 是否启用 SNAT（源地址转换）
  forward-ports:                   # 端口转发（DNAT）
  source-ports:                    # 源端口限制
  icmp-blocks:                     # 阻止的 ICMP 类型
  rich rules:                      # 富规则列表（按优先级）
    rule family="ipv4" source address=192.168.10.0/24 accept
    rule family="ipv4" source address=10.0.0.100 drop
```

#### 日志管理

```
# 记录所有被拒绝的包
sudo firewall-cmd --set-log-denied=all

# 仅记录特定区域
sudo firewall-cmd --zone=public --set-log-denied=unicast

# 关闭日志
sudo firewall-cmd --set-log-denied=off

# 实时查看
sudo journalctl -k -f | grep -E "REJECT|DROP"
```

#### 完全重置

```
# 停止服务
sudo systemctl stop firewalld

# 清空所有配置
sudo rm -rf /etc/firewalld/zones/*
sudo rm -rf /etc/firewalld/services/custom-*

# 恢复默认并重启
sudo firewall-cmd --reset-to-defaults
sudo systemctl start firewalld
```

------

## 四、ufw vs firewalld：深度对比

| 维度                | **ufw**                    | **firewalld**                    |
| ------------------- | -------------------------- | -------------------------------- |
| **设计目标**        | 极简、快速上手             | 企业级、动态管理                 |
| **默认发行版**      | Ubuntu、Debian             | RHEL、CentOS、Fedora、SUSE       |
| **配置语法**        | 类英文（`allow 22/tcp`）   | 参数式（`--add-port=22/tcp`）    |
| **生效方式**        | 立即生效                   | 运行时立即，永久需 `reload`      |
| **底层路径**        | ufw → iptables → nftables  | firewalld → **直接 nftables**    |
| **区域概念**        | ❌ 无                       | ✅ 多 zone，动态切换              |
| **运行时/永久分离** | ❌ 无（所有规则立即持久化） | ✅ 明确分离，安全测试             |
| **富规则能力**      | 基础（IP、端口、limit）    | 强大（时间、优先级、日志、icmp） |
| **服务抽象**        | 简单（applications.d）     | 完善（XML 定义，内置 100+）      |
| **IPv6 支持**       | 自动，同规则               | 自动，同规则                     |
| **NAT/端口转发**    | 需手动编辑 before.rules    | 原生支持（`--add-forward-port`） |
| **与 Docker 集成**  | 冲突较多                   | 相对友好                         |
| **学习曲线**        | 平缓                       | 陡峭但功能更强                   |

### 4.1 选型建议

| 场景                 | 推荐                            | 理由                            |
| -------------------- | ------------------------------- | ------------------------------- |
| 个人服务器/VPS       | **ufw**                         | 三条命令搞定，不折腾            |
| Ubuntu 云主机        | **ufw**                         | 官方支持，文档丰富              |
| RHEL/CentOS 企业环境 | **firewalld**                   | SELinux 集成，审计合规          |
| 需要动态区域切换     | **firewalld**                   | zone 机制，网络环境变化自动适配 |
| 复杂 NAT/端口转发    | **firewalld**                   | 原生支持，无需手写规则          |
| 容器化环境（K8s）    | **直接 nftables** 或 **Cilium** | 绕过用户层工具，性能最优        |

------

## 五、底层探秘：nftables 原生操作

### 5.1 查看翻译后的规则

```
# 查看 ufw 生成的 nftables 规则
sudo nft list ruleset | grep -A20 "chain ufw-user-input"

# 查看 firewalld 生成的 nftables 规则
sudo nft list ruleset | grep -A20 "chain filter_IN_public"

# 完整规则集
sudo nft list ruleset > /tmp/nftables-rules.txt
```

### 5.2 直接操作 nftables（高级）

```
# 创建表和链
sudo nft add table inet my_filter
sudo nft add chain inet my_filter my_input { type filter hook input priority 0 \; policy drop \; }

# 添加规则
sudo nft add rule inet my_filter my_input tcp dport 22 accept
sudo nft add rule inet my_filter my_input ip saddr 192.168.1.0/24 accept

# 查看
sudo nft list table inet my_filter
```

------

## 六、故障排查速查表

| 现象                  | 排查命令                                   | 解决                               |
| --------------------- | ------------------------------------------ | ---------------------------------- |
| 规则不生效            | `sudo nft list ruleset`                    | 检查是否有 DROP 在前               |
| ufw 启动失败          | `sudo ufw status verbose`                  | 检查 `before.rules` 语法           |
| firewalld reload 报错 | `sudo firewall-cmd --check-config`         | 检查 XML 语法                      |
| Docker 端口绕过防火墙 | `sudo iptables -t nat -L -n`               | 禁用 Docker iptables 或 ufw-docker |
| 日志不记录            | `sudo dmesg | grep -i nft`                 | 检查日志级别和内核模块             |
| 连接数暴涨            | `sudo ss -s` / `sudo conntrack -L | wc -l` | 调整 conntrack 表大小              |



防火墙之ufw与firewall

## 一、现象识别：客户端看到什么？

端口映射失败的**客户端表现**多种多样，准确描述现象是定位的第一步：

| 客户端现象                          | 可能层级    | 关键特征                           |
| ----------------------------------- | ----------- | ---------------------------------- |
| `Connection refused` / `连接被拒绝` | 服务层      | TCP 握手第一步失败，端口无进程监听 |
| `Connection timed out` / `连接超时` | 网络层      | 包到达但无响应，或被中间设备丢弃   |
| `No route to host` / `主机不可达`   | 路由层      | 目标 IP 不可达，或路由表缺失       |
| `SSL handshake failed` / 证书错误   | 应用层      | 端口通但协议不匹配，或证书过期     |
| 页面空白 / 404 / 502                | 应用层      | 端口通、协议通，但后端服务异常     |
| 间歇性通断                          | 性能/安全层 | 连接数超限、WAF 拦截、DDoS 防护    |

**关键认知**：`telnet IP 端口` 和 `curl -v URL` 的输出是**分层定位的黄金线索**。

------

## 二、三层排查法：从近到远，逐层剥离

### 2.1 第一层：本机服务层（服务是否活着？）

**核心问题**：进程是否启动？端口是否监听？绑定地址是否正确？

#### 2.1.1 进程状态检查

```
# 查看进程是否存在
ps aux | grep nginx
systemctl status nginx
docker ps | grep myapp

# 查看端口监听状态（关键！）
sudo ss -tlnp | grep :80
sudo netstat -tlnp | grep :3306

# 现代推荐：ss 替代 netstat
sudo ss -tlnp
# 输出解读：
# LISTEN  0  128  0.0.0.0:80  0.0.0.0:*  users:(("nginx",pid=1234,fd=6))
#         ↑  ↑    ↑           ↑
#         │  │    │           └── 远程地址（* = 任意）
#         │  │    └── 本地地址（0.0.0.0 = 所有网卡）
#         │  └── backlog 队列长度
#         └── 连接状态
```

**致命陷阱**：`127.0.0.1:8080` ≠ `0.0.0.0:8080`

```
# 错误：只绑定本地回环，外部无法访问
tcp    LISTEN   0   128   127.0.0.1:8080   *:*   users:(("python",pid=5678))

# 正确：绑定所有网卡
tcp    LISTEN   0   128   0.0.0.0:8080     *:*   users:(("nginx",pid=1234))
```

**修复**：

```
# Python Flask 示例：显式绑定 0.0.0.0
app.run(host='0.0.0.0', port=8080)

# Nginx 示例：listen 指令
server {
    listen 80;           # 默认 0.0.0.0:80
    listen [::]:80;      # IPv6
}

# Docker 示例：映射到宿主机所有接口
docker run -p 0.0.0.0:8080:80 nginx
# 或简写
docker run -p 8080:80 nginx
```

#### 2.1.2 本机连通性验证

```
# 测试 1：本地回环（验证服务本身正常）
curl -v http://127.0.0.1:8080/health

# 测试 2：本机网卡 IP（验证绑定正确）
curl -v http://192.168.1.10:8080/health

# 测试 3：telnet 验证 TCP 层
telnet 127.0.0.1 8080
# 输出 "Connected" = 服务正常
# 输出 "Connection refused" = 服务未启动或绑定错误
```

**三层结论**：

| 测试结果                        | 结论                   | 下一步                 |
| ------------------------------- | ---------------------- | ---------------------- |
| 127.0.0.1 通，192.168.1.10 不通 | 服务只绑定了 127.0.0.1 | 修改绑定地址为 0.0.0.0 |
| 两者都不通                      | 服务未启动或崩溃       | 查看日志，排查应用层   |
| 两者都通                        | 服务层正常，进入第二层 | 检查服务器防火墙       |

------

### 2.2 第二层：服务器防火墙层（流量被本机拦截？）

**核心问题**：iptables/ufw/firewalld 是否放行？SELinux 是否限制？云厂商安全组是否拦截？

#### 2.2.1 Linux 本地防火墙排查

```
# ===== ufw (Ubuntu/Debian) =====
sudo ufw status verbose
# 输出示例：
# Status: active
# Logging: on (low)
# Default: deny (incoming), allow (outgoing), disabled (routed)
# New profiles: skip
#
# To                         Action      From
# --                         ------      ----
# 22/tcp                     ALLOW IN    Anywhere
# 80/tcp                     ALLOW IN    Anywhere
# 8080/tcp                   DENY IN     10.0.0.0/8      ← 注意！显式拒绝

# 快速放行
sudo ufw allow 8080/tcp
sudo ufw reload

# ===== firewalld (RHEL/CentOS) =====
sudo firewall-cmd --list-all --zone=public
# 输出关键：
#   ports: 22/tcp 80/tcp
#   rich rules:                    ← 检查是否有富规则限制

# 放行并持久化
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

# ===== iptables/nftables (底层) =====
sudo iptables -L INPUT -n -v | grep 8080
sudo nft list ruleset | grep 8080
```

#### 2.2.2 SELinux/AppArmor 排查

```
# SELinux 是否阻止端口绑定？
sudo getenforce                    # Enforcing = 严格模式
sudo grep denied /var/log/audit/audit.log | grep 8080

# 临时关闭测试（危险！仅排查）
sudo setenforce 0

# 永久放行端口
sudo semanage port -a -t http_port_t -p tcp 8080

# AppArmor 排查
sudo aa-status | grep nginx
sudo dmesg | grep apparmor | grep denied
```

#### 2.2.3 云厂商安全组/ACL（最容易遗漏！）

| 云厂商         | 排查位置                        | 常见陷阱                           |
| -------------- | ------------------------------- | ---------------------------------- |
| **阿里云 ECS** | 控制台 → 安全组 → 入方向规则    | 安全组未关联实例                   |
| **腾讯云 CVM** | 控制台 → 防火墙 → 入站规则      | 有"默认安全组"和"自定义"冲突       |
| **AWS EC2**    | Security Groups → Inbound rules | 源 IP 写成了特定地址而非 0.0.0.0/0 |
| **Azure VM**   | Networking → NSG                | 子网 NSG 和 NIC NSG 叠加           |
| **华为云 ECS** | 安全组 → 入方向规则             | 企业项目隔离导致看不到规则         |

**验证命令**（从其他服务器测试）：

```
# 在同一 VPC 的其他机器测试
curl -v http://<目标内网IP>:8080/

# 如果内网通，公网不通 = 安全组或 NAT 网关问题
# 如果内网也不通 = 目标机器防火墙或服务问题
```

#### 2.2.4 第二层验证清单

```
# 完整验证流程（在服务器上执行）
echo "=== 1. 服务监听 ==="
sudo ss -tlnp | grep :8080

echo "=== 2. 本地防火墙 ==="
sudo ufw status numbered 2>/dev/null || sudo firewall-cmd --list-ports

echo "=== 3. SELinux ==="
getenforce

echo "=== 4. 从同网段其他机器测试 ==="
# 在另一台机器执行：
curl -v http://<目标IP>:8080/ 2>&1 | head -20
```

------

### 2.3 第三层：公网映射层（流量到不了服务器？）

**核心问题**：路由器/NAT 网关/负载均衡是否配置正确？公网 IP 是否可达？端口映射是否生效？

#### 2.3.1 家庭/企业路由器端口映射

```
# 典型拓扑
[公网用户] → [路由器公网IP:8080] → [NAT转换] → [内网服务器:80]

# 排查点：
# 1. 路由器虚拟服务器/端口转发配置
#    - 外部端口：8080
#    - 内部 IP：192.168.1.10（必须是静态或 DHCP 保留）
#    - 内部端口：80
#
# 2. 常见错误：
#    - 内网 IP 是 DHCP 自动获取，已变化
#    - 路由器本身防火墙拦截
#    - 运营商封锁 80/443/8080 等端口（国内常见）
```

**运营商封锁检测**：

```
# 从公网 VPS 测试目标公网 IP 的端口
nmap -Pn -p 80,443,8080,8081 <你的公网IP>

# 如果所有端口都 filtered = 运营商或上级防火墙拦截
# 如果 8080 filtered，8081 open = 特定端口被封锁
```

#### 2.3.2 云厂商 NAT 网关/负载均衡

| 产品                   | 排查要点                                    |
| ---------------------- | ------------------------------------------- |
| **阿里云 SLB**         | 监听端口 → 后端服务器组 → 健康检查状态      |
| **腾讯云 CLB**         | 四层/七层监听器 → 转发规则 → 绑定关系       |
| **AWS ALB/NLB**        | Target Group 健康检查 → Security Group 允许 |
| **Nginx/HAProxy 自建** | `proxy_pass` 配置 → `upstream` 后端状态     |

**关键验证**：

```
# 在负载均衡/网关服务器上测试后端
curl -v http://<后端内网IP>:8080/health

# 如果这里不通，问题在网关到服务器之间
# 如果这里通，问题在公网到网关之间
```

#### 2.3.3 CDN/WAF 层拦截

```
# 现象：直接访问源站 IP 正常，访问域名异常
curl -v http://<源站IP>:8080/        # 通
curl -v http://www.example.com:8080/  # 不通或 403

# 可能原因：
# - CDN 只开启了 80/443，未配置 8080
# - WAF 规则拦截（如 User-Agent、IP 地理位置）
# - 证书 SNI 不匹配

# 绕过 CDN 测试
curl -v -H "Host: www.example.com" http://<源站IP>:8080/
```

------

## 三、工具箱：排查神器

### 3.1 网络层工具

```
# ===== 端口连通性 =====
# 快速测试 TCP 端口（比 telnet 更轻量）
nc -vz <IP> <Port>
nc -vz 192.168.1.10 8080

# 全端口扫描（找开放端口）
nmap -p 1-65535 <IP>

# 指定源 IP 测试（多网卡服务器）
nc -s 10.0.0.5 -vz 192.168.1.10 8080

# ===== 路由追踪 =====
# 看包走到哪一跳丢失
traceroute -T -p 8080 <目标IP>    # TCP 模式
mtr -T -P 8080 <目标IP>            # 实时丢包率

# ===== 抓包分析（终极武器） =====
# 服务器侧：看有没有收到 SYN
sudo tcpdump -i any port 8080 -n -S
# 输出 "Flags [S]" = 收到 SYN
# 无输出 = 流量没到，检查上层网络

# 客户端侧：看有没有收到 SYN-ACK
sudo tcpdump -i any host <目标IP> and port 8080
```

### 3.2 应用层工具

```
# ===== HTTP 详细调试 =====
curl -v http://<IP>:8080/           # 完整握手过程
curl -I http://<IP>:8080/           # 只看响应头
curl -H "X-Forwarded-For: 1.2.3.4"  # 模拟代理头

# ===== WebSocket 测试 =====
wscat -c ws://<IP>:8080/socket

# ===== 性能压测（验证并发） =====
ab -n 1000 -c 100 http://<IP>:8080/
wrk -t12 -c400 -d30s http://<IP>:8080/
```

------

## 四、典型案例分析

### 案例 1：Docker 端口映射"灵异"不通

**现象**：

```
docker run -d -p 8080:80 nginx
curl http://localhost:8080/        # 通
curl http://<公网IP>:8080/         # 不通
```

**排查**：

```
# 1. 确认容器监听
docker exec <id> ss -tlnp | grep :80   # 通，容器正常

# 2. 确认宿主机监听
sudo ss -tlnp | grep :8080             # 通，docker-proxy 正常

# 3. 检查 ufw（发现！）
sudo ufw status | grep 8080            # 无输出，未放行

# 4. 放行解决
sudo ufw allow 8080/tcp
```

**根因**：Docker 的 `-p` 只创建 iptables NAT 规则，**不绕过 ufw**。ufw 在 INPUT 链 DROP，流量到不了 docker-proxy。

------

### 案例 2：阿里云安全组"已放行"但不通

**现象**：安全组已添加 `0.0.0.0/0:8080`，但外部仍 timeout。

**排查**：

```
# 1. 在 ECS 上抓包
sudo tcpdump -i eth0 port 8080 -n
# 输出：空！没有收到任何 SYN

# 2. 检查安全组关联
# 控制台 → 实例详情 → 安全组 → 发现绑定了"默认安全组"
# 而规则加在了"自定义安全组"上！

# 3. 解绑旧安全组，绑定新安全组，解决
```

**根因**：一台 ECS 可绑定多个安全组，**实际生效的是交集**，或绑错了安全组。

------

### 案例 3：Nginx 反向代理 502

**现象**：端口通，但返回 502 Bad Gateway。

**排查**：

```
# 1. 检查 Nginx 错误日志
sudo tail /var/log/nginx/error.log
# 输出：connect() failed (111: Connection refused) while connecting to upstream

# 2. 检查 upstream
curl http://127.0.0.1:3000/    # 不通！后端服务崩溃

# 3. 重启后端服务，解决
systemctl restart node-app
```

**根因**：Nginx 监听正常，但 **upstream 后端服务未启动**，不是端口映射问题。

------

## 五、排查流程图（保存备用）

```
开始
  │
  ▼
curl http://127.0.0.1:PORT    # 本机回环测试
  │
  ├──► 不通 ──► 服务未启动/绑定错误 ──► 检查进程日志
  │
  ▼ 通
curl http://<内网IP>:PORT     # 网卡绑定测试
  │
  ├──► 不通 ──► 只绑定了 127.0.0.1 ──► 修改绑定为 0.0.0.0
  │
  ▼ 通
从同VPC其他机器测试           # 内网连通性
  │
  ├──► 不通 ──► 服务器防火墙拦截 ──► ufw/firewalld/安全组
  │
  ▼ 通
从公网测试                   # 完整链路
  │
  ├──► 不通 ──► NAT/路由器/运营商 ──► 检查映射配置、换端口测试
  │
  ▼ 通
完成！
```

------

## 六、一句话速查

| 层级     | 关键命令                                   | 通过标准                   |
| -------- | ------------------------------------------ | -------------------------- |
| 服务层   | `ss -tlnp | grep :PORT`                    | `0.0.0.0:PORT` 或 `*:PORT` |
| 防火墙层 | `ufw status` / `firewall-cmd --list-ports` | 端口在允许列表             |
| 安全组层 | 云控制台 + 同VPC机器测试                   | 内网通，公网不通 = 安全组  |
| 公网层   | `nc -vz <公网IP> PORT`                     | `succeeded!`               |



端口映射失败的排查思路

## 一、环境准备

### 1.1 系统更新与基础工具

```
# 更新系统包（避免旧版本兼容性问题）
sudo apt update && sudo apt upgrade -y

# 安装编译工具链（后续安装 Python 包需要）
sudo apt install -y build-essential python3-pip curl git wget \
    libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
    libsqlite3-dev llvm libncurses5-dev libncursesw5-dev \
    xz-utils tk-dev libffi-dev liblzma-dev
```

**关键说明**：

- `build-essential`：提供 GCC/G++，编译 PyTorch 等库必需
- 开发库（zlib/bzip2/readline 等）：Python 解释器编译依赖

### 1.2 NVIDIA 驱动与 CUDA（略）

> 假设已完成：
>
> - 驱动版本 ≥ 525.60.13（CUDA 12.x 兼容）
> - `nvidia-smi` 正常输出
> - `nvcc --version` 显示 CUDA 12.x

**验证命令**：

```
nvidia-smi  # 应显示 GPU 型号、温度、显存占用
nvcc -V     # 应显示 release 12.x
```

------

## 二、Python 环境：Miniconda 隔离管理

### 2.1 为什么选择 Miniconda？

| 方案          | 优点                                  | 缺点                       |
| ------------- | ------------------------------------- | -------------------------- |
| 系统 Python   | 简单                                  | 包冲突、无法多版本并存     |
| virtualenv    | 轻量                                  | 编译依赖复杂               |
| **Miniconda** | **预编译包、环境隔离、CUDA 自动匹配** | 体积稍大                   |
| Docker        | 完全隔离                              | 调试麻烦、GPU 穿透配置繁琐 |

### 2.2 安装与配置

```
# 下载官方安装脚本（约 100MB）
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

# 静默安装到用户目录（-b 跳过交互，-p 指定路径）
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3

# 加入环境变量（当前 shell 生效）
echo 'export PATH=$HOME/miniconda3/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
conda --version  # 应显示 conda 23.x 或更高
```

### 2.3 创建专用环境

```
# 创建 Python 3.10 环境（LLM 生态最稳定版本）
conda create -n llm python=3.10 -y

# 激活环境（后续所有操作都在此环境）
conda activate llm

# 升级基础工具
pip install --upgrade pip setuptools wheel
```

**环境管理速查**：

```
conda env list          # 查看所有环境
conda deactivate        # 退出当前环境
conda remove -n llm --all  # 删除环境（危险）
```

------

## 三、核心依赖安装：PyTorch 与 Transformers

### 3.1 安装命令

```
# 核心推理栈
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# HuggingFace 生态（模型加载、量化、加速）
pip install transformers accelerate bitsandbytes

# 可选：FlashAttention 加速（需 CUDA 11.6+，A100/H100 推荐）
pip install flash-attn --no-build-isolation
```

### 3.2 关键包功能说明

| 包名           | 作用                  | 关键特性                   |
| -------------- | --------------------- | -------------------------- |
| `torch`        | PyTorch 深度学习框架  | CUDA 加速、自动求导        |
| `transformers` | HuggingFace 模型库    | AutoModel、AutoTokenizer   |
| `accelerate`   | 多卡/混合精度训练推理 | `device_map="auto"`        |
| `bitsandbytes` | 8-bit/4-bit 量化      | `load_in_4bit=True` 省显存 |
| `flash-attn`   | 内存高效 Attention    | 2-4× 速度提升，支持长序列  |

### 3.3 安装验证

```
python -c "
import torch
print(f'PyTorch: {torch.__version__}')
print(f'CUDA available: {torch.cuda.is_available()}')
print(f'CUDA version: {torch.version.cuda}')
print(f'GPU: {torch.cuda.get_device_name(0)}')
print(f'GPU memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB')
"
```

**预期输出**：

```
PyTorch: 2.3.0+cu121
CUDA available: True
CUDA version: 12.1
GPU: NVIDIA A100-SXM4-80GB
GPU memory: 80.0 GB
```

------

## 四、模型下载：魔搭社区（ModelScope）加速

### 4.1 为什么选择 ModelScope？

| 渠道           | 优点                         | 缺点                  |
| -------------- | ---------------------------- | --------------------- |
| HuggingFace    | 最全                         | 国内访问慢，易中断    |
| **ModelScope** | **国内 CDN、速度快、免登录** | 部分新模型滞后        |
| 官方 GitHub    | 源码完整                     | 无 LFS 加速，大文件慢 |
| 百度网盘/迅雷  | 民间镜像                     | 版本混乱、安全风险    |

### 4.2 安装与配置

```
# 安装魔搭客户端
pip install modelscope

# 设置国内镜像（可选，自动识别）
export MODELSCOPE_CACHE=/home/roots/models  # 自定义缓存目录
```

### 4.3 下载模型（以 70B 为例）

```
# 创建模型目录
mkdir -p /home/roots/models/DeepSeek-R1-Distill-Llama-70B

# 最好使用终端复用工具（如tmux）进行下载，防止断开下载连接
# 开始下载（约 140GB，根据网速 30-120 分钟）
# 支持断点续传，中断后重新执行会自动跳过已下载
modelscope download \
    --local_dir /home/roots/models/DeepSeek-R1-Distill-Llama-70B \
    --model deepseek-ai/DeepSeek-R1-Distill-Llama-70B
```

**下载进度监控**：

```
# 另开终端查看
watch -n 5 'du -sh /home/roots/models/DeepSeek-R1-Distill-Llama-70B'
```

### 4.4 模型文件结构验证

```
ls -lh /home/roots/models/DeepSeek-R1-Distill-Llama-70B
```

**预期输出**：

```
total 140G
-rw-r--r-- 1 roots roots  1.5K config.json
-rw-r--r-- 1 roots roots  4.8K generation_config.json
-rw-r--r-- 1 roots roots  9.0G model-00001-of-00015.safetensors
-rw-r--r-- 1 roots roots  9.0G model-00002-of-00015.safetensors
...
-rw-r--r-- 1 roots roots  9.0G model-00015-of-00015.safetensors
-rw-r--r-- 1 roots roots   16K model.safetensors.index.json
-rw-r--r-- 1 roots roots  4.9M tokenizer.json
-rw-r--r-- 1 roots roots  1.1M tokenizer.model
-rw-r--r-- 1 roots roots   51K tokenizer_config.json
```

**关键文件**：

- `config.json`：模型架构配置（层数、隐藏维度、注意力头数）
- `*.safetensors`：模型权重（HuggingFace 安全格式，替代 pickle）
- `tokenizer.*`：分词器（BPE 算法，将文本转为 token ID）

------

## 五、最小推理验证：Transformers 原生加载

### 5.1 编写推理脚本

```
cat > /home/roots/run.py <<'EOF'
#!/usr/bin/env python3
"""
最小化 DeepSeek-R1-Distill-Llama 推理脚本
支持 4-bit 量化，单卡/多卡自动分配
"""

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
import warnings
warnings.filterwarnings("ignore")

# ==================== 配置 ====================
MODEL_PATH = "/home/roots/models/DeepSeek-R1-Distill-Llama-70B"
# 若显存不足，换 8B 版本：
# MODEL_PATH = "/home/roots/models/DeepSeek-R1-Distill-Llama-8B"

QUERY = "你是谁？你能做些什么？请用中文回答。"

# ==================== 加载分词器 ====================
print(f"[1/3] 正在加载分词器: {MODEL_PATH}")
tokenizer = AutoTokenizer.from_pretrained(
    MODEL_PATH,
    trust_remote_code=True,  # DeepSeek 有自定义代码
    padding_side="left"      # 生成模型通常左填充
)

# 设置 pad_token（Llama 系列默认无 pad）
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

# ==================== 加载模型 ====================
print("[2/3] 正在加载模型（4-bit 量化，自动分配设备）...")
model = AutoModelForCausalLM.from_pretrained(
    MODEL_PATH,
    torch_dtype=torch.float16,           # 权重 FP16，计算 FP16
    device_map="auto",                    # 自动分配到所有 GPU
    load_in_4bit=True,                    # 4-bit 量化，显存省 4×
    bnb_4bit_compute_dtype=torch.float16, # 计算时还原 FP16
    bnb_4bit_use_double_quant=True,       # 嵌套量化，再省 0.4 bit
    trust_remote_code=True
)

print(f"    模型设备分布:")
for name, device in model.hf_device_map.items():
    print(f"    - {name}: {device}")

# ==================== 推理 ====================
print("[3/3] 开始推理...")
inputs = tokenizer(QUERY, return_tensors="pt").to("cuda")

# 生成参数
generate_kwargs = {
    "max_new_tokens": 512,      # 最多生成 512 个新 token
    "temperature": 0.7,         # 采样温度（0=确定，1=随机）
    "top_p": 0.9,               # 核采样，保留累积概率 90%
    "repetition_penalty": 1.1,  # 惩罚重复，1.0=无惩罚
    "do_sample": True,          # 启用采样（False=贪心解码）
    "pad_token_id": tokenizer.pad_token_id
}

with torch.no_grad():
    outputs = model.generate(**inputs, **generate_kwargs)

response = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(f"\n{'='*50}")
print(f"用户: {QUERY}")
print(f"AI: {response[len(QUERY):].strip()}")  # 去掉输入部分
print(f"{'='*50}")

# 显存统计
if torch.cuda.is_available():
    print(f"\n显存占用:")
    for i in range(torch.cuda.device_count()):
        mem = torch.cuda.memory_allocated(i) / 1e9
        max_mem = torch.cuda.max_memory_allocated(i) / 1e9
        print(f"  GPU {i}: {mem:.2f} GB / {max_mem:.2f} GB (峰值)")
EOF
```

### 5.2 运行推理

```
# 确保在 llm 环境
conda activate llm

# 运行（首次加载需 2-5 分钟，从磁盘读 140GB）
python /home/roots/run.py
```

**预期输出**：

```
[1/3] 正在加载分词器: /home/roots/models/DeepSeek-R1-Distill-Llama-70B
[2/3] 正在加载模型（4-bit 量化，自动分配设备）...
    模型设备分布:
    - model.embed_tokens: cuda:0
    - model.layers.0-39: cuda:0
    - model.layers.40-79: cuda:1
    - model.norm: cuda:1
    - lm_head: cuda:1
[3/3] 开始推理...

==================================================
用户: 你是谁？你能做些什么？请用中文回答。
AI: 我是 DeepSeek-R1 蒸馏后的 Llama 模型，由 DeepSeek 团队训练。我可以帮助你进行文本生成、代码编写、数学推理、知识问答等任务。我的回答基于训练数据中的模式，但请注意核实重要信息。
==================================================

显存占用:
  GPU 0: 38.5 GB / 40.2 GB (峰值)
  GPU 1: 38.2 GB / 39.8 GB (峰值)
```

------

## 六、生产级部署：vLLM 高性能服务

### 6.1 为什么选择 vLLM？

| 特性       | Transformers          | vLLM                                  |
| ---------- | --------------------- | ------------------------------------- |
| 吞吐量     | 低（逐序列生成）      | **高（连续批处理 + PagedAttention）** |
| 并发支持   | 差                    | **优秀（动态批处理）**                |
| 显存效率   | 一般（KV-Cache 碎片） | **高（分页管理）**                    |
| API 兼容性 | 无                    | **OpenAI 兼容**                       |
| 生产适用性 | 实验/调试             | **在线服务**                          |

### 6.2 安装 vLLM

```
conda activate llm

# 安装指定版本（与 CUDA 12.1 匹配）
pip install vllm==0.5.1

# 或最新版（可能需编译）
pip install -U vllm
```

### 6.3 启动服务（单卡/多卡）

```
# 8B 模型，单卡启动
python -m vllm.entrypoints.openai.api_server \
    --model /home/roots/models/DeepSeek-R1-Distill-Llama-8B \
    --host 0.0.0.0 \
    --port 36000 \
    --dtype half \
    --gpu-memory-utilization 0.9 \
    --trust-remote-code

# 70B 模型，双卡张量并行（需 2×A100-80GB 或 4×A100-40GB）
python -m vllm.entrypoints.openai.api_server \
    --model /home/roots/models/DeepSeek-R1-Distill-Llama-70B \
    --host 0.0.0.0 \
    --port 36000 \
    --dtype half \
    --tensor-parallel-size 2 \
    --quantization bitsandbytes \
    --load-format safetensors \
    --gpu-memory-utilization 0.95 \
    --trust-remote-code \
    --max-model-len 8192 \
    --max-num-seqs 16
```

**参数详解**：

| 参数                       | 说明           | 建议值                      |
| -------------------------- | -------------- | --------------------------- |
| `--model`                  | 本地模型路径   | 绝对路径                    |
| `--host`                   | 监听地址       | `0.0.0.0`（允许外部访问）   |
| `--port`                   | 服务端口       | 36000                       |
| `--dtype`                  | 权重精度       | `half`（FP16）或 `bfloat16` |
| `--tensor-parallel-size`   | 张量并行卡数   | 2/4/8，需整除注意力头数     |
| `--quantization`           | 量化方式       | `bitsandbytes`（8bit/4bit） |
| `--gpu-memory-utilization` | 显存利用率上限 | 0.9-0.95，留余量给 KV-Cache |
| `--max-model-len`          | 最大序列长度   | 模型支持的最大上下文        |
| `--max-num-seqs`           | 最大并发序列数 | 根据显存调整                |

**首次启动**：会自动编译 CUDA kernel，持续 2-3 分钟，看到 `Uvicorn running on http://0.0.0.0:36000` 即成功。

### 6.4 API 调用测试

#### 续写接口（Completions）

```
curl http://localhost:36000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "/home/roots/models/DeepSeek-R1-Distill-Llama-8B",
    "prompt": "如何查看GPU温度？",
    "max_tokens": 80,
    "temperature": 0.7
  }'
```

**响应**：

```
{
  "id": "cmpl-abc123",
  "object": "text_completion",
  "created": 1699999999,
  "model": "/home/roots/models/DeepSeek-R1-Distill-Llama-8B",
  "choices": [{
    "text": "你可以使用 nvidia-smi 命令查看 GPU 温度、功耗和显存占用。",
    "index": 0,
    "logprobs": null,
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 25,
    "total_tokens": 37
  }
}
```

#### 聊天接口（Chat Completions，推荐）

```
curl http://localhost:36000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token-abc123" \
  -d '{
    "model": "/home/roots/models/DeepSeek-R1-Distill-Llama-8B",
    "messages": [
      {"role": "system", "content": "你是一个 helpful 的 AI 助手。"},
      {"role": "user", "content": "你好，你能干什么呢？用中文回答我"}
    ],
    "max_tokens": 200,
    "temperature": 0.7,
    "top_p": 0.9
  }'
```

**字段详解**：

| 字段          | 类型   | 说明                                         |
| ------------- | ------ | -------------------------------------------- |
| `model`       | string | 本地模型绝对路径（vLLM 直接当模型名用）      |
| `messages`    | array  | OpenAI 标准格式，`system`/`user`/`assistant` |
| `max_tokens`  | int    | 最多生成多少新 token（约 0.75 汉字/token）   |
| `temperature` | float  | 0-2，越高越随机，0.7 平衡创意与稳定          |
| `top_p`       | float  | 核采样，0.9 表示从累积概率前 90% 采样        |

### 6.5 性能压测

```
# 安装压测工具
pip install aiohttp

# 并发压测脚本（100 并发，1000 请求）
python -c "
import asyncio, aiohttp, time, json

async def request(session):
    async with session.post(
        'http://localhost:36000/v1/chat/completions',
        json={
            'model': '/home/roots/models/DeepSeek-R1-Distill-Llama-8B',
            'messages': [{'role': 'user', 'content': '你好'}],
            'max_tokens': 50
        }
    ) as resp:
        return await resp.json()

async def main():
    async with aiohttp.ClientSession() as session:
        start = time.time()
        tasks = [request(session) for _ in range(1000)]
        await asyncio.gather(*tasks)
        print(f'1000 请求完成，耗时: {time.time()-start:.2f}s')
        print(f'平均 QPS: {1000/(time.time()-start):.2f}')

asyncio.run(main())
```

------

## 七、生产环境加固

### 7.1 Systemd 服务化

```
sudo tee /etc/systemd/system/vllm-deepseek.service <<'EOF'
[Unit]
Description=vLLM DeepSeek-R1 Service
After=network.target

[Service]
Type=simple
User=roots
Group=roots
WorkingDirectory=/home/roots
Environment="PATH=/home/roots/miniconda3/envs/llm/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
Environment="CUDA_VISIBLE_DEVICES=0,1"
Environment="VLLM_LOGGING_LEVEL=INFO"

ExecStart=/home/roots/miniconda3/envs/llm/bin/python -m vllm.entrypoints.openai.api_server \
    --model /home/roots/models/DeepSeek-R1-Distill-Llama-70B \
    --host 0.0.0.0 \
    --port 36000 \
    --dtype half \
    --tensor-parallel-size 2 \
    --quantization bitsandbytes \
    --gpu-memory-utilization 0.95 \
    --trust-remote-code \
    --max-model-len 8192

Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now vllm-deepseek
sudo systemctl status vllm-deepseek
```

### 7.2 Nginx 反向代理（SSL + 限流）

```
# /etc/nginx/sites-available/vllm
server {
    listen 443 ssl http2;
    server_name llm.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:36000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # 限流：每分钟 100 请求
        limit_req zone=api_limit burst=20 nodelay;
    }
}

# 限流配置（http 块）
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=100r/m;
```

### 7.3 监控与告警（Prometheus + Grafana）

```
# vLLM 自带 metrics 端点
curl http://localhost:36000/metrics

# 关键指标
vllm:gpu_cache_usage_perc        # KV-Cache 使用率
vllm:num_requests_running        # 正在处理的请求数
vllm:time_to_first_token_seconds # 首 token 延迟
vllm:time_per_output_token_seconds # 生成速度
```

------

## 八、故障排查速查表

| 现象                       | 可能原因                | 解决                                        |
| -------------------------- | ----------------------- | ------------------------------------------- |
| `CUDA out of memory`       | 模型太大，显存不足      | 加 `--quantization bitsandbytes` 或换小模型 |
| `RuntimeError: CUDA error` | 驱动/CUDA 版本不匹配    | 重装对应版本 PyTorch                        |
| 生成速度慢                 | 未使用 FP16/BF16        | 加 `--dtype half`                           |
| 首 token 延迟高            | 模型未预热，KV-Cache 空 | 发送 warm-up 请求                           |
| 并发一高就 OOM             | `max-num-seqs` 太大     | 降低 `--max-num-seqs`                       |
| 中文乱码                   | 分词器配置错误          | 检查 `tokenizer_config.json`                |

