四层代理 on Liangweidong's blog

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 集群流量入口：Ingress-nginx 七层与 TCP/UDP 四层代理实战

Tue, 15 Dec 2020 00:00:00 +0800

K8s 集群流量入口：Ingress-nginx 七层与 TCP/UDP 四层代理实战

TL;DR：在 K8s 里 Pod IP / ClusterIP 只能在集群内访问。要把服务暴露到集群外，常见链路是 ingress-nginx（七层 HTTP）→ Service（ClusterIP）→ Pod；非 HTTP 的 TCP/UDP 流量（数据库、MQTT、WebSocket、SSH）走 ingress-nginx 的 四层 stream-snippet / ConfigMap 或 hostNetwork + DaemonSet 模式。本文是一份基于生产二进制集群踩坑的实战笔记。

一、为什么需要 Ingress（When to use）

K8s 提供了 4 种把集群内服务暴露到外部的方式：

方式	适用场景	优点	缺点
`NodePort`	开发测试、单端口临时调试	简单，配置最少	端口范围受限（30000-32767），要逐个开防火墙
`LoadBalancer`	云厂商环境	自动化分配公网 IP	依赖云厂商 LB，每个 Service 一个 LB 贵
`Ingress`	HTTP/HTTPS 七层路由，多域名多路径	一台 LB 服务多套系统，支持 TLS 终止、灰度	只能代理 HTTP/HTTPS
`hostNetwork`	四层流量 + 极致性能	走宿主机网络，无 kube-proxy 转发损耗	一个 Node 只能跑一个 Pod，要配 `nodeSelector`

核心架构：

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


外网 (Client)
 │
 ▼
[ NodePort / LoadBalancer / hostNetwork ]
 │
 ▼
[ ingress-nginx-controller ] ← 七层：解析 Host / Path
 │
 ▼
[ Service (ClusterIP) ] ← 集群内虚拟 IP
 │
 ▼
[ Pod (业务容器) ]

原则：ingress 代理 service，service 代理 pod。Ingress 本身不直接连 Pod，一定要过 Service 这一层（service mesh 也是同理）。

API 版本注意：本文示例全部使用 apiVersion: networking.k8s.io/v1（K8s 1.19 GA，1.22 起 extensions/v1beta1 被彻底移除）。kubernetes.io/ingress.class 注解在 1.18 后也已被 spec.ingressClassName 取代，请直接使用新写法。

二、安装 ingress-nginx

2.1 部署清单来源

官方仓库：https://github.com/kubernetes/ingress-nginx
云厂商部署清单：https://github.com/kubernetes/ingress-nginx/blob/main/deploy/static/provider/cloud/deploy.yaml

⚠️ 版本匹配：K8s 1.19+ 务必使用 ingress-nginx v0.46+（首个 networking.k8s.io/v1 稳定支持的 controller），2020 年下半年该分支已 GA。

2.2 应用与查看

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


# 部署
kubectl apply -f /etc/k8s/ingress-nginx/deploy.yaml

# 删除
kubectl delete -f /etc/k8s/ingress-nginx/deploy.yaml

# 部署后产生的核心资源
namespace/ingress-nginx created
serviceaccount/ingress-nginx created
serviceaccount/ingress-nginx-admission created
role.rbac.authorization.k8s.io/ingress-nginx created
clusterrole.rbac.authorization.k8s.io/ingress-nginx created
configmap/ingress-nginx-controller created
service/ingress-nginx-controller created
deployment.apps/ingress-nginx-controller created
job.batch/ingress-nginx-admission-create created
job.batch/ingress-nginx-admission-patch created
ingressclass.networking.k8s.io/nginx created
validatingwebhookconfiguration.admissionregistration.k8s.io/ingress-nginx-admission created

2.3 资源清单

1

kubectl get all -n ingress-nginx

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


NAME READY STATUS RESTARTS AGE
pod/ingress-nginx-admission-create-cf9w5 0/1 Completed 0 7m36s
pod/ingress-nginx-admission-patch-zm7m5 0/1 Completed 0 7m36s
pod/ingress-nginx-controller-766bcbf897-fhvrb 1/1 Running 0 7m36s

NAME TYPE CLUSTER-IP PORT(S)
service/ingress-nginx-controller NodePort 10.x.x.x 80:30080/TCP,443:30443/TCP
service/ingress-nginx-controller-admission ClusterIP 10.x.x.x 443/TCP

NAME READY UP-TO-DATE AVAILABLE
deployment.apps/ingress-nginx-controller 1/1 1 1

这里的 ingressclass.networking.k8s.io/nginx 是 v1 引入的 IngressClass 对象，下游 Ingress 资源靠 spec.ingressClassName: nginx 引用它。

三、最简七层反代测试

3.1 测试 Deployment / Service / Ingress

 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


# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 namespace: test
spec:
 replicas: 3
 selector:
 matchLabels:
 app: nginx
 template:
 metadata:
 labels:
 app: nginx
 spec:
 containers:
 - name: nginx
 image: nginx:1.25
---
# service.yaml
apiVersion: v1
kind: Service
metadata:
 name: nginx-service
 namespace: test
spec:
 selector:
 app: nginx
 ports:
 - port: 80
 targetPort: 80

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


# ingress.yaml（networking.k8s.io/v1）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: test-ingress
 namespace: test
spec:
 ingressClassName: nginx
 rules:
 - host: nginx.example.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: nginx-service
 port:
 number: 80

1
2
3


kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
kubectl apply -f ingress.yaml

3.2 查看 Ingress 解析结果

1

kubectl describe ingress test-ingress -n test

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


Name: test-ingress
Namespace: test
Address: 10.x.x.x
Ingress Class: nginx
Default backend: <default>
Rules:
 Host Path Backends
 ---- ---- --------
 nginx.example.com
 / nginx-service:80 (10.244.1.10:80, 10.244.2.71:80, 10.244.3.8:80)
Events:
 Type Reason Age From Message
 ---- ------ ---- ---- -------
 Normal Sync 110s (x2 over 2m22s) nginx-ingress-controller Scheduled for sync

3.3 本地 hosts + curl 测试

1
2
3
4
5
6
7
8


# /etc/hosts（开发机）
# 内网IP-A nginx.example.com tomcat.example.com

# 直接访问 NodePort
curl -H "Host: nginx.example.com" http://内网IP-A:30080/

# 或先 ping 测连通
ping 内网IP-A

v1 与 v1beta1 的关键差异（写错会 apply 失败）：

字段 extensions/v1beta1（已弃用） networking.k8s.io/v1（本文用）

apiVersion extensions/v1beta1 networking.k8s.io/v1

路径匹配 path: /foo（隐式 Prefix） path: /foo + pathType: Prefix | Exact | ImplementationSpecific（必填）

后端 backend.serviceName + servicePort backend.service.name + backend.service.port.number/name

Ingress 类注解 kubernetes.io/ingress.class: nginx spec.ingressClassName: nginx

字段	`extensions/v1beta1`（已弃用）	`networking.k8s.io/v1`（本文用）
apiVersion	`extensions/v1beta1`	`networking.k8s.io/v1`
路径匹配	`path: /foo`（隐式 Prefix）	`path: /foo` + `pathType: Prefix \| Exact \| ImplementationSpecific`（必填）
后端	`backend.serviceName` + `servicePort`	`backend.service.name` + `backend.service.port.number/name`
Ingress 类	注解 `kubernetes.io/ingress.class: nginx`	`spec.ingressClassName: nginx`

四、关键注解（Annotations）速查

完整注解列表：https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md

4.1 不配置 host，用路径区分服务（Nacos 场景）

把 Nacos 控制台通过 /nacos 路径前缀反代出去，不绑定 host：

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


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: nacos-ingress
 namespace: example-corp
 annotations:
 nginx.ingress.kubernetes.io/use-regex: "true"
spec:
 ingressClassName: nginx
 rules:
 - http:
 paths:
 - pathType: Prefix
 path: /nacos
 backend:
 service:
 name: nacos-headless
 port:
 name: server

访问地址：http://内网IP-A/nacos

注意：当 host 字段省略，Ingress 会响应所有到达 controller 的请求，生产环境强烈建议绑定 host 防止冲突。如果一定要多服务复用 host，请用 pathType: Prefix 拆分路径。

4.2 app-root：访问根路径自动重定向

1
2
3


metadata:
 annotations:
 nginx.ingress.kubernetes.io/app-root: /corp

访问 https://example-corp.com/ 会 302 到 https://example-corp.com/corp，适合老门户的默认页迁移。

五、hostNetwork 模式：性能 + 四层必备

默认 ingress-nginx-controller 是 Deployment + Service(NodePort)，但生产环境有两类需求让它不够用：

直接监听 80/443 端口——不想用 30080/30443 这种高位端口
代理 TCP/UDP 四层流量——NodePort 不支持 stream

解决方案：hostNetwork: true + DaemonSet + nodeSelector，让 controller 在每个打了 ingress=true 标签的 Node 上独占监听宿主机网络。

5.1 修改清单的关键点

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


spec:
 # 1. 改成 DaemonSet：一个 Node 只能跑一个 controller
 kind: DaemonSet

 template:
 spec:
 # 2. 与宿主机共享网络栈
 hostNetwork: true

 # 3. 节点选择器
 nodeSelector:
 kubernetes.io/os: linux
 ingress: "true"

 # 4. hostNetwork 模式下要保留 K8s DNS
 dnsPolicy: ClusterFirstWithHostNet

删除 replicas、strategy.rollingUpdate 等 Deployment 专属字段。

5.2 给 Node 打标签

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


# 打标签
kubectl label node k8s-master-1 ingress=true
kubectl label node k8s-master-2 ingress=true
kubectl label node k8s-master-3 ingress=true

# 移除标签
kubectl label node k8s-master-3 ingress=true-

# 容忍 NoSchedule 污点（master 节点常有）
kubectl taint nodes k8s-master-1 node-role.kubernetes.io/control-plane:NoSchedule-

# 查看所有节点标签
kubectl get node --show-labels

5.3 部署与验证

1
2
3
4
5
6
7
8


# 先删旧 Deployment
kubectl delete -f /etc/k8s/ingress-nginx/deploy.yaml

# 部署新清单
kubectl apply -f /etc/k8s/ingress-nginx/hostNetwork.yaml

# 查看 controller 是否在每个 Node 跑一个
kubectl get pods -n ingress-nginx -o wide

1
2
3
4


NAME READY STATUS IP NODE
ingress-nginx-controller-cd58b 1/1 Running 内网IP-B k8s-master-2
ingress-nginx-controller-cgzk7 1/1 Running 内网IP-C k8s-master-1
ingress-nginx-controller-p2fdt 1/1 Running 内网IP-D k8s-master-3

5.4 验证四层与七层

1
2
3
4
5


# 七层：80 端口直接访问
curl http://nginx.example.com

# 四层：可以走 NodePort 也可以走宿主机 IP 直连
curl -H "Host: nginx.example.com" http://内网IP-A

六、四层代理：代理集群外的 TCP / WS / UDP

ingress-nginx 默认只代理 HTTP / HTTPS。要让 ingress-nginx 转发 TCP / UDP 流量（如 MySQL 3306、MQTT 1883、自定义 WebSocket），有三种方案：

6.1 方案对比

方案	适用场景	优点	缺点
① `stream-snippet` 注解	单个 Ingress 临时使用	配置最简单	不易复用
② `ConfigMap` 集中管理	多服务、需统一管理	一个 CM 管多个端口	要修改 DaemonSet args
③ `ExternalName` + Service	集群内 Pod 访问集群外	应用侧零配置	集群外无法反向访问

6.2 方案一：使用 Endpoints + Service + Ingress + stream-snippet

核心思路：用 Endpoints 直接指向集群外的 IP:PORT，再通过 Ingress 的 stream-snippet 注解把流量引过去。

⚠️ Endpoints.name 必须和 Service.name 完全一致——这是手写四层 Service 的铁律，写错 Service 永远 no endpoints available。

 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


# tcp-outside-3306.yaml
apiVersion: v1
kind: Endpoints
metadata:
 name: external-mysql
 namespace: example-corp
subsets:
 - addresses:
 - ip: 内网IP-E  # 集群外的 MySQL 真实地址
 ports:
 - port: 3306
 protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
 name: external-mysql
 namespace: example-corp
spec:
 clusterIP: None  # Headless Service，由 Endpoints 决定后端
 type: ClusterIP
 ports:
 - port: 7306 # 集群内访问用的端口
 protocol: TCP
 targetPort: 3306 # 转发到 Endpoints 里的 3306

 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


# tcp-outside-3306-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: external-mysql-ingress
 namespace: example-corp
 annotations:
 nginx.ingress.kubernetes.io/stream-snippet: |
 server {
 listen 8000;
 proxy_pass 内网IP-E:3306;
 }
spec:
 ingressClassName: nginx
 rules:
 - host: mysql.example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: external-mysql
 port:
 number: 7306

TCP 流量不要用 HTTP 测：四层流量没有 Host 头，curl http://内网IP-A:8000 会一直 400。正确姿势：nc -vz 内网IP-A 8000 或 telnet 内网IP-A 8000。

6.3 方案二：ConfigMap 集中管理（推荐生产用）

第一步：创建 ConfigMap 占位

1

kubectl -n ingress-nginx create configmap tcp-services

第二步：编辑 ConfigMap

1

kubectl edit -n ingress-nginx cm tcp-services

1
2
3
4
5
6
7
8
9


apiVersion: v1
kind: ConfigMap
metadata:
 name: tcp-services
 namespace: ingress-nginx
data:
 # 格式："<对外端口>": "<namespace>/<service>:<service-port>"
 "7306": "example-corp/external-mysql:7306"
 "1883": "example-corp/mqtt-service:1883"

第三步：让 controller 加载 ConfigMap

1

kubectl edit -n ingress-nginx DaemonSet/ingress-nginx-controller

1
2
3
4
5
6
7
8


spec:
 template:
 spec:
 containers:
 - args:
 - /nginx-ingress-controller
 - --tcp-services-configmap=$(POD_NAMESPACE)/tcp-services
 - --udp-services-configmap=$(POD_NAMESPACE)/udp-services

重要：$(POD_NAMESPACE) 是 controller 自带的 downward API 变量，会自动展开为 ingress-nginx，不要手写死。

第四步：补充 Service 端口暴露

1

kubectl edit -n ingress-nginx Service/ingress-nginx-controller

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


spec:
 ports:
 - name: http
 port: 80
 targetPort: 80
 - name: https
 port: 443
 targetPort: 443
 - name: external-mysql
 port: 7306
 targetPort: 7306
 protocol: TCP

第五步：调整 Service 类型与 externalIPs

1
2
3


# 类型改为 LoadBalancer（云厂商自动分配 IP）
kubectl patch svc ingress-nginx-controller -n ingress-nginx \
 -p '{"spec": {"type": "LoadBalancer", "externalIPs":["内网IP-A"]}}'

6.4 集群内测试连通

 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


# 用 busybox 测连通
kubectl exec -it busybox -- sh
ping external-mysql.example-corp.svc.cluster.local
telnet external-mysql.example-corp.svc.cluster.local 3306

# 用 ubuntu + mycli 工具测
cat << "EOF" > ubuntu.yml
apiVersion: v1
kind: Pod
metadata:
 name: diag-pod
spec:
 containers:
 - name: ubuntu
 image: ubuntu:22.04
 command: [ "/bin/bash", "-c", "--" ]
 args: [ "while true; do sleep 3600; done;" ]
EOF

kubectl apply -f ubuntu.yml
kubectl exec -it diag-pod -- bash
apt update && apt install -y python3-pip
pip3 install mycli

# 用 K8s Service DNS 名连接（注意改密码）
mycli -h external-mysql.example-corp.svc.cluster.local -uroot -p'<REDACTED-MYSQL-PWD>'

七、TLS 终端

7.1 创建 Secret

1
2
3
4
5
6
7
8


# 先建命名空间
kubectl create namespace example-corp

# 从证书文件创建 TLS Secret
kubectl create secret generic www-example-corp-secret \
 --from-file=tls.key=<CERT_ID>__example-corp.com.key \
 --from-file=tls.crt=<CERT_ID>__example-corp.com.pem \
 -n example-corp

7.2 开启 configuration-snippet

ingress-nginx v0.46+ 默认禁用 configuration-snippet（安全考量），要自定义 nginx 片段必须先开：

1

kubectl edit -n ingress-nginx configmap/ingress-nginx-controller

1
2


data:
 allow-snippet-annotations: "true" # 允许使用 configuration-snippet 注解

7.3 启用 TLS 的 Ingress

 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


apiVersion: v1
kind: Endpoints
metadata:
 name: www-service
 namespace: example-corp
subsets:
 - addresses:
 - ip: 内网IP-F
 ports:
 - port: 81
 protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
 name: www-service
 namespace: example-corp
spec:
 ports:
 - port: 81
 targetPort: 81
 protocol: TCP
 type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: www-ingress
 namespace: example-corp
 annotations:
 nginx.ingress.kubernetes.io/app-root: /corp
 nginx.ingress.kubernetes.io/use-regex: "true"
 nginx.ingress.kubernetes.io/configuration-snippet: |
 access_log /var/log/nginx/www.example-corp.com.access.log upstreaminfo if=$loggable;
 error_log /var/log/nginx/www.example-corp.com.error.log;
spec:
 ingressClassName: nginx
 tls:
 - hosts:
 - example-corp.com
 - www.example-corp.com
 secretName: www-example-corp-secret
 rules:
 - host: www.example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: www-service
 port:
 number: 81
 - host: example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: www-service
 port:
 number: 81

1

kubectl apply -f /etc/k8s/ingress/www-ingress.yaml

访问：https://example-corp.com https://www.example-corp.com

八、WebSocket 代理

ingress-nginx 默认支持 WebSocket，但要在 location 里显式设置：

1
2
3
4
5
6
7
8
9


location / {
 proxy_pass http://backend;
 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_read_timeout 3600s; # 长连接超时
}

在 ingress-nginx 里用注解实现：

1
2
3
4
5


metadata:
 annotations:
 nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
 nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
 # WebSocket 自动识别 Connection: Upgrade

默认 60s 不发包就断，WebSocket / 长轮询场景必须把 read/send timeout 拉到 3600s 以上，否则客户端会频繁断连。

九、Nacos 反代实战

Nacos Headless Service（clusterIP: None）+ Ingress 是社区最常见的"在 K8s 外面访问 Nacos 控制台"姿势：

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


# 假设 Nacos 已经用 Helm 或 Operator 部署好
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: nacos-console
 namespace: nacos
 annotations:
 nginx.ingress.kubernetes.io/use-regex: "true"
 nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
spec:
 ingressClassName: nginx
 rules:
 - host: nacos.example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: nacos-headless
 port:
 name: server  # 8848，对应 service.port.name

同样适用 Apollo、Consul、Sentinel Dashboard 等"控制台类服务"。use-regex: "true" 是因为 Nacos 前端路由里有 /#/xxx 这种 hash 路径，不开 regex 会被当成物理路径处理。

十、常见 8 个坑

#	坑	现象	解决
1	用了 `extensions/v1beta1`	K8s 1.22+ 直接 `apply` 失败 `no matches for kind`	改用 `networking.k8s.io/v1`，`pathType` 必填
2	忘写 `pathType`	`networking.k8s.io/v1` apply 报 `pathType Required value`	路径下必须显式 `pathType: Prefix \| Exact \| ImplementationSpecific`
3	Windows 能 ping 通但浏览器打不开	hosts 配了域名，ping 通，浏览器 502	关代理、关防火墙；`netsh winsock reset` 重启
4	客户端开了代理工具后无法访问 Ingress	浏览器挂了科学上网工具，所有流量走代理，Ingress 不通	代理工具"Bypass Domain/IP"里加业务域名；或选"全球直连"
5	Endpoints.name 与 Service.name 不一致	Service 一直无 Endpoints，curl 报 no endpoints available	严格保持两个 name 一致；这是 K8s 老坑
6	hostNetwork 模式下 DNS 解析错乱	Pod 用宿主机 `/etc/resolv.conf`，找不到集群内服务	`dnsPolicy: ClusterFirstWithHostNet`
7	DaemonSet 配了 replicas 字段	apply 时报 validation error	删掉 `replicas` 和 `strategy.rollingUpdate`
8	`configuration-snippet` 不生效	自定义 nginx 片段被忽略	ConfigMap 里设 `allow-snippet-annotations: "true"`
9	TCP 走 8000 端口但用 HTTP 测	telnet 通，curl 失败	四层不能用 HTTP 探测；用 `nc -vz` 或 `telnet`

十一、核心 6 点速记

链路：外网 → NodePort/hostNetwork → ingress-nginx → Service → Pod
七层（HTTP）用 Ingress；四层（TCP/UDP）用 stream-snippet 或 ConfigMap + DaemonSet args
生产必开 hostNetwork：直连 80/443 + 支持四层；必须配 DaemonSet + nodeSelector + dnsPolicy: ClusterFirstWithHostNet
Endpoints.name == Service.name 是手写四层 Service 的铁律
TLS 终端走 Ingress tls.hosts + secretName；自定义 nginx 片段需先开 allow-snippet-annotations
Ingress 不直接连 Pod：中间一定要过 Service（service mesh 同样），不要图省事

十二、排错命令速查

 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


# 查看 controller 配置
kubectl exec -it <pod> -n ingress-nginx -- cat /etc/nginx/nginx.conf

# 实时日志
kubectl logs -f -n ingress-nginx <pod>

# 集群内连通性
kubectl exec -it busybox -- sh
ping <svc>.<ns>.svc.cluster.local

# Service 详情
kubectl describe svc <svc-name> -n <ns>
kubectl describe endpoints <svc-name> -n <ns>

# Ingress 状态
kubectl get ingress -A
kubectl describe ingress <name> -n <ns>

# IngressClass 引用关系
kubectl get ingressclass
kubectl get ingress -A -o jsonpath='{range .items[?(@.spec.ingressClassName)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'

# hostNetwork 模式查看端口监听
ss -tlnp | grep -E ":(80|443|3306|1883)"

# 检查 controller 加载的 TCP/UDP ConfigMap
kubectl logs -n ingress-nginx <pod> | grep -E "tcp-services|stream-snippet"

十三、参考资料

ingress-nginx 仓库：https://github.com/kubernetes/ingress-nginx
官方部署清单：https://github.com/kubernetes/ingress-nginx/blob/main/deploy/static/provider/cloud/deploy.yaml
Annotation 索引：https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md
Ingress API v1 文档：https://kubernetes.io/docs/concepts/services-networking/ingress/
K8s 1.20 Release Notes（v1 Ingress GA）：https://kubernetes.io/blog/2020/12/08/kubernetes-1-20-release-announcement/
nginx stream 模块：https://nginx.org/en/docs/stream/ngx_stream_core_module.html
Nacos 集群部署：https://nacos.io/zh-cn/docs/cluster-mode-quick-start.html