边缘 nginx
证书、真实 IP、超时与请求体上限都在这一层。这里配错了,集群里一切正常,用户侧却是 413、断流和 502。
1. 为什么要有这一层
Istio 的 ingressgateway 在单机上只有一个 NodePort,且参考环境的 Gateway 只声明了 80 端口——
TLS 不在集群内终止。于是集群前面需要一层 nginx,它负责四件事:
| 职责 | 不做会怎样 |
|---|---|
| 证书与 HTTPS | 只能用 http://<IP>:<NodePort> 访问,OIDC 回调、Secure Cookie 全部不可用 |
| 请求体上限 | nginx 默认 client_max_body_size 1m,一次上传 12 张图直接 413 |
| 长连接超时 | nginx 默认 proxy_read_timeout 60s,对话流与 SSE 到 60 秒被切断 |
| 真实客户端 IP | 日志、限流、按 IP 排查全部失效(看到的都是节点地址) |
2. 安装与证书
cat /etc/os-release # 确认发行版
sudo apt update
sudo apt install nginx
sudo systemctl enable --now nginx
一张证书覆盖全部域名
一台机器上一般有 4–8 个子域指向同一个入口(站点、网关、身份、控制台……),它们同属一个根域名—— 私有化部署只申请这一个根域名即可,子域不用单独申请。签一张多域名(SAN)证书 比分域名各签一张更简单:续期只有一条 lineage,配置里所有 server 块引用同一对文件。
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx \
--cert-name <证书名> \
-d titanides.com -d gateway.titanides.com -d accounts.titanides.com -d console.titanides.com
三件事先说清楚,后面加域名时才不会乱:
--cert-name要显式给。 不给时 certbot 用第一个-d的域名做 lineage 名(即/etc/letsencrypt/live/titanides.com/)。以后加域名稍有不慎就会签出第二条 lineage,而 nginx 还指着第一条。 给一个与域名无关的名字(如<产品名>),一开始就不会混。- 证书路径和
server_name是两件独立的事。 多个 server 块引用同一对ssl_certificate完全正常, 不要求目录名等于域名。 --nginx插件会直接改配置:它在sites-enabled的文件里补ssl_certificate几行、补 80→443 跳转块,并留下# managed by Certbot标记。
后来要加域名:--expand
新增一个域名(比如后来给 kubectl 加了个入口)时,不要重新签一张,要把它并进原来那张:
sudo certbot --nginx --cert-name <证书名> --expand \
-d titanides.com -d gateway.titanides.com -d accounts.titanides.com -d console.titanides.com \
-d k8s.titanides.com
- 命令行里要列出「全部旧域名 + 新域名」。只列新域名,得到的就是一张只有新域名的证书,业务域名立刻掉到
NET::ERR_CERT_COMMON_NAME_INVALID; --expand的作用是不弹「新建还是替换」的提问,直接把新域名并进--cert-name指的那一张;- 忘了
--expand也不会出事,certbot 会问一句;真正会出事的是上面那条——漏了旧域名。
签完确认:
sudo certbot certificates # 每条 lineage 的域名、到期日、证书路径
不想让 certbot 改配置
手工维护 sites-enabled 的团队,用只签证书的模式,证书路径自己写进 server 块:
# 用 80 端口做校验;此时 nginx 需要先停
sudo systemctl stop nginx
sudo certbot certonly --standalone -d titanides.com
sudo systemctl start nginx
# 或者让 nginx 保持运行,使用 webroot
sudo certbot certonly --webroot -w /var/www/html -d titanides.com
同一台机器上不要一部分证书归 certbot 管、一部分手工维护——续期日志里看不出哪张是谁在续, 出问题只能靠回忆。要么全交给
--nginx,要么全部certonly加手写配置。
续期
apt install certbot 会装一个 systemd timer(systemctl list-timers | grep certbot 可见),
到期前 30 天自动续,续期后执行 deploy hook —— --nginx 模式下默认就是 reload nginx。
上生产前执行一次:
sudo certbot renew --dry-run
续期走 HTTP-01,会从公网回源到
/.well-known/acme-challenge/。前面还有 CDN 或跳转规则时, 确认这条路径没被拦——见前置 Cloudflare 第 7 节。
3. 反代到 Istio
在 /etc/nginx/sites-enabled/ 里加一个站点。先取 NodePort:
kubectl -n istio-system get svc istio-ingressgateway \
-o jsonpath='{.spec.ports[?(@.port==80)].nodePort}{"\n"}'
一个站点文件通常就是下面这四块。map 必须写在 http 层——sites-enabled 里的文件本身就包含在
http {} 内,所以写在文件顶层即可;它在文件里的先后顺序不影响,nginx 是先读完整份配置再解析引用。
# ① WebSocket 升级判断:全站一份,所有 server 块共用
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
# ② 业务入口:所有指向集群的域名共用一个 server 块
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name titanides.com gateway.titanides.com accounts.titanides.com console.titanides.com;
# 一张多域名证书;其它 server 块也可以指这同一对文件
ssl_certificate /etc/letsencrypt/live/<证书名>/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/<证书名>/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
location / {
proxy_pass http://127.0.0.1:<http-nodeport>;
# Host 必须原样透传:Istio 的 VirtualService 靠 Host 头匹配
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 Stripe-Signature $http_stripe_signature;
# WebSocket(GraphQL 订阅)
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# 请求体:见下面参数表
client_max_body_size 50M;
# 长任务:默认 60s,对话与导出会被准时切断
proxy_connect_timeout 5s;
proxy_send_timeout 86400s;
proxy_read_timeout 86400s;
proxy_cache_bypass $http_upgrade;
}
# ③ 事件流单独一条路径(可选,见本节末尾)
location ^~ /stream {
proxy_pass http://127.0.0.1:<http-nodeport>;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Connection ''; # SSE 不是 WebSocket:清空 Upgrade
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
add_header Cache-Control no-cache;
}
}
# ④ 80 → 443
server {
listen 80;
listen [::]:80;
server_name titanides.com gateway.titanides.com accounts.titanides.com console.titanides.com;
return 301 https://$host$request_uri;
}
改完先 sudo nginx -t 再 sudo nginx -s reload。
certbot 会把 ④ 拆碎。 它每加一个域名,就在文件里另起一个
listen 80的 server 块,内容是if ($host = titanides.com) { return 301 https://$host$request_uri; };同一个块中出现多个if是正常现象, 等价于上面 ④ 的写法,不影响行为,不必手工合并。反过来,手工写了 ④ 之后又执行一次--nginx,会得到 两套并存——仍然等价,只是难读。
client_max_body_size 的两级配置
nginx 取最内层匹配的那一条。参考实现里 server 层写了 8m、location / 里写了 50M,
实际生效的是 50M;server 层那条只对没有在自己的 location 里覆盖过的路径起作用。两级并存容易让后来的人
误判,建议只写在一处。
为什么 ③ 单独一条 /stream
proxy_buffering 默认是 on,nginx 会先把上游响应缓冲,再统一发送。SSE 要的是「一条一条往下流」,于是:
- 上游发了
X-Accel-Buffering: no的,主 location 不关缓冲也能流; - 上游没发、或者您不确定,就必须在 location 上显式
proxy_buffering off; proxy_cache off;。
参考实现把事件流单独放在一条路径上,就是为了让这条路径自带全套参数,而不去改主 location 的行为 (主 location 保持缓冲,静态响应更快)。
参数为什么是这些
| 指令 | 参考值 | 依据 | 配错的症状 |
|---|---|---|---|
Host 透传 |
$host |
VirtualService 按 Host 匹配 | 所有域名都落到默认服务,或直接 404 |
client_max_body_size |
参考 50M,须 ≥ 网关的上传上限 | 网关自己还有 UPLOAD_MAX_FILE_SIZE 一层 |
上传到 100% 时 413(默认值只有 1m) |
proxy_read_timeout |
参考 86400s,至少 ≥ AJAX_TIMEOUT_MS(900s) |
网关到后端的转发超时 15 分钟 | 长任务/对话流 在 60 秒处被切断(默认值) |
proxy_send_timeout |
与 read 同量级 | 默认 60s,回源慢时中途断连 | 大文件传到一半连接被关 |
proxy_buffering off |
只在 /stream 上开 |
SSE(/events) |
事件滞留在缓冲区,前端表现为长时间无更新 |
Connection $connection_upgrade |
map 结果 | GraphQL 订阅走 WebSocket | 握手 400 / 连接立即关闭 |
Stripe-Signature |
透传 | 网关把回调转给支付服务后要验签 | 充值不到账,日志里是签名校验失败 |
client_max_body_size是两层中的外层:网关自己还有UPLOAD_MAX_FILE_SIZE与GRAPHQL_BODY_LIMIT。只调 nginx 不调网关,仍然是 413;只调网关不调 nginx,nginx 先拒。 两层取值不一致时,以小的那个为准——参考环境里 nginx 是 50M、网关默认更高,实际卡在 50M。 要放开更大的文件,两处一起调。
4. 集群 API 单独一个 server
kubectl 与 tethys 控制台都需要从外部访问 API Server(MicroK8s 默认 16443)。它和业务流量
不要共用一个 server 块——kubectl 的 exec / logs 是 WebSocket,缓冲与超时需求不同:
server {
listen 443 ssl;
server_name k8s.titanides.com;
location / {
proxy_pass https://127.0.0.1:16443;
# 自签证书时跳过校验;正式环境应配 proxy_ssl_trusted_certificate
proxy_ssl_verify off;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade; # kubectl exec / logs 必需
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_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
proxy_buffering off;
}
}
把 API Server 暴露到公网等于把集群控制面暴露出去。只在内网或 VPN 内这么做,并确保至少是 客户端证书或 token 鉴权;能连上就等于能操作。
5. 装完自检
# 1. 入口通、Host 匹配对
curl -sS -o /dev/null -w '%{http_code}\n' https://titanides.com/
curl -sS -o /dev/null -w '%{http_code}\n' https://gateway.titanides.com/graphql -X POST
# 2. 证书是一张、域名齐全、链完整(边缘配置要指 fullchain.pem,不是 cert.pem)
openssl s_client -connect titanides.com:443 -servername titanides.com </dev/null 2>/dev/null \
| openssl x509 -noout -text | grep -A1 'Subject Alternative Name'
openssl s_client -connect titanides.com:443 -servername titanides.com </dev/null 2>/dev/null \
| openssl crl2pkcs7 -nocrl -certfile /dev/stdin | openssl pkcs7 -print_certs -noout
# 3. 上传上限(用一个略大于 client_max_body_size 的文件,应当是 200 而不是 413)
head -c 52000000 /dev/zero > /tmp/big.bin
curl -sS -o /dev/null -w '%{http_code}\n' -F 'file=@/tmp/big.bin' https://titanides.com/<上传接口>
# 4. 流式不断流(保持 5 分钟以上不报错)
curl -N -H 'Accept: text/event-stream' https://gateway.titanides.com/<sse路径>
第 2 条的 Subject Alternative Name 是加域名之后最该看的一行:只加了一部分域名时,证书照样签发成功,
只有访问漏掉的那个域名才会报证书错误。第 3、4 条是最容易漏掉的:日常点击全部正常,只有在真实上传或长任务时才会出现。
6. 前面再挂 CDN
Cloudflare 一类 CDN 与 nginx 是两段独立 TLS。它会覆盖掉这一层的部分行为——真实 IP、缓存、 100 秒的源站超时、100 MB 的请求体上限——完整配法见前置 Cloudflare。