Stream on Liangweidong's blog

Nginx 自建镜像实战：前端静态、反向代理、WebSocket 与四层转发

Fri, 15 Sep 2023 00:00:00 +0800

Nginx 容器化部署看似简单——docker run -d -p 80:80 nginx 就能跑——但生产里要解决的是：怎么把前端 dist、nginx.conf、SSL 证书打包成可复用的镜像，而不是每次新环境都 ssh 进去改配置。这篇把多年自建 Nginx 镜像的套路整理清楚。

阅读对象：前端工程师、运维、需要部署 Web 服务的全栈工程师 覆盖范围：前端 dist 打包 + nginx.conf 模板 + 反向代理 / WebSocket / TCP UDP 四层 + SSL + bitnami/nginx 优势对比

一、为什么需要自建 Nginx 镜像

docker run nginx 看似省事，但生产场景里很快撞墙：

前端 dist 在外面：每次新构建都要 docker cp 或 bind mount，配置不统一
nginx.conf 在外面：集群里 5 台机器 5 份配置，改一行同步半天
SSL 证书在容器内：Let’s Encrypt 三个月续期，每台机器都跑一遍 certbot
个性化配置散落：gzip、autoindex、限流、灰度发布，每个项目都要从头写

自建 Nginx 镜像的本质：把"配置 + 静态资源 + 证书"做成不可变的镜像。新机器拉新镜像即用，配置漂移被堵在镜像层之外。

When to use：

同一份前端代码需要部署到多台机器（灰度 / 多机房）

业务方只关心"上传代码 + 重启容器"，不想碰 nginx.conf

团队有统一的反代规范（统一超时、统一 gzip、统一 WebSocket 头）

二、最小化 Dockerfile

1
2
3


FROM dockerhub.example.com/base/nginx:latest
ADD html /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

文件结构：

1
2
3
4
5


.
├── Dockerfile
├── html
│ └── index.html
└── nginx.conf

构建：

1
2
3


docker build -t dockerhub.example.com/library/nginx:20240730 .
docker run -d --restart=always --name apph5 --net=host \
 dockerhub.example.com/library/nginx:20240730

关键点：

ADD html 会把整个目录解压到镜像里，比 COPY html 更适合静态文件（虽然官方推荐 COPY，但 ADD 对本地目录行为一致）
--net=host 让 Nginx 直接监听宿主机端口，省一层 NAT——H5 活动页常用
library/nginx:20240730 用日期做 tag，避免覆盖旧版本

三、生产级 nginx.conf 模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


user root;
worker_processes 1;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
 worker_connections 1024;
}

http {
 include /etc/nginx/mime.types;
 default_type application/octet-stream;

 log_format main '$remote_addr - $remote_user [$time_local] "$request" '
 '$status $body_bytes_sent "$http_referer" '
 '"$http_user_agent" "$http_x_forwarded_for"';

 access_log /var/log/nginx/access.log main;

 sendfile on;
 keepalive_timeout 65;

 # ============ 核心优化 ============
 autoindex on; # 目录浏览（文件服务器场景）

 gzip on; # 开启 gzip
 gzip_buffers 32 4K; # 压缩缓冲
 gzip_comp_level 6; # 压缩级别 1-9，6 是性价比甜蜜点
 gzip_min_length 1k; # 1K 以下不压缩
 gzip_types application/javascript text/css text/xml; # 压缩类型
 gzip_disable "MSIE [1-6]\."; # 兼容老 IE
 gzip_http_version 1.1; # 最低 HTTP 版本
 gzip_vary on; # 传输压缩标志

 # ============ 大文件上传 ============
 client_max_body_size 2000M; # 上传文件大小限制
 client_header_buffer_size 128k;
 large_client_header_buffers 4 128k;

 # ============ 业务 server ============
 server {
 listen 10082;
 server_name location;
 add_header 'Access-Control-Allow-Origin' '*'; # 跨域
 root /usr/share/nginx/html;
 index index.html;
 try_files $uri $uri/ /index.html; # SPA 路由

 # 反向代理后端 API
 location ^~ /api/ {
 proxy_pass http://localhost:9527/;
 }
 }
}

实战要点：

try_files $uri $uri/ /index.html：SPA 路由必备——直接访问 /user/profile 不 404
gzip_types 务必加 application/javascript（不是 text/javascript）——新版 MIME 标准
client_max_body_size 2000M：配合后端 Spring Boot 的 spring.servlet.multipart.max-file-size 一起调
add_header 'Access-Control-Allow-Origin' '*'：只用于开发，生产应该用 https://www.example.com 白名单

四、WebSocket 反向代理

Nginx 反代 WebSocket 关键是保留 Upgrade 头：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# http block 顶部加映射
map $http_upgrade $connection_upgrade {
 default upgrade;
 '' close;
}

# server block 内 location
location /ws/ {
 proxy_pass http://localhost:8080/;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection $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_read_timeout 300s;
 proxy_send_timeout 300s;
}

没加 Upgrade 头时浏览器控制台会报 WebSocket connection to 'ws://...' failed: Invalid frame header。

五、四层转发：TCP / UDP 代理

Nginx 从 1.9 开始支持 stream 模块（四层），可以代理 MySQL、Redis、MQTT、SIP 等非 HTTP 协议。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


# nginx.conf 顶层加 stream block（与 http 同级）
stream {
 log_format proxy '[$time_local] $protocol status:$status, '
 'bytes client:$bytes_sent/$bytes_received $session_time, '
 'client: $remote_addr, upstream:"$upstream_addr", '
 'bytes upstream:$upstream_bytes_sent $upstream_bytes_received';
 access_log /var/log/nginx/stream.log proxy;

 # MySQL 反代
 upstream mysql {
 server 10.0.0.1:3306 max_fails=2 fail_timeout=10s;
 server 10.0.0.2:3306 max_fails=2 fail_timeout=10s;
 }
 server {
 listen 3306;
 proxy_pass mysql;
 proxy_connect_timeout 5s;
 }

 # 端口段转发（PASV FTP 必备）
 server {
 listen 21100-21110;
 proxy_pass 10.0.0.1:$server_port; # $server_port 是动态端口
 }
}

实战案例：FTP 服务主动模式要在客户端出口网络（防火墙 / NAT）做端口段转发，stream 模块就是干这个的。

六、SSL / HTTPS 完整配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


server {
 server_name api.example.com;
 listen 443 ssl;

 ssl_certificate /etc/nginx/ssl/fullchain.pem;
 ssl_certificate_key /etc/nginx/ssl/privkey.pem;

 # 协议版本（生产只开 TLS 1.2+）
 ssl_protocols TLSv1.2 TLSv1.3;

 # 加密套件
 ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
 ssl_prefer_server_ciphers on;

 # session 复用
 ssl_session_cache shared:SSL:10m;
 ssl_session_timeout 1d;
 ssl_session_tickets off;

 # HSTS
 add_header Strict-Transport-Security "max-age=63072000" always;

 # HTTP 强转 HTTPS
 error_page 497 https://$host$request_uri;

 location / {
 proxy_pass http://localhost:9000;
 proxy_set_header Host $http_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;
 }
}

# 80 强转 443
server {
 listen 80;
 server_name api.example.com;
 return 301 https://$server_name$request_uri;
}

证书挂载（推荐用 bind mount 而非 ADD 进镜像）：

1
2
3


docker run -d \
 -v /etc/letsencrypt/live/api.example.com:/etc/nginx/ssl:ro \
 ...

证书 3 个月续期时 nginx -s reload 一下，不用重启容器。

七、bitnami/nginx 镜像优势

bitnami/nginx 相对官方 nginx 镜像有几个明显优势：

特性	官方 `nginx`	`bitnami/nginx`
非 root 用户运行	默认 `root`（安全风险）	默认 uid 1001
默认 HSTS / 安全头	无	有
健康检查	无	`HEALTHCHECK` 内置
日志切分	无	接入 stdout/stderr
镜像体积	~ 140MB	~ 90MB

生产强烈推荐 bitnami 镜像。root 运行的 nginx 容器一旦被攻破就拿到宿主 root——bitnami 默认 nginx 用户运行，减少 90% 的攻击面。

八、生产部署清单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 1. 准备前端 dist
npm run build # 生成 dist/

# 2. 准备 nginx.conf（用上面的模板）

# 3. 准备 SSL 证书
mkdir -p ssl && cp /etc/letsencrypt/live/example.com/* ssl/

# 4. 构建镜像
docker build -t dockerhub.example.com/library/web:20240730 .

# 5. 推到 Harbor
docker push dockerhub.example.com/library/web:20240730

# 6. 生产部署
docker run -d --name web --restart=always \
 --network=web \
 -p 443:443 -p 80:80 \
 -v /data/web/ssl:/etc/nginx/ssl:ro \
 dockerhub.example.com/library/web:20240730

九、监控与日志

日志接入：

1
2
3
4
5
6
7


# 用 Loki / ELK 收集，docker-compose 里加 logging driver
logging:
 driver: loki
 options:
 loki-url: "http://internal.example.com:3100/loki/api/v1/push"
 max-size: "50m"
 max-file: "10"

健康检查：

1
2
3
4
5
6


location /nginx_status {
 stub_status on;
 access_log off;
 allow 127.0.0.1; # 只允许内网
 deny all;
}

容器外查：

1
2
3
4
5


curl http://container-ip/nginx_status
# Active connections: 2
# server accepts handled requests
# 100 100 200
# Reading: 0 Writing: 1 Waiting: 1

十、常见坑位

10.1 反代后端丢失 HTTPS 信息

后端 Spring Boot 拿到 request.getScheme() 是 http 不是 https——因为 nginx 用 HTTP 协议连后端。

修复：后端配 server.tomcat.remoteip.protocol-header=X-Forwarded-Proto，或 Nginx 显式传：

1

proxy_set_header X-Forwarded-Proto $scheme;

10.2 SPA 路由 404

直接访问 https://app.example.com/user/profile 返回 404。

修复：try_files $uri $uri/ /index.html;——所有未匹配路径都返回 index.html，由前端路由处理。

10.3 WebSocket 反复断连

症状：WSS 连接 60 秒断一次。

原因：默认 proxy_read_timeout 60s，WebSocket 是长连接，超过 60 秒没数据就被切断。

修复：proxy_read_timeout 300s; 或更长。

10.4 gzip 对小文件无效果

gzip_min_length 1k; 控制 1KB 以下的文件不压缩——gzip_types 只决定"压缩什么类型"，文件大小阈值由 min_length 控制。

2024+ 视角补充

本文写于 2023-09，2024-2026 期间 Nginx 自建镜像关键演进：

Nginx 1.27 LTS（2024-11）：HTTP/3（QUIC）GA；OpenSSL 3.x；动态 SSL 证书加载
Nginx 1.28 LTS（2025-Q4 预期）：ACMEv2 自动证书（不用 certbot）；BoringSSL 可选
Nginx Unit 1.34+（2024-2026）：应用服务器模式（Go / Node / Python / Java / PHP）——Web + App Server 一体
Nginx Ingress 1.12+（K8s）：Gateway API GA；IPV6 双栈；WAF 集成
OpenResty 1.25+：Lua 生态成熟，API Gateway / WAF 场景仍是首选
bitnami/nginx 镜像：2024+ 仍维护，非 root 用户 / 健康检查仍是优势
替代品（2024+ 视角）：
- Caddy 2.x：自动 HTTPS / Caddyfile 简洁——新项目首选
- Traefik 3.x：K8s 原生 / 自动服务发现
- HAProxy 3.x：四层代理性能优于 Nginx——数据库 / TCP 代理首选

实战建议（2025-2026 视角）：

传统 Web 反代 / 静态站 → Nginx 1.27 LTS 仍是生产首选
想要最少配置 / 自动 HTTPS → Caddy 2.x
K8s 入口 → Nginx Ingress 1.12+ / Traefik 3.x / Gateway API
API Gateway / WAF → OpenResty 1.25+ 仍是稳态
数据库 / TCP 代理 → HAProxy 3.x

下一步

想看 Go 自建最小镜像（scratch 5MB 级别）→ Go 自建最小镜像
想看 MinIO 对象存储实战（含 Nginx 反代安全加固）→ MinIO 对象存储实战
想看 Java 微服务治理（Sentinel 限流 / Spring Boot Admin）→ Java 微服务治理

FTP 服务自托管：vsftpd / pure-ftpd 主被动模式 + Nginx stream + SSL

Mon, 15 Mar 2021 00:00:00 +0800

FTP 是企业里"老但稳定"的文件传输方案——服务器间脚本同步、备份归档、跨地域传输都还在用。本篇把 vsftpd 与 pure-ftpd 的 Docker 化部署、主被动模式原理、Nginx stream 四层代理、SSL 加密整理清楚。

阅读对象：运维 / 部署工程师、需要搭建内部文件服务器的技术团队 覆盖范围：FTP 主动 / 被动模式原理 + vsftpd 完整部署 + pure-ftpd 完整部署 + 虚拟用户 + SSL/TLS 加密 + Nginx stream 反代 + 常见客户端测试

一、FTP 协议基础

1.1 两个端口

端口	作用
21	控制端口（命令）
20	数据端口（仅主动模式）

主动模式（PORT）：服务器从 20 端口主动连客户端告知的端口。 被动模式（PASV）：服务器告知客户端自己的地址 + 端口，等客户端来连。

实战推荐被动模式——客户端不用开端口，服务器在公网就行。

1.2 主动 vs 被动模式

维度	主动模式	被动模式
数据连接	服务器 → 客户端	客户端 → 服务器
客户端要求	必须有公网 IP	任何网络
防火墙	客户端要放行随机端口	服务器要放行 PASV 端口段
适用	内网	公网推荐

核心难点：FTP 协议需要 2 个连接，NAT / 防火墙容易把数据连接搞断——必须正确配置。

二、vsftpd 部署

vsftpd（Very Secure FTPD）是 Linux 默认 FTP 服务端，最稳定。

2.1 拉取镜像

1

docker pull fauria/vsftpd

2.2 启动容器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 测试端口占用
lsof -i:21100-21110

# 启动
docker run -d --name vsftpd --restart=always \
 -p 20:20 \
 -p 21:21 \
 -p 21100-21110:21100-21110 \
 -v /home/docker/vsftpd/data:/home/vsftpd \
 -v /home/docker/vsftpd/log:/var/log \
 -e FTP_USER=www \
 -e FTP_PASS={{REDACTED}} \
 -e PASV_ADDRESS=203.0.113.10 \
 -e PASV_MIN_PORT=21100 \
 -e PASV_MAX_PORT=21110 \
 -e REVERSE_LOOKUP_ENABLE=NO \
 fauria/vsftpd

关键参数：

PASV_ADDRESS=203.0.113.10：服务器公网 IP——必须设对，否则客户端连不上
PASV_MIN_PORT / MAX_PORT：PASV 模式端口段——防火墙必须放行
REVERSE_LOOKUP_ENABLE=NO：强烈推荐——避免 DNS 反向解析卡登录

2.3 完整环境变量

变量	默认	说明
`FTP_USER`	`admin`	默认用户
`FTP_PASS`	随机 16 位	不指定就随机
`PASV_ADDRESS`	Docker host IP	配服务器公网 IP
`PASV_ADDR_RESOLVE`	`NO`	主机名解析
`PASV_ENABLE`	`YES`	启用被动模式
`PASV_MIN_PORT`	`21100`	PASV 起始端口
`PASV_MAX_PORT`	`21110`	PASV 结束端口
`REVERSE_LOOKUP_ENABLE`	`YES`	设为 NO 加快登录
`PASV_PROMISCUOUS`	`NO`	关闭被动模式安全检查
`PORT_PROMISCUOUS`	`NO`	关闭主动模式安全检查

2.4 手动创建用户

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 进入容器
docker exec -i -t vsftpd bash

# 创建用户目录
mkdir /home/vsftpd/myuser

# 写虚拟用户
echo -e "myuser\nmypass" >> /etc/vsftpd/virtual_users.txt

# 转换数据库
/usr/bin/db_load -T -t hash -f /etc/vsftpd/virtual_users.txt /etc/vsftpd/virtual_users.db

# 退出并重启
exit
docker restart vsftpd

2.5 生成 SSL 证书

1
2
3
4
5


# 创建自签证书（生产用 Let's Encrypt）
openssl req -x509 -nodes -days 365 \
 -newkey rsa:2048 \
 -keyout /etc/vsftpd/vsftpd.pem \
 -out /etc/vsftpd/vsftpd.pem

挂载到容器：

1

-v /home/docker/vsftpd/ssl/vsftpd.pem:/etc/vsftpd/vsftpd.pem:ro

在 vsftpd.conf 加：

1
2
3
4
5
6
7
8


ssl_enable=YES
ssl_tlsv1=YES
ssl_sslv2=NO
ssl_sslv3=NO
require_ssl_reuse=NO
ssl_ciphers=HIGH
rsa_cert_file=/etc/vsftpd/vsftpd.pem
rsa_private_key_file=/etc/vsftpd/vsftpd.pem

客户端必须选"显式 TLS"（FTPS），不是 SFTP（SSH 文件传输）。

三、pure-ftpd 部署

pure-ftpd 是另一个流行的 FTP 服务端，虚拟用户管理更灵活。

3.1 拉取镜像

1

docker pull stilliard/pure-ftpd

3.2 启动容器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


docker run -d --name ftp --restart=always \
 -p 20-21:20-21 \
 -p 30000-30009:30000-30009 \
 -v /home/ftp/conf:/etc/pure-ftpd/passwd \
 -v /home/ftp/data:/home/ftpusers/www \
 -v /home/ftp/data:/home/ftp \
 -e "PUBLICHOST=localhost" \
 stilliard/pure-ftpd \
 /bin/bash -c "useradd ftp; \
 usermod -d /home/ftp ftp; \
 /run.sh -c 100 -C 10 \
 -l puredb:/etc/pure-ftpd/pureftpd.pdb \
 -j -i -R \
 -P 10.0.0.1 -p 30000:30009"

3.3 参数详解

参数	含义
`-c 100`	最大客户端数 100
`-C 10`	每 IP 最多 10 个连接
`-l puredb:...`	虚拟用户文件
`-j`	自动创建家目录
`-i`	匿名用户不允许上传
`-R`	不允许 chmod
`-P 10.0.0.1`	PASV 模式告知客户端的 IP
`-p 30000:30009`	PASV 端口段

3.4 虚拟用户管理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# 进入容器
docker exec -it ftp /bin/bash

# 添加用户 www（密码 {{REDACTED}}）
pure-pw useradd www \
 -f /etc/pure-ftpd/passwd/pureftpd.passwd \
 -m \
 -u ftpuser \
 -d /home/ftpusers/www

# 修改家目录权限
chmod -R 777 /home/ftp/data/

# 删除用户
pure-pw userdel www -f /etc/pure-ftpd/passwd/pureftpd.passwd -m

# 查看用户列表
pure-pw list -f /etc/pure-ftpd/passwd/pureftpd.passwd

3.5 验证测试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 1. 在宿主机创建文件
touch /home/ftp/data/test.txt

# 2. 浏览器访问（匿名）
ftp://<SERVER_IP>:21
# 应该能看到 test.txt（无需密码）

# 3. FTP 工具连接
# 用户名 www，密码 {{REDACTED}}
# 看到 test.txt，能下载能上传能删除

# 4. 主被动模式测试
# 在客户端（FileZilla）切换主动 / 被动模式，都能正常上传下载

3.6 清理

1
2


docker rm -f ftp
rm -rf /home/ftp

四、Nginx stream 四层代理

FTP 服务器在内网，要暴露到公网？Nginx stream 模块做四层代理。

4.1 完整 stream 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


stream {
 # FTP 控制端口
 upstream ftp_control {
 server 10.0.0.1:21;
 }
 server {
 listen 21;
 proxy_pass ftp_control;
 proxy_connect_timeout 1s;
 proxy_timeout 10m;
 }

 # FTP 主动模式数据端口（20）
 upstream ftp_data {
 server 10.0.0.1:20;
 }
 server {
 listen 20;
 proxy_pass ftp_data;
 proxy_connect_timeout 1s;
 proxy_timeout 10m;
 }

 # PASV 端口段
 server {
 listen 21100-21110;
 proxy_pass 10.0.0.1:$server_port; # $server_port 是动态端口
 }
}

关键点：

proxy_pass 10.0.0.1:$server_port：动态端口转发——客户端连 21100 转到 21100，21101 转到 21101
proxy_timeout 10m：10 分钟无数据不切断——大文件传输必备
proxy_upload_rate / proxy_download_rate：限速（生产推荐）

1
2
3
4
5
6


server {
 listen 21100;
 proxy_pass 10.0.0.1:21100;
 proxy_upload_rate 10240k; # 上传限速 10MB/s
 proxy_download_rate 20480k; # 下载限速 20MB/s
}

4.2 SSL / FTPS 代理

FTPS（FTP over TLS）的四层代理较复杂——TLS 加密流无法被 Nginx 解密再加密。

推荐方案：

用 HAProxy（原生支持 SSL 透传）
或直接在 FTP 服务器端处理 TLS，Nginx 只代理明文

五、客户端使用

5.1 命令行

1
2
3
4
5
6
7
8


# 上传 / 下载测试
curl -u www:{{REDACTED}} ftp://203.0.113.10/k8s/test.sh | bash

# 列出
curl -u www:{{REDACTED}} ftp://203.0.113.10/

# 主动模式
curl -u www:{{REDACTED}} --ftp-port - ftp://203.0.113.10/file

5.2 FileZilla

跨平台 FTP 客户端，首选：

1
2
3
4


主机：203.0.113.10
用户名：www
密码：{{REDACTED}}
端口：21

关键设置：

传输模式：被动（推荐）
加密：显式的 TLS（FTPS）

5.3 WinSCP（Windows）

适合自动化脚本（批处理）：

1
2
3
4
5


@echo off
"C:\Program Files\WinSCP\WinSCP.com" ^
  /command "open ftp://www:{{REDACTED}}@203.0.113.10/" ^
  "put C:\local\file.zip /remote/file.zip" ^
  "exit"

5.4 lftp（Linux 推荐）

1
2
3
4
5


# 批量上传
lftp -u www,{{REDACTED}} -e "mirror -R /local/path /remote/path" 203.0.113.10

# 加密传输
lftp -u www,{{REDACTED}} -e "set ftp:ssl-force true; set ftp:ssl-protect-data true; ls" 203.0.113.10

六、典型坑位

6.1 登录成功但列不出文件

症状：PASV 模式登录后卡住，服务器等待客户端连数据端口。

原因：

PASV_ADDRESS 没设对
防火墙没放行 PASV 端口段
Nginx 反代没配端口段转发

修复：

1
2
3
4
5


# 1. 确认 PASV_ADDRESS 是公网 IP（不是 127.0.0.1）
echo $PASV_ADDRESS
# 2. 防火墙放行
iptables -A INPUT -p tcp --dport 21100:21110 -j ACCEPT
# 3. Nginx stream 加端口段

6.2 主动模式连不上

症状：PORT 模式报 “Connection refused”。

原因：服务器 20 端口主动连客户端，客户端在 NAT / 防火墙后。

修复：改用 PASV 模式，别折腾主动模式。

6.3 上传文件 0 字节

症状：客户端显示上传成功，服务器文件是 0 字节。

原因：PASV 端口被防火墙 drop 掉了。

修复：

1
2
3
4
5


# 1. tcpdump 看数据连接
tcpdump -i any port 21100-21110

# 2. 防火墙状态
iptables -L -n | grep 21100

6.4 vsftpd 启动报 “500 OOPS”

修复：

1
2
3
4
5
6
7


# 容器内检查 vsftpd.conf
docker exec vsftpd cat /etc/vsftpd/vsftpd.conf | grep -v "^#" | grep -v "^$"

# 常见错误：listen_ipv6=YES + listen=YES 冲突
# 修法：二选一
echo "listen=YES" >> /etc/vsftpd/vsftpd.conf
echo "listen_ipv6=NO" >> /etc/vsftpd/vsftpd.conf

七、vsftpd vs pure-ftpd 选型

维度	vsftpd	pure-ftpd
性能	高	中等
稳定性	极高	高
配置	简洁	灵活
虚拟用户	手动 db_load	pure-pw 命令行
TLS / SSL	支持	支持
Docker 镜像	官方 vsftpd / fauria	stilliard
适合	生产 / 简单场景	多用户 / 复杂权限

简单场景选 vsftpd（稳定为先），多用户管理选 pure-ftpd（命令行友好）。

八、生产安全清单

8.1 强制 TLS

vsftpd：

1
2
3
4
5
6
7
8


ssl_enable=YES
allow_anon_ssl=NO
force_local_data_ssl=YES
force_local_logins_ssl=YES
ssl_tlsv1=YES
ssl_sslv2=NO
ssl_sslv3=NO
require_ssl_reuse=NO

pure-ftpd：

1
2


echo "TLS 1" > /etc/pure-ftpd/conf/TLS
# 把证书放到 /etc/ssl/private/pure-ftpd.pem

8.2 限制用户目录

1
2
3


# vsftpd
chroot_local_user=YES
allow_writeable_chroot=YES

1
2


# pure-ftpd
echo "YES" > /etc/pure-ftpd/conf/ChrootEveryone

8.3 限速

1
2
3


# vsftpd
local_max_rate=1024000 # 1MB/s
anon_max_rate=512000 # 500KB/s

8.4 禁用匿名

1

anonymous_enable=NO

8.5 fail2ban 防爆破

1
2
3
4
5
6
7
8


# /etc/fail2ban/jail.local
[vsftpd]
enabled = true
port = ftp,ftp-data,ftps,ftps-data
filter = vsftpd
logpath = /var/log/vsftpd.log
maxretry = 5
bantime = 3600

九、监控与日志

9.1 vsftpd 日志

1
2
3
4
5
6
7


# 容器内
docker exec vsftpd tail -f /var/log/vsftpd.log

# 输出示例
Mon May 21 03:00:00 2021 [pid 1] CONNECT: Client "1.2.3.4"
Mon May 21 03:00:01 2021 [pid 1] [www] OK LOGIN: Client "1.2.3.4"
Mon May 21 03:00:05 2021 [pid 1] [www] OK UPLOAD: Client "1.2.3.4", "/file.zip", 12345 bytes, 1.2 MB/s

9.2 pure-ftpd 日志

1

docker exec ftp tail -f /var/log/pure-ftpd/pureftpd.log

9.3 接入 Loki

1
2
3
4


logging:
 driver: loki
 options:
 loki-url: "http://internal.example.com:3100/loki/api/v1/push"

十、卸载清理

1
2
3
4
5
6
7


# vsftpd
docker rm -f vsftpd
rm -rf /home/docker/vsftpd

# pure-ftpd
docker rm -f ftp
rm -rf /home/ftp

十一、2024+ 视角补充

本文写于 2021-03，2024-2026 这几年里"FTP 该不该用"的共识有明显变化：

FTP 整体趋势：FTP 协议在 2020s 越来越被视为遗留技术——所有主流浏览器（Chrome、Firefox、Edge、Safari）自 2020-2021 起就在逐步淘汰 FTP 协议。RFC 959 设计于 1985，默认明文传输是致命伤（用户名/密码/文件内容全裸奔）。2024+ 的新项目，优先选 SFTP / HTTPS / MinIO / S3 兼容对象存储：

场景	2021 主流	2024+ 推荐	理由
内部脚本同步	FTP/FTPS	SFTP（SSH 自带）	SSH 默认安全，无需额外服务
跨地域文件交换	FTP 服务器	MinIO / S3 兼容对象存储	签名 URL、版本控制、跨域复制
浏览器下载	FTP URL	HTTPS + 静态站点	浏览器已不再支持 `ftp://` 链接
客户端工具上传	FileZilla/FTP	rclone + S3 兼容	增量同步、加密、断点续传
老设备/老协议对接	FTP	FTP/FTPS（保留）	无替代品时仍可用

vsftpd / pure-ftpd 项目现状：

vsftpd 仍维护，但 2024 年发布节奏明显放缓（最后大版本 3.0.5 在 2021）。新特性很少，主要是 CVE 修复
pure-ftpd 状态类似。社区分裂（部分分支用 Rust 重写，但未成熟）
ProFTPD 仍活跃（2024-2025 有 1.3.8+ 发布），但市场份额不大
新部署不推荐用这俩老牌项目，能用 SFTP 就用 SFTP

SFTP 容器化（vsftpd 替代）：

1
2
3
4
5
6
7
8


# atmoz/sftp 是 2024+ 最流行的自托管 SFTP 镜像
docker run -d \
 --name sftp \
 -p 2222:22 \
 -v /home/sftp/users.conf:/etc/sftp/users.conf:ro \
 -v /home/sftp/data:/home \
 atmoz/sftp \
 www:{{REDACTED}}:1001:1001:upload

users.conf 一行一个用户：用户名:密码:UID:GID:家目录——比 vsftpd 虚拟用户简单。

FTP 仍必要的场景（2024 仍存在）：

老的工业设备（数控机床、医疗仪器）只支持 FTP 上报数据
老的 ERP / 财务系统只支持 FTP 文件交换
与海外客户的 B2B 集成（对方系统只懂 FTP）
备份归档脚本（老脚本不愿重写）

这些场景的加固清单：

必须 FTPS（FTP over TLS），不能明文
必须 fail2ban
必须 chroot + 限制用户家目录
必须限速（防 DoS）
定期审计：看 /var/log/vsftpd.log 谁连了、传了什么
计划退出：列入"2026 技术债清单"，逐年替换

生产实践补充（2024 更新）：

HAProxy 替代 Nginx stream 做 FTPS 四层代理（Nginx stream 透传 TLS 麻烦）
CrowdSec 替代 fail2ban：社区共享 IP 黑名单，更新更频繁（2024 主流）
Caddy + sftp-bridge：Caddy 2024+ 原生支持 SFTP 代理，可以少一层 vsftpd

十二、最佳实践清单

PASV 模式 + 公网 IP：避免主动模式 NAT 问题
PASV_ADDRESS 必填：客户端才知道连哪里
PASV 端口段防火墙放行：21100-21110（或自定义）
Nginx stream 四层代理：内网 FTP 暴露公网
强制 TLS / SSL：FTPS 而非明文 FTP
chroot 限制用户家目录：防止越权访问
限速：避免大文件占满带宽
禁用匿名：除非业务需要
fail2ban / CrowdSec 防爆破：5 次失败封 1 小时
定期清理日志：vsftpd.log 不会自动 rotate
新项目优先 SFTP / S3：FTP 仅作为兼容老系统的备选

下一步

想看 NextCloud 网盘自托管（家用云盘）→ NextCloud 网盘自托管
想看 Seafile 私有云盘（高性能文件同步）→ Seafile 私有云盘
想看 Cloudreve 网盘（多存储后端）→ Cloudreve 网盘
想看 MinIO 对象存储实战（S3 兼容对象存储）→ MinIO 对象存储实战
想看 Nginx 自建镜像实战（含 stream 四层）→ Nginx 自建镜像实战

Nginx stream 四层 TCP 代理实战：MSTSC 远程桌面透传与排错

Sun, 15 Sep 2013 00:00:00 +0800

背景

Nginx 早期是 HTTP（七层）反代神器，但从 1.9.0（2015 年）开始，ngx_stream_core_module 提供了四层（TCP/UDP）代理——能代理任何 TCP 协议：

RDP（Windows 远程桌面 3389）
MySQL、Redis、MongoDB
SSH
SMTP、POP3
游戏服务器
自定义 TCP 协议

与 HAProxy/LVS 对比：

维度	Nginx stream	HAProxy	LVS
学习成本	最低	中	高
性能	中等	强	最强
七层能力	同时支持	同时支持	不支持
适用规模	中小（< 5w QPS）	大	超大

典型场景：公司有几台 Windows 服务器，通过一台 Linux 反代把不同端口的 RDP 流量透明转发到不同后端，外网只暴露一个 VIP。

一、Nginx stream 模块基础

1.1 编译参数

stream 模块不是默认编译的，需要 --with-stream：

1
2
3


nginx -V
# 看是否有 --with-stream
# 如果没有，要重编译

重编译步骤：

1
2
3
4
5
6
7


# 看现有参数
nginx -V
# 在最后加 --with-stream
./configure <原参数> --with-stream
make
# 不要 make install（会覆盖），手动替换二进制
cp objs/nginx /usr/local/nginx/sbin/nginx

1.2 配置结构

/etc/nginx/nginx.conf：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 顶层 stream 块（与 http 同级）
stream {
 log_format proxy '$remote_addr [$time_local] '
 '$protocol $status $bytes_sent $bytes_received '
 '$session_time "$upstream_addr" '
 '$upstream_bytes_sent $upstream_bytes_received '
 '$upstream_connect_time';
 
 # 引入 conf.d/ 下的所有 stream 配置
 include /etc/nginx/stream/*.conf;
}

/etc/nginx/stream/rdp.conf：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


upstream rdp_pool {
 hash $remote_addr consistent; # 同一客户端固定连同一后端
 server 10.0.0.10:3389 max_fails=3 fail_timeout=30s;
 server 10.0.0.11:3389 max_fails=3 fail_timeout=30s;
}

server {
 listen 3390; # 外网端口
 proxy_pass rdp_pool; # 转发到 upstream
 proxy_connect_timeout 10s;
 proxy_timeout 300s;
 
 # 自定义日志
 access_log /var/log/nginx/rdp_access.log proxy;
 error_log /var/log/nginx/rdp_error.log;
}

关键点：

stream 块在顶层（与 http 同级），不在 http 里面
监听端口不能与 http 块冲突
没有 server_name、没有 location（四层只看 IP:Port）

二、MSTSC 远程桌面透传实战

场景：公网 IP 47.104.152.64，Windows 内网 RDP 真实地址 10.0.0.10:3389。

2.1 完整配置

1
2
3
4
5
6
7
8
9


stream {
 log_format proxy '[$time_local] $protocol status:$status, '
 'bytes client:$bytes_sent/$bytes_received $session_time, '
 'client: $remote_addr, upstream:"$upstream_addr", '
 'bytes upstream:$upstream_bytes_sent $upstream_bytes_received '
 '$upstream_connect_time';
 
 include /etc/nginx/stream/*.conf;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# /etc/nginx/stream/rdp.conf
upstream mstsc {
 hash $remote_addr consistent;
 server 10.0.33.101:3389 max_fails=3 fail_timeout=30s;
}

server {
 error_log /var/log/nginx/101_3399_error.log;
 access_log /var/log/nginx/101_3399_access.log proxy;
 listen 3399; # 外网访问 3399
 proxy_connect_timeout 10s;
 proxy_timeout 300s;
 proxy_pass mstsc;
}

客户端连接：mstsc /v:47.104.152.64:3399

2.2 日志样例

1
2
3


[25/Apr/2017:17:55:57 +0800] TCP status:200, bytes client:103/122 10.671, 
client: 192.168.3.218, upstream: "192.168.1.176:59001" 
bytes upstream:122/103 0.000

字段解读：

bytes client:103/122：客户端发送 103 字节，接收 122 字节
client: 192.168.3.218：客户端真实 IP（不是 47.104.152.64）
upstream: "192.168.1.176:59001"：Nginx 主动连到 Windows 的源端口
bytes upstream:122/103：Nginx 转发给后端的字节数

三、Nginx HTTP 反代的 9 大 buffer 调优

常见 warning（Nginx error.log）：

1

an upstream response is buffered to a temporary file

原因：Nginx 默认的 buffer 太小，每个请求的缓存不够，请求头 header 太大或响应体超过 buffer 时，写入磁盘临时文件，造成 IO 飙升，访问卡顿。

3.1 完整 buffer 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


http {
 # client body（上传）
 client_max_body_size 2048m; # 最大上传 2GB
 client_body_buffer_size 1024k; # body 缓冲 1MB
 
 # proxy buffer
 proxy_buffer_size 256k; # header 缓冲 256K
 proxy_buffering on; # 开启缓冲（默认 on）
 proxy_buffers 64 128k; # 64 个 128K 缓冲（共 8MB）
 proxy_busy_buffers_size 512k; # 忙缓冲 512K（不能 > proxy_buffers 总和/2）
 
 # FastCGI buffer（PHP-FPM）
 fastcgi_buffer_size 512k; # header 缓冲
 fastcgi_buffers 6 512k; # 6 个 512K 缓冲（共 3MB）
 fastcgi_busy_buffers_size 512k; # 忙缓冲
 fastcgi_temp_file_write_size 512k; # 临时文件写入块大小
 fastcgi_intercept_errors on; # 拦截错误（4xx/5xx 自己处理）
}

3.2 各项调优解释

配置	作用	调优建议
`client_max_body_size`	最大请求体（POST 上传）	按业务定，文件上传建议 1g+
`client_body_buffer_size`	客户端 body 缓冲	16k ~ 1m
`proxy_buffer_size`	后端响应头缓冲	4k ~ 32k，大响应头可调到 128k
`proxy_buffers`	后端响应体缓冲（数量 × 单个大小）	通常 `8 16k` 或 `64 128k`
`proxy_busy_buffers_size`	正在发送的缓冲上限	必须 < `proxy_buffers` 总和的 1/2
`proxy_temp_file_write_size`	临时文件单次写入大小	默认 8k，调大可减少 IO 次数
`fastcgi_intercept_errors`	Nginx 拦截 FastCGI 错误	`on` 配合 `error_page` 自定义错误页

3.3 调优公式

总 buffer = proxy_buffer_size + proxy_buffers × 数量

例：proxy_buffers 64 128k = 64 × 128K = 8MB 单连接缓存

繁忙 buffer = proxy_busy_buffers_size × 2 ≤ 总 buffer

例：512k × 2 = 1MB ≤ 8MB ✓

四、Connection reset by peer 排错

完整错误：

1
2
3
4


recv() failed (104: Connection reset by peer) 
while proxying and reading from upstream, 
client: 89.248.163.87, server: 0.0.0.0:3399, 
upstream: "10.8.33.101:3389"

104 错误 = TCP RST，连接被对端强制关闭。

常见原因：

后端服务主动断开（如 Windows RDP 服务异常）
后端超时未响应，TCP keepalive 触发 RST
后端资源耗尽（CPU 100%、连接数打满）
Nginx 与后端的网络问题（中间设备丢包）

4.1 调优配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


upstream bigdata {
 server 10.0.20.1:18018;
 server 10.0.20.2:18018;
 server 10.0.20.3:18018;
 server 10.0.20.4:18018;
 keepalive 100; # Nginx 与上游保持的长连接数
}

location / {
 proxy_pass http://bigdata;
 
 # 加大超时（默认 60s 偏短）
 proxy_connect_timeout 120;
 proxy_send_timeout 120;
 proxy_read_timeout 120;
 
 # 关键：启用 HTTP/1.1 + 清理 Connection header
 proxy_http_version 1.1;
 proxy_set_header Connection "";
}

关键点：

配置	作用
`keepalive 100`	Nginx 与每个上游保持 100 个长连接（连接复用）
`proxy_http_version 1.1`	必须 1.1——HTTP/1.0 不支持 keep-alive
`proxy_set_header Connection ""`	清掉 `Connection: close`，让 keep-alive 生效

为什么 HTTP/1.1 + Connection "" 必加？

HTTP/1.0 的 Connection: keep-alive 是可选的，HTTP/1.1 默认 keep-alive 但 Connection: close 可以强制关闭。Nginx 默认往上游发的 Connection: close（不重用连接），所以必须显式清掉。

五、实战：MySQL stream 代理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


stream {
 upstream mysql_pool {
 server 10.0.0.10:3306;
 server 10.0.0.11:3306;
 }
 
 server {
 listen 33306;
 proxy_pass mysql_pool;
 proxy_connect_timeout 5s;
 proxy_timeout 600s;
 }
}

客户端连接：

1

mysql -h <nginx-ip> -P 33306 -u root -p

注意：MySQL 认证是基于 IP 的，代理后所有客户端都是 nginx-ip，可能触发 host 'nginx-ip' is not allowed。对策：

MySQL 授权时用 'root'@'%'
或在 MySQL 端用 skip-name-resolve

六、实战：Redis stream 代理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


stream {
 upstream redis_pool {
 server 10.0.0.10:6379;
 }
 
 server {
 listen 36379;
 proxy_pass redis_pool;
 proxy_connect_timeout 5s;
 proxy_timeout 300s;
 }
}

Redis 协议简单，stream 代理几乎零问题。

七、SSL/TLS over stream

stream 块也支持 SSL（需 --with-stream_ssl_module）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


stream {
 upstream mysql_ssl {
 server 10.0.0.10:3306;
 }
 
 server {
 listen 33307 ssl;
 proxy_pass mysql_ssl;
 ssl_certificate /etc/nginx/ssl/server.crt;
 ssl_certificate_key /etc/nginx/ssl/server.key;
 ssl_protocols TLSv1.2 TLSv1.3;
 }
}

典型场景：MySQL 客户端启 SSL，但不想让客户端直接连真实 MySQL，走 Nginx 反代统一证书。

八、负载均衡算法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


upstream backend {
 # 1. 轮询（默认）
 # server 10.0.0.10:8080;
 # server 10.0.0.11:8080;
 
 # 2. 加权轮询
 # server 10.0.0.10:8080 weight=3;
 # server 10.0.0.11:8080 weight=1;
 
 # 3. ip_hash（会话保持）
 # ip_hash;
 # server 10.0.0.10:8080;
 # server 10.0.0.11:8080;
 
 # 4. consistent hash（一致性 hash，加减节点影响小）
 hash $remote_addr consistent;
 server 10.0.0.10:8080;
 server 10.0.0.11:8080;
 
 # 5. least_conn（最闲）
 # least_conn;
 # server 10.0.0.10:8080;
 
 # 6. random
 # random;
}

九、健康检查与失败处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


upstream backend {
 server 10.0.0.10:8080 max_fails=3 fail_timeout=30s;
 server 10.0.0.11:8080 max_fails=3 fail_timeout=30s;
 # 健康检查：失败 3 次标记为 down，30 秒后再试
}

server {
 listen 80;
 proxy_pass backend;
 proxy_next_upstream error timeout invalid_header http_502 http_503;
 # 后端 error/timeout/502/503 时，自动切到下一个 upstream
 proxy_next_upstream_tries 2;
 proxy_next_upstream_timeout 10s;
}

max_fails 与 fail_timeout：

30 秒内失败 3 次 → 标记 down
30 秒后再尝试（如果还失败，继续 down）

proxy_next_upstream：

error：连接错误
timeout：超时
invalid_header：响应头无效
http_502/503/504：HTTP 错误码
off：禁用

十、常见错误

10.1 stream 块识别为 HTTP

症状：Nginx 启动报 unknown directive "stream"。

原因：编译时没加 --with-stream。

对策：重编译 nginx 加 --with-stream，参考 1.1 节。

10.2 listen 端口冲突

1

bind() to 0.0.0.0:3399 failed (98: Address already in use)

对策：

1
2
3


ss -tan | grep 3399
# 看哪个进程占用
lsof -i :3399

10.3 客户端真实 IP 丢失

默认情况：后端看到的客户端 IP 是 Nginx 内网 IP（不是真实客户端）。

对策（仅限 HTTP，TCP 协议做不到）：

1
2
3
4
5


location / {
 proxy_pass http://backend;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

stream 块没有 proxy_set_header！要传真实 IP 必须用应用层协议（如 HTTP 的 X-Forwarded-For、MySQL 的账号 IP 白名单）。

10.4 大量 TIME_WAIT

症状：netstat -an | grep TIME_WAIT | wc -l 几万。

对策：

1
2
3
4
5


# 开启 TIME_WAIT 复用
sysctl -w net.ipv4.tcp_tw_reuse=1

# 缩短 TIME_WAIT 时间（默认 60s）
sysctl -w net.ipv4.tcp_fin_timeout=30

小结

Nginx stream 模块让 Nginx 从七层反代进化为"四/七层通吃"：

编译加 --with-stream
stream 块与 http 同级
listen + proxy_pass 简单粗暴
keepalive + HTTP/1.1 + Connection "" 是 HTTP 反代性能关键
buffer 调优避免写临时文件
客户端真实 IP（四层）传不到后端，靠应用层协议

生产建议：

七层反代：用 Nginx，配置友好
四层 1w-5w QPS：用 Nginx stream
四层 5w+ QPS：用 LVS DR 或 HAProxy
多协议混合：Nginx 统一管（HTTP 在 http 块，TCP 在 stream 块）

下一步：

用 Nginx stream + Let’s Encrypt 做 TLS 反代
上 HAProxy 做更细的健康检查
用 Envoy / APISIX 做云原生时代的四/七层代理

2024 视角：Nginx 仍是 1.25+ / 1.27+ 时代的王者

2013 那篇的 ngx_stream_core_module 仍是 Nginx 的核心特性。2024 视角下：

一、Nginx 1.25 / 1.27（2024 主流）

Nginx 1.25.x（2023-05 起的 mainline）：实验新特性。
Nginx 1.27.x（2024-08）：新 mainline，引入 HTTP/3 over QUIC 完整支持。
Nginx Plus R32（2024）：商业版新增 Dynamic Configuration via API、Active Health Checks 增强。

1
2
3


# 看版本
nginx -v
# nginx version: nginx/1.27.0

二、QUIC / HTTP/3 已成"必选项"

2013 那篇完全没提 QUIC。2024 视角下 QUIC / HTTP/3 已是性能优化标配：
- 握手 0-RTT（比 TLS 1.3 还快）
- 连接迁移（IP 变化不重连）
- 多路复用（解决 HTTP/2 队头阻塞）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# Nginx 1.25+ 启用 HTTP/3
server {
 listen 443 ssl;
 http2 on;
 
 # 启用 HTTP/3（同时监听 UDP 443）
 add_header Alt-Svc 'h3=":443"; ma=86400';
 
 ssl_protocols TLSv1.2 TLSv1.3;
 ssl_early_data on;
 ssl_protocols TLSv1.3;
}

# Nginx 1.27+ 直接
server {
 listen 443 quic reuseport;
 listen 443 ssl;
 http2 on;
 add_header Alt-Svc 'h3=":443"; ma=86400';
}

三、buffer 调优的"现代"配方

2013 那篇给的 proxy_buffer_size 256k / proxy_buffers 64 128k 仍是有效。
2024 实践：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 大文件 / 视频流
proxy_buffer_size 1m;
proxy_buffers 8 1m; # 8 个 1M（共 8M）
proxy_busy_buffers_size 2m;
proxy_temp_file_write_size 4m;

# API 服务（小响应）
proxy_buffer_size 16k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;

新指令：
- proxy_socket_keepalive on：向上游发 TCP keep-alive（避免 TIME_WAIT 堆积）
- proxy_pass_request_body off：透传大 body 优化
- proxy_force_ranges on：强制 Range 支持

四、`Connection reset by peer` 的 2024 排查清单

2013 那篇给的 proxy_http_version 1.1 + Connection "" + keepalive 100 仍是标准动作。2024 升级：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


upstream backend {
 server 10.0.20.1:18018 resolve;
 server 10.0.20.2:18018 resolve;
 keepalive 32; # 适当调小（旧值 100 过大）
 keepalive_requests 1000; # 单连接最多 1000 请求后关闭（防内存泄漏）
 keepalive_timeout 60s;
}

location / {
 proxy_pass http://backend;
 proxy_http_version 1.1;
 proxy_set_header Connection "";
 proxy_connect_timeout 5s; # 比 120s 短
 proxy_send_timeout 60s;
 proxy_read_timeout 60s;
 proxy_socket_keepalive on; # 2024 新
 proxy_next_upstream error timeout http_502 http_503;
 proxy_next_upstream_tries 2;
}

新调试工具：
- nginx -T：dump 完整配置（include 全部展开）
- error.log debug：详细 debug 日志
- stub_status：基础统计
- /usr/lib/nginx/modules/ngx_http_vhost_traffic_status（淘宝开源）：流量详情

五、stream 块在 K8s 时代的"角色"

2024 趋势：Nginx stream 在 K8s 时代被 Envoy 替代。
Nginx Ingress Controller（K8s 标准 Ingress 实现）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# k8s-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: myapp
 annotations:
 nginx.ingress.kubernetes.io/proxy-body-size: "50m"
 nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
spec:
 ingressClassName: nginx
 rules:
 - host: myapp.example.com
 http:
 paths:
 - path: /
 pathType: Prefix
 backend:
 service:
 name: myapp
 port:
 number: 80

优势：Nginx Ingress Controller = Nginx + K8s 自动化（自动 reload、自动证书、自动 upstream）。

六、动态 upstream 的"现代"实现

2013 那篇的 upstream 是静态配置。
2024 现代姿势：upstream {} 动态解析（DNS + Service Discovery）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 动态 upstream（Nginx Plus 特性，开源版部分支持）
upstream backend {
 zone backend 64k;
 server backend-service.default.svc.cluster.local:80 resolve;
 resolver kube-dns.kube-system.svc.cluster.local valid=30s;
}

# 通过 API 动态加 backend
curl -X POST http://127.0.0.1:8080/api/version/http/upstreams/backend/servers/ \
 -d '{"server":"10.0.1.50:80"}'

Nginx 开源版（1.27+）也支持 resolver + resolve 指令，SVC 后端自动发现。

七、SSL/TLS 的"现代"最佳实践

2013 那篇的 ssl_protocols TLSv1 TLSv1.1 TLSv1.2 已经被2024 安全规范淘汰。
2024 强制：

1
2
3
4
5
6
7
8


ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:50m;
ssl_session_timeout 1d;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;

OCSP Stapling：减少客户端验证延迟
TLS 1.3 强制：禁用 TLS 1.0/1.1

八、Nginx + 服务网格的"混合部署"

2024 大量 K8s 项目不再用 Nginx 反代——用 Istio / Linkerd 自带 Envoy。
Nginx 仍在用的场景：
- 边缘节点（CDN 边缘）
- 物理机 / 虚拟机（不在 K8s 里）
- Web 服务器（静态资源）
- API 网关（Apigee / Kong 基于 Nginx）
- Sidecar 替代（轻量场景，Nginx sidecar 比 Envoy 资源占用更少）

九、Nginx 商业替代

F5 NGINX Plus（商业版）：Dynamic Configuration API、Active Health Checks、JWT 验证、WAF
OpenResty（章亦春）：Lua 脚本扩展——2024 仍是国内"高阶 Nginx 玩法"主流
Caddy：自动 HTTPS（Let’s Encrypt 内置）
Traefik：云原生时代的"动态 Nginx"

源文档：

os/linux/第三方tools/dev/反向代理/Nginx/nginx.md（stream TCP 代理 + 自定义日志）
os/linux/第三方tools/dev/反向代理/Nginx/问题.md（buffer 调优 + Connection reset by peer）