Nginx on Liangweidong's blog

反向代理 6 巨头 + 内网穿透双雄：从 Nginx/Tengine 健康检查到全场景工具横评

Wed, 15 Apr 2026 00:00:00 +0800

写于 2026 年 4 月的回望

做博客 14 年，第一次把"反向代理 + 内网穿透"合并到一篇文章里——不是因为它们逻辑上多紧密，而是因为在写代码、跑业务、对外服务这条链路上，这两类工具几乎总是成对出现：你先要有个公网入口（反代 + 四层代理），再考虑内网服务怎么被访问（内网穿透）。入口打不通，内网穿透也无处发力。

本文是 0.7 批次"架构实战"系列的一篇，合并源文档 9 篇（其中 3 篇有实战内容、6 篇仅有工具骨架），目标是给读者一份可立即拿去选型的横评 + 实战手册。

全文目录

一、为什么需要反向代理？3 个真实场景
二、6 款主流反代工具特性横评
三、Nginx 与 Tengine：编译安装 + 健康检查实战（基于源文档深度展开）
四、Stream 四层代理：主动检查 vs 被动检查的踩坑点
五、内网穿透双雄：frp 与 cpolar 选型
六、选型矩阵：按业务场景一图看懂
七、常见 8 个坑点速查

一、为什么需要反向代理？3 个真实场景

反向代理（Reverse Proxy） 站在客户端与真实服务器之间，客户端只看到代理的地址，永远不知道后端有几台机器。在生产环境里，反向代理通常承担三类职责：

统一入口 + 域名路由：把 a.example.com、b.example.com 解析到同一个入口，按 Host 头转发到不同后端
TLS 终结 + HTTPS 加速：所有证书/加解密在反代层完成，后端只跑明文 HTTP，省 CPU 省证书
负载均衡 + 健康检查：检测后端故障、自动剔除/恢复

在微服务、Service Mesh、API 网关场景里，反代还承担动态路由、灰度发布、限流熔断等高级职责——这正是 Caddy、Traefik、Envoy、BFE 竞相入场的原因。

二、6 款主流反代工具特性横评

工具	出品方 / 协议	核心定位	配置风格	动态生效	四层代理	生态优势
Nginx	F5 / BSD-2	HTTP 反代事实标准	静态 conf + reload	需 reload	stream 模块	模块生态最丰富
Tengine	阿里 / BSD-2	Nginx 增强 + 通用 API 网关	兼容 Nginx + 动态配置	支持域名/证书/路由动态生效	stream + UDP bypass	双 11 验证 + Ingress 标注
Caddy	个人作者 / Apache-2	自动 HTTPS + 极简配置	Caddyfile / JSON	reload（零停机）	需 reverse_proxy + layer4 插件	自动 ACME、HTTP/3 默认开
Traefik	Traefik Labs / MIT	云原生动态反代	动态发现（Docker/K8s）	热加载（监听 provider）	需 entrypoints TCP	K8s Ingress 一等公民
Envoy	Lyft/CNCF / Apache-2	Service Mesh 数据面	YAML/JSON xDS	xDS 热推送	原生 L4/L7	Istio 默认 sidecar
BFE	百度 / Apache-2	大流量七层网关	类 Nginx conf	动态配置	支持七层 + 部分四层	百度搜索/地图规模验证

工具生态位速读

Nginx / Tengine：做"经典反代"——nginx.conf 写好、reload 完事，适合中小规模、配置不频繁变化的场景
Caddy：做"个人/小团队站点"——默认自动 HTTPS，省心，配置文件 5 行就能跑
Traefik：做"K8s/容器编排动态反代"——监听 Docker/K8s 标签自动生成路由
Envoy：做"Service Mesh 数据面"——xDS 协议动态下发配置，Istio 默认用它
BFE：做"超大流量七层网关"——百度搜索级别流量验证，国内大厂可选

三、Nginx 与 Tengine：编译安装 + 健康检查实战

本节是源文档里有完整实战内容的部分，逐行引用并补全注释。

3.1 编译选项对比

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


# Nginx 1.24 编译（Debian/Ubuntu 风格）
./configure \
 --prefix=/usr/local/nginx \
 --with-http_ssl_module \
 --with-http_stub_status_module \
 --with-pcre \
 --with-http_gzip_static_module \
 --with-stream \
 --with-stream_ssl_module \
 --add-module=../nginx_upstream_check_module

make && make install

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# Tengine 3.1 编译（额外启用 HTTP/2、realip、upstream_check）
./configure \
 --prefix=/usr/local/nginx \
 --with-http_ssl_module \
 --with-http_v2_module \
 --with-stream \
 --with-stream_ssl_module \
 --with-http_realip_module \
 --with-http_gzip_static_module \
 --add-module=../nginx_upstream_check_module

Tengine 在 Nginx 1.24 基础上额外提供（源文档原文特性清单）：

HTTP/3 支持（QUIC v1 与 draft-29）
基于 header / cookie / query / 服务权重的高级路由，动态无损生效
配置分域名 TLS 多版本、timeout、强制 HTTPS、CORS、robots 动态生效
bypass 内核的用户态 UDP 转发（xUDP），性能远高于内核 UDP
流式上传到后端 / FastCGI
异步 OpenSSL，可对接 QAT 硬件加速
更强大的负载均衡：一致性 hash、会话保持、主动健康检查、动态 upstream 域名解析
CSS/JS 合并、空白字符去除、内存监控、CPU 亲缘性自动绑定

3.2 迁移原 Nginx 到 Tengine

源文档提供了一套保留证书与 conf 的安全迁移流程：

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


# 1. 备份
mkdir -p /backup
rsync -av /usr/local/nginx/conf/cert /backup/
rsync -av /usr/local/nginx/conf/nginx.conf /backup/

# 2. 停止原服务（如有 HAProxy/keepalived 协同）
systemctl stop keepalived
systemctl stop nginx
systemctl stop nginxwebui

# 3. 卸载旧版
rm -rf /usr/local/nginx

# 4. 安装 Tengine（编译步骤见 3.1）

# 5. 还原备份
rsync -av --force /backup/nginx.conf /usr/local/nginx/conf/
rsync -av /backup/cert /usr/local/nginx/conf/

# 6. 启动
systemctl start keepalived
systemctl start nginx
systemctl start nginxwebui

关键点：Tengine 完全兼容 Nginx 配置，所以可以直接复用 nginx.conf 与证书目录。--force 标志在还原时避免 rsync 因目标存在而拒绝覆盖。

四、Stream 四层代理：主动检查 vs 被动检查的踩坑点

源文档反复强调的一条铁律：

注意：这个模块（nginx_upstream_check_module）只能支持 HTTP，不支持 stream；且被动检查不能和主动检查同时使用。

4.1 主动健康检查（仅 HTTP）

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


http {
 upstream backend_http {
 server {{BACKEND_1}}:8080;
 server {{BACKEND_2}}:8080;
 check type=http;
 check interval=5000 rise=2 fall=3 timeout=2000;
 check_http_send "GET /health HTTP/1.0\r\nHost: example.com\r\n\r\n";
 check_http_expect_alive http_2xx;
 }

 server {
 listen 80;
 location / {
 proxy_pass http://backend_http;
 }
 }
}

参数含义（源文档原文）：

interval：调用间隔（毫秒）
rise：连续成功多少次后标记存活
fall：连续失败多少次后摘除
timeout：单次检查超时

4.2 被动健康检查（stream 块）

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


stream {
 upstream backend_tcp {
 server {{MQTT_NODE_1}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_2}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_3}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_4}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_5}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_6}}:1883 fail_timeout=30s max_fails=3;
 keepalive 32;
 }

 server {
 listen 1883;
 proxy_pass backend_tcp;
 }
}

被动检查的语义：客户端连接失败 3 次（max_fails=3）后，30 秒内不再向该后端转发——完全由"连接失败"驱动，不需要主动探测。

4.3 主动 vs 被动：什么时候用哪个？

维度	主动检查	被动检查
适用协议	HTTP（仅）	TCP/UDP/任意四层
检查方式	定期 GET 健康路径	客户端连接失败计数
摘除速度	`interval` 周期级	30s 内响应
副作用	后端会收到"无意义的健康探测"	零副作用
踩坑点	不能与被动同时用	必须配置 `max_fails`

结论：HTTP 反代用主动（拿到 2xx 200 状态才算健康）；stream / MQTT / 数据库连接池用被动（主动检查模块不支持 stream）。

4.4 主动检查可视化（Nginx 自带状态页）

1
2
3
4
5
6


# 启动两个测试后端
docker run -d --name nginx1 --restart=always -p {{PORT_HTTP_1}}:80 nginx:latest
docker run -d --name nginx2 --restart=always -p {{PORT_HTTP_2}}:80 nginx:latest

# 访问状态页
curl http://{{STATUS_HOST}}:{{STATUS_PORT}}/status

输出示例（源文档原文截图对应文字）：

1
2
3
4
5


Nginx http upstream check status
Check upstream server number: 2, generation: 1
Index Upstream Name Status Rise counts Fall counts Check type Check port
0 cluster {{HOST}}:{{PORT_HTTP_1}} up 2 0 tcp 0
1 cluster {{HOST}}:{{PORT_HTTP_2}} up 2 0 tcp 0

停掉一个后端（docker stop nginx1），状态页会显示 down + Fall counts 递增；两个全挂后服务直接 502——这就是 source 文档实测的"主动检查 + 服务降级"行为。

五、内网穿透双雄：frp 与 cpolar 选型

内网穿透解决"没有公网 IP 时，怎么让外部访问内网服务“的问题。市面上有两类典型玩家：

frp（fast reverse proxy）：开源、自建、需要一台公网 VPS 当中转
cpolar：商业化、零配置、官方中转服务器（有公网域名）

5.1 frp / frpc 速读

维度	详情
协议	TCP / UDP / HTTP / HTTPS / QUIC
客户端	frpc（运行在内网机器）
服务端	frps（运行在公网 VPS）
配置格式	INI（v0.50 之前）/ TOML（v0.50+）
鉴权	token + TLS 可选
性能	公网 VPS 带宽上限
部署成本	需要 1 台公网 VPS（最低配置 1C1G）

典型 frpc 配置文件片段（公开文档参考）：

1
2
3
4
5
6
7
8
9


serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000

启动后 ssh -oPort=6000 user@x.x.x.x 就能连到内网机器的 22 端口。

5.2 cpolar 速读

维度	详情
部署	零配置，下载即用
中转	官方中转服务器（提供二级公网域名）
限制	免费档限带宽、限连接数
适合场景	临时演示 / 个人远程
不适合场景	长期高带宽、对延迟敏感

5.3 选型建议

自建、自有 VPS、长期使用 → 选 frp
临时演示、个人远程、不想运维 → 选 cpolar
公司有安全合规要求、要求数据走自建 → frp
想用现成公网域名做微信小程序回调 → cpolar

六、选型矩阵：按业务场景一图看懂

业务场景	推荐工具	理由
经典 Web 反代 + 域名路由	Nginx	文档最全、运维最熟
Nginx 配置 + 动态生效 + 阿里生态	Tengine	双 11 验证、Ingress 注解丰富
个人博客 / 小团队 + 想省心	Caddy	自动 HTTPS + 配置 5 行
K8s/容器编排	Traefik	动态发现 + Ingress 一等公民
Service Mesh 数据面	Envoy	Istio 默认 + xDS 协议
超大流量七层网关（百度级别）	BFE	国内大厂验证
内网 SSH/MySQL 临时外访	frp	自建、可控、性能强
个人远程、临时演示	cpolar	零配置、免运维

七、常见 8 个坑点速查

stream 块里用 nginx_upstream_check_module → 不支持，主动检查只对 HTTP 生效
主动检查 + 被动检查同时配置 → 行为未定义，只能二选一
/status 状态页暴露在公网 → 加 allow / deny 或只监听内网 IP
Tengine 迁移后旧证书路径不一致 → 备份+还原时注意 cert/ 相对路径
HTTP/3（QUIC）开启后 443/udp 被防火墙拦 → 提前在 LB/防火墙开 UDP 443
Traefik 监听 Docker 标签后服务起来没路由 → 检查 traefik.enable=true 标签
frpc 配置改完忘 reload → frpc 默认不会自动 reload，用 systemctl restart frpc
cpolar 免费档被限速 → 长期高带宽业务直接换 frp

前置知识 / 下一步

前置：Nginx 基础配置（upstream、location、proxy_pass）、systemd 服务管理
下一步：K8s Ingress 选型（Traefik vs nginx-ingress）、Service Mesh 入门（Envoy + Istio）、CDN 与反代的协同

高可用负载均衡：Nginx + Keepalived 编译与 VIP 漂移

Thu, 15 Feb 2024 00:00:00 +0800

为什么需要 Nginx + Keepalived

K8s 1.28 集群 3 个 master 上的 kube-apiserver 监听 6443 端口，但是：

worker 节点上的 kubelet 不会写死某个 master IP——它们需要一个虚拟入口
kubectl 客户端也希望只配置一个 server 地址
多个 master 之间的负载需要均衡

业界主流方案是 Nginx 4 层 stream 反代 + Keepalived VIP 漂移：

Nginx 用 stream 块做 TCP 4 层反代（不是 7 层 HTTP），把 10443 端口收到的请求分发到 3 个 master 的 6443
Keepalived 用 VRRP 协议做 VIP 漂移（抢占模式必须 nopreempt），3 个 master 只有一个是 MASTER，2 个 BACKUP

适用版本：nginx 1.24.0 / keepalived 2.2.8 / Ubuntu 22.04 部署位置：master1、master2（只在 2 台上部署，master3 上可装可不装，但 stream 配置要一样）

1. 编译安装 Nginx

1.1 编译依赖

1

apt install -y make g++ openssl libssl-dev libpcre3 libpcre3-dev zlib1g-dev libgd-dev

1.2 编译配置

关键参数：--with-stream（4 层反代）、--with-stream_ssl_module（TLS 透传）、--with-http_ssl_module（7 层 HTTPS）。

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


cd /data/softs
tar xf nginx-1.24.0.tar.gz && cd nginx-1.24.0

./configure \
 --prefix=/usr/local/nginx \
 --with-http_ssl_module \
 --with-http_stub_status_module \
 --with-pcre \
 --with-http_gzip_static_module \
 --with-stream \
 --with-stream_ssl_module

make && make install

如果还要支持 --with-stream_ssl_preread_module（按 SNI 分流），需要二次编译：

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


./configure \
 --prefix=/usr/local/nginx \
 --with-http_ssl_module \
 --with-http_stub_status_module \
 --with-pcre \
 --with-http_gzip_static_module \
 --with-stream \
 --with-stream_ssl_module \
 --with-stream_ssl_preread_module

make
# 备份旧的
mv /usr/local/nginx/sbin/nginx /usr/local/nginx/sbin/nginx_bak
# 替换
cp objs/nginx /usr/local/nginx/sbin/

1.3 解决 libpcre.so.1 not found

1
2
3
4


# 查依赖
ldd $(which /usr/local/nginx/sbin/nginx)
# libpcre.so.1 => not found
# 解决：编译时加 --with-pcre=../pcre-xxx 源码路径，或安装 libpcre3-dev

2. Nginx 配置

2.1 主配置 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


worker_processes 1;
events {
 worker_connections 1024;
}
http {
 include 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"';

 sendfile on;
 keepalive_timeout 65;
 autoindex on;
 gzip on;
 gzip_buffers 32 4K;
 gzip_comp_level 6;
 gzip_min_length 1k;
 gzip_types application/javascript text/css text/xml;
 gzip_disable "MSIE [1-6]\.";
 gzip_http_version 1.1;
 gzip_vary on;

 client_body_buffer_size 1024k;
 client_max_body_size 2048m;
 client_header_buffer_size 128k;
 large_client_header_buffers 4 128k;

 proxy_buffer_size 256k;
 proxy_buffering on;
 proxy_buffers 64 128k;
 proxy_busy_buffers_size 512k;

 fastcgi_buffers 6 512k;
 fastcgi_buffer_size 512k;
 fastcgi_busy_buffers_size 512k;
 fastcgi_temp_file_write_size 512k;
 fastcgi_intercept_errors on;

 include conf.d/*.conf;
}
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 stream/*.conf;
}

2.2 stream 反代 kube-apiserver

stream/stream.conf：

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


upstream k8sapiserver {
 hash $remote_addr consistent;
 server <master1-ip>:6443 max_fails=3 fail_timeout=30s;
 server <master2-ip>:6443 max_fails=3 fail_timeout=30s;
 server <master3-ip>:6443 max_fails=3 fail_timeout=30s;
}
server {
 error_log logs/10443_error.log;
 access_log logs/10443_access.log proxy;
 listen 10443;
 proxy_connect_timeout 1s;
 proxy_pass k8sapiserver;
}

2.3 测试页 conf.d/default.conf

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


server {
 listen 10088;
 server_name localhost;
 error_log logs/10088_error.log;
 access_log logs/10088_access.log;

 location / {
 root html;
 index index.html index.htm;
 }
 error_page 500 502 503 504 /50x.html;
 location = /50x.html {
 root html;
 }
}

2.4 systemd 单元

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


[Unit]
Description=kube-apiserver nginx proxy
After=network.target
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
ExecStartPre=/usr/local/nginx/sbin/nginx -c /usr/local/nginx/conf/nginx.conf -p /usr/local/nginx -t
ExecStart=/usr/local/nginx/sbin/nginx -c /usr/local/nginx/conf/nginx.conf -p /usr/local/nginx
ExecReload=/usr/local/nginx/sbin/nginx -c /usr/local/nginx/conf/nginx.conf -p /usr/local/nginx -s reload
PrivateTmp=true
Restart=always
RestartSec=5
StartLimitInterval=0
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

启动：

1
2
3
4
5
6
7
8
9


systemctl daemon-reload
systemctl enable --now nginx.service
systemctl status nginx.service
journalctl -f -u nginx.service

# 验证（区分两台机器的页面）
sed -i "s#Welcome to nginx#Welcome to nginx master1#g" /usr/local/nginx/html/index.html
curl <master1-ip>:10088
curl <master2-ip>:10088

3. Keepalived 编译与配置

3.1 编译安装

1
2
3
4
5
6
7
8


cd /data/softs
tar xf keepalived-2.2.8.tar.gz && cd keepalived-2.2.8

./configure --prefix=/usr/local/keepalived
make && make install
cd .. && rm -rf keepalived-2.2.8

mkdir -p /usr/local/keepalived/conf

3.2 健康检查脚本

check_nginx.sh：每 2 秒检查一次 nginx，挂了先重启；重启失败就让 keepalived 主动降权让 VIP 漂走。

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


cat << "EOF" > /usr/local/keepalived/conf/check_nginx.sh
#!/bin/bash
url="http://127.0.0.1:10088"
code=`curl -s -o /dev/null -w %{http_code} $url`
if [ $code -ne 200 ]; then
 /usr/bin/systemctl start nginx
 sleep 2
 code=`curl -s -o /dev/null -w %{http_code} $url`
 if [ $code -ne 200 ]; then
 /usr/bin/systemctl stop keepalived
 fi
fi
EOF

chmod +x /usr/local/keepalived/conf/check_nginx.sh

必须：脚本用 HTTP 200 判断，不能用 ps -C nginx——多 worker 进程下 ps 不可靠。

3.3 keepalived.conf（master1）

 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


global_defs {
 router_id LVS_DEVEL
 vrrp_skip_check_adv_addr
 vrrp_garp_interval 0
 vrrp_gna_interval 0
}
vrrp_script check_nginx {
 script "/usr/local/keepalived/conf/check_nginx.sh"
 interval 2
 weight -2
}
vrrp_instance VI_1 {
 state MASTER
 interface eno1 # 网卡名按机器实际改
 mcast_src_ip <master1-ip>
 virtual_router_id 51
 priority 100
 advert_int 2
 nopreempt # **关键**：不抢占，主恢复后 VIP 不会自动抢回
 authentication {
 auth_type PASS
 auth_pass K8SHA_KA_AUTH
 }
 virtual_ipaddress {
 <vip-internal>
 <vip-public>
 }
 track_script {
 check_nginx
 }
}

3.4 keepalived.conf（master2）

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


global_defs { router_id LVS_DEVEL ... }
vrrp_script check_nginx { script ".../check_nginx.sh"; interval 2; weight -2; }
vrrp_instance VI_1 {
 state BACKUP # BACKUP 角色
 interface eno1
 mcast_src_ip <master2-ip>
 virtual_router_id 51 # 必须和 master1 一致
 priority 80 # 比 MASTER 低
 advert_int 2
 nopreempt
 authentication { auth_type PASS; auth_pass K8SHA_KA_AUTH; }
 virtual_ipaddress { <vip-internal> <vip-public> }
 track_script { check_nginx; }
}

3.5 keepalived.conf（master3，可选）

1
2
3
4


state BACKUP
priority 60
virtual_router_id 51
... (其余同 master2)

3.6 systemd 单元

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


[Unit]
Description=VRRP High Availability Monitor
After=network-online.target syslog.target
Wants=network-online.target
Documentation=https://keepalived.org/manpage.html

[Service]
Type=forking
KillMode=process
ExecStart=/usr/local/keepalived/sbin/keepalived -D -f /usr/local/keepalived/conf/keepalived.conf
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target

启动：

1
2
3
4
5


systemctl daemon-reload
systemctl enable --now keepalived
systemctl restart keepalived
systemctl status keepalived
journalctl -f -u keepalived

打包已安装的 keepalived 用于其他节点：

1
2
3


cd /usr/local
tar -zcvf keepalived.tar.gz keepalived
scp keepalived.tar.gz master2:/usr/local/

4. 跨机房 VIP（Unicast 模式）

如果两个机房之间是 L3 路由（不是同 L2），VRRP 多播会被丢，需要切到单播模式：

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


vrrp_instance VI_1 {
 state MASTER
 interface eno1
 virtual_router_id 51
 priority 100
 advert_int 1
 unicast_src_ip <this-node-ip>
 unicast_peer {
 <peer-node-ip> # 另一机房的对端 IP
 }
 authentication { auth_type PASS; auth_pass 1111; }
 virtual_ipaddress { <vip-cross-dc> }
}

unicast_src_ip + unicast_peer 显式指定对端，绕过 VRRP 多播。

5. 验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 验证 VIP
curl <vip-internal>:10088

# 停 master1 模拟故障
ssh master1 "systemctl stop keepalived"
# VIP 应该在 1-3 秒内漂到 master2

# 启动 master1 keepalived
ssh master1 "systemctl start keepalived"
# 因为 nopreempt，VIP 不会回到 master1，仍在 master2 上

6. 常见问题

6.1 ping 不通 VIP

ARP 缓存未刷新。在 client 上：

1
2


# 清理 ARP 缓存
arp -n | awk '/^[1-9]/{print "arp -d " $1}' | sh

或等 30 秒（ARP 默认老化时间）。

6.2 不同网段 ping 不通

防火墙或路由限制。检查 iptables -L -n 与 ip route。

6.3 VIP 漂移后不能自动启动

健康检查脚本没成功。先手动跑：

1

bash /usr/local/keepalived/conf/check_nginx.sh

6.4 master3 也想加 VIP 漂移

把 master3 也装 nginx + keepalived，配置 state BACKUP + priority 60 即可。

7. 小结

Nginx stream 4 层 + Keepalived VIP 是 K8s 1.20+ 时代最稳的 apiserver HA 方案。几个关键点：

nginx 必须 --with-stream 编译
keepalived 必须 nopreempt（否则主备反复切换时丢包）
健康检查用 HTTP 200 不用 ps
跨机房用 unicast_src_ip + unicast_peer 替代多播

下一步：etcd 3.5 集群二进制部署与 TLS 证书签发。

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 微服务治理

Vaultwarden 自托管密码管理：Bitwarden 兼容 + 轻量部署

Sun, 25 Dec 2022 00:00:00 +0800

密码多了记不住、用一个密码到处用又不安全，密码管理器就成了现代数字生活的刚需。1Password / LastPass 是闭源 SaaS，价格不菲、数据出境也有合规风险。Bitwarden 是开源免费的密码管理器，官方有 SaaS 版也可以自托管——但官方服务端是 .NET + MSSQL，重型不友好。Vaultwarden（原 bitwarden_rs）是 Bitwarden 服务端的第三方 Rust 重写版，完全兼容官方客户端，资源占用只有官方的 1/10——一个容器、单文件二进制、SQLite 存储，1C1G 都能跑。这篇文章讲清楚部署、反代、客户端使用。

阅读对象：想给团队/个人自托管密码管理器、又想用 Bitwarden 官方客户端体验的同学
覆盖范围：Vaultwarden 容器化部署、Nginx 反代（WebSocket + /admin）、Robots 屏蔽、客户端使用

一、背景

项目	状态	特点
Bitwarden 官方服务端	闭源、.NET + MSSQL	重型、SaaS 也用
Vaultwarden（原 `bitwarden_rs`）	活跃	Rust 重写、Bitwarden 兼容、SQLite
Bitwarden 客户端	闭源客户端 / 开源 SDK	全平台（Win/macOS/Linux/iOS/Android/浏览器）

重要时间线：

2021-04-27：bitwarden_rs 项目更名为 Vaultwarden（因为 Bitwarden 官方要求改名）

后续社区全力投入 Vaultwarden 维护，Bitwarden 官方也认可 Vaultwarden 兼容客户端

兼容客户端：Vaultwarden 部署后，所有 Bitwarden 官方客户端（桌面、移动、浏览器扩展）都能直接连接 Vaultwarden 服务端。

二、容器化部署

2.1 拉镜像

1

docker pull vaultwarden/server:1.25.1-alpine

Alpine 版 ~50MB，比 Debian 版小 5 倍。

2.2 最简启动

1
2
3
4
5
6


docker run -d \
 --name vaultwarden \
 --restart=always \
 -v /home/docker/vaultwarden/data:/data \
 -p 8087:80 \
 vaultwarden/server:1.25.1-alpine

访问 http://{{HOST}}:8087 看 Web 界面（其实 Web 端用得少，主要用客户端）。

2.3 数据持久化

/data 目录存 SQLite 数据库 + 附件，必须挂出来。

2.4 启用管理后台（可选）

容器内 /data/config.json：

1
2
3


{
 "admin_token": "{{ADMIN_TOKEN}}"
}

重启 Vaultwarden 后，访问 https://{{DOMAIN}}/admin，输入 {{ADMIN_TOKEN}} 进入管理后台：

查看注册用户数
邀请新用户
删除用户
查看系统状态

生产环境强烈建议开启：方便清退离职员工、清异常账号。

2.5 禁用注册（生产环境）

默认任何人都能注册。要么手动邀请（管理后台生成邀请链接），要么关掉：

1
2
3


{
 "disable_signup": true
}

关掉后只有管理后台邀请的邮箱能注册，安全得多。

2.6 关闭 Web Vault（可选）

如果你只用客户端、不需要 Web 端：

1
2
3


{
 "web_vault_enabled": false
}

减少攻击面。

三、Nginx 反向代理

Vaultwarden 涉及 WebSocket（实时通知）+ HTTPS（官方客户端要求） + /admin（管理后台） + /notifications/hub（实时通知）：

 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


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

 ssl_certificate /www/cert/vault.example.com/fullchain.pem;
 ssl_certificate_key /www/cert/vault.example.com/privkey.pem;

 # 客户端上传
 client_max_body_size 128M;

 # Vaultwarden 主服务
 location / {
 proxy_pass http://127.0.0.1:8087;
 proxy_http_version 1.1;
 proxy_cache_bypass $http_upgrade;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header X-Forwarded-Host $host;
 proxy_set_header X-Forwarded-Port $server_port;
 }

 # 实时通知（WebSocket）
 location /notifications/hub {
 proxy_pass http://127.0.0.1:3012;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 }

 # 通知协商
 location /notifications/hub/negotiate {
 proxy_pass http://127.0.0.1:8087;
 }

 # 管理后台
 location /admin {
 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_pass http://127.0.0.1:8087;
 }

 # 屏蔽搜索引擎
 location = /robots.txt {
 root /home/wwwroot/Bitwarden;
 }
}

/notifications/hub 必须用 WebSocket：客户端实时同步密码变更（多设备）依赖 WebSocket，缺了同步会有延迟。 robots.txt 屏蔽：Vaultwarden 路径不应当被搜索引擎收录，避免泄露用户邮箱前缀（注册验证邮件 URL）。 HTTPS 必须：Bitwarden 官方客户端要求 HTTPS，明文 HTTP 客户端拒绝连接。

3.1 /admin 必须 IP 白名单

/admin 是高权限入口，建议加 IP 白名单：

1
2
3
4
5
6


location /admin {
 allow 192.168.0.0/16; # 内网网段
 allow 10.0.0.0/8;
 deny all;
 # ... proxy 配置同上
}

四、客户端使用

4.1 桌面 / 移动客户端

到 https://bitwarden.com/download/ 下载对应平台客户端，安装过程和官方 SaaS 一样。

首次配置：

服务器 URL：填 https://vault.example.com（不是官方 https://vault.bitwarden.com）
邮箱 + 密码注册（如果开了 disable_signup，先用管理后台邀请）
登录后自动同步

4.2 浏览器扩展

Chrome / Edge / Firefox 都有 Bitwarden 官方扩展，安装后点"设置 → 服务器 URL"填自托管地址。

4.3 客户端特性

密码自动填充
跨设备同步（WebSocket 实时）
TOTP 双因素认证
密码生成器
安全审计（弱密码、重复密码、泄露检查）
附件 / 文件存储
紧急访问（指定信任人）

五、备份与安全

5.1 备份

SQLite 数据库（/data/db.sqlite3）：每周 sqlite3 .backup 或直接 cp
附件目录（/data/attachments）：增量备份到 OSS
config.json：包含 admin_token，单独保管

5.2 安全建议

强制 HTTPS——客户端拒绝明文 HTTP
管理后台 IP 白名单——见 3.1
强 admin_token——32+ 位随机字符串
开启 2FA——所有用户强制开启二次验证（管理后台可设）
禁用注册——disable_signup: true，只邀请
定期审计——/admin 看活跃用户、清退离职员工
fail2ban——/admin 加 fail2ban 防止爆破

六、踩坑清单

客户端连不上——HTTPS 没配 / 证书错误 / 客户端服务器 URL 填错
同步延迟——/notifications/hub WebSocket 没配，缺实时推送
/admin 502——config.json 没挂出来或 admin_token 没设
数据丢失——/data 没挂出来，容器销毁即丢
附件上传失败——client_max_body_size 默认 1M，调成 128M
被搜索引擎收录——/robots.txt 没配，路径暴露到 Google
多人协作看不到——disable_signup: true 后只用管理后台邀请，Organization 功能需要付费

七、参考资料

Vaultwarden 官方仓库：https://github.com/dani-garcia/vaultwarden
Vaultwarden 文档：https://github.com/dani-garcia/vaultwarden/wiki
Bitwarden 客户端：https://bitwarden.com/download/
Bitwarden 自托管文档：https://bitwarden.com/help/install-on-premise/

下一步

想要 HTTPS 网关？→ Nginx 反向代理实战一文
想要 VPN？→ OpenVPN 自建 VPN 服务一文
想做安全监控？→ HertzBeat 轻量监控告警一文

Nginx 反向代理实战：WebSocket、HTTPS、静态站点与 MinIO 网关

Fri, 15 Apr 2022 00:00:00 +0800

Nginx 几乎是后端服务的标配——静态站点、反向代理、负载均衡、WebSocket 网关、HTTPS 终结，每个开发者都用过。但真正"线上跑得稳"需要把几个坑都踩过：WebSocket 反代不写 Upgrade 头、gzip 配错类型反向变慢、HTTPS 证书路径不对、buffer 不够大上传大文件 502。这篇文章把零散在多个笔记里的 Nginx 实战经验整理成一篇。

阅读对象：需要在容器化环境部署 Nginx 做反向代理/静态服务/WebSocket 网关的同学
覆盖范围：Nginx 容器化部署、反向代理基础、HTTPS 终结、WebSocket 反代、gzip/buffer 优化、MinIO 反代示例

一、容器化部署

1.1 最简启动

1

docker run -d --restart=always --name nginx -p 80:80 nginx:stable

推荐用 nginx:stable 而不是 nginx:latest：stable 标签跟小版本号（1.22、1.24 等），latest 偶尔会跳大版本。

1.2 配置持久化

生产环境必须挂载配置和静态文件：

1
2
3
4
5
6
7


docker run -d --name nginx --restart=always -p 80:80 \
 -v /home/nginx/logs:/var/log/nginx \
 -v /home/nginx/conf/conf.d:/etc/nginx/conf.d \
 -v /home/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
 -v /home/nginx/dist:/usr/share/nginx/html \
 -v /etc/localtime:/etc/localtime:ro \
 nginx:stable

或者 host 网络模式（适合内网用 80 端口）：

1
2
3
4
5
6


docker run -d --name nginx --restart=always --net=host \
 -v /home/docker/nginx/log:/var/log/nginx \
 -v /home/docker/nginx/conf/conf.d:/etc/nginx/conf.d \
 -v /home/docker/nginx/conf/stream:/etc/nginx/stream \
 -v /home/docker/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
 nginx:stable

1.3 Alpine 版（更小）

1
2
3
4
5
6
7


docker run -d --name nginx --restart=always -p 80:80 \
 -v /home/nginx/logs:/var/log/nginx \
 -v /home/nginx/conf/conf.d:/etc/nginx/conf.d \
 -v /home/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
 -v /home/nginx/dist:/usr/share/nginx/html \
 -v /etc/localtime:/etc/localtime:ro \
 nginx:1.25-alpine

Alpine 版镜像只有 40MB 左右，但没有预装 shell 和常用工具（wget/curl/vi），排查问题时进容器会比较痛苦。

二、生产级 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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71


user root;
worker_processes 1; # 推荐设为 CPU 核心数

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 优化 =====
 gzip on;
 gzip_buffers 32 4K;
 gzip_comp_level 6;
 gzip_min_length 1k;
 gzip_types application/javascript text/css text/xml;
 gzip_disable "MSIE [1-6]\.";
 gzip_http_version 1.1;
 gzip_vary on;

 # ===== 客户端 body/header buffer（上传大文件必须调）=====
 client_body_buffer_size 1024k;
 client_max_body_size 2048m;

 client_header_buffer_size 128k;
 large_client_header_buffers 4 128k;

 # ===== 代理 buffer =====
 proxy_buffer_size 256k;
 proxy_buffering on;
 proxy_buffers 64 128k;
 proxy_busy_buffers_size 512k;

 # ===== FastCGI buffer =====
 fastcgi_buffers 6 512k;
 fastcgi_buffer_size 512k;
 fastcgi_busy_buffers_size 512k;
 fastcgi_temp_file_write_size 512k;
 fastcgi_intercept_errors on;

 # ===== WebSocket 关键配置（http 段顶层）=====
 map $http_upgrade $connection_upgrade {
 default upgrade;
 '' close;
 }

 include /etc/nginx/conf.d/*.conf;
}

# ===== TCP/UDP 4 层转发（可选）=====
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;
}

关键参数解读：

client_max_body_size 2048m：上传文件超过默认 1M 会 413，调大

client_header_buffer_size 128k：HTTP header 单行超过 1k 会 400，调大

proxy_buffer_size / proxy_buffers：调大避免后端响应一次性写入临时文件

map $http_upgrade $connection_upgrade：WebSocket 反代必须，否则 426 错误

三、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


server {
 listen 443 ssl;
 server_name example.com;

 ssl_certificate /www/server/panel/vhost/cert/example.com/fullchain.pem;
 ssl_certificate_key /www/server/panel/vhost/cert/example.com/privkey.pem;
 ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

 charset utf-8;

 location / {
 proxy_pass http://localhost:9000;
 proxy_redirect http:// https://;
 proxy_set_header Host $http_host;
 }
}

server {
 listen 80;
 server_name example.com;

 # HTTP 自动跳 HTTPS
 if ($scheme = http) {
 return 301 https://$host:443$request_uri;
 }
}

证书路径：生产环境用 certbot / acme.sh 自动签发 Let’s Encrypt 证书，定时续期。

四、反向代理 + WebSocket

WebSocket 反代必须带 Upgrade 和 Connection: upgrade 头：

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


location ^~ /ws/ {
 proxy_pass http://{{BACKEND_HOST}}/ws/;
 proxy_http_version 1.1;
 proxy_read_timeout 300s;
 proxy_send_timeout 300s;

 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;

 # WebSocket 关键
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection $connection_upgrade;
}

$connection_upgrade 由前面 map 指令定义，根据客户端 Upgrade 头动态返回 upgrade 或 close。如果忘了配 map，WebSocket 连接会被 nginx 关闭。

五、MinIO 网关示例

MinIO 经常用 Nginx 做反代，重点是 WebSocket（控制台实时通知）+ 大文件上传：

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


location ^~ /minio/ {
 proxy_pass http://localhost:9090/;
 proxy_read_timeout 300s;
 proxy_send_timeout 300s;

 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;
 proxy_http_version 1.1;

 # WebSocket
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection $connection_upgrade;
}

MINIO_BROWSER_REDIRECT_URL 必须配成 Nginx 转发后的地址，否则 MinIO 控制台会 404：

1
2


environment:
 - MINIO_BROWSER_REDIRECT_URL=http://{{NGINX_HOST}}/minio

六、踩坑清单

WebSocket 426/断开——忘了 map $connection_upgrade，或者 location 段漏 Upgrade 头
上传 413——client_max_body_size 默认 1M，调成业务需要的最大值
Header 400——client_header_buffer_size 默认 1k，Cookie 巨长的请求会超
代理慢/卡顿——proxy_buffer_size 太小，后端响应被频繁写入临时文件
gzip 没生效——gzip_types 漏了类型，或者 gzip_min_length 设太大（小文件不压缩）
配置改完没生效——nginx -s reload 失败（语法错），需要 docker logs nginx 查原因
HTTPS 跳不过来——return 301 写在 location / 里而不是 server 顶层
跨域 CORS——后端没设 CORS 头，Nginx 要么 add_header 加，要么在 if 段处理 OPTIONS 预检

七、2024+ 视角补充

本文写于 2022-04，2024-2026 期间 Nginx 关键演进：

Nginx 1.25+（2023-06 起）：HTTP/3 (QUIC) 实验性支持；gRPC 代理原生；动态 SSL 证书加载（不用 reload）
Nginx 1.27 LTS（2024-11）：HTTP/3 默认开；OpenSSL 3.x 兼容；更精细的限流（limit_req_dry_run 等）
Nginx Ingress 1.10+（K8s）：Gateway API 全面支持（vs 老 Ingress API）；IPV6 双栈
Nginx Unit 1.32+：应用服务器模式（跑 Go / Node / Python / Java / PHP / Perl）——Web 服务器 + 应用服务器一体
OpenResty 1.25+：Lua 生态成熟，WAF / API Gateway 场景仍是首选
替代品（2024+ 视角）：
- Caddy 2.x：自动 HTTPS / Caddyfile 简洁 / Go 跨平台——新项目首选
- Traefik 3.x：K8s 原生 / 自动服务发现 / Let’s Encrypt 自动化
- HAProxy 3.0+：四层代理性能优于 Nginx，数据库 / TCP 代理首选
- Envoy 1.32+：Service Mesh 标配（Istio / Consul / Linkerd）

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

传统 Web 反代 / 静态站 → Nginx 1.27 LTS 仍是生产首选
K8s 入口 → Nginx Ingress 1.10+ / Traefik 3.x / Gateway API
数据库 / TCP 代理 → HAProxy 3.0+（性能与功能强于 Nginx stream）
新项目想要最少配置 → Caddy 2.x（HTTPS 配置从 30 行降到 3 行）

八、参考资料

Nginx 官方文档：http://nginx.org/en/docs/
Nginx 反向代理 WebSocket：https://nginx.org/en/docs/http/websocket.html
Mozilla SSL 配置生成器：https://ssl-config.mozilla.org/

下一步

想做安全网关？→ Vaultwarden 自托管密码一文（也用 Nginx 反代）
想做企业 VPN？→ OpenVPN 自建 VPN 服务一文
想用 K8s Ingress？→ 看 K8s 集群流量入口 Ingress-nginx 一文

分布式限流实战：Nginx + Tomcat + Guava + Redis Lua

Wed, 15 Sep 2021 00:00:00 +0800

本文写于 2021 年 9 月——彼时 Sentinel 已经在阿里系大规模落地，但中小厂仍以"自研 + Redis Lua"为主流。

一、限流分层架构

限流不是"做一次就够"，需要从边缘到核心层层设防：

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


 ┌──────────┐
 用户请求 ───> │ CDN │ 第 1 层：CDN 限流（按地区/ISP）
 └────┬─────┘
 ▼
 ┌──────────┐
 │ Nginx │ 第 2 层：边缘网关限流（IP / 域名）
 └────┬─────┘
 ▼
 ┌──────────┐
 │ Tomcat │ 第 3 层：Web 容器限流（maxThreads）
 └────┬─────┘
 ▼
 ┌──────────┐
 │ 网关层 │ 第 4 层：Spring Cloud Gateway / Sentinel
 └────┬─────┘
 ▼
 ┌──────────┐
 │ 单体应用 │ 第 5 层：Guava RateLimiter
 └────┬─────┘
 ▼
 ┌──────────┐
 │ 分布式 │ 第 6 层：Redis + Lua 全局限流
 │ Redis │
 └──────────┘

核心思想：越靠近用户限流越粗（IP / 域名），越靠近业务限流越细（接口 / 用户）。

二、Nginx 限流（边缘网关层）

2.1 核心指令

Nginx 自带两个限流模块：

limit_req：限制请求速率（QPS）
limit_conn：限制并发连接数

2.2 完整配置

 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


# ===== 第一步：定义限流 zone（http 块）=====

# 根据 IP 限速：每秒 10 个请求
limit_req_zone $binary_remote_addr zone=iplimit:20m rate=10r/s;

# 根据 server 限速：每秒 1 个请求
limit_req_zone $server_name zone=serverlimit:10m rate=1r/s;

# 根据 IP 限并发：每个 IP 最多 100 个连接
limit_conn_zone $binary_remote_addr zone=perip:20m;

# 根据 server 限并发：每个 server 最多 100 个连接
limit_conn_zone $server_name zone=perserver:20m;

# ===== 第二步：在 location 应用 =====

server {
 server_name www.test.com;
 
 # 接口限流
 location /access-limit/ {
 proxy_pass http://127.0.0.1:8080/;
 
 # IP 限速（burst=2 允许瞬时 2 个排队，nodelay 不延迟立即处理）
 limit_req zone=iplimit burst=2 nodelay;
 # server 限速
 limit_req zone=serverlimit burst=2 nodelay;
 # IP 限并发 100
 limit_conn zone=perip 100;
 # server 限并发 100
 limit_conn zone=perserver 1;
 # 限流触发时返回 504（默认 503）
 limit_req_status 504;
 limit_conn_status 504;
 }
 
 # 限速下载
 location /download/ {
 # 前 100m 不限速
 limit_rate_after 100m;
 # 之后限速 256k/s
 limit_rate 256k;
 }
}

2.3 关键参数

burst=2：允许瞬时超出 rate 2 个请求排队等待
nodelay：排队不延迟，超出的请求立即返回 503（默认是延迟处理）
rate=10r/s：每秒 10 个请求（也支持 30r/m 每分钟 30 个）

三、Tomcat 限流（Web 容器层）

3.1 核心配置

Tomcat 8.5 通过 conf/server.xml 配置最大线程数：

1
2
3
4
5
6


<Connector port="8080"
 protocol="HTTP/1.1"
 connectionTimeout="20000"
 maxThreads="150" <!-- 最大线程数 -->
 acceptCount="100" <!-- 等待队列长度 -->
 redirectPort="8443" />

工作原理：

当并发请求 > maxThreads（默认 150）时，请求进入等待队列
等待队列满后，新请求被拒绝
天然限流

3.2 调优建议

小贴士：maxThreads 默认 150（Tomcat 8.5.42），但不是越大越好：

每开 1 个线程 → 1MB JVM 内存（线程栈）
线程越多 → GC 负担越重
OS 限制：Windows 每进程 ≤ 2000 线程，Linux 每进程 ≤ 1000 线程

经验值：8 核 16G 机器配 maxThreads=400 较合理，再多就是 GC 抖动的开始。

四、单体应用限流（Guava RateLimiter）

4.1 引入依赖

1
2
3
4
5
6


<!-- https://mvnrepository.com/artifact/com.google.guava/guava -->
<dependency>
 <groupId>com.google.guava</groupId>
 <artifactId>guava</artifactId>
 <version>31.1-jre</version>
</dependency>

4.2 简单使用

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


@Slf4j
@RestController
@RequestMapping("/limit")
public class LimitController {
 
 // 限流策略：1 秒钟 2 个请求
 private final RateLimiter limiter = RateLimiter.create(2.0);
 
 @GetMapping("/test1")
 public String testLimiter() {
 // 500 毫秒内，没拿到令牌就降级
 boolean tryAcquire = limiter.tryAcquire(500, TimeUnit.MILLISECONDS);
 
 if (!tryAcquire) {
 log.warn("进入服务降级，时间{}", LocalDateTime.now());
 return "当前排队人数较多，请稍后再试！";
 }
 
 log.info("获取令牌成功，时间{}", LocalDateTime.now());
 return "请求成功";
 }
}

4.3 Guava 限流模式

模式	类	特点
平滑突发（SmoothBursty）	`RateLimiter.create(permitsPerSecond)`	启动即可满速率
平滑预热（SmoothWarmingUp）	`RateLimiter.create(permitsPerSecond, warmupPeriod, unit)`	启动后有预热期，逐步提到配置速率

4.4 自定义注解 + AOP（接口级限流）

注解：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@Documented
public @interface Limit {
 String key() default ""; // 资源 key
 double permitsPerSecond(); // QPS
 long timeout(); // 最大等待时间
 TimeUnit timeunit() default TimeUnit.MILLISECONDS;
 String msg() default "系统繁忙,请稍后再试.";
}

AOP 切面：

 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


@Slf4j
@Aspect
@Component
public class LimitAop {
 
 private final Map<String, RateLimiter> limitMap = Maps.newConcurrentMap();
 
 @Around("@annotation(com.example.limit.Limit)")
 public Object around(ProceedingJoinPoint joinPoint) throws Throwable {
 MethodSignature signature = (MethodSignature) joinPoint.getSignature();
 Method method = signature.getMethod();
 Limit limit = method.getAnnotation(Limit.class);
 
 if (limit != null) {
 String key = limit.key();
 RateLimiter rateLimiter = limitMap.computeIfAbsent(
 key, k -> RateLimiter.create(limit.permitsPerSecond())
 );
 
 // 拿令牌
 boolean acquire = rateLimiter.tryAcquire(limit.timeout(), limit.timeunit());
 if (!acquire) {
 log.debug("令牌桶={}，获取令牌失败", key);
 this.responseFail(limit.msg());
 return null;
 }
 }
 return joinPoint.proceed();
 }
 
 private void responseFail(String msg) {
 HttpServletResponse response = ((ServletRequestAttributes) 
 RequestContextHolder.getRequestAttributes()).getResponse();
 ResultData<Object> resultData = ResultData.fail(ReturnCode.LIMIT_ERROR.getCode(), msg);
 WebUtils.writeJson(response, resultData);
 }
}

Controller：

1
2
3
4
5
6
7


@GetMapping("/test2")
@Limit(key = "limit2", permitsPerSecond = 1, timeout = 500, 
 timeunit = TimeUnit.MILLISECONDS, msg = "排队中，请稍候")
public String limit2() {
 log.info("limit2 获取令牌成功");
 return "ok";
}

4.5 IP 级限流

思路：每个 IP 一个 RateLimiter，缓存到 LoadingCache。

限流工具类：

 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


public class RateLimitUtil {
 /** 缓存：1000 个 IP，过期 1 天 */
 private static LoadingCache<String, RateLimiter> limitCaches = CacheBuilder.newBuilder()
 .maximumSize(1000)
 .expireAfterWrite(1, TimeUnit.DAYS)
 .build(new CacheLoader<String, RateLimiter>() {
 @Override
 public RateLimiter load(String key) {
 double perSecond = RateLimitUtil.getCacheKeyPerSecond(key);
 return RateLimiter.create(perSecond);
 }
 });
 
 /** 唯一 key = 资源名:ip:perSecond */
 public static String generateCacheKey(Method method, HttpServletRequest request) {
 RateLimit rateLimit = method.getAnnotation(RateLimit.class);
 StringBuilder cacheKey = new StringBuilder(rateLimit.name() + ":");
 cacheKey.append(getIpAddr(request) + ":");
 cacheKey.append(rateLimit.perSecond());
 return cacheKey.toString();
 }
 
 public static double getCacheKeyPerSecond(String cacheKey) {
 return Double.parseDouble(cacheKey.split(":")[2]);
 }
 
 public static String getIpAddr(HttpServletRequest request) {
 String ip = request.getHeader("x-forwarded-for");
 if (ip == null || ip.length() == 0 || "unknown".equalsIgnoreCase(ip)) {
 ip = request.getHeader("Proxy-Client-IP");
 }
 if (ip == null || ip.length() == 0 || "unknown".equalsIgnoreCase(ip)) {
 ip = request.getRemoteAddr();
 }
 // 多级代理取第一个 IP
 if (ip != null && ip.length() > 15) {
 if (ip.indexOf(",") > 0) {
 ip = ip.substring(0, ip.indexOf(","));
 }
 }
 return ip;
 }
}

五、分布式应用限流（Redis + Lua 令牌桶）

5.1 为什么需要 Redis 限流

Guava RateLimiter 是进程内的，集群部署时每个节点都有一份独立的限流器——比如 3 节点配 100 QPS，实际可能是 300 QPS。

Redis 限流 = 全集群共享一份限流计数。

5.2 令牌桶算法（Lua 实现）

 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


-- KEYS[1]: 接口唯一 ID
-- ARGV[1]: max_token（桶容量）
-- ARGV[2]: token_rate（每秒产生令牌数）
-- ARGV[3]: current_time（当前时间戳，毫秒）

local ratelimit_info = redis.pcall('HMGET', KEYS[1], 'last_time', 'current_token')
local last_time = ratelimit_info[1]
local current_token = tonumber(ratelimit_info[2])
local max_token = tonumber(ARGV[1])
local token_rate = tonumber(ARGV[2])
local current_time = tonumber(ARGV[3])

if current_token == nil then
 current_token = max_token
 last_time = current_time
else
 local past_time = current_time - last_time
 
 if past_time > 1000 then
 current_token = current_token + token_rate
 last_time = current_time
 end
 
 -- 防止溢出
 if current_token > max_token then
 current_token = max_token
 last_time = current_time
 end
end

local result = 0
if (current_token > 0) then
 result = 1
 current_token = current_token - 1
 last_time = current_time
end

redis.call('HMSET', KEYS[1], 'last_time', last_time, 'current_token', current_token)
return result

关键点：

每个接口的 key（如 uri:/api/order/create）对应一个 Hash
Hash 存 last_time（上次请求时间）+ current_token（当前桶内令牌数）
每隔 1000ms 自动补充 token_rate 个令牌
拿不到令牌返回 0，拿到了返回 1 并减 1

5.3 Spring Boot 集成

Redis 序列化配置：

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


@Bean(value = "redisTemplate")
@Primary
public RedisTemplate redisTemplate(RedisConnectionFactory factory) {
 RedisTemplate<String, Object> template = new RedisTemplate<>();
 template.setConnectionFactory(factory);
 
 ObjectMapper objectMapper = new ObjectMapper();
 objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
 
 StringRedisSerializer stringRedisSerializer = new StringRedisSerializer();
 Jackson2JsonRedisSerializer jsonRedisSerializer = new Jackson2JsonRedisSerializer(Object.class);
 jsonRedisSerializer.setObjectMapper(objectMapper);
 
 template.setKeySerializer(stringRedisSerializer);
 template.setHashKeySerializer(stringRedisSerializer);
 template.setValueSerializer(jsonRedisSerializer);
 template.setHashValueSerializer(jsonRedisSerializer);
 return template;
}

限流工具类：

 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


public class RedisLimiterUtils {
 
 private static StringRedisTemplate stringRedisTemplate = 
 ApplicationContextUtils.applicationContext.getBean(StringRedisTemplate.class);
 
 /**
 * 拿令牌
 * @param key 请求 ID（如接口 URI）
 * @param max 桶容量
 * @param rate 每秒生成令牌数
 * @return true=拿到，false=限流
 */
 public static boolean tryAcquire(String key, int max, int rate) {
 List<String> keyList = new ArrayList<>(1);
 keyList.add(key);
 
 DefaultRedisScript<Long> script = new DefaultRedisScript<>();
 script.setResultType(Long.class);
 script.setScriptText(LUA_SCRIPT);
 
 Long result = stringRedisTemplate.execute(
 script, keyList,
 Integer.toString(max),
 Integer.toString(rate),
 Long.toString(System.currentTimeMillis())
 );
 
 return Long.valueOf(1).equals(result);
 }
}

5.4 注解 + 拦截器

注解：

1
2
3
4
5
6
7


@Inherited
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimit {
 int capacity() default 100; // 桶容量
 int rate() default 10; // 每秒令牌数
}

拦截器：

 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


@Component
public class RateLimiterIntercept implements HandlerInterceptor {
 
 @Override
 public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
 Object handler) throws Exception {
 if (handler instanceof HandlerMethod) {
 HandlerMethod handlerMethod = (HandlerMethod) handler;
 Method method = handlerMethod.getMethod();
 
 RateLimit rateLimit = AnnotationUtils.findAnnotation(method, RateLimit.class);
 if (Objects.isNull(rateLimit)) {
 rateLimit = AnnotationUtils.findAnnotation(
 handlerMethod.getBean().getClass(), RateLimit.class);
 }
 
 if (Objects.isNull(rateLimit)) return true;
 
 // 拿令牌，失败抛异常
 if (!RedisLimiterUtils.tryAcquire(
 request.getRequestURI(),
 rateLimit.capacity(),
 rateLimit.rate())) {
 throw new TimeOutException("系统繁忙，请稍后再试");
 }
 }
 return true;
 }
}

注册拦截器：

1
2
3
4
5
6
7
8


@Configuration
public class WebConfigurer implements WebMvcConfigurer {
 @Override
 public void addInterceptors(InterceptorRegistry registry) {
 registry.addInterceptor(new RateLimiterIntercept())
 .addPathPatterns("/**");
 }
}

六、4 种限流方案对比

维度	Nginx	Tomcat	Guava	Redis + Lua
粒度	IP / Server	容器线程	接口	接口 / 用户 / 全局
作用层	边缘	容器	单体应用	分布式
性能	极高	高	高	中（网络 IO）
跨节点	是	否	否	是
实现成本	配置	配置	引入 + AOP	Lua + 工具类
推荐场景	公网入口	单体应用	单体应用	分布式集群

七、面试常问

Q：令牌桶和漏桶有什么区别？ A：

令牌桶：以恒定速率生产令牌，请求消耗令牌。允许突发流量（桶满时能瞬时处理多个请求）
漏桶：以恒定速率流出请求，水（请求）任意速率流入桶。强制平滑，不允许突发

Q：为什么 Redis 限流要选 Lua 脚本？ A：Redis 单线程 + Lua 原子执行，整个限流判断在一次 RTT 内完成。如果用 Java 代码分多次调用（HMGET → 业务判断 → HMSET），中间被打断会导致计数错乱。

Q：Guava RateLimiter 和 Redis 限流怎么选？ A：

单实例 / 性能敏感：Guava（避免 Redis 网络 IO）
多实例 / 严格全局限流：Redis（保证全集群总和）

Q：Nginx 的 burst 和 nodelay 怎么理解？ A：burst=10 nodelay 表示允许 10 个请求瞬时超出 rate，但立即处理不排队。等价于"令牌桶初始有 10 个令牌，被拿完后必须等下一个令牌生成"。

八、小结

限流分层：CDN → Nginx → Tomcat → Gateway → 单体应用 → 分布式 Redis
Nginx：边缘限流首选，配置简单性能高
Tomcat：maxThreads 调优是基本功
Guava：单体内 AOP + 注解最优雅
Redis + Lua：分布式场景的必选，原子性 + 全局一致

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 自建镜像实战

K8s API Server 高可用：Nginx 四层 + Keepalived VIP 漂移

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

写于 2021-03，背景：K8s 1.21 GA 阶段，二进制高可用部署仍然是国内大厂主流。本文用编译版 Nginx 1.24 + Keepalived 2.2 实现 API Server 的统一入口 VIP 漂移。

一、为什么需要 VIP

3 master 集群时，apiserver 监听在 3 个不同 IP:6443：

1
2
3


master1 → 192.168.139.133:6443
master2 → 192.168.139.134:6443
master3 → 192.168.139.135:6443

但 kubectl 只能配 1 个 --server：

1
2


kubectl --server=https://192.168.139.133:6443 get nodes
# 如果 master1 挂了？

解决思路：在 master 节点前再加一层"虚拟 IP"，3 个 master 通过 VRRP 协议竞选 VIP，VIP 永远在 1 个能用的 master 上。

1
2
3
4
5


kubectl → VIP:6443 (192.168.139.150)
 ↓ VRRP
 ┌────┴────┬────────┐
 master1 master2 master3
 :6443 :6443 :6443

二、方案选型

方案	优点	缺点
Nginx + Keepalived	成熟稳定，二层/四层都能做	需要编译
HAProxy + Keepalived	性能比 Nginx 高	配置稍复杂
Envoy + Keepalived	支持高级路由	太重
公有云 SLB	零运维	绑定云厂商

本文选 Nginx stream + Keepalived——最常见、配置清晰。

三、集群规划

主机名	IP	角色
master1	192.168.139.133	nginx + keepalived MASTER
master2	192.168.139.134	nginx + keepalived BACKUP
master3	192.168.139.135	nginx + keepalived BACKUP
VIP	192.168.139.150	漂移地址

端口约定：

apiserver：6443
nginx stream 监听：8443（外部访问 VIP:8443 → 内部 apiserver 6443）
keepalived VRRP：协议号 112

四、编译 Nginx（master1 + master2）

只在两台装 nginx + keepalived 即可（master3 不需要，节省资源）。如果所有 3 台都装，keepalived 仍能正常选举。

4.1 装编译依赖

1

apt install -y make g++ openssl libssl-dev libpcre3 libpcre3-dev zlib1g-dev libgd-dev

4.2 编译 Nginx

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


cd /k8s/softs
tar xf nginx-1.24.0.tar.gz && cd nginx-1.24.0

./configure \
 --prefix=/usr/local/nginx \
 --with-http_ssl_module \
 --with-http_stub_status_module \
 --with-pcre \
 --with-http_gzip_static_module \
 --with-stream \
 --with-stream_ssl_module

make -j$(nproc) && make install

关键参数：**--with-stream**（TCP 四层代理），**--with-stream_ssl_module**（与 apiserver HTTPS 通信）

4.3 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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


cat > /usr/local/nginx/conf/nginx.conf << 'EOF'
worker_processes 1;
events {
 worker_connections 1024;
}
http {
 include 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"';

 sendfile on;
 keepalive_timeout 65;
 autoindex on;
 gzip on;
 gzip_buffers 32 4K;
 gzip_comp_level 6;
 gzip_min_length 1k;
 gzip_types application/javascript text/css text/xml;
 gzip_disable "MSIE [1-6]\.";
 gzip_http_version 1.1;
 gzip_vary on;

 client_body_buffer_size 1024k;
 client_max_body_size 2048m;

 client_header_buffer_size 128k;
 large_client_header_buffers 4 128k;

 proxy_buffer_size 256k;
 proxy_buffering on;
 proxy_buffers 64 128k;
 proxy_busy_buffers_size 512k;

 include conf.d/*.conf;
}

stream {
 log_format proxy '[$time_local] $protocol status:$status, '
 'client: $remote_addr, upstream:"$upstream_addr", '
 'bytes: $bytes_sent/$bytes_received '
 'time: $session_time/$upstream_connect_time';

 include stream/*.conf;
}
EOF

mkdir -p /usr/local/nginx/conf/{conf.d,stream}

4.4 stream 配置

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


cat > /usr/local/nginx/conf/stream/stream.conf << 'EOF'
upstream k8sapiserver {
 hash $remote_addr consistent;
 server 192.168.139.133:6443 max_fails=3 fail_timeout=30s;
 server 192.168.139.134:6443 max_fails=3 fail_timeout=30s;
 server 192.168.139.135:6443 max_fails=3 fail_timeout=30s;
}

server {
 error_log logs/8443_error.log;
 access_log logs/8443_access.log proxy;
 listen 8443;
 proxy_connect_timeout 1s;
 proxy_pass k8sapiserver;
}
EOF

关键参数：

hash $remote_addr consistent：同一客户端始终连同一后端（会话保持）
max_fails=3 fail_timeout=30s：3 次失败标记 down，30 秒后重试
proxy_connect_timeout 1s：连不上后端立即失败，让 keepalived 切主

五、systemd 单元

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


[Unit]
Description=kube-apiserver nginx proxy
After=network.target network-online.target
Wants=network-online.target

[Service]
Type=forking
ExecStartPre=/usr/local/nginx/sbin/nginx -c /usr/local/nginx/conf/nginx.conf -p /usr/local/nginx -t
ExecStart=/usr/local/nginx/sbin/nginx -c /usr/local/nginx/conf/nginx.conf -p /usr/local/nginx
ExecReload=/bin/kill -s HUP $MAINPID
PrivateTmp=true
Restart=always
RestartSec=5
StartLimitInterval=0
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

启动：

1
2
3
4


systemctl daemon-reload
systemctl enable --now kube-nginx
systemctl status kube-nginx
curl 192.168.139.133:8443 # 不报错即可

六、Keepalived 配置

6.1 编译 Keepalived（master1 + master2）

1
2
3
4
5


cd /k8s/softs
tar xf keepalived-2.2.8.tar.gz && cd keepalived-2.2.8
./configure --prefix=/usr/local/keepalived
make -j$(nproc) && make install
mkdir -p /usr/local/keepalived/conf

6.2 健康检查脚本

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


cat > /usr/local/keepalived/conf/check_nginx.sh << 'EOF'
#!/bin/bash
A=$(ps -C nginx --no-header | wc -l)
if [ $A -eq 0 ]; then
 /usr/bin/systemctl start kube-nginx
 sleep 2
 if [ $(ps -C nginx --no-header | wc -l) -eq 0 ]; then
 /usr/bin/systemctl stop kube-keepalived
 fi
fi
EOF
chmod +x /usr/local/keepalived/conf/check_nginx.sh

逻辑：nginx 挂了 → 尝试重启 → 启不来就停 keepalived，让 VIP 漂到其他节点。

6.3 master1 配置（priority 100 = MASTER）

 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


cat > /usr/local/keepalived/conf/kube-keepalived.conf << 'EOF'
global_defs {
 router_id LVS_DEVEL
}
vrrp_script check_nginx {
 script "/usr/local/keepalived/conf/check_nginx.sh"
 interval 5
 weight -5
 fall 2
 rise 1
}
vrrp_instance VI_1 {
 state MASTER
 interface ens33
 mcast_src_ip 192.168.139.133
 virtual_router_id 51
 priority 100
 nopreempt
 advert_int 2
 authentication {
 auth_type PASS
 auth_pass K8SHA_KA_AUTH
 }
 virtual_ipaddress {
 192.168.139.150
 }
 track_script {
 check_nginx
 }
}
EOF

6.4 master2 配置（priority 90 = BACKUP）

 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


cat > /usr/local/keepalived/conf/kube-keepalived.conf << 'EOF'
global_defs {
 router_id LVS_DEVEL
}
vrrp_script check_nginx {
 script "/usr/local/keepalived/conf/check_nginx.sh"
 interval 5
 weight -5
 fall 2
 rise 1
}
vrrp_instance VI_1 {
 state BACKUP
 interface ens33
 mcast_src_ip 192.168.139.134
 virtual_router_id 51
 priority 90
 nopreempt
 advert_int 2
 authentication {
 auth_type PASS
 auth_pass K8SHA_KA_AUTH
 }
 virtual_ipaddress {
 192.168.139.150
 }
 track_script {
 check_nginx
 }
}
EOF

关键参数：

virtual_router_id 51：同一集群必须一致（不同集群必须不同！）
priority 100 > 90：数字大 = 高优先级
nopreempt：原 master 恢复后不抢回 VIP（避免脑裂）
track_script：nginx 挂了直接降 priority 5，触发 VIP 漂移
auth_pass K8SHA_KA_AUTH：明文 VRRP 认证，生产请用 16 位随机字符串

6.5 systemd 单元

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


[Unit]
Description=VRRP High Availability Monitor
After=network-online.target syslog.target
Wants=network-online.target
Documentation=https://keepalived.org/manpage.html

[Service]
Type=forking
KillMode=process
ExecStart=/usr/local/keepalived/sbin/keepalived -D -f /usr/local/keepalived/conf/kube-keepalived.conf
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target

启动：

1
2
3
4


systemctl daemon-reload
systemctl enable --now kube-keepalived
systemctl status kube-keepalived
journalctl -f -u kube-keepalived

七、验证

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


# master1 上看 VIP 是否绑定
ip addr show ens33
# inet 192.168.139.133/24 ...
# inet 192.168.139.150/32 ... ← 看到这行说明 VIP 成功

# 验证 VIP 可访问 apiserver
curl -k https://192.168.139.150:8443/version
# {
# "major": "1",
# "gitVersion": "v1.28.5",
# ...
# }

配置 kubectl 使用 VIP：

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


mkdir -p ~/.kube
cat > ~/.kube/config << EOF
apiVersion: v1
kind: Config
clusters:
- cluster:
 server: https://192.168.139.150:8443
 certificate-authority-data: <base64 编码的 ca.pem>
 name: kubernetes
contexts:
- context:
 cluster: kubernetes
 user: kubernetes-admin
 name: default
current-context: default
users:
- name: kubernetes-admin
 user:
 client-certificate-data: <base64 编码的 admin.pem>
 client-key-data: <base64 编码的 admin-key.pem>
EOF

kubectl get nodes

八、故障演练

8.1 模拟 master1 整机宕机

1
2


# 在 master1 上
shutdown -h now

观察 master2：

1
2
3
4
5
6
7


# master2 上
ip addr show ens33
# inet 192.168.139.134/24 ...
# inet 192.168.139.150/32 ... ← VIP 漂到 master2

# 验证 VIP 仍可访问
curl -k https://192.168.139.150:8443/version

预期 5~10 秒后 VIP 漂到 master2，kubectl 无感。

8.2 模拟 master1 nginx 进程挂

1
2


# 在 master1 上
pkill nginx

观察：

check_nginx.sh 检测到 nginx 死 → 尝试 systemctl start kube-nginx
如果能起来：keepalived 继续，VIP 不漂
如果起不来（概率低）：脚本 systemctl stop kube-keepalived，VIP 强制漂走

8.3 恢复 master1

1
2


# master1
systemctl start kube-apiserver kube-nginx kube-keepalived

由于 nopreempt，VIP 不会抢回（继续在 master2）。这是有意设计——避免脑裂。

九、生产环境加固

关闭 mcast_src_ip 改 unicast（云环境 VRRP multicast 被禁用）：

1
2
3
4
5
6
7


vrrp_instance VI_1 {
 ...
 unicast_src_ip 192.168.139.133
 unicast_peer {
 192.168.139.134
 }
}

认证密码用随机 16 位：
1

openssl rand -base64 12
keepalived 配 3 台而不是 2 台：3 节点可以容忍 1 节点挂，2 节点只容忍 0 节点挂（脑裂风险大）。
监控 VIP：把 192.168.139.150 加入 Prometheus blackbox_exporter 监控。
DNS 解析：把 kubernetes-api.example.com 解析到 VIP，kubectl 用域名而不是 IP。

十、常见坑

virtual_router_id 不一致：3 节点 VRRP 选举失败
多播被防火墙挡：VRRP 协议号 112，iptables 默认会拦
nopreempt 没配：master1 恢复时把 VIP 抢回，可能导致短暂脑裂
check_nginx.sh 权限不足：keepalived 跑不了脚本，nginx 挂 VIP 不漂
VIP 绑定到错的 interface：interface ens33 配错网卡，VIP 上不去

十一、前置知识 / 下一步

前置：

nginx 编译与配置
keepalived VRRP 原理
kube-apiserver systemd 单元（参考 2020-12-15《K8s Master 三大组件》）

下一步：

K8s 集群插件（2021-09-15）—— CNI / CoreDNS / Metrics / Dashboard
K8s 集群管理（2021-12-15）—— 升级、节点隔离、排错

参考资料

PHP 7.4 实战：Nginx + PHP-CGI + Xdebug 调试一体化

Wed, 15 Apr 2020 00:00:00 +0800

前置知识

Windows 命令行基础（cmd / PowerShell）
知道什么是 Web 服务器、什么是 CGI
至少跑过一个 PHP 页面

为什么 2020 年还在用 PHP

2010 年代后期，Go / Node.js / Python Web 框架方兴未艾，唱衰 PHP 的声音不断——“性能差”、“语法老”、“现代特性缺”。但 PHP 7.4（2019-11 发布）做了一次关键升级：

PHP 7.0 vs 5.6 性能提升 2 倍（WordPress 主页 QPS 从 100 涨到 300+）
OPcache 集成（字节码缓存默认开启）
类型属性（class 属性可以声明 int、string）
箭头函数（fn($x) => $x * 2）
预加载（PHP 7.4 新特性，把框架文件预加载到 OPCache）

WordPress 占据全球 40%+ 的网站、Magento / Laravel 长期稳居主流——PHP 工程师的需求量在 2020 年依然巨大。学 PHP 7.4 是性价比最高的后端入门选择。

一、Windows 下 PHP 7.4 + Nginx 一体化搭建

1.1 下载三件套

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 1. Nginx 1.18
# 官网下载 stable 版
# https://nginx.org/en/download.html

# 2. PHP 7.4.6 (NTS, x64, VC15)
# https://windows.php.net/download/
# 选 php-7.4.6-nts-Win32-vc15-x64.zip

# 3. RunHiddenConsole.exe
# 一个 1KB 工具，让 nginx / php 以后台方式跑
# 网上搜 RunHiddenConsole 下载

1.2 目录规划

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<PHP_SOFT_DIR>
├── nginx-1.18.0\
├── php-7.4.6\
│ ├── php.exe
│ ├── php.ini
│ ├── ext\
│ └── php-cgi.exe
├── RunHiddenConsole.exe
├── start.bat # 一键启动
└── stop.bat # 一键停止

1.3 PHP 7.4 配置（php.ini）

把 php.ini-development 复制一份改名为 php.ini：

 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


; 时区（中国）
date.timezone = Asia/Shanghai

; 扩展目录
extension_dir = "ext"

; 启用常用扩展
extension=curl
extension=fileinfo
extension=gd2
extension=mbstring
extension=mysqli
extension=openssl
extension=pdo_mysql
extension=xml
extension=zip

; CGI 相关
enable_dl = On
cgi.force_redirect = 0
fastcgi.impersonate = 1
cgi.rfc2616_headers = 1

; 上传文件大小
upload_max_filesize = 50M
post_max_size = 50M
memory_limit = 256M

1.4 Nginx 配置

编辑 nginx-1.18.0\conf\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


worker_processes 1;
events {
 worker_connections 1024;
}

http {
 include mime.types;
 default_type application/octet-stream;
 sendfile on;
 keepalive_timeout 65;
 charset utf-8; # 第 39 行去 # 改 utf-8

 server {
 listen 80;
 server_name localhost;

 # 站点根目录
 root D:/workspace/soft/nginx/www;
 index index.php index.html;

 location / {
 try_files $uri $uri/ /index.php?$query_string;
 }

 # PHP 处理
 location ~ \.php$ {
 fastcgi_pass 127.0.0.1:9000;
 fastcgi_index index.php;
 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
 include fastcgi_params;
 }
 }
}

1.5 启动脚本

start.bat（双击启动）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@echo off
cd /d <PHP_SOFT_DIR>

REM 启动 PHP-CGI（监听 9000 端口）
start /b "php-cgi" "RunHiddenConsole.exe" "php-7.4.6\php-cgi.exe" -b 127.0.0.1:9000 -c "php-7.4.6\php.ini"

REM 启动 Nginx
start /b "nginx" "RunHiddenConsole.exe" "nginx-1.18.0\nginx.exe"

echo PHP-CGI and Nginx started in background.
pause

stop.bat：

1
2
3
4
5


@echo off
taskkill /F /IM nginx.exe
taskkill /F /IM php-cgi.exe
echo Stopped.
pause

1.6 验证

1
2
3
4
5
6


# 检查进程
tasklist | findstr "nginx"
tasklist | findstr "php-cgi"

# 浏览器访问
# http://localhost

新建 <PHP_SOFT_DIR>nginx\www\index.php：

1
2


<?php
 phpinfo();

看到 PHP 7.4.6 配置页 = 成功。

二、Xdebug 远程调试

Xdebug 是 PHP 调试的事实标准——和 Java 的 JDWP、Python 的 pdb 一样，可以在 IDE 里打断点、单步执行、查看变量。

2.1 下载 Xdebug

打开 https://xdebug.org/download，选对应 PHP 版本的 dll：

PHP 7.4 NTS x64 → php_xdebug-2.9.5-7.4-vc15-nts-x86_64.dll
PHP 7.4 TS x64 → php_xdebug-2.9.5-7.4-vc15-ts-x86_64.dll

⚠️ NTS / TS 一定要对（NTS = Non-Thread-Safe，TS = Thread-Safe）——错版本直接起不来。

放到 php-7.4.6\ext\ 目录下。

2.2 php.ini 启用 Xdebug

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[xdebug]
zend_extension = <PHP_SOFT_DIR>php-7.4.6\ext\php_xdebug-2.9.5-7.4-vc15-nts-x86_64.dll

; 远程调试配置
xdebug.idekey = PHPXDEBUG
xdebug.remote_enable = 1
xdebug.remote_host = 127.0.0.1
xdebug.remote_port = 9001
xdebug.remote_handler = dbgp
xdebug.remote_autostart = 1

2.3 IDEA / PhpStorm 配置

Settings → PHP：

字段	值
PHP language level	7.4
CLI Interpreter	<PHP_SOFT_DIR>php-7.4.6\php.exe

Settings → PHP → Debug：

Xdebug
Debug port: 9001

Settings → PHP → Debug → DBGp Proxy：

IDE key: PHPXDEBUG
Host: 127.0.0.1
Port: 9000

Settings → PHP → Servers：

Name: php7.4 Server
Host: 127.0.0.1
Port: 80
Debugger: Xdebug

PHP → Debug → Start Listening（点电话图标变绿 = 监听中）。

2.4 Chrome / Postman 触发断点

方法 1：Chrome 装 Xdebug helper 插件

打开插件设置 → IDE key 选 PHPXDEBUG
访问 http://localhost/index.php → IDE 自动中断

方法 2：Postman 加 Cookie

1

Cookie: XDEBUG_SESSION=PHPXDEBUG

或加 query string：

1

GET /index.php?XDEBUG_SESSION_START=PHPXDEBUG

2.5 Xdebug 高级功能

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


; 性能分析（生成 cachegrind 文件，可用 KCacheGrind 看）
xdebug.profiler_enable = 0
xdebug.profiler_enable_trigger = 1
xdebug.profiler_output_dir = "D:\workspace\profiler"

; 代码覆盖率
xdebug.coverage_enable = 1

; 远程 trace（每行函数调用日志）
xdebug.remote_mode = jit
xdebug.trace_output_dir = "D:\workspace\trace"

三、常见错误速查

3.1 `Call to undefined function curl_init()`

1
2
3
4


; 在 php.ini 加
extension=curl

; 重启 php-cgi

Windows 下还要确认 php-7.4.6\ext\php_curl.dll 存在、<PHP_SOFT_DIR>php-7.4.6 目录里有 libeay32.dll ssleay32.dll（PHP 7.4 自带）。

3.2 `SQLSTATE[HY000] [2002] No connection could be made`

PDO / mysqli 连不上 MySQL。检查项：

MySQL 服务在跑（net start mysql）
localhost vs 127.0.0.1 —— MySQL 用 socket、127.0.0.1 用 TCP，新版 MySQL 默认走 socket，PDO 报 2002
端口（默认 3306）防火墙是否放行

1

$pdo = new PDO('mysql:host=127.0.0.1;port=3306;dbname=test', 'root', 'password');

3.3 `No input file specified.`

Nginx 配置的 root 路径和 PHP 文件实际路径不一致。

1
2
3
4
5
6
7


location ~ \.php$ {
 root D:/workspace/soft/nginx/www; # ← 必须用 / 不要用 \
 fastcgi_pass 127.0.0.1:9000;
 fastcgi_index index.php;
 fastcgi_param SCRIPT_FILENAME D:/workspace/soft/nginx/www$fastcgi_script_name;
 include fastcgi_params;
}

$document_root 和 fastcgi_param SCRIPT_FILENAME 路径要完全一致。

3.4 `500 Internal Server Error`

打开 php.ini 错误显示：

1
2
3
4
5


display_errors = On
display_startup_errors = On
error_reporting = E_ALL
log_errors = On
error_log = <PHP_SOFT_DIR>php-7.4.6\logs\php_error.log

重启 php-cgi，看浏览器错误 + log 文件。

3.5 502 Bad Gateway

Nginx 收不到 PHP-CGI 的响应——PHP-CGI 没启动或挂了：

1
2
3


tasklist | findstr php-cgi
# 没结果 → 重启 start.bat
# 有结果但 502 → 检查 php-cgi -b 参数端口是不是 9000

四、生产环境建议

本地调试用 php-cgi.exe + Nginx 够用，但生产绝不能用这套——php-cgi 是单进程、崩溃不会自启、并发上不去。

4.1 用 PHP-FPM 替代

Linux 上一律用 PHP-FPM（FastCGI Process Manager）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Ubuntu
apt install php7.4-fpm
systemctl start php7.4-fpm

# nginx 配置
location ~ \.php$ {
 fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; # 走 Unix Socket 比 TCP 快
 fastcgi_index index.php;
 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
 include fastcgi_params;
}

4.2 用 Docker 跑 PHP

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


# docker-compose.yml
version: '3'
services:
 php:
 image: php:7.4-fpm-alpine
 volumes:
 - ./www:/var/www/html
 networks:
 - backend

 nginx:
 image: nginx:1.18-alpine
 ports:
 - "80:80"
 volumes:
 - ./nginx.conf:/etc/nginx/conf.d/default.conf
 - ./www:/var/www/html
 depends_on:
 - php
 networks:
 - backend

networks:
 backend:

4.3 性能调优清单

项	默认	建议
`opcache.enable`	1	保持开启
`opcache.memory_consumption`	128	256
`opcache.max_accelerated_files`	10000	20000
`pm.max_children` (FPM)	5	`nproc × 2`
`pm.start_servers`	2	`nproc × 1`
`request_terminate_timeout`	0	30s（防止慢请求占资源）

五、2024 视角：PHP 8.3 升级与 EOL 提醒

⚠️ 重要时间线：PHP 7.4 已于 2022-11-28 正式 EOL（End Of Life），不再收到任何安全更新。本文 2020 年写于 7.4 时代，今天（2024+）继续使用 7.4 = 裸奔。强烈建议升级到 PHP 8.3（2023-11 发布，当前 active branch）。

5.1 PHP 7.4 → 8.x 升级成本

好消息：8.0/8.1/8.2/8.3 都是渐进式升级，几乎没有 breaking change：

版本	发布	EOL	升级成本
7.4	2019-11	2022-11（已 EOL）	—
8.0	2020-11	2023-11	低（Named Args、Match、Attributes）
8.1	2021-12	2025-12	中（Enums、Fibers、Readonly Properties）
8.2	2022-12	2026-12	低（DNF Types、Constants in Traits）
8.3	2023-11	2027-12	低（Typed Class Constants、`#[\Override]`）

5.2 PHP 8.x 关键新特性（精选 6 个）

1. 命名参数（Named Arguments）—— 8.0

1
2
3
4
5


// 之前：靠顺序
htmlspecialchars($str, ENT_QUOTES | ENT_HTML5, 'UTF-8', false);

// 现在：跳着填
htmlspecialchars($str, double_encode: false);

2. Match 表达式 —— 8.0

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


// 之前
switch ($status) {
 case 200: $msg = 'OK'; break;
 case 404: $msg = 'Not Found'; break;
 default: $msg = 'Unknown';
}

// 现在
$msg = match (true) {
 $status >= 200 && $status < 300 => 'OK',
 $status === 404 => 'Not Found',
 default => 'Unknown',
};

3. 枚举（Enums） —— 8.1

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


enum Status: string
{
 case Active = 'active';
 case Banned = 'banned';
 case Pending = 'pending';

 public function label(): string
 {
 return match ($this) {
 self::Active => '活跃',
 self::Banned => '封禁',
 self::Pending => '待审',
 };
 }
}

4. 只读属性（Readonly Properties） —— 8.1

1
2
3
4
5
6
7


class Money
{
 public function __construct(
 public readonly int $amount,
 public readonly string $currency,
 ) {}
}

5. 纤程（Fibers） —— 8.1（类似 Go goroutine 的简化版）

1
2
3
4
5
6
7


$fiber = new Fiber(function (): void {
 $value = Fiber::suspend('fiber suspended');
 echo "Resumed with: $value\n";
});

$value = $fiber->start(); // "fiber suspended"
$fiber->resume('test'); // "Resumed with: test"

实战意义：让 PHP 能写真正的协程，AmPHP 3 / Revolt / ReactPHP 都基于 Fibers 重写了事件循环。

6. 类型化类常量（Typed Class Constants） —— 8.3

1
2
3
4
5


class HttpStatus
{
 public const int OK = 200; // 8.3 前是 mixed
 public const string NOT_FOUND = '404 is wrong here'; // 编译期就会报错
}

5.3 PHP 8.x 性能

指标	7.4	8.0	8.3
WordPress 主页 QPS	300	350	420+
Symfony Welcome 页 QPS	1.2k	1.5k	1.9k
内存峰值（典型 Web 请求）	12 MB	11 MB	9 MB
JIT 编译器	无	tracing JIT（可选）	function JIT（默认更智能）

8.3 的 JIT 对纯计算密集型任务（图像处理、数值计算、规则引擎）能再涨 1.5~3 倍。

5.4 7.4 → 8.3 升级路径（最短 4 步）

PHPCompatibility 静态扫描：composer require --dev phpcompatibility/phpcompatibility
修 deprecation：{ 改为 {$var}、each() 改 foreach
CI 跑通：把 7.4 跑过的测试在 8.3 跑一遍
生产灰度：金丝雀 5% → 25% → 50% → 100%

参考工具：PHPStan 静态分析、Psalm、Rector（自动重构 7.4 → 8.x 代码）。

5.5 如果还在用 PHP 5.x / 7.0/7.1/7.2/7.3

危险——这些版本都 EOL：

版本	EOL 时间	风险
5.6	2019-01	已知多个未修复漏洞
7.0	2019-01	同上
7.1	2019-12	同上
7.2	2020-11	同上
7.3	2021-12	同上
7.4	2022-11	最新 EOL，建议立即升级
8.0	2023-11	需升级到 8.1+
8.3	2027-12	当前推荐版本

结论：2024+ 新项目直接用 PHP 8.3；老项目至少升级到 8.1+（还有 1 年多支持），最迟 2025 年前完成 8.2/8.3 升级。

六、下一步

PHP 8.3 现代特性（命名参数、Enums、Fibers、Readonly）：PHP 8 迁移指南
框架：Laravel 11 / Symfony 7 / ThinkPHP 8——Laravel 仍是事实标准
Composer：PHP 包管理——composer require vendor/package
测试：PHPUnit 11 + Mockery + Pest（PHPUnit 之上的现代语法糖）
静态分析：PHPStan / Psalm（类似 TypeScript 的 tsc）
协程：基于 Fibers 的 AmPHP 3 / Revolt

参考资料

PHP 官方文档：https://www.php.net/docs.php
Xdebug 官方文档：https://xdebug.org/docs/
Nginx 官方文档：https://nginx.org/en/docs/
PHP The Right Way（社区最佳实践）：https://phptherightway.com/
PHP 8.3 发布公告：https://www.php.net/releases/8.3/zh.php

nginxWebUI 可视化配置：图形化管理 Nginx 反向代理与证书

Thu, 15 Mar 2018 00:00:00 +0800

背景

直接编辑 nginx.conf 对老手不是问题，但对多机器、多域名、多证书的场景：

10 台机器的 Nginx 配置逐个 scp + reload，效率低
Let’s Encrypt 证书 90 天过期，每次手动续期累
反代配置改一行，要 grep + vim + nginx -t + reload 反复验证
团队里新人不会写 nginx.conf

nginxWebUI（cym1102/nginxWebUI）是国产开源的Nginx 图形化管理工具：

Web 界面配置 server、location、upstream、SSL
可视化反向代理、负载均衡、HTTPS、HTTP/2
证书申请支持 Let’s Encrypt（DNS 验证）+ 自有证书
集群同步多台 Nginx 配置一致
参数模板常用片段（WebSocket、HTTPS、限流）

适用场景：

中小企业多机器统一配置
不熟悉 nginx.conf 的运维新人
大量多域名业务（虚拟主机）
证书自动续期 + 同步

前置知识：

Nginx 基础
一台已装 Nginx 1.16+ 的 Linux 机器
JDK 1.8（运行 Spring Boot）

重要原则：nginxWebUI 直接修改nginx.conf 并 reload，所有手工编辑的注释必须用 # nginxWebUI 标记（避免被覆盖）。

一、架构

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


 ┌──────────────────┐
 │ nginxWebUI Web │ ← 用户浏览器
 │ (Spring Boot) │
 │ :8080/:8082 │
 └────────┬─────────┘
 │
 ┌──────┴──────┐
 │ │
 ┌────▼─────┐ ┌────▼─────┐
 │ Nginx │ │ 配置文件 │ ← /home/nginxWebUI/
 │ :80/443 │ │ 模板、 │
 │ reload │ │ 证书、 │
 └──────────┘ │ 集群配置 │
 └──────────┘

关键路径：

Web UI：http://<ip>:8080（默认）
项目目录：/home/nginxWebUI/
配置文件：/home/nginxWebUI/conf/
证书目录：/home/nginxWebUI/.acme.sh/

二、前置工作

2.1 安装 JDK 1.8

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


# 下载并解压
curl -O https://example.com/jdk-8u381-linux-x64.tar.gz
tar -xzvf jdk-8u381-linux-x64.tar.gz -C /usr/local

# 配置环境变量
cat << "EOF" >> /etc/profile
export JAVA_HOME=/usr/local/jdk1.8.0_381
export CLASSPATH=$JAVA_HOME/bin:$JAVA_HOME/lib:$JAVA_HOME/jre/lib
export PATH=.:$JAVA_HOME/bin:$JAVA_HOME/jre/bin:$PATH
EOF

# 生效
source /etc/profile

# 验证
java -version
# java version "1.8.0_381"

2.2 准备 Nginx

编译选项必须包含（缺哪个就重编）：

1
2
3
4
5
6
7
8


nginx -V
# 关键参数：
# --with-http_ssl_module HTTPS 必备
# --with-http_stub_status_module 状态监控
# --with-pcre 正则
# --with-http_gzip_static_module 静态压缩
# --with-stream TCP/UDP 四层代理
# --with-stream_ssl_module TCP SSL

如果没有 --with-stream，重编译：

1
2
3
4
5
6
7
8


./configure --prefix=/usr/local/nginx \
 --with-http_ssl_module \
 --with-http_stub_status_module \
 --with-pcre \
 --with-http_gzip_static_module \
 --with-stream \
 --with-stream_ssl_module
make && make install

把 nginx 加入 PATH：

1
2
3
4
5
6


cat << "EOF" >> /etc/profile
PATH=$PATH:/usr/local/nginx/sbin
export PATH
EOF
source /etc/profile
nginx -V

三、安装 nginxWebUI

3.1 下载 jar

1
2
3


mkdir -p /home/nginxWebUI/
wget -O /home/nginxWebUI/nginxWebUI.jar \
 https://gitee.com/cym1102/nginxWebUI/releases/download/4.3.0/nginxWebUI-4.3.0.jar

版本选择：4.x 需要 JDK 11+，4.2.x 兼容 JDK 1.8。

3.2 启动（测试）

1
2
3
4


nohup java -jar -Dfile.encoding=UTF-8 \
 /home/nginxWebUI/nginxWebUI.jar \
 --server.port=8080 \
 --project.home=/home/nginxWebUI/ > /dev/null &

3.3 systemd 守护（生产推荐）

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


cat << "EOF" > /etc/systemd/system/nginxwebui.service
[Unit]
Description=NginxWebUI
After=syslog.target
After=network.target

[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/home/nginxWebUI
ExecStart=/usr/local/jdk1.8.0_381/bin/java -jar -Dfile.encoding=UTF-8 \
 /home/nginxWebUI/nginxWebUI.jar --server.port=8082
Restart=always
ReStartSec=600

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now nginxwebui.service
systemctl status nginxwebui.service

四、首次登录

4.1 访问

1

http://<server-ip>:8082

4.2 修改默认密码

第一次登录会要求修改默认账号（默认 admin / nginxWebUI 或类似，取决于版本）。

必须改强密码——这个 Web 界面一旦被破，攻击者直接控制你的 Nginx。

4.3 主界面

登录后看到 5 大模块：

反向代理：可视化配置 server/location/upstream
证书管理：Let’s Encrypt 申请 + 续期
参数模板：常用片段（WebSocket、HTTPS、限流）
集群管理：多机器同步
系统设置：日志、备份、安全

五、反向代理实战

5.1 创建一个 HTTP 反代

反向代理 → 创建：

1
2
3
4


名称：blog-app
监听端口：80
域名：blog.example.com
上游地址：127.0.0.1:3000

nginxWebUI 自动生成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


server {
 listen 80;
 server_name blog.example.com;
 
 location / {
 proxy_pass http://127.0.0.1:3000;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 }
}

5.2 HTTPS + WebSocket 模板

反向代理 → 编辑 → 启用 SSL：

1
2
3


证书：选择 let's encrypt 自动申请
强制 HTTPS：是
模板：WebSocket

自动生成：

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


server {
 listen 443 ssl http2;
 server_name blog.example.com;
 
 ssl_certificate /home/nginxWebUI/.acme.sh/blog.example.com/fullchain.cer;
 ssl_certificate_key /home/nginxWebUI/.acme.sh/blog.example.com/blog.example.com.key;
 
 location / {
 proxy_pass http://127.0.0.1:3000;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 # WebSocket 超时
 proxy_read_timeout 600s;
 }
}

5.3 负载均衡

上游 → 创建：

1
2
3
4
5
6


名称：api-pool
负载策略：ip_hash（会话保持）
节点：
 - 10.0.1.10:8080
 - 10.0.1.11:8080
 - 10.0.1.12:8080

在反代 location 选 api-pool，自动生成：

1
2
3
4
5
6


upstream api-pool {
 ip_hash;
 server 10.0.1.10:8080;
 server 10.0.1.11:8080;
 server 10.0.1.12:8080;
}

5.4 重载配置

右上角 → 替换文件 → 验证配置 → 重新加载 nginx

1
2


nginx -t
nginx -s reload

nginxWebUI 自动执行这两步。

六、证书自动申请

6.1 阿里云 DNS 验证

证书管理 → 申请证书 → DNS 验证 → 阿里云：

需要阿里云 AccessKey（最小权限：AliyunDNSFullAccess）：

1
2


AccessKey ID: LTAI5txxxxxxxxxxx
AccessKey Secret: h8Q4xxxxxxxxxxxx

强烈建议用 RAM 子账号 AccessKey，不要用主账号。

6.2 申请流程

选择 DNS 厂商（阿里云 / 腾讯云 / Cloudflare / 华为云）
填 AccessKey
输入要申请证书的域名
nginxWebUI 自动：
- 在 DNS 添加 _acme-challenge TXT 记录
- 等 Let’s Encrypt 验证
- 保存证书到 /home/nginxWebUI/.acme.sh/
在反代配置中选这个证书

6.3 自动续期

Let’s Encrypt 证书 90 天过期。nginxWebUI 内置 cron 任务：

每天检查 30 天内过期的证书
自动调用 acme.sh 续期
自动 reload nginx

无需人工干预。

6.4 多域名（SAN 证书）

1
2
3


example.com
www.example.com
api.example.com

一次申请，3 个域名共用 1 张证书。

七、集群同步

7.1 场景

N 台 Nginx 机器（机房 A 3 台 + 机房 B 2 台），配置要完全一致。

7.2 配置主从

集群管理 → 添加节点：

1
2
3
4
5


节点名：nginx-slave-01
IP：10.0.1.21
SSH 端口：22
SSH 用户：root
认证方式：SSH 私钥

主节点（你这台）配置变更后，点"同步"会自动 scp 配置 + reload 到所有从节点。

7.3 同步内容

反代配置
证书
模板
不同步：日志、本地统计

7.4 同步失败的常见原因

SSH 免密没配：ssh-keygen + ssh-copy-id 先打通
nginx 路径不同：从节点 /usr/local/nginx/sbin/nginx 不存在
JDK 没装：从节点没 java，nginxWebUI 跑不起来
防火墙：从节点没开放 22 给主节点

八、参数模板

把常用配置片段做成模板，一处维护，到处使用。

8.1 内置模板

WebSocket 反代：Upgrade + Connection "upgrade" + 长超时
HTTPS 优化：ssl_protocols / ssl_ciphers / session cache
静态资源：gzip / expires / cache-control
限流：limit_req_zone 限 IP / URI
防盗链：referer 白名单

8.2 自定义模板

1
2
3
4
5


# 我的限流模板
location / {
 limit_req zone=one burst=10 nodelay;
 proxy_pass http://backend;
}

保存后，在反代编辑界面可以一键插入。

九、备份与恢复

9.1 自动备份

系统设置 → 自动备份：

备份目录：/home/nginxWebUI/backup/
备份内容：所有反代配置 + 证书
备份频率：每天 / 每周
保留份数：30 份

9.2 手动备份

1
2
3
4
5
6
7


# 备份项目目录
tar -czf nginxWebUI_$(date +%F).tar.gz /home/nginxWebUI/

# 排除 .acme.sh（可重新申请）
tar -czf nginxWebUI_config_$(date +%F).tar.gz \
 --exclude='*.acme.sh' \
 /home/nginxWebUI/

9.3 跨机迁移

1
2
3
4
5
6


# 旧机器打包
tar -czf nginxWebUI.tar.gz /home/nginxWebUI/

# 新机器恢复
tar -xzf nginxWebUI.tar.gz -C /
# 然后启动 systemd 即可

记得修改 --project.home 指向新路径。

十、安全加固

10.1 Web UI 端口保护

1
2
3
4
5
6


# 用 Nginx 反代 nginxWebUI，加 basic auth
location / {
 auth_basic "NginxWebUI Admin";
 auth_basic_user_file /etc/nginx/.htpasswd;
 proxy_pass http://127.0.0.1:8082;
}

10.2 HTTPS for Web UI

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 生成自签证书（内网用）
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
 -keyout /home/nginxWebUI/ssl.key \
 -out /home/nginxWebUI/ssl.crt \
 -subj "/CN=nginxwebui.internal"

# 启动加 --server.ssl.key-store
nohup java -jar nginxWebUI.jar \
 --server.port=8443 \
 --server.ssl.key-store=/home/nginxWebUI/ssl.jks \
 --server.ssl.key-store-password=changeit &

10.3 操作审计

审计台 → 操作日志：所有 Web UI 操作都记录（谁在什么时间改了什么）。

十一、常见问题

11.1 配置替换后 nginx -t 报错

原因：上游地址不可达 + nginx -t 不检查 upstream 通断。

对策：

在 nginxWebUI 启用"测试"模式（不直接 reload）
手工 nginx -t 验证语法

11.2 证书申请失败

DNS 验证失败：阿里云 AccessKey 没 AliyunDNSFullAccess
速率限制：Let’s Encrypt 一周 5 张同域名证书，用 staging 环境测
端口 80 被占：HTTP 验证需要 80 端口，改用 DNS 验证

11.3 Web UI 502 Bad Gateway

8080 端口被占：lsof -i :8080
Java 进程没起来：systemctl status nginxwebui
磁盘满：证书申请要写临时文件

11.4 集群同步后从节点 nginx 起不来

检查从节点 nginx 编译参数一致
检查从节点 /etc/nginx 是否被覆盖（nginxWebUI 默认只动 conf.d）

十二、卸载

1
2
3
4
5


systemctl stop nginxwebui.service
systemctl disable nginxwebui.service
rm -rf /etc/systemd/system/nginxwebui.service
rm -rf /home/nginxWebUI
systemctl daemon-reload

小结

nginxWebUI 是国产最易用的 Nginx 可视化工具：

图形化反代——不用手写 nginx.conf
证书自动续期——Let’s Encrypt 90 天焦虑解除
集群同步——多机器配置一致性
模板复用——常用片段一处维护

生产使用三原则：

Web UI 加 basic auth + HTTPS
手写配置必须带 # nginxWebUI 标记避免被覆盖
定期备份 /home/nginxWebUI/

替代方案对比：

nginxWebUI（本篇）：Spring Boot + Web，集群同步
Nginx Proxy Manager：Docker 化，UI 更现代
Caddy：自带 HTTPS，但生态小
APISIX：企业级网关，APISIX Ingress

下一步：

用 Nginx Proxy Manager 做内网穿透入口
用 APISIX 做 API 网关（限流、鉴权、灰度）
自建证书监控（certspotter / cert-expiry-monitor）

2024 视角：Web UI 类工具已"百花齐放"

2018 那篇只有 nginxWebUI 一个国产工具。2024 视角下，Web UI 类 Nginx 工具已经"百花齐放"。

一、nginxWebUI 4.x（2024 现状）

当前版本 4.3.x（2024 持续更新）。
新特性：
- JDK 17+ 兼容（不再强依赖 JDK 8）
- 国密 SM2/SM3/SM4（国内信创环境）
- 集群同步 增强：支持灰度发布
- OpenAPI：用 REST API 自动化配置

1
2
3
4
5
6


# 2024 装
wget -O /home/nginxWebUI/nginxWebUI.jar \
 https://gitee.com/cym1102/nginxWebUI/releases/download/4.3.0/nginxWebUI-4.3.0.jar

# 启动（要求 JDK 17+）
java -jar nginxWebUI.jar --server.port=8080 --project.home=/home/nginxWebUI/

二、Nginx Proxy Manager（NPM）—— 2024 主流"最易用"工具

Nginx Proxy Manager（NginxProxyManager/nginx-proxy-manager）：Docker 一行命令 起 UI。

1
2
3
4
5
6
7


# 装
docker run -d \
 --name nginx-proxy-manager \
 -p 80:80 -p 443:443 -p 81:81 \
 -v /data/npm/data:/data \
 -v /data/npm/letsencrypt:/etc/letsencrypt \
 jc21/nginx-proxy-manager:latest

优势：
- UI 极其现代（Vue 3 + Element Plus）
- Let’s Encrypt 自动续期（内置）
- Access List（HTTP Basic Auth 访问控制）
- Audit Log（所有操作记录）
2024 主流：NPM 在个人 / 小团队 / 自托管场景已经超过 nginxWebUI。

三、Caddy —— “自动 HTTPS"的魅力

Caddy（Go 写）自动申请 Let’s Encrypt 证书 + 自动续期——配置极简：

1
2
3
4
5
6
7
8
9


# /etc/caddy/Caddyfile
myapp.example.com {
 reverse_proxy localhost:3000
}

blog.example.com {
 reverse_proxy localhost:8080
 encode gzip
}

1
2
3
4


# 装
apt install caddy
caddy run
# 自动 HTTPS + 自动续期

2024 趋势：Caddy 在静态博客 / 个人网站 / 内部工具场景全面替代 Nginx。
劣势：插件生态远不如 Nginx（没有 stream 四层、不能编译第三方模块）。

四、APISIX / Kong —— “API 网关"路线

APISIX（Apache 顶级项目，国产）：云原生 API 网关——支持动态路由、限流、鉴权、灰度、gRPC：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# APISIX Route
upstreams:
 - id: "1"
 nodes:
 - host: "10.0.1.10"
 port: 8080
 weight: 1
 - host: "10.0.1.11"
 port: 8080
 weight: 1
 type: roundrobin

Kong（基于 Nginx + Lua）：商业 API 网关老牌，2024 仍是外企主流。

五、Traefik —— K8s 时代的"动态反代”

Traefik（Go 写）自动发现 K8s 资源（Ingress / Service）——几乎零配置：

1
2
3
4
5
6


# Helm 装
helm repo add traefik https://traefik.github.io/charts
helm install traefik traefik/traefik

# 自动发现所有 Ingress
kubectl apply -f myapp-ingress.yaml

自动 HTTPS（Let’s Encrypt + cert-manager 集成）。
2024 K8s 项目默认 Ingress Controller 之一（与 Nginx Ingress Controller 并列）。

六、`acme.sh` —— 命令行证书申请的事实标准

2018 那篇的 nginxWebUI 内置 acme.sh。2024 视角：

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


# 装
curl https://get.acme.sh | sh
source ~/.bashrc

# 申请证书（DNS 验证）
export Ali_Key="xxx"
export Ali_Secret="yyy"
acme.sh --issue -d example.com --dns dns_ali

# 复制到 Nginx
acme.sh --install-cert -d example.com \
 --key-file /etc/nginx/ssl/example.com.key \
 --fullchain-file /etc/nginx/ssl/example.com.crt \
 --reloadcmd "systemctl reload nginx"

acme.sh 2024 仍是 80+ DNS 厂商支持的"证书神器”——比 certbot 简单、比 nginxWebUI 灵活。

七、Web UI 工具选型 2024 决策表

场景	2018 选择	2024 推荐
个人博客 / 静态站	Caddy / Nginx	Caddy（自动 HTTPS）
小团队 1-3 台 Nginx	nginxWebUI	NPM（UI 现代）
中小企业多 Nginx	nginxWebUI + rsync	NPM 或 APISIX
K8s 集群 Ingress	（K8s 还没普及）	Traefik / Nginx Ingress / APISIX Ingress
API 网关 / 限流	（没普及）	APISIX / Kong
信创 / 国密	nginxWebUI	nginxWebUI 4.x
跨境 / 外企	nginxWebUI	Nginx Plus 或 Kong Enterprise

八、Web UI 工具的"未来趋势"

AI 辅助配置（2024 萌芽）：自然语言生成 Nginx 配置
GitOps 化：Web UI 改动自动 commit 到 Git
多集群联邦：一个 UI 管多 K8s 集群的 Ingress
安全扫描：Web UI 内置配置审计（防止错误配置）

源文档：os/linux/第三方tools/net/nginx/nginxwebUI.md（JDK 安装、Nginx 编译、jar 启动、systemd 守护、证书申请）

海康摄像头按需推流：Java + FFmpeg + Nginx-rtmp 浏览器播放

Thu, 15 Mar 2018 00:00:00 +0800

一、为什么浏览器不能直接播 RTSP

海康 / 大华等安防摄像头默认协议是 RTSP（Real Time Streaming Protocol），浏览器原生不支持 RTSP——Chrome / Edge / Firefox 都不行。

两条主流路径让浏览器能播摄像头：

RTSP → RTMP → Flash / HLS（老方案）—— 需 nginx-rtmp-module + video.js / videojs-flash
RTSP → WebRTC / HLS（新方案）—— 用 ZLMediaKit / MediaMTX / go2rtc 媒体网关，浏览器原生 video 标签

本文讲第一种老方案——因为很多 2018-2020 年的项目（GB28181 视频监控平台）仍依赖此架构，且控制粒度细（按需推流 = 节省服务器资源）。

二、整体流程

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


点击播放按钮
 ↓
1. 判断 ffmpeg 进程是否存在
 ↓ 存在
2. 获取进程 PID
3. 用 taskkill 关闭 ffmpeg（关流）
 ↓ 不存在
 ↓
4. 启动 ffmpeg 进程：rtsp → rtmp
 ↓
5. nginx-rtmp-module 接收 rtmp 流
 ↓
6. 浏览器用 video.js / vue-video-player 播放

关键点：

按需推流 = 不点就不推，ffmpeg 进程按需启动 / 关闭
FFmpeg = RTSP → RTMP 转协议 + 转封装
Nginx-rtmp-module = RTMP 服务端，支持 HLS / DASH 切片
vue-video-player = 浏览器播放器，带 RTMP 播放能力（需 videojs-flash 插件）

三、服务端部署

3.1 安装 Nginx + nginx-rtmp-module

Windows 编译 nginx-rtmp-module 较麻烦，推荐用现成的 Windows 集成版：

项目：nginx-rtmp-win32（GitHub 搜 nginx-rtmp-win32 或 nginx-rtmp-module-win32）
下载后解压到 D:\nginx-ffmpeg\

3.2 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


worker_processes 1;
events {
 worker_connections 1024;
}

# RTMP 服务
rtmp {
 server {
 listen 1935;
 chunk_size 4096;

 application live {
 live on;
 record off;

 # 推流后自动 HLS 切片
 hls on;
 hls_path D:/nginx-ffmpeg/hls;
 hls_fragment 5s;
 hls_playlist_length 30s;
 }
 }
}

# HTTP 服务（提供 HLS 播放）
http {
 include mime.types;
 default_type application/octet-stream;
 sendfile on;
 keepalive_timeout 65;

 server {
 listen 8080;
 server_name localhost;

 # 静态 HLS 文件
 location /hls {
 types {
 application/vnd.apple.mpegurl m3u8;
 video/mp2t ts;
 }
 root D:/nginx-ffmpeg/;
 add_header Cache-Control no-cache;
 }
 }
}

启动 nginx：

1
2


cd D:\nginx-ffmpeg
nginx.exe

测试 RTMP 端口：

1

Test-NetConnection localhost -Port 1935

3.3 安装 FFmpeg

官方：https://ffmpeg.org/download.html#build-windows
推荐：gyan.dev 出品的 ffmpeg-release-essentials.zip
解压到 D:\nginx-ffmpeg\ffmpeg\bin\

把 D:\nginx-ffmpeg\ffmpeg\bin\ 加到 PATH。

四、FFmpeg 推流命令

1
2
3


ffmpeg -i "rtsp://USERNAME:PASSWORD@IP:PORT/Streaming/Channels/<通道ID>" ^
 -b 4096k -f flv -r 25 -s 1920x1080 -an ^
 "rtmp://127.0.0.1:1935/live/<自定义名称>"

参数说明：

-i —— 输入 RTSP URL
-b 4096k —— 视频比特率 4 Mbps
-f flv —— 输出格式 FLV（RTMP 走 FLV 封装）
-r 25 —— 帧率 25 fps
-s 1920x1080 —— 分辨率
-an —— 去掉音频（RTMP 推摄像头画面不需要音轨）
最后是 RTMP URL，<自定义名称> 是 stream key

4.1 海康 RTSP URL 格式

1
2
3
4
5
6
7


rtsp://<username>:<password>@<ip>:<port>/Streaming/Channels/<channel_id>

# 主码流（高清）
rtsp://admin:password123@192.168.1.100:554/Streaming/Channels/101

# 子码流（流畅）
rtsp://admin:password123@192.168.1.100:554/Streaming/Channels/102

101 = 通道 1 主码流，102 = 通道 1 子码流。

五、Java 后端：调 FFmpeg 推流

5.1 项目结构

1
2
3
4


src/main/java/com/example/videoplay/
├── VideoPlayService.java # 服务类
├── StreamManager.java # 流管理（启停）
└── ...

5.2 ProcessBuilder 启动 FFmpeg

 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


import java.io.*;
import java.util.*;

public class StreamManager {

 /**
 * 启动 ffmpeg 推流
 * @param rtsp 摄像头 RTSP 地址
 * @param rtmp RTMP 推流地址
 * @param s 分辨率（如 "1920x1080"）
 * @return 启动的进程（用于后续关流）
 */
 public static Process openLiu(String rtsp, String rtmp, String s) {
 if (s == null) s = "1920x1080";

 ProcessBuilder builder = new ProcessBuilder();
 List<String> commend = new ArrayList<>();
 commend.add("D:/nginx-ffmpeg/ffmpeg/bin/ffmpeg.exe");
 commend.add("-i");
 commend.add(rtsp);
 commend.add("-f");
 commend.add("flv");
 commend.add("-r");
 commend.add("25");
 commend.add("-s");
 commend.add(s);
 commend.add("-an");
 commend.add(rtmp);

 builder.command(commend);
 builder.redirectErrorStream(true);

 try {
 return builder.start();
 } catch (IOException e) {
 e.printStackTrace();
 return null;
 }
 }

 /**
 * 关闭 ffmpeg 进程（关流）
 * @param pid ffmpeg 进程 PID
 */
 public static void closeLiu(String pid) {
 try {
 Runtime.getRuntime().exec("taskkill /F /PID " + pid);
 } catch (IOException e) {
 e.printStackTrace();
 }
 }
}

5.3 获取 FFmpeg 进程 PID

 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


/**
 * 查 ffmpeg 进程的 PID
 */
public static String getPid() {
 String pid = null;
 try {
 Process process = Runtime.getRuntime().exec(
 "tasklist /fi \"imagename eq ffmpeg.exe\" /fo list"
 );
 InputStream inputStream = process.getInputStream();
 BufferedReader bf = new BufferedReader(
 new InputStreamReader(inputStream, "GBK")
 );
 String line;
 while ((line = bf.readLine()) != null) {
 if (line.startsWith("PID")) {
 String[] array = line.split(":");
 pid = array[1].trim();
 }
 }
 } catch (Exception e) {
 e.printStackTrace();
 }
 return pid;
}

编码必须是 GBK——tasklist.exe 在中文 Windows 上输出是 GBK 编码，UTF-8 会乱码。

5.4 关流流程

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


// 1. 查进程是否存在
String pid = StreamManager.getPid();

if (pid != null) {
 // 2. 关流
 StreamManager.closeLiu(pid);
 // 3. 短暂等待 ffmpeg 退出
 Thread.sleep(500);
}

// 4. 推新流
Process process = StreamManager.openLiu(rtsp, rtmp, "1920x1080");

六、前端：Vue + vue-video-player

6.1 安装

1
2


npm install --save vue-video-player
npm install --save videojs-flash

6.2 组件

 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
55
56
57
58
59
60


<template>
 <videoPlayer
 ref="videoPlayer"
 :options="videoOptions"
 class="vjs-custom-skin videoPlayer"
 :playsinline="false"
 @play="onPlayerPlay()"
 />
</template>

<script>
import 'video.js/dist/video-js.css'
import { videoPlayer } from 'vue-video-player'
import 'videojs-flash'

export default {
 components: { videoPlayer },
 data() {
 return {
 videoOptions: {
 playbackRates: [0.7, 1.0, 1.5, 2.0],
 autoplay: false,
 muted: false,
 loop: false,
 preload: 'auto',
 language: 'zh-CN',
 aspectRatio: '16:9',
 techOrder: ['flash', 'html5'], // 兼容顺序
 sources: [{
 type: 'rtmp/hls',
 src: 'rtmp://127.0.0.1:1935/live/cam001' // 你的 RTMP 地址
 }],
 poster: '',
 notSupportedMessage: '此视频暂无法播放，请稍后再试',
 controlBar: {
 timeDivider: true,
 durationDisplay: true,
 remainingTimeDisplay: false,
 fullscreenToggle: true
 }
 }
 }
 },
 methods: {
 onPlayerPlay() {
 // 暂停其他视频
 this.$refs.videoPlayer.player.pause()

 // 调后端 API
 this.$http.get('/api/stream/play', {
 params: {
 rtsp: this.videoRtsp,
 rtmp: this.videoRtmp,
 fenbianlv: '1920x1080'
 }
 })
 }
 }
}
</script>

techOrder: ['flash', 'html5'] —— 优先 Flash（RTMP），回退 HTML5（HLS）。但 Chrome 88+ 已经彻底禁用 Flash，所以生产请直接用 HLS。

七、按需推流：点击播放事件

 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


onPlayerPlay() {
 this.$refs.videoPlayer.player.pause()

 // 1. 查流进程
 this.$http.get('/api/stream/isLiu').then(res => {
 const liuSta = res.data.result

 if (liuSta) {
 // 2. 进程存在 → 取 PID
 this.$http.get('/api/stream/getFFpid').then(res => {
 const pid = res.data.message

 // 3. 关流
 this.$http.post('/api/stream/closeLiu', { pid }).then(() => {

 // 4. 推新流
 this.$http.post('/api/stream/openLiu', {
 rtsp: this.videoRtsp,
 rtmp: this.videoRtmp,
 fenbianlv: '1920x1080'
 })
 })
 })
 } else {
 // 5. 进程不存在 → 直接推
 this.$http.post('/api/stream/openLiu', {
 rtsp: this.videoRtsp,
 rtmp: this.videoRtmp,
 fenbianlv: '1920x1080'
 })
 }
 })
}

八、生产级方案升级

8.1 RTMP → HLS 切片

nginx-rtmp-module 自动把 RTMP 切成 HLS 切片：

浏览器用 http://server:8080/hls/cam001.m3u8 播放
支持原生 video 标签，不用 Flash
延迟 5-10 秒（HLS 切片固定延迟）

8.2 用 ZLMediaKit 替代 nginx-rtmp

项目：https://github.com/ZLMediaKit/ZLMediaKit
支持 RTSP/RTMP/HLS/HTTP-FLV/WebRTC 全协议
延迟可调到 1 秒级
2018-2023 持续维护，生产首选

8.3 用 go2rtc 做"轻量转协议"

项目：https://github.com/alexxit/go2rtc
几乎零配置，Docker 一行起
支持 RTSP / RTMP / WebRTC / MSE / HLS 多协议转发

8.4 浏览器兼容性

协议	Chrome	Edge	Firefox	Safari
RTMP	❌（Flash 88+ 已删）	❌	❌	❌
HLS	❌	❌	❌	✅
HTTP-FLV	✅（via MSE）	✅	✅	❌
WebRTC	✅	✅	✅	✅

结论：生产请走 HLS（兼容 Safari）或 WebRTC（低延迟）。RTMP 已经是 2010 年代技术。

九、常见 5 个坑

RTSP URL 认证失败——海康 RTSP 默认需要先在摄像头后台开启 RTSP 服务（路径：网络 → 平台接入 → RTSP）
ffmpeg 推流卡顿——-b 4096k 太高，降到 2048k 或 1024k；或者 -c:v copy 不转码（前提是摄像头 H.264）
nginx-rtmp hls 切片生成失败——hls_path 目录nginx 没写权限
videojs-flash 加载失败——Chrome 88+ 不再支持 Flash，改用 videojs-http-streaming (VHS) 播 HLS
ffmpeg 进程关不掉——taskkill /F /PID 仍关不掉时，用 wmic process where "name='ffmpeg.exe'" call terminate

十、总结

老方案 = FFmpeg + nginx-rtmp + video.js / vue-video-player（2018-2020 经典）
新方案 = ZLMediaKit / MediaMTX / go2rtc 直接做 RTSP → HLS/WebRTC（2021+ 推荐）
按需推流 = 不点就不开 ffmpeg，省 CPU 省带宽
Java 调 FFmpeg 用 ProcessBuilder + tasklist /fi "imagename eq ffmpeg.exe" 查 PID + taskkill /F /PID
浏览器兼容：RTMP 已死（Flash 88+ 被删），走 HLS / WebRTC / HTTP-FLV
延迟排序：WebRTC (~500ms) < HTTP-FLV (~1s) < HLS (~5-10s) < RTMP (~1-2s)

参考资料

Windows 自托管服务实战：Nginx、Caddy、Redis、MinIO、Elasticsearch 与 WinSW 注册服务

Thu, 15 Jun 2017 00:00:00 +0800

一、为什么要在 Windows 上自托管服务

Linux 是服务器的主流，但以下场景 Windows 是更好的选择：

本机开发调试：不想用 Docker 跑 Redis / MinIO，直接在 Windows 起一个更轻；
边缘设备：工控机、收银终端、POS 机多数是 Windows；
客户现场：客户系统是 Windows Server，部署要符合现场环境；
个人 NAS / 家用服务器：Windows 桌面系统易用，存储/相册/笔记都靠它。

本文给出 Nginx / Caddy / Redis / MinIO / Elasticsearch 五个常用自托管服务的 Windows 绿色版部署方案，统一用 WinSW 把 exe 注册成系统服务，重启自启。

二、Nginx for Windows

2.1 下载与目录

nginx.org/en/download.html 下载 nginx-1.24.0.zip（mainline 1.25.x 也可以）。

1
2
3
4
5
6
7


D:\portable\dev\nginx-1.24.0\
├── conf\
│ ├── nginx.conf
│ └── conf.d\ # 自定义配置
├── html\
├── logs\
└── nginx.exe

2.2 配置环境变量

1

PATH=D:\portable\dev\nginx-1.24.0

1
2


nginx -v
# nginx version: nginx/1.24.0

2.3 启停命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 启动（前台）
start nginx

# 优雅停止
nginx -s stop
nginx -s quit
nginx -s reload # 重载配置（不中断连接）
nginx -s reopen # 重开日志文件

# 暴力杀进程（兜底）
taskkill /f /t /im nginx.exe

2.4 反代示例

conf/conf.d/frontend.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


server {
 listen 8080;
 server_name localhost;

 # 静态站点
 root D:/wwwroot/site;
 index index.html;

 # 反向代理
 location /api/ {
 proxy_pass http://127.0.0.1:3000/;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }

 # WebSocket
 location /ws/ {
 proxy_pass http://127.0.0.1:3001/;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 }

 # 大文件上传
 client_max_body_size 100m;
}

主 conf/nginx.conf 引入：

1
2
3
4
5
6
7
8


http {
 include mime.types;
 default_type application/octet-stream;
 sendfile on;
 keepalive_timeout 65;
 gzip on;
 include conf.d/*.conf;
}

2.5 TCP/UDP 四层代理

conf/stream/video.conf：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


stream {
 server {
 listen 1935;
 proxy_pass stream_backend;
 }
 upstream stream_backend {
 server 127.0.0.1:1936;
 server 127.0.0.1:1937;
 }
}

启动时 nginx 会要求主 nginx.conf 引入 stream 块，默认 nginx.conf 不带，要手动加。

三、Caddy：自动 HTTPS 的 HTTP/2 服务器

3.1 下载

caddyserver/caddy/releases 下载 caddy_2.6.4_windows_amd64.zip，解压到 D:\portable\dev\caddy。

3.2 Caddyfile 最小配置

1
2
3
4
5
6


example.com {
 root * D:/wwwroot/site
 file_server
 encode gzip
 reverse_proxy /api/* 127.0.0.1:3000
}

3.3 关键命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 启动（前台，监视配置改动自动 reload）
.\caddy.exe run --watch

# 启动（守护进程）
.\caddy.exe start

# 格式化配置文件（推荐编辑后立即 fmt）
.\caddy.exe fmt --overwrite Caddyfile

# 自签证书测试
curl https://localhost --ssl-no-revoke

3.4 Caddy vs Nginx

维度	Caddy	Nginx
自动 HTTPS	默认开（Let’s Encrypt）	需 acme.sh + cron
配置语法	极简	模块化、灵活
性能	单核略低于 Nginx	极致优化
生态	较新，模块少	老牌，几乎所有场景都有现成配置
适合	个人/小团队博客、内网工具	生产大流量反代、网关

四、Redis for Windows

4.1 下载

官方 Redis 不提供 Windows 版。社区维护两个分支：

tporadowski/redis（Cygwin 版）；
redis-windows/redis-windows（MinGW 版，2023+ 维护）。

下载 Redis-7.4.1-Windows-x64-cygwin-with-Service.zip，解压到 D:\portable\dev\redis。

4.2 启动

1
2
3
4
5
6
7


# 启动 redis-server
D:\portable\dev\redis\redis-server.exe redis.conf

# 客户端
D:\portable\dev\redis\redis-cli.exe
127.0.0.1:6379> ping
PONG

4.3 配置 redis.conf 关键项

1
2
3
4
5
6
7
8
9


bind 127.0.0.1
port 6379
daemonize no # Windows 不支持 daemonize
loglevel notice
logfile "D:/portable/dev/redis/logs/redis.log"
dir D:/portable/dev/redis/data
maxmemory 256mb
maxmemory-policy allkeys-lru
requirepass {{REDACTED}}

4.4 用 Redis Desktop Manager 连

RDM（uglide/RedisDesktopManager）2021.3 起开源。Windows 端推荐用 Another Redis Desktop Manager，绿色解压即用。

1
2
3


host: 127.0.0.1
port: 6379
password: <requirepass>

五、MinIO：对象存储

5.1 下载

dl.minio.io + dl.min.io/client/mc/release/windows-amd64/mc.exe，放到 D:\portable\dev\minio\。

5.2 目录

1
2
3
4


D:\portable\dev\minio\
├── data\ # 对象数据
├── minio.exe
└── minio.bat # 启动脚本

minio.bat：

1
2
3
4
5


@echo off
set path=D:\portable\dev\minio
set minPath=D:\portable\dev\minio\data
"%path%\minio.exe" server %minPath% --console-address ":9000" --address ":9090"
pause

5.3 启动

1
2
3
4
5


.\minio.bat
# 输出：
# API: http://127.0.0.1:9090
# WebUI: http://127.0.0.1:9000
# 默认账号: minioadmin / minioadmin ← 首次启动后立即改密

5.4 mc 客户端

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


# 配置 host
.\mc.exe config host add local http://127.0.0.1:9090 minioadmin minioadmin

# 列 bucket
.\mc.exe ls local/

# 创建 bucket
.\mc.exe mb local/test-bucket

# 上传文件
.\mc.exe cp D:/test.zip local/test-bucket/

# 列已配 host
.\mc.exe config host list

安全提示：minioadmin/minioadmin 是默认账号，生产环境必须通过 MINIO_ROOT_USER / MINIO_ROOT_PASSWORD 环境变量或 config.json 修改。

六、Elasticsearch

6.1 下载

elastic.co/downloads/past-releases#elasticsearch 选 8.x zip。

6.2 启动

1
2


cd D:\portable\dev\elasticsearch-8.11.0
bin\elasticsearch.bat

6.3 关键配置

config/elasticsearch.yml：

1
2
3
4
5
6


cluster.name: dev-cluster
node.name: dev-node-1
network.host: 127.0.0.1
http.port: 9200
discovery.type: single-node
xpack.security.enabled: false

config/jvm.options：

1
2


-Xms2g
-Xmx2g

避坑：Windows 上 ES 跑 2GB 堆需要至少 4GB 物理内存，老机器慎用。

6.4 Kibana 配套

KIMB elastic.co/downloads/kibana 下 Windows zip，启动后访问 http://127.0.0.1:5601，Dev Tools Console 是排查 ES 最方便的工具。

七、WinSW：把 exe 注册成系统服务

7.1 简介

winsw/winsw 是 Windows Service Wrapper，可以把任何可执行文件注册成 Windows 系统服务（支持开机自启、失败重启、日志轮转）。

下载 WinSW-x64.exe（注意 64/32 位），改名成与 XML 同名。

7.2 XML 配置

把 WinSW-x64.exe 复制到 D:\portable\dev\nginx-1.24.0\nginx-service.exe，新建 nginx-service.xml：

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


<service>
 <id>nginx-server</id>
 <name>nginx-server</name>
 <description>Nginx 1.24 反向代理服务</description>
 <executable>D:\portable\dev\nginx-1.24.0\nginx.exe</executable>
 <startarguments>-p D:\portable\dev\nginx-1.24.0\</startarguments>
 <stopexecutable>D:\portable\dev\nginx-1.24.0\nginx.exe</stopexecutable>
 <stoparguments>-p D:\portable\dev\nginx-1.24.0\ -s stop</stoparguments>
 <logpath>%BASE%\logs</logpath>
 <log mode="rotate">
 <sizeThreshold>10240</sizeThreshold>
 <keepFiles>3</keepFiles>
 </log>
</service>

7.3 安装 / 启动 / 卸载

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


# 安装服务（管理员 cmd）
nginx-service.exe install

# 启动
nginx-service.exe start
nginx-service.exe stop
nginx-service.exe restart
nginx-service.exe status

# 卸载
nginx-service.exe uninstall

# 不重装刷新配置
nginx-service.exe refresh

7.4 日志按时间轮转

1
2
3
4
5
6


<log mode="roll-by-size-time">
 <sizeThreshold>10240</sizeThreshold>
 <pattern>yyyyMMdd</pattern>
 <autoRollAtTime>00:00:00</autoRollAtTime>
 <zipOlderThanNumDays>5</zipOlderThanNumDays>
</log>

7.5 实战：MinIO 服务化

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


<service>
 <id>minio-server</id>
 <name>minio-server</name>
 <description>MinIO 对象存储服务</description>
 <env name="HOME" value="%BASE%"/>
 <env name="MINIO_ROOT_USER" value="root"/>
 <env name="MINIO_ROOT_PASSWORD" value="{{REDACTED}}"/>
 <executable>%BASE%\minio.exe</executable>
 <arguments>server "%BASE%\data" --console-address ":9090" --address ":9091"</arguments>
 <logpath>%BASE%\logs</logpath>
 <log mode="roll-by-size-time">
 <sizeThreshold>10240</sizeThreshold>
 <pattern>yyyyMMdd</pattern>
 </log>
</service>

7.6 WinSW 完整命令表

命令	用途
install	安装服务
uninstall	卸载服务
start	启动
stop	停止
restart	重启
status	查看状态
refresh	刷新服务属性（不重装）
customize	自定义包装可执行文件
dev ps	显示服务进程树
dev kill	强制杀掉服务进程
dev list	列出本 exe 注册的所有服务

八、把它们装在一起的服务清单

1
2
3
4
5
6
7
8


D:\portable\services\
├── nginx\ # 端口 80 / 8080
├── caddy\ # 端口 443（自动 HTTPS）
├── redis\ # 端口 6379
├── minio\ # 端口 9090 (API) / 9000 (WebUI)
├── elasticsearch\ # 端口 9200
├── kibana\ # 端口 5601
└── nssm\ # 备用服务化工具

每个目录下放 <服务名>.exe（WinSW 改名）和 <服务名>.xml，统一 install 即可。

九、常见坑与对策

现象	原因	对策
Nginx 启动 403 Forbidden	SELinux / 文件权限	Windows 上多数是路径写错
Caddy 启动报 “bind: address already in use”	端口被占	`netstat -ano
Redis 启动报 “Bad file format”	Windows redis 版本错	装 Cygwin 版（tporadowski）
MinIO 控制台打不开	防火墙	首次启动后改 `minioadmin` 密码
ES 启动 OOM	JVM 堆	`-Xms1g -Xmx1g` 调小
WinSW 服务起不来	不是管理员	用管理员 cmd

十、下一步

Caddy 进阶：用 Cloudflare DNS plugin 自动签通配符证书
MinIO 进阶：搭建 4 节点分布式集群（参考 2022-09-15《MinIO 对象存储实战》）
Redis 进阶：Redis Sentinel 高可用、Redis Cluster 集群
ES 进阶：用 Docker Compose 拉起 ES + Kibana 全套（参考 2025-03-15《Prometheus 监控告警体系》）

十一、参考资料

HAProxy + Keepalived 高可用实战：Nginx 主备双机 + VIP 漂移

Thu, 15 Dec 2016 00:00:00 +0800

背景

单点故障是生产环境的头号杀手——一台 Nginx 挂了，整个网站就 502。

HA（High Availability） = 多台机器 + 故障自动切换，业内有两大经典方案：

方案	代表	适用
LVS + Keepalived	章文嵩博士	四层负载、性能极致
HAProxy + Keepalived	Willy Tarreau	四/七层、配置友好、社区活跃
Nginx + Keepalived	1.x / plus	七层、配置最简单

本篇方案：Nginx + Keepalived + HAProxy（可选用），经典"主备双机 + VIP 漂移"。

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


[客户端] ──> [VIP: 192.168.50.130]
 │ 
 │ ARP 通告 / VRRP 协议
 │
 ┌───────┴───────┐
 │ │
 [主节点 Master] [备节点 Backup]
 Keepalived Keepalived
 Nginx :80 Nginx :80 (standby)
 priority=100 priority=90
 │
 └─> [后端真实服务器池] (tomcat / gunicorn / ...)

故障切换流程：

主节点 Keepalived 心跳正常 → VIP 留在主节点
主节点 Nginx 挂了 → nginx_check.sh 检测失败
Keepalived 把自己的 priority 减 20
备节点 priority 100 > 主节点 80 → VIP 漂移到备节点
备节点 Nginx 接管服务（前提：备节点 Nginx 配置和数据一致）

一、HAProxy vs Nginx vs LVS

1.1 三者对比

维度	LVS	HAProxy	Nginx
工作层	四层（IP）	四/七层	七层（HTTP）
性能	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
功能	仅转发	丰富（健康检查、会话保持、统计）	反代、缓存、限流
配置复杂度	复杂（需要 ipvsadm）	中等	简单
社区	中国主导	法国/欧洲主导	俄罗斯主导
HA 角色	DR 模式性能最强	七层更智能	最简单

选型建议：

追求性能（十万 QPS 以上）：LVS
追求灵活（健康检查细、会话保持复杂）：HAProxy
追求简单（七层反代、HTTP 处理）：Nginx

1.2 为什么本篇选 Nginx + Keepalived

Nginx 已经是"事实标准"的反代，用 Nginx 做 HA 比 HAProxy 更省机器（HAProxy 当主、备各一台 + Nginx 后端，又多两层）。Keepalived 提供 VIP 漂移，简单可靠。

如果业务量大（单 VIP 扛不住 5w+ QPS），应该做"LVS DR + 多 Nginx"或"HAProxy + 多 Nginx"，不要在单 Nginx 上死磕。

二、安装

2.1 Keepalived 2.2.x

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# Ubuntu
apt show keepalived
sudo apt install keepalived -y

# CentOS
yum install keepalived -y

# 验证
keepalived -v
# Keepalived v2.2.4 (08/21,2021)

systemd 管理：

1
2
3


systemctl enable keepalived
systemctl start keepalived
systemctl status keepalived

2.2 HAProxy 2.4.x（可选）

如果需要 HAProxy 做四层负载 + Nginx 后端：

1
2
3
4
5
6
7


# Ubuntu
apt show haproxy
sudo apt install haproxy -y

# 验证
haproxy -v
# HAProxy version 2.4.22-0ubuntu0.22.04.2 2023/08/14

systemd 管理：

1
2
3


systemctl enable haproxy
systemctl start haproxy
systemctl status haproxy

卸载：

1

sudo apt purge haproxy -y

三、HAProxy 配置（可选）

配置文件：/etc/haproxy/haproxy.cfg

3.1 最小可用配置

 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


global
 log /dev/log local0
 log /dev/log local1 notice
 chroot /var/lib/haproxy
 stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
 stats timeout 30s
 user haproxy
 group haproxy
 daemon

 # Default SSL material locations
 ca-base /etc/ssl/certs
 crt-base /etc/ssl/private

 # Mozilla Intermediate
 ssl-default-bind-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:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
 ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
 ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets

defaults
 log global
 mode http
 option httplog
 option dontlognull
 timeout connect 5000
 timeout client 50000
 timeout server 50000
 errorfile 400 /etc/haproxy/errors/400.http
 errorfile 403 /etc/haproxy/errors/403.http
 errorfile 408 /etc/haproxy/errors/408.http
 errorfile 500 /etc/haproxy/errors/500.http
 errorfile 502 /etc/haproxy/errors/502.http
 errorfile 503 /etc/haproxy/errors/503.http
 errorfile 504 /etc/haproxy/errors/504.http

3.2 反代后端

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


# Web 负载
frontend http-in
 bind *:80
 default_backend web-pool

backend web-pool
 balance roundrobin
 option httpchk GET /
 server web1 10.0.1.10:8080 check
 server web2 10.0.1.11:8080 check
 server web3 10.0.1.12:8080 check

# 统计页面
listen stats
 bind *:9000
 stats enable
 stats uri /stats
 stats auth admin:yourpassword

热加载（不中断）：

1
2


haproxy -c -f /etc/haproxy/haproxy.cfg # 验证
systemctl reload haproxy # 重新加载

四、Keepalived 配置（Nginx 主备）

4.1 关键概念

概念	含义
VRRP	Virtual Router Redundancy Protocol，虚拟路由冗余协议
VIP	Virtual IP，对外服务的 IP（飘在主节点网卡上）
priority	优先级（0-254），主高备低
nopreempt	不抢占模式（备升主后，原主恢复不再抢回）
advert_int	VRRP 通告间隔（秒），默认 1
virtual_router_id	VRRP 实例 ID（同组必须相同）
authentication	简单密码认证（防止误抢）
unicast_src_ip / unicast_peer	单播模式（云环境默认，组播被禁用）

4.2 主节点（Master）/etc/keepalived/keepalived.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


! Configuration File for keepalived
global_defs {
 # 标识本节点的字符串，通常为 hostname
 # hostnamectl set-hostname nginx-master1 设置
 router_id nginx-master1
}

# Nginx 健康检查脚本
vrrp_script chk_nginx {
 script "/etc/keepalived/nginx_check.sh"
 interval 2 # 每 2 秒检查一次
 weight -20 # 失败一次 priority -20
 fall 3 # 连续失败 3 次才算挂
 rise 2 # 连续成功 2 次才恢复
}

# 虚拟路由实例
vrrp_instance VI_1 {
 state MASTER # 主节点
 interface eth0 # 绑 VIP 的网卡（云主机可能是 eth1 / ens5）
 virtual_router_id 51 # 虚拟路由 ID（0-255），同组必须一致
 mcast_src_ip 192.168.50.133 # 本机真实 IP
 priority 100 # 主节点优先级（0-254）
 nopreempt # 不抢占（备升主后，原主恢复不再抢）
 advert_int 1 # 通告间隔 1 秒

 # 认证（两边必须一致）
 authentication {
 auth_type PASS
 auth_pass 1111
 }

 # 健康检查
 track_script {
 chk_nginx
 }

 # 虚拟 IP（对外服务的 IP）
 virtual_ipaddress {
 192.168.50.130/24 dev eth0
 }
}

4.3 备节点（Backup）/etc/keepalived/keepalived.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


! Configuration File for keepalived
global_defs {
 router_id nginx-backup1
}

vrrp_script chk_nginx {
 script "/etc/keepalived/nginx_check.sh"
 interval 2
 weight -20
 fall 3
 rise 2
}

vrrp_instance VI_1 {
 state BACKUP # 备节点
 interface eth0
 virtual_router_id 51 # 必须与主一致
 mcast_src_ip 192.168.50.134 # 备机真实 IP
 priority 90 # 备节点优先级（< 主）
 nopreempt
 advert_int 1

 authentication {
 auth_type PASS
 auth_pass 1111
 }

 track_script {
 chk_nginx
 }

 virtual_ipaddress {
 192.168.50.130/24 dev eth0
 }
}

4.4 健康检查脚本 /etc/keepalived/nginx_check.sh

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


#!/bin/bash
# 检测 Nginx 是否存活，不存活就停止 keepalived，触发 VIP 漂移

A=$(ps -C nginx --no-heading | wc -l)
if [ "${A}" -eq 0 ]; then
 # 尝试启动 nginx
 systemctl start nginx
 sleep 2
 # 再查一次
 A=$(ps -C nginx --no-heading | wc -l)
 if [ "${A}" -eq 0 ]; then
 # 启动失败，停掉 keepalived，VIP 漂移到备
 systemctl stop keepalived
 fi
fi

权限与运行：

1

chmod +x /etc/keepalived/nginx_check.sh

4.5 启动

1
2


systemctl enable --now keepalived
systemctl status keepalived

查看 VIP 状态（主节点应有 VIP，备节点没有）：

1
2
3


ip addr show eth0
# 主节点：inet 192.168.50.130/24 ...（VIP 在）
# 备节点：没有 192.168.50.130

查看 VRRP 状态：

1
2
3


tail -f /var/log/syslog | grep -i vrrp
# VRRP_Instance(VI_1) Transition to MASTER STATE
# VRRP_Instance(VI_1) Entering MASTER STATE

五、故障切换演练

5.1 模拟主节点 Nginx 挂掉

1
2
3
4
5


# 在主节点
systemctl stop nginx
# 等 6 秒（fall=3 × interval=2）
# Keepalived 检测到 nginx 挂了，stop keepalived
# VIP 漂移到备节点

观察：

1
2
3
4
5
6
7


# 主节点
ip addr show eth0
# VIP 消失

# 备节点
ip addr show eth0
# VIP 出现 192.168.50.130

客户端视角：从浏览器访问 http://192.168.50.130，整个过程大概 6-10 秒有 502 错误，然后恢复。

5.2 主节点恢复（nopreempt 模式）

1
2
3
4


# 在原主节点
systemctl start nginx
# 启动 nginx，但 keepalived 还没启动
# 此时备节点继续服务（因为 nopreempt）

nopreempt 的意义：

不用 nopreempt → 原主恢复后会"抢回" VIP，两次切换造成额外中断
用 nopreempt → 原主恢复后保持 BACKUP，VIP 留在备，只在下次主挂时才回切

生产建议：用 nopreempt。避免"来回切换"的抖动。

5.3 强制回切（如果需要）

临时：手动在备节点 systemctl stop keepalived，VIP 漂回主。

永久：用 preempt_delay（Keepalived 1.3+）：

1
2
3
4
5
6


vrrp_instance VI_1 {
 state BACKUP
 priority 90
 preempt_delay 300 # 备升主后，5 分钟内原主恢复不回切
 ...
}

六、单播模式（云环境必看）

传统 VRRP 用组播（224.0.0.18），但云主机（阿里云、AWS、华为云）通常禁止组播。必须改单播：

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


vrrp_instance VI_1 {
 state MASTER
 interface eth0
 virtual_router_id 51

 # 关闭组播
 # mcast_src_ip 192.168.50.133 ← 注释掉

 # 开启单播
 unicast_src_ip 192.168.50.133 # 本机真实 IP
 unicast_peer {
 192.168.50.134 # 对端真实 IP
 }

 priority 100
 ...
}

两个节点都要配（主备互换 unicast_src_ip 和 unicast_peer）。

七、Nginx + Keepalived 完整架构

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


 [客户端]
 │
 ↓
 [VIP 192.168.50.130]
 │
 ┌───────────────────────┴───────────────────────┐
 │ │ │
 [主 Nginx] [备 Nginx] [后端集群]
 10.0.1.10 10.0.1.11 10.0.1.20-30
 Keepalived MASTER Keepalived BACKUP Tomcat/...
 priority 100 priority 90
 │ │
 nginx -t / reload nginx -t / reload
 │ │
 /etc/nginx/conf.d/ /etc/nginx/conf.d/ ← rsync 同步
 ↓ ↓
 [共享后端 pool]

主备配置一致（用 rsync/ansible 同步）：

1
2
3


# 在主节点
rsync -avz /etc/nginx/ 10.0.1.11:/etc/nginx/
rsync -avz /var/www/ 10.0.1.11:/var/www/

自动化：用 lsyncd（inotify + rsync）实时同步，或用 etcd/consul 配置中心。

八、Keepalived 邮件告警（可选）

Keepalived 自带邮件提醒，需要 sendmail/postfix：

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


global_defs {
 notification_email {
 admin@example.com
 }
 notification_email_from keepalived@example.com
 smtp_server 127.0.0.1
 smtp_connect_timeout 30
 router_id nginx-master1
}

vrrp_instance VI_1 {
 state MASTER
 smtp_alert # 启用邮件告警
 ...
}

建议用第三方监控代替（Zabbix/Prometheus），邮件告警延迟高、易被忽略。

九、常见问题

9.1 VIP 不漂移

症状：主 nginx 挂了，备节点 VIP 一直不来。

排查：

1
2
3
4
5
6
7


# 看 keepalived 日志
journalctl -u keepalived -f
# 或
tail -f /var/log/syslog | grep -i keepalived

# 看 VRRP 通信
tcpdump -i eth0 vrrp

常见原因：

virtual_router_id 不一致
auth_pass 不一致
防火墙没放 VRRP 协议（云环境）：
1

iptables -I INPUT -p vrrp -j ACCEPT
组播在云环境被禁用 → 改 unicast

9.2 脑裂（split-brain）

症状：主备同时持有 VIP，客户端有时连到主有时连到备。

原因：

主备之间通信中断（如防火墙、心跳网络故障）
两边都以为对方挂了

对策：

双心跳线：两条物理/逻辑链路
iptables 阻断：主检测到脑裂时自己 iptables drop VRRP 报文，主动让出 VIP
云环境：用云厂商的 HAVIP（高可用虚拟 IP）+ API 切换

9.3 VIP 配置后 ping 不通

1
2
3
4
5
6
7
8


# 看 VIP 是不是在网卡上
ip addr show eth0

# 看本地能否 ping 通
ping 192.168.50.130

# 看路由
ip route get 192.168.50.130

云环境特殊：AWS/阿里云 HAVIP 需要显式启用 ARP 响应。

9.4 keepalived 启动失败

1
2
3


# 详细日志
keepalived -D -f /etc/keepalived/keepalived.conf
# 看具体错误

十、卸载

1
2
3
4
5
6
7


systemctl stop keepalived
systemctl disable keepalived
apt remove keepalived -y
rm -rf /etc/keepalived

# 清理 VIP
ip addr del 192.168.50.130/24 dev eth0

小结

HAProxy + Keepalived 是"主备双机 + VIP 漂移"的经典方案：

Keepalived 提供 VIP 漂移（VRRP 协议）
Nginx 健康检查脚本触发 failover
nopreempt 模式避免来回切换
云环境用 unicast（组播被禁用）
主备配置必须一致（rsync/ansible 同步）

生产部署三原则：

必须双心跳线（防止脑裂）
必须 rsync 配置（主备一致）
必须 nopreempt（避免抖动）

替代方案：

云原生：ALB/NLB + 多 AZ
K8s：Service + Ingress Controller
更激进：双活（active-active），两边同时服务

下一步：

上 K8s，用 K8s Service + Ingress 替代 VIP
用 Pacemaker + Corosync 做更复杂的 HA 集群
商业方案：F5 BIG-IP、Citrix ADC

2024 视角：Keepalived 在云原生时代"角色变化"

2016 那篇是基于"自己买物理机 / 私有云"的 HA 方案。2024 视角下，Keepalived 角色已经变化——在云上变成"边缘 / 混合云"工具，K8s / 微服务已经走另一套方案。

一、Keepalived 2.2 → 2.3（2024 现状）

2024 主流版本：Keepalived 2.2.7+（2023-12 起进入 2.3 系列开发）。
新特性：
- vrrp_unicast_peer 增强：单播模式支持多 peer
- vrrp_startup_delay：开机延迟（避免启动时误切换）
- vrrp_priority_increment：动态调整 priority
- Python bindings（实验性）：动态控制 keepalived

1
2
3
4


# 2024 装
apt install keepalived
keepalived -v
# Keepalived v2.2.7 (10/18,2023)

二、云上的"VIP 漂移"由云厂商接管

2016 那篇自建 VIP 在云上经常失效（云厂商禁止组播 / 不允许私设 IP）。
2024 云上 VIP 漂移由云厂商原生提供：
- AWS：Secondary IP + ENI（高可用虚拟 IP）
- 阿里云：HAVIP（高可用虚拟 IP）+ API
- Azure：Load Balancer + Floating IP
- 华为云：HA VIP（2023 起提供）

1
2
3
4
5


# AWS CLI 把 Secondary IP 漂到备机
aws ec2 assign-private-ip-addresses \
 --network-interface-id eni-xxx \
 --private-ip-addresses 10.0.1.100 \
 --allow-reassignment

结论：云上不需要 Keepalived——直接用云厂商的 HA 方案。
Keepalived 仍有价值的场景：
- 私有数据中心（自建机房）
- 边缘节点（IoT / 工厂）
- 混合云（部分在云、部分本地）

三、K8s 时代的"VIP 替代"

2016 那篇 HA 思路是"VIP 漂移到备机"。
K8s 时代：Service + Endpoints + kube-proxy 自动做"虚拟 IP 漂移"：

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


# K8s Service（自动实现 VIP 漂移）
apiVersion: v1
kind: Service
metadata:
 name: nginx-ha
spec:
 selector:
 app: nginx
 ports:
 - port: 80
 targetPort: 80
 type: ClusterIP
# K8s 自动分配 VIP（如 10.96.100.50）
# kube-proxy iptables / ipvs 自动 load balance

优势：无需 Keepalived、K8s 自动处理故障切换、漂移时间 < 1 秒。

四、HAProxy 2.4 → 3.0+ 的变化

HAProxy 3.0（2024-04 发布 LTS）：
- HTTP/3（QUIC） 完整支持
- Runtime API 增强（动态改配置）
- Threads 模型（多线程 LB）
- 新的 nbthread / thread-group 指令

1
2
3
4


# HAProxy 3.0 启用多线程
global
 nbthread 4
 cpu-map auto:1-4 0-3

2024 HAProxy 仍是四/七层 LB 主流，但 Envoy / APISIX 正在分食市场。

五、Envoy / APISIX 的"现代 VIP 替代"

Envoy（CNCF毕业项目，2024 仍是云原生服务网格标准代理）：

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


# Envoy Listener（替代 VIP）
static_resources:
 listeners:
 - name: main
 address:
 socket_address:
 address: 0.0.0.0
 port_value: 80
 filter_chains:
 - filters:
 - name: envoy.filters.network.http_connection_manager
 config:
 stat_prefix: ingress_http
 route_config:
 virtual_hosts:
 - name: backend
 domains: ["*"]
 routes:
 - match: { prefix: "/" }
 route: { cluster: backend_cluster }

APISIX（国产 Apache 项目，2024 大量企业用）：
- 动态路由（不重启热更）
- 多协议（HTTP/gRPC/WebSocket/MQTT）
- 内置 Dashboard（可视化配置）

六、`keepalived + HAProxy` 的"现代双活"写法

2016 那篇给的是主备（一主一备）。
2024 趋势：双活（两边同时服务）—— Keepalived 可以实现：

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


# 主节点 keepalived.conf
vrrp_instance VI_1 {
 state BACKUP
 interface eth0
 virtual_router_id 51
 priority 100
 nopreempt
 
 # 两边都启用 nginx
 notify_master "/etc/keepalived/scripts/start_local_lb.sh"
 notify_backup "/etc/keepalived/scripts/keep_local_lb.sh"
}

两边都跑 nginx / HAProxy，但通过 DNS 智能解析 + 全局负载均衡分配流量。

七、Keepalived 的"健康检查"增强

2016 那篇给的 nginx_check.sh 是"脚本检测 nginx 进程"。
2024 现代写法：用 vrrp_track + vrrp_script + HTTP 检查：

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


vrrp_script chk_nginx {
 script "curl -sf http://127.0.0.1/health || exit 1"
 interval 2
 weight -20
 fall 3
 rise 2
 timeout 5
}

vrrp_script chk_disk {
 script "df -h / | awk 'NR==2 {print $5}' | grep -E '^[8-9][0-9]%' && exit 1"
 interval 30
 weight -10
}

track_script 多个 script 同时跟踪。

八、IPv6 VIP

2024 趋势：IPv6 的 VIP 部署：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


vrrp_instance VI_1 {
 state MASTER
 interface eth0
 virtual_router_id 51
 priority 100
 
 virtual_ipaddress {
 192.168.50.130/24 dev eth0
 2001:db8::130/64 dev eth0
 }
}

IPv6 默认不依赖 ARP / 组播——使用 NDP（Neighbor Discovery Protocol）。

源文档：os/linux/第三方tools/dev/高可用/高可用.md（HAProxy/Keepalived 安装、主备配置、nginx_check.sh）

CentOS 7 全面实战：阿里源、Docker、Harbor 与 Nginx+Let's Encrypt

Tue, 15 Sep 2015 00:00:00 +0800

一、为什么 2015 年要写这份"一站式"

2015 年的 CentOS 7 服务器基本就是"yum 源 + Docker + Web 服务"三件套。本篇把三个场景串成一篇深度文——从国内 yum 源选择、装 Docker CE、起 Harbor 私有仓库，到 Docker 化部署 Nginx + 申请 Let’s Encrypt 免费证书并自动续期。每个环节的坑都标出来了。

本文写于 2015-09-15。Let’s Encrypt 2015-09-14 进入公开 beta，2016-04 正式 GA，本文示例贴近 Let’s Encrypt 早期生态。CentOS 7 已 2024-06-30 进入 ELS 阶段，新机器建议直接 Rocky / Alma 9。

二、国内 yum 源选择

CentOS 7 装好后第一件事就是换源——官方源国内外都慢，国内服务器一定要换。常见选择：

源	特点
阿里云 `mirrors.aliyun.com/repo/Centos-7.repo`	同步快、稳定、企业用得多
网易 163 `mirrors.163.com/.help/CentOS7-Base-163.repo`	老牌、文档多
中科大 USTC	高校机房友好
清华 TUNA	高校机房友好

阿里云（企业最常见）：

1
2
3
4


mv /etc/yum.repos.d/CentOS-Base.repo /etc/yum.repos.d/CentOS-Base.repo.bak
curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.repo
yum clean all && yum makecache
yum update

装 EPEL 源（很多 Python 包靠它）：

1

yum install -y epel-release

三、Docker CE 安装

3.1 卸载旧版

1
2
3
4
5
6
7
8


sudo yum remove docker \
 docker-client \
 docker-client-latest \
 docker-common \
 docker-latest \
 docker-latest-logrotate \
 docker-logrotate \
 docker-engine

注意：/var/lib/docker 目录（镜像、容器、卷、网络）默认不会删，重装后数据还在。

3.2 走官方 yum 源

1
2
3


sudo yum install -y yum-utils device-mapper-persistent-data lvm2
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce

想装指定老版本：

1
2


yum list docker-ce --showduplicates | sort -r
sudo yum install docker-ce-18.09.1

3.3 走 get.docker.com 一键脚本

2015-2017 社区更常用：

1
2
3


curl -sSL https://get.docker.com/ | sh
systemctl start docker
systemctl enable docker

3.4 加 docker 用户组

1
2


sudo usermod -aG docker <your-user>
# 重新登录生效

3.5 验证

1

sudo docker run hello-world

四、配置阿里云 Docker 镜像加速

DockerHub 拉镜像国内极慢，必须配镜像加速器。2015-2016 年用得最多的是 daocloud.io：

1
2
3
4
5
6
7
8
9


mkdir -p /etc/docker
tee /etc/docker/daemon.json <<-'EOF'
{
 "registry-mirrors": ["http://f1361db2.m.daocloud.io"],
 "insecure-registries": []
}
EOF
systemctl daemon-reload
systemctl restart docker

多镜像源写法（2020+ 推荐）：

1
2
3
4
5
6
7


{
 "registry-mirrors": [
 "https://mirror.ccs.tencentyun.com",
 "https://docker.mirrors.ustc.edu.cn"
 ],
 "insecure-registries": ["<your-private-registry>:5000"]
}

验证是否生效：

1
2


ps -ef | grep docker
# 命令行里看到 --registry-mirror=... 就对了

五、装 docker-compose

5.1 早期：pip 装（2015-2017）

1
2


yum install -y python-pip
pip install docker-compose

5.2 中期：二进制直装

1
2
3
4


curl -L "https://github.com/docker/compose/releases/download/1.25.0/docker-compose-$(uname -s)-$(uname -m)" \
 -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
docker-compose version

5.3 2020+：Docker CLI plugin

1
2
3
4
5
6


# Compose v2
mkdir -p ~/.docker/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v2.23.3/docker-compose-linux-x86_64 \
 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
docker compose version

六、Harbor 私有仓库

Harbor 是 VMware 开源的镜像仓库（2016-03 第一个 release），到 2017-2018 年成为国内事实标准。2017-2019 期间安装用 离线包最稳：

6.1 下载离线安装包

1
2
3


wget https://github.com/vmware/harbor/releases/download/v1.9.1/harbor-offline-installer-v1.9.1.tgz
tar -xvf harbor-offline-installer-v1.9.1.tgz
cd harbor

6.2 改配置

1
2
3
4
5
6


vim harbor.yml

hostname: <your-registry-ip-or-domain> # 例: 192.168.6.128
http:
 port: 28083
harbor_admin_password: <your-admin-pass>

6.3 装 + 启

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


./install.sh

# 启停
docker-compose stop
docker-compose start

# 改完配置要重生效
docker-compose down -v
vim harbor.yml
./prepare
docker-compose up -d

# 推镜像
docker login <your-registry-ip>:28083
docker tag alpine <your-registry-ip>:28083/dev/alpine:3.10.3
docker push <your-registry-ip>:28083/dev/alpine:3.10.3

6.4 默认凭据

admin 账号：admin / Harbor12345（生产环境一定要改）
db_auth PostgreSQL root：root123（同上）

七、Docker 容器日志切割

不切日志，/var/lib/docker/containers/ 下的 *-json.log 可以把磁盘塞满：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# /etc/docker/daemon.json
{
 "log-driver": "json-file",
 "log-opts": {
 "max-size": "500m",
 "max-file": "3"
 }
}
systemctl daemon-reload
systemctl restart docker

坑提醒：只对新建容器生效，老容器需要 docker rm 后重建。

清空单个容器日志：

1

truncate -s 0 /var/lib/docker/containers/<container-id>/*-json.log

八、Nginx + Let’s Encrypt 免费证书

Let’s Encrypt 2015-09-14 公开 beta、2016-04 正式 GA，把免费 HTTPS 证书从"程序员折腾"变成了"运维 5 分钟"。证书有效期 90 天，必须用 certbot renew 自动续期。

8.1 安装 certbot

1
2


yum install -y epel-release
yum install -y certbot

8.2 申请证书（webroot 方式）

要求域名已经解析到本机：

1
2
3
4
5


certbot certonly --webroot \
 -w /var/www/html \
 -d mydemo.com \
 -m <your-email> \
 --agree-tos

成功后证书在：

1
2
3
4
5


/etc/letsencrypt/live/mydemo.com/
├── cert.pem # 用户证书
├── chain.pem # 中间证书
├── fullchain.pem # cert + chain
└── privkey.pem # 私钥

8.3 查有效期

1
2
3


openssl x509 -noout -dates -in /etc/letsencrypt/live/mydemo.com/cert.pem
# notBefore=...
# notAfter=...

8.4 配合 Docker Nginx

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


# docker-compose.yml
services:
 nginx:
 image: nginx
 container_name: nginx
 ports:
 - "80:80"
 - "443:443"
 volumes:
 - /var/www/html:/usr/share/nginx/html:ro
 - /webser/etc/nginx:/etc/nginx/conf.d
 - /webser/logs/nginx:/var/log/nginx
 - /etc/ssl:/etc/ssl
 - /etc/letsencrypt:/etc/letsencrypt

8.5 Nginx 配置

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


server {
 listen 443 ssl http2;
 server_name mydemo.com;

 ssl_certificate /etc/letsencrypt/live/mydemo.com/fullchain.pem;
 ssl_certificate_key /etc/letsencrypt/live/mydemo.com/privkey.pem;

 ssl_session_timeout 1d;
 ssl_session_cache shared:SSL:50m;
 ssl_session_tickets on;

 # 前向保密（PFS）参数
 ssl_dhparam /etc/ssl/private/dhparam.pem;

 ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
 ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:...:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK';
 ssl_prefer_server_ciphers on;

 root /usr/share/nginx/html;
 index index.html;
}

dhparam.pem 生成（一次性，2-3 分钟）：

1
2


mkdir -p /etc/ssl/private
openssl dhparam 2048 -out /etc/ssl/private/dhparam.pem

8.6 自动续期 crontab

1
2
3
4


crontab -e

# 每月 1 号 05:00 续期 + 重启 nginx
00 05 01 * * /usr/bin/certbot renew --quiet && docker restart nginx

坑提醒：续期时网站必须能访问到 /.well-known/acme-challenge/——也就是说 HTTP 80 端口必须能从公网访问到 webroot。

九、Docker 存储路径搬家

/var/lib/docker 默认在根盘，根盘很容易塞满：

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


systemctl stop docker
mkdir -p /home/docker

vim /usr/lib/systemd/system/docker.service
# ExecStart=/usr/bin/dockerd \
# --graph=/home/docker \ # Docker 17.05+ 推荐 data-root
# -H fd:// \
# --containerd=/run/containerd/containerd.sock

systemctl disable docker
systemctl enable docker
systemctl daemon-reload
systemctl start docker
docker info | grep "Docker Root Dir"
# Docker Root Dir: /home/docker

17.05+ 推荐用 data-root 而不是 --graph，后者已 deprecated。

十、磁盘空间排查速查

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 全局
df -h

# 各目录占用
du -sh /*

# 当前目录前 10 大
du -hd 1 | sort -hr | head

# 删除 7 天前的文件
find ./ -mtime +7 | xargs rm -rf

生产环境慎用 rm -rf / 这类命令——本文示例中所有路径都加了具体子目录，是基本的安全习惯。

十一、典型坑速查

现象	原因	处理
`docker run` 报 “Cannot connect to the Docker daemon”	daemon 没启 / 装完没 reload	`systemctl daemon-reload && systemctl restart docker`
拉镜像超慢	没配镜像加速	改 `/etc/docker/daemon.json` 的 `registry-mirrors`
`docker-compose` 命令找不到	只装了 docker，没装 compose	走 §5 装 compose
容器日志把磁盘塞满	没切日志大小	改 `daemon.json` 的 `log-opts`
Let’s Encrypt 续期失败	80 端口被占 / 域名解析不到	`certbot renew --dry-run` 模拟一次排查
Harbor 装完访问 502	端口冲突 / yml 改完没 `prepare`	改完 yml 必跑 `./prepare`

十二、下一步

想把 Harbor 升级到 v2.x → 见 Harbor 升级文档，先备份 /data/database 再升级
想换 SSL 自动化方案（acme.sh / Caddy） → 见 2017-09-15 CentOS 7 开发环境
想上 Kubernetes → 走 kubeadm，先关 swap（见 2012-12-15 CentOS 7 早期实践）
不想自己维护 Harbor → 换 Docker Hub Pro / 阿里云 ACR / 腾讯云 TCR

参考资料

2024 视角：Docker 24+ / 25+ / 26+ 已经"云原生一体化"

2015 那篇是 Docker 1.7~1.12 时代。2024 视角下 Docker 已经 26+（2024-04），加上 containerd / BuildKit / compose v2 已经"完全成熟"。

一、Docker 24 → 26+（2024 主流）

Docker 24.0（2023-05）：引入 Docker Scout（镜像漏洞扫描）、Docker Debug。
Docker 25.0（2024-01）：Compose v2 全面替代 Compose v1（v1 已废弃）。
Docker 26.0（2024-04）：BuildKit 默认启用、WebAssembly 支持。
Docker 27.0（2024-06）：Testcontainers 集成、容器测试能力。

1
2
3
4


docker --version
# Docker version 26.1.4, build 5650f9b
docker compose version
# Docker Compose version v2.27.0

二、containerd 替代 dockerd 的趋势

2024 大量 K8s 集群已经直接用 containerd（不再用 Docker）：
- containerd 1.7+（2023-04）：K8s CRI 兼容
- nerdctl：containerd 的 Docker-like CLI
- ctr（containerd 原生 CLI）

1
2


# 用 nerdctl 跑容器（语法跟 docker 一样）
nerdctl run -d --name nginx -p 80:80 nginx:1.25

2024 趋势：K8s 节点不要装 Docker，直接装 containerd——少 30% 资源占用。

三、BuildKit 时代

BuildKit（Docker 18.09+ 实验 → 26+ 默认）大幅提升 docker build 速度：
- 并行构建（多 stage 一起）
- 缓存复用（跨 build 共享层缓存）
- mount 语法（--mount=type=cache）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# BuildKit 语法（2024 推荐）
# syntax=docker/dockerfile:1
FROM golang:1.22 AS builder
WORKDIR /app
COPY . .
RUN --mount=type=cache,target=/root/.cache/go \
 go build -o /out/app

FROM alpine
COPY --from=builder /out/app /app

四、Harbor v2.x 已成事实标准

2015 那篇是 Harbor v1.9 时代。2024 主流：

Harbor 2.10+（2024）：支持 OCI 标准、镜像签名（cosign）、P2P 镜像分发（kraken）。
Harbor 2.11+（2024-05）：AI 模型管理（ML Model Registry）—— LLM 镜像 / 权重文件直接托管。

1
2
3
4
5
6


# 2024 装 Harbor 2.10
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
tar xvf harbor-offline-installer-v2.10.0.tgz
cd harbor
cp harbor.yml.tmpl harbor.yml
./install.sh

五、Let’s Encrypt 的"现代"姿势

2015 那篇是 certbot + crontab。2024 主流：

acme.sh：单脚本，80+ DNS 厂商支持，更轻量：

1
2
3
4
5
6
7
8


curl https://get.acme.sh | sh
export Ali_Key="xxx"
export Ali_Secret="yyy"
acme.sh --issue -d example.com --dns dns_ali
acme.sh --install-cert -d example.com \
 --key-file /etc/nginx/ssl/example.com.key \
 --fullchain-file /etc/nginx/ssl/example.com.crt \
 --reloadcmd "systemctl reload nginx"

lego（Go 写）：另一个 ACME 客户端，比 certbot 快。
Caddy：内置 ACME——配置即用：

1
2
3
4


example.com {
 reverse_proxy localhost:3000
}
# 自动 HTTPS + 自动续期

六、阿里云 Docker 镜像加速 2024 现状

2015 那篇的 daocloud.io 已经 2020 起停止免费服务。

2024 推荐：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "registry-mirrors": [
 "https://docker.m.daocloud.io", # DaoCloud 现仍可
 "https://mirror.baidubce.com", # 百度云
 "https://hub-mirror.c.163.com", # 网易
 "https://docker.mirrors.ustc.edu.cn", # 中科大
 "https://docker.nju.edu.cn", # 南京大学
 "https://docker.mirrors.sjtug.sjtu.edu.cn" # 上交大
 ]
}

2024 国内云厂商镜像（更稳定）：
- 阿里云：<regionId>.mirror.aliyuncs.com（每个 region 独立）
- 腾讯云：mirror.ccs.tencentyun.com
- 华为云：swr.cn-north-4.myhuaweicloud.com

七、`docker-compose` → `docker compose` 时代

2024 已无 docker-compose（v1 命令），统一用 docker compose（v2 plugin）。
2023-08 Docker 移除 Compose v1，所有项目必须迁移：

1
2
3
4
5


# 旧
docker-compose up -d

# 新
docker compose up -d

八、Docker 在 K8s 时代的"角色"

2024 大量生产项目已经不用 Docker 跑生产——直接用 K8s + containerd。
Docker 仍用的场景：
- 本地开发
- CI/CD 构建
- 小规模部署（< 10 容器）
- 个人项目
K8s 时代：
- K3s（轻量 K8s，单二进制）
- K0s（CNCF 零摩擦 K8s）
- MicroK8s（Ubuntu 出的）
- minikube（本地开发）

九、Docker 替代品

Podman（Red Hat 出，CentOS Stream / RHEL 9 默认）：无 daemon 架构，rootless 容器。
nerdctl（containerd CLI）：K8s 节点首选。
Buildah：专为 build 场景，无 daemon。
LXC / LXD：系统容器（类似 VM 的容器）。

Nginx + Keepalived 双机热备与 VRRP 原理

Mon, 15 Dec 2014 00:00:00 +0800

本文写于 2014 年 12 月——彼时 Nginx 反代 + Keepalived 是中小公司做"高可用"的标配，比上硬件 F5 便宜，比 DNS 切换快。

一、为什么需要双机热备

单点 Nginx 一旦宕机，整个网站瞬间 503。在没有云 SLB 的年代，IDC 机房做"对外服务的入口高可用"几乎只有两条路：

硬件 F5 / A10 负载均衡：贵，动辄几十万
软件 VRRP 协议 + 两台 Nginx：Nginx 本身免费，Keepalived 同样免费

Nginx + Keepalived 方案的核心是虚拟 IP（VIP）漂移：两台机器共享一个 VIP，正常情况下 VIP 在主节点，一旦主节点 Nginx 挂了，VIP 自动漂到备节点，对外几乎无感。

二、Keepalived 工作原理

Keepalived 是基于 VRRP（Virtual Router Redundancy Protocol，虚拟路由冗余协议） 实现的高可用服务软件，主要功能是真机故障隔离 + 负载均衡器间失败切换，防止单点故障。

VRRP 协议保证：当主机的下一跳路由器出现故障时，由另一台路由器代替故障路由器工作，从而保持网络通信的连续性和可靠性。

关键点：VRRP 虚拟出来的是"路由"——本质是一组路由器（物理机）共享一个虚拟 IP，对外只暴露 VIP，内部选举谁持有 VIP。

三、Nginx + Keepalived 双机热备部署

3.1 拓扑结构

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


 ┌──────────────┐
 │ VIP │ <- 对外服务的虚拟 IP（如 192.168.6.100）
 │ 192.168.6.100│
 └──────┬───────┘
 │ VRRP 心跳
 ┌───────┴───────┐
 │ │
┌──────┴──────┐ ┌─────┴───────┐
│ Master │ │ Backup │
│ 192.168.6.29│ │192.168.6.30 │
│ Nginx+Keep │ │ Nginx+Keep │
└─────────────┘ └─────────────┘

3.2 安装 Keepalived

两台机器都装：

1

yum install keepalived -y

3.3 配置 keepalived.conf

主节点（/etc/keepalived/keepalived.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


vrrp_script check_nginx {
 script "/usr/local/src/check_nginx.sh"
 interval 2 # 每 2 秒检查一次
 weight -20 # 失败时优先级减 20
 fall 3 # 连续 3 次失败才认为真挂了
 rise 2 # 连续 2 次成功才认为恢复
}

vrrp_instance VI_1 {
 state MASTER # 本机初始状态
 interface eth0 # 绑定的网卡
 virtual_router_id 51
 priority 100 # 主节点优先级（备节点配 90）
 advert_int 1 # VRRP 通告间隔（秒）
 authentication {
 auth_type PASS
 auth_pass 1111
 }
 virtual_ipaddress {
 192.168.6.100/24 # VIP
 }
 track_script {
 check_nginx
 }
}

备节点唯一区别：state BACKUP + priority 90。

3.4 健康检查脚本

Keepalived 不仅能检查自己心跳，更强大的是通过脚本检查 Nginx 是否活着——/usr/local/src/check_nginx.sh：

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


#!/bin/bash
# Nginx 健康检查：HTTP 200 才算健康
A=`ps -C nginx --no-header | wc -l`
if [ $A -eq 0 ]; then
 # Nginx 挂了，尝试拉起
 /usr/local/nginx/sbin/nginx
 sleep 2
 if [ `ps -C nginx --no-header | wc -l` -eq 0 ]; then
 # 拉起失败，关闭 Keepalived，让 VIP 漂到备机
 killall keepalived
 fi
fi

加执行权限：chmod +x /usr/local/src/check_nginx.sh。

3.5 启动

1
2


nginx # 先启动 Nginx
systemctl start keepalived # 再启动 Keepalived

查看 VIP 是否在主节点：ip addr show eth0，应能看到 inet 192.168.6.100/24 出现在主节点。

四、模拟故障测试

1
2
3
4
5
6
7


# 1. 在主节点停掉 Nginx
nginx -s stop

# 2. 检查脚本会拉起 Nginx（如果起不来，则杀掉 Keepalived）
# 3. 观察 VIP 漂移到备节点
ip addr show eth0
# 备节点上应出现 192.168.6.100

五、VRRP 选举细节

优先级（priority）：数值越大越优先成为 Master，Master 范围 1-254（0 和 255 有特殊用途）
不抢占模式（nopreempt）：默认是抢占的（备机升级为主机后，原主机恢复会再抢回 VIP），但实际生产中建议配不抢占——避免抖动
认证（authentication）：PASS 认证要求主备密码一致，否则收不到通告
virtual_router_id：同一 VRRP 实例内必须相同，不同实例必须不同

六、Nginx + Keepalived 的局限

VIP 漂移有秒级延迟：默认 advert_int 1 + 脚本 interval 2 + fall 3，最坏 5-6 秒才完成漂移
脑裂问题：主备之间心跳断了但都还活着，会出现两个 VIP 抢同一资源——解法：① 双心跳线（串口线 + 网线）；② 监控脚本探测对端
单点配置不统一：两台机器的 Nginx 配置必须同步——解法：用 rsync + inotify 自动同步，或上配置中心（Nacos/Consul）

七、后续演进

随着云时代到来，这套方案在 2017 年后逐渐被替代：

云厂商 SLB（阿里云 SLB / AWS ELB）：开箱即用，自带高可用
LVS + Keepalived：Nginx 退到 7 层，LVS 在 4 层做入口，更稳
Nginx + UPScript + Consul：服务发现 + 健康检查 + 动态 upstream，比静态 VIP 更灵活

但理解 VRRP 原理是面试高频题——它不仅能解释 Keepalived，也能解释 LVS、HAProxy、Cisco HSRP、华为 VRRP，本质都是同一个协议家族。

八、面试常问

Q：Keepalived 和 Heartbeat 有什么区别？ A：都是高可用集群管理软件，但 Keepalived 基于 VRRP 协议工作在网络层，主要做 IP 漂移；Heartbeat 更老，做资源接管和消息心跳。Keepalived 配置简单 + 自带健康检查脚本，是现在的事实标准。

Q：脑裂怎么解？ A：三招——① 双心跳线（网线 + 串口）物理防脑裂；② 监控脚本（监控对端 VIP 是否存在）；③ 业务层幂等设计兜底（即使双写也保证最终一致）。

Q：Nginx + Keepalived 和 LVS + Keepalived 怎么选？ A：LVS 工作在 4 层（传输层），性能更高（百万级并发），但配置复杂；Nginx 工作在 7 层（应用层），可以做按 URL / Header 灰度，但性能低一档（10 万级并发）。实际生产两者经常配合：LVS 做入口 → Nginx 7 层分流 → 后端应用。

九、小结

核心思想：VRRP 协议 + 共享 VIP + 健康检查 + 自动漂移
部署关键：两台机器 + 同样 Nginx 配置 + 同样 Keepalived 配置（priority 不同）
健康检查脚本：让 Keepalived 不只检查自己，更检查 Nginx 进程
演进方向：云 SLB / LVS 4 层 / Consul 服务发现

十、2024+ 视角：10 年后回望，VRRP 仍不过时

本文写于 2014 年 12 月。10 年后的 2024-2026，Nginx + Keepalived 这套方案依然没死——只是从"主力"变成"基础设施"。

10.1 Keepalived 10 年未变：协议层的"长寿"

2014 年的 Keepalived 配置和 2024 年的 Keepalived 配置核心语法几乎一样——这是协议层（VRRP RFC 5798）稳定的胜利。

2024-2026 行业里 Keepalived 仍在用的场景：

传统行业（银行 / 政企 / 制造）—— 上 K8s 太重，传统 IDC 还在用 Keepalived
私有云 / 混合云—— 自建机房 + 公有云的混合架构，Keepalived 比云 SLB 更灵活
数据库双主 / 主备—— MySQL / PostgreSQL 高可用方案里 Keepalived 仍是标配
国产化替代—— 信创场景（国产化软硬件替代）里，Keepalived 是少数没被卡脖子的 HA 方案

关键认知：VRRP 协议"够简单、够稳定"是 10 年长寿的根本——AI 时代到来时，最朴素的技术反而最难被淘汰。

10.2 云原生时代的 HA 演进

2014 年我们用 Keepalived 做"主备 + VIP 漂移"。2024-2026 主流 HA 方案：

场景	2014 主流	2024+ 主流
公有云入口	Nginx + Keepalived	阿里云 SLB / AWS ALB / Cloudflare
私有云入口	Nginx + Keepalived	Nginx Ingress + K8s Service
数据库高可用	MySQL + Keepalived + VIP	MHA / Orchestrator / Patroni / Galera
Redis 高可用	Redis Sentinel + Keepalived	Redis Sentinel + Cluster + K8s Operator
消息队列 HA	RabbitMQ + Keepalived	RabbitMQ Cluster + K8s Operator
全局负载	DNS 轮询 + F5	DNS + 全球 Anycast（Cloudflare / AWS Global Accelerator）

关键变化：Keepalived 的角色从"主备入口"变成"K8s / 数据库内部"—— 它没有消失，只是下沉了。

10.3 K8s 时代的 VIP 替代方案

2014 年的"VIP 漂移"在 K8s 时代有了新解法：

K8s Service (ClusterIP)：内部自动负载均衡 + 健康检查——VIP 概念被抽象
MetalLB（2024-2026 稳定）：K8s 集群内的"LoadBalancer"实现——给 bare-metal 集群提供 VIP 能力
Ingress-Nginx + ExternalDNS：把 K8s 服务暴露到公网，VIP 概念被 DNS 替代
Cilium + BGP：基于 eBPF 的网络方案，VIP 通过 BGP 协议声明

1
2
3
4
5
6
7
8
9


# MetalLB 2024 主流配置（替代 Keepalived 在 K8s 中的角色）
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
 name: production
 namespace: metallb-system
spec:
 addresses:
 - 192.168.6.100-192.168.6.110 # VIP 池

2024 主流选择：新项目直接上 K8s + MetalLB；老项目继续 Keepalived 不动——两者并不冲突。

10.4 现代 HA 方案的"5 个特性"对比

方案	自动漂移	健康检查	跨地域	与服务发现集成	复杂度
Nginx + Keepalived	✅	✅（脚本）	❌	❌	低
HAProxy + Keepalived	✅	✅（内置）	❌	❌	低
LVS + Keepalived	✅	✅	❌	❌	中
K8s Service + MetalLB	✅	✅	弱	✅（K8s 原生）	中
云 SLB（阿里/AWS）	✅	✅	✅	✅	极低
Istio / Service Mesh	✅	✅	✅	✅	高
Cloudflare Load Balancer	✅	✅	✅	✅	极低

2024+ 选型经验：小团队用云 SLB / Cloudflare；中等规模 K8s + MetalLB；大规模 Istio / Linkerd；政企 / 信创 Keepalived + 国密 SSL。

10.5 面试题补充（2024+ 视角）

Q：Keepalived 的 VRRP 协议在 IPv6 时代还有用吗？ A：有用。VRRPv3（RFC 5798） 同时支持 IPv4 和 IPv6，2024+ 国产化 IPv6 改造里 Keepalived 仍是首选 HA 方案。

Q：脑裂问题在 K8s 时代怎么解决？ A：K8s 通过 etcd + Raft 协议避免脑裂——集群状态写入 etcd，多数节点同意才算"主"。这是分布式系统层面的"反脑裂"。

Q：为什么云厂商几乎不用 Keepalived？ A：云厂商用底层网络设备的 Anycast + ECMP 实现 LB，Keepalived 是"用户态方案"，在大规模下性能 / 可观测性都比不上硬件方案。但对中小企业，Keepalived 仍然是性价比最高的选择。

Q：Nginx + Keepalived 在 AI 时代还能用吗？ A：能。 AI 服务的入口（推理 API 网关）本质上还是 HTTP，Nginx + Keepalived 一样能跑。区别是 Nginx 需要装 ngx_http_auth_request_module 之类的模块对接 AI 鉴权。

10.6 个人总结：10 年技术演进的"启示"

写这篇文章时我刚毕业 1 年，Keepalived 是我接触的第一个"高可用"方案。10 年后再看：

协议层的稳定性 > 框架的时髦度——VRRP 10 年没变，Spring Cloud / Dubbo 换了 3 套
“够用"比"更好"更重要——Keepalived 不是最优解，但 10 年后仍是"够用” 的方案
云时代不等于"传统方案已死"——Keepalived 仍在政企 / 信创 / 数据库 HA 场景下活得很好
架构选型要"看 10 年"——2014 年选 Keepalived 的项目，2024 年大多还在用

2024+ 给后辈的建议：

面试要会 VRRP 原理——它是 Keepalived / LVS / HSRP 的共同基础

生产要懂 K8s Service——新项目都用这个

架构要懂 BGP / Anycast——云时代的 HA 底层

传统行业要会用 Keepalived——政企 / 银行 / 信创仍是主力

10 年后，VRRP 协议可能还是不会变——这就是"基础设施"的浪漫。

参考资料（2024+ 补充）

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）