Websocket on Liangweidong's blog

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

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

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

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

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

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

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

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

When to use：

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

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

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

二、最小化 Dockerfile

1
2
3


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

文件结构：

1
2
3
4
5


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

构建：

1
2
3


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

关键点：

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

三、生产级 nginx.conf 模板

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


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

events {
 worker_connections 1024;
}

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

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

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

 sendfile on;
 keepalive_timeout 65;

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

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

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

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

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

实战要点：

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

四、WebSocket 反向代理

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

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


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

# server block 内 location
location /ws/ {
 proxy_pass http://localhost:8080/;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection $connection_upgrade;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

 # 长连接超时
 proxy_read_timeout 300s;
 proxy_send_timeout 300s;
}

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

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

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

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


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

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

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

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

六、SSL / HTTPS 完整配置

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


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

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

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

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

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

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

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

 location / {
 proxy_pass http://localhost:9000;
 proxy_set_header Host $http_host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }
}

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

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

1
2
3


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

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

七、bitnami/nginx 镜像优势

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

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

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

八、生产部署清单

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


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

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

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

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

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

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

九、监控与日志

日志接入：

1
2
3
4
5
6
7


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

健康检查：

1
2
3
4
5
6


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

容器外查：

1
2
3
4
5


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

十、常见坑位

10.1 反代后端丢失 HTTPS 信息

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

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

1

proxy_set_header X-Forwarded-Proto $scheme;

10.2 SPA 路由 404

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

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

10.3 WebSocket 反复断连

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

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

修复：proxy_read_timeout 300s; 或更长。

10.4 gzip 对小文件无效果

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

2024+ 视角补充

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

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

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

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

下一步

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

Vaultwarden 密码管理自托管：Bitwarden 兼容 + WebSocket + Nginx 反代

Wed, 15 Mar 2023 00:00:00 +0800

密码管理是企业 / 个人最值得投资的安全基础设施之一。1Password / LastPass 商业版每年几十美元 / 用户，Vaultwarden（Bitwarden 兼容）自托管只要 1 个 Docker 容器——而且数据完全掌控在自己手里。本篇把完整部署、Nginx 反代、WebSocket 通知、生产加固整理清楚。

阅读对象：技术团队负责人 / 注重个人隐私的开发者 覆盖范围：Vaultwarden 基础部署 + 完整 docker-compose + WebSocket 通知 + Nginx 反代 + 备份恢复 + 高级加固

一、为什么选 Vaultwarden

Bitwarden 是开源密码管理器，跨平台支持完善（Windows / macOS / Linux / iOS / Android / 浏览器扩展）。但官方服务端需要 SQL Server（商业版），自托管成本高。

Vaultwarden 是 Bitwarden 服务端的社区重写版（原名 bitwarden_rs）：

维度	官方 Bitwarden	Vaultwarden
镜像大小	~ 1.5 GB（含 SQL Server）	~ 80 MB
内存占用	2GB+	50-100 MB
数据库	SQL Server（必须）	SQLite / PostgreSQL / MySQL
客户端兼容	官方客户端	官方客户端全兼容
API 兼容	原生	100% 兼容
项目维护	Bitwarden Inc.	社区

2021-04-27 项目从 bitwarden_rs 更名为 Vaultwarden，客户端仍是 Bitwarden 官方客户端——只是服务端换成 Vaultwarden 即可。

When to use：

团队 / 公司有 5+ 员工，需要共享密码

注重数据隐私，不想把密码交给第三方

已经买了 1Password 商业版但想降本

二、基础部署

2.1 SQLite 版本（个人 / 小团队）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


docker run -d \
 --name vaultwarden \
 --restart always \
 -e WEBSOCKET_ENABLED=true \
 -e SIGNUPS_ALLOWED=false \
 -e WEB_VAULT_ENABLED=true \
 -v /home/vw/data:/data \
 -p 8087:80 \
 -p 3012:3012 \
 vaultwarden/server:1.25.1-alpine

环境变量：

WEBSOCKET_ENABLED=true：启用 WebSocket（密码同步通知）
SIGNUPS_ALLOWED=false：禁止注册——第一次部署时自己注册后改 false
WEB_VAULT_ENABLED=true：启用 Web 客户端
ADMIN_TOKEN=...（可选）：后台管理密码

2.2 docker-compose 完整版

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


version: '3'
services:
 vaultwarden:
 image: vaultwarden/server:1.25.1-alpine
 container_name: vaultwarden
 restart: always
 environment:
 WEBSOCKET_ENABLED: "true"
 SIGNUPS_ALLOWED: "false"
 WEB_VAULT_ENABLED: "true"
 ADMIN_TOKEN: "{{REDACTED}}" # 用 openssl rand -base64 48 生成
 ROCKET_PORT: "8087"
 DOMAIN: "https://vw.example.com"
 SHOW_PASSWORD_HINT: "false"
 LOG_LEVEL: "warn"
 volumes:
 - /home/vw/data:/data
 ports:
 - "8087:8087"
 - "3012:3012"

ADMIN_TOKEN 用 openssl rand -base64 48 生成——这是后台管理面板 /admin 的访问密码。

2.3 PostgreSQL 版本（生产推荐）

SQLite 在并发写入时容易锁库——团队 20+ 用户推荐 PostgreSQL：

 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


version: '3'
services:
 vaultwarden:
 image: vaultwarden/server:latest
 container_name: vaultwarden
 restart: always
 depends_on:
 - postgres
 environment:
 DATABASE_URL: postgresql://vaultwarden:{{DB_PASS}}@postgres:5432/vaultwarden
 WEBSOCKET_ENABLED: "true"
 SIGNUPS_ALLOWED: "false"
 WEB_VAULT_ENABLED: "true"
 ADMIN_TOKEN: "{{REDACTED}}"
 DOMAIN: "https://vw.example.com"
 volumes:
 - /home/vw/data:/data
 ports:
 - "8087:8087"
 - "3012:3012"

 postgres:
 image: postgres:13-alpine
 container_name: vaultwarden-db
 restart: always
 environment:
 POSTGRES_USER: vaultwarden
 POSTGRES_PASSWORD: "{{DB_PASS}}"
 POSTGRES_DB: vaultwarden
 volumes:
 - /home/vw/pgdata:/var/lib/postgresql/data

生产推荐用 PostgreSQL，性能 + 并发 + 备份工具都更成熟。

三、Nginx 反向代理

直接用 :8087 端口访问不安全——必须套 HTTPS。

3.1 完整 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
50
51
52
53
54
55
56
57
58


server {
 listen 80;
 server_name vw.example.com;
 return 301 https://$server_name$request_uri;
}

server {
 listen 443 ssl http2;
 server_name vw.example.com;

 ssl_certificate /etc/nginx/ssl/vw.example.com.fullchain.pem;
 ssl_certificate_key /etc/nginx/ssl/vw.example.com.privkey.pem;
 ssl_protocols TLSv1.2 TLSv1.3;

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

 # 反代主应用
 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";
 }

 # WebSocket 协商
 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;
 }
}

关键点：

proxy_http_version 1.1：必须 1.1，HTTP/1.0 不支持 Upgrade
proxy_set_header Connection "upgrade"：触发协议升级
/notifications/hub 走 3012 端口（WebSocket 专用）
/admin 路径在 Vaultwarden 中默认不开放——要 ADMIN_TOKEN 启用

3.2 反代安全清单

风险	修复
`robots.txt` 让搜索引擎爬	必须配自定义 robots.txt 禁止爬取
弱密码	注册时强制密码强度，禁止 `123456` 等
`SIGNUPS_ALLOWED=true`	第一次注册后立刻改 false
暴露管理面板	`ADMIN_TOKEN` 用 48 字节随机数，别用生日
没限流	用 Nginx `limit_req` 防爆破

1
2
3
4
5
6
7


# 登录限流
limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;

location /api/auth {
 limit_req zone=login burst=3 nodelay;
 proxy_pass http://127.0.0.1:8087;
}

四、客户端使用

4.1 桌面客户端

打开 Bitwarden 桌面客户端 → 设置 → 服务器 URL → https://vw.example.com

4.2 浏览器扩展

Chrome / Edge / Firefox 商店搜 “Bitwarden” → 安装 → 设置 → 服务器 URL。

4.3 移动端

iOS / Android 装 Bitwarden 官方 App，首次登录用自托管 URL。

4.4 导入已有密码

Bitwarden 支持从以下来源导入：

1Password（.1pif）
LastPass（.csv）
Chrome / Firefox（.csv）
KeePass（.xml）
Dashlane / RoboForm / Enpass

Web 客户端 https://vw.example.com/#/tools/import 操作。

五、备份与恢复

5.1 SQLite 备份

1
2
3
4
5


# 在线备份（不锁库）
docker exec vaultwarden sqlite3 /data/db.sqlite3 ".backup '/data/backup/db-$(date +%Y%m%d).sqlite3'"

# 拷贝出来
docker cp vaultwarden:/data/backup ./vaultwarden_backup_$(date +%Y%m%d)

5.2 PostgreSQL 备份

1
2
3
4
5


# 逻辑备份
docker exec vaultwarden-db pg_dump -U vaultwarden vaultwarden > vw-$(date +%Y%m%d).sql

# 物理备份（推荐）
docker exec vaultwarden-db pg_basebackup -D /backup/$(date +%Y%m%d) -U vaultwarden -Fp -Xs -P

5.3 附件 / 密钥 / RSA 密钥

1
2
3
4
5


# 全量备份
tar czf vw-full-backup-$(date +%Y%m%d).tar.gz /home/vw/data

# 上传对象存储
ossutil cp vw-full-backup-*.tar.gz oss://backup-bucket/vaultwarden/

5.4 恢复

1
2
3
4
5
6
7
8


# 1. 停服
docker compose down

# 2. 恢复数据
tar xzf vw-full-backup-20240315.tar.gz -C /

# 3. 启动
docker compose up -d

自动备份到 OSS：

1
2


# crontab 每天 3 点
0 3 * * * /usr/local/bin/vw_backup.sh

六、Admin 后台

启用 ADMIN_TOKEN 后访问 https://vw.example.com/admin：

1
2
3


# 生成强 token
openssl rand -base64 48
# 输出：eK7vN9pQ2xR5tY8wA1bC3dF6gH0iJ4kL7mN9oP2qR5tU8vW1xY4zA7bC0dF3gH6i

后台功能：

查看用户列表
禁用 / 启用用户
强制 2FA（团队必开）
查看登录日志
删除用户及其数据

强 2FA 策略：

1
2


# 禁止非 2FA 用户登录（管理面板）
# 后台 → Users → 用户 → 勾选 "Require 2FA"

七、生产加固清单

7.1 网络层

强制 HTTPS（Nginx 301 重定向）
限流（Nginx limit_req 防爆破）
IP 白名单（后台 /admin 限定内网）
fail2ban（自动封禁多次失败 IP）

7.2 应用层

SIGNUPS_ALLOWED=false（注册后必关）
强 ADMIN_TOKEN（48 字节随机）
数据库连接加密（PostgreSQL SSL）
禁用密码提示：SHOW_PASSWORD_HINT=false

7.3 监控

1
2
3
4
5
6


# 接入 Loki
docker run -d \
 --name vaultwarden \
 --log-driver=loki \
 --log-opt loki-url="http://internal.example.com:3100/loki/api/v1/push" \
 ...

告警规则：

失败登录 > 100/小时：可能有人在爆破
新用户注册：SIGNUPS_ALLOWED=false 后应为 0
数据库连接失败：PostgreSQL 健康检查

八、典型坑位

8.1 WebSocket 连接 404

症状：客户端同步卡死，提示 WebSocket 失败。

修复：

WEBSOCKET_ENABLED=true 环境变量
3012 端口在 Nginx 暴露：location /notifications/hub
proxy_http_version 1.1 + proxy_set_header Connection "upgrade"

8.2 文件上传 413

症状：上传附件 > 1MB 失败。

修复：

1

client_max_body_size 100m;

8.3 团队成员密码泄露

应急：

1
2
3
4


# 1. 后台 /admin 禁用该用户
# 2. 强制全员改主密码
# 3. 检查登录日志，看是否有异常 IP
docker logs vaultwarden 2>&1 | grep -E "Failed login|Invalid"

8.4 Vaultwarden 升级失败

症状：升级后数据库迁移报错。

修复：

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


# 1. 升级前必备份
docker exec vaultwarden-db pg_dump -U vaultwarden vaultwarden > vw-backup.sql

# 2. 升级
docker compose pull vaultwarden
docker compose up -d

# 3. 启动失败时查看日志
docker logs vaultwarden

# 4. 回滚
docker compose down
docker compose up -d vaultwarden-server:1.25.0 # 回退到旧版本

九、Vaultwarden vs 其他方案

工具	开源	自托管	跨平台	团队功能	2FA
Vaultwarden	✅	✅	✅	✅	✅
1Password	❌	❌	✅	✅	✅
LastPass	❌	❌	✅	✅	✅
KeePass + SyncTrayzor	✅	✅	⚠️	❌	⚠️
Bitwarden 官方	✅	⚠️	✅	✅	✅

自托管 + 团队功能两个条件同时满足，Vaultwarden 是唯一靠谱的开源选择。

十、完整 docker-compose 生产示例

 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


version: '3.8'
services:
 vaultwarden:
 image: vaultwarden/server:1.30.0-alpine
 container_name: vaultwarden
 restart: always
 depends_on:
 - postgres
 environment:
 DATABASE_URL: postgresql://vaultwarden:{{DB_PASS}}@postgres:5432/vaultwarden
 WEBSOCKET_ENABLED: "true"
 SIGNUPS_ALLOWED: "false"
 WEB_VAULT_ENABLED: "true"
 ADMIN_TOKEN: "{{REDACTED}}"
 DOMAIN: "https://vw.example.com"
 SHOW_PASSWORD_HINT: "false"
 LOG_LEVEL: "warn"
 SIGNUPS_DOMAINS_WHITELIST: "example.com" # 只允许企业邮箱注册（首次）
 INVITATIONS_ALLOWED: "true" # 团队邀请
 DISABLE_ICON_DOWNLOAD: "true" # 防止外网图片泄露
 volumes:
 - /home/vw/data:/data
 networks:
 - vw-net
 healthcheck:
 test: ["CMD", "curl", "-f", "http://localhost:8087/alive"]
 interval: 30s
 timeout: 5s
 retries: 3

 postgres:
 image: postgres:15-alpine
 container_name: vaultwarden-db
 restart: always
 environment:
 POSTGRES_USER: vaultwarden
 POSTGRES_PASSWORD: "{{DB_PASS}}"
 POSTGRES_DB: vaultwarden
 volumes:
 - /home/vw/pgdata:/var/lib/postgresql/data
 networks:
 - vw-net

networks:
 vw-net:
 driver: bridge

首次部署流程：

启动 → 访问 https://vw.example.com/#/register
注册一个管理员账户（比如 admin@example.com）
立刻改 SIGNUPS_ALLOWED=false，重启
用该账户登录 → 邀请团队成员
强制全员开 2FA

2024+ 视角补充

本文写于 2023-03，2024-2026 期间 Vaultwarden 关键演进：

Vaultwarden 1.30+（2024-08）：Passkey / WebAuthn 完整支持（vs 老版本仅 TOTP）——2024+ 无密码化趋势下的核心能力
Vaultwarden 1.32+（2025-Q1）：内置 SSO（SAML 2.0 / OIDC）——企业 AD / Okta / Azure AD 集成开箱即用
Vaultwarden 1.33+（2025-Q3）：Send 端到端加密文件分享（vs 老版本仅文字）；风险评估报告（用户密码健康度）
Bitwarden 官方 2024 重构：原 Bitwarden 服务端（商业版）2024-2025 全面转向 Rust 重写，性能 3x 提升——但 Vaultwarden 仍 100% 兼容官方客户端
替代品（2024+ 视角）：
- Bitwarden 官方（商业）：2024 起免费版限制到 2 用户——中小企业必须付费
- Proton Pass（2024-Q3）：Proton 公司出品，E2EE 邮件 + 密码一体化——隐私党新选择
- 1Password 8.x（2024）：Linux 客户端 GA，CLI 工具完善，企业级SCIM 同步
- Passwork / Psono（2024）：欧洲 GDPR 友好，自托管 + 团队功能
- KeePassXC + KeePassDX（移动）+ Syncthing 同步：纯本地方案 2024 仍活跃

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

个人 / 小团队 → Vaultwarden 1.33+ 仍是首选自托管方案
企业 / 合规 → Vaultwarden 1.32+ 的 SSO + RBAC 满足等保 / SOC 2 基础要求
无密码化 → Passkey + Vaultwarden 1.30+ 已是稳态组合
云服务 → Bitwarden / 1Password / Proton Pass 三足鼎立

下一步

想看 VPN 与代理自托管（OpenVPN / V2Ray）→ VPN 与代理自托管
想看 站点与博客自托管（WordPress / WVP 视频监控）→ 站点与博客自托管
想看 Watchtower 容器自动更新（守护所有容器的升级）→ Watchtower 容器自动更新
想看 MinIO 对象存储实战（S3 兼容对象存储）→ MinIO 对象存储实战

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 一文

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

四、关键注解（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

字段	`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`