利用 Nginx 实现灰度环境的 H5 应用发布策略

背景介绍

在现代互联网应用开发中，灰度发布（又称金丝雀发布）是一种非常重要的部署策略。它允许我们将新版本服务逐步推送给部分用户，而不是一次性全量发布，从而降低风险并快速获得用户反馈。本文将分享一个实际的灰度环境部署案例，涉及两个服务（fbdm和grayfbdm）共享同一数据库但运行不同代码的场景。 **目前场景：**用于线上功能和需求验证，防止全量上线验证出问题，减少回滚的概率。

某业务系统中存在两个核心后端服务：

fbdm：正式服务，面向所有用户；
grayfbdm：灰度服务，仅对测试或特定用户开放。

两者数据库一致，配置相同，仅代码版本不同。灰度发布前必须先完成数据库字段变更，以保证向前兼容。在这里插入图片描述

前端页面通过不同的访问地址与 Header 标签来区分灰度与正式流量。

访问角色	访问域名	Header 特征	Nginx 路由目标
测试用户	`gray.example.com`	`appenv=gray`	grayfbdm
正式用户	`prod.example.com`	无灰度标签	fbdm

灰度环境请求需满足下列任一条件，即可命中 grayfbdm：

请求 Header 包含 appenv=gray；
URL 参数中包含 appEnv=gray 或灰度域名作为 returnUrl；
Origin 为灰度域名。

系统架构概述

基本系统包含以下关键组件：

两个后端服务：
- fbdm：生产环境服务
- grayfbdm：灰度环境服务
共享数据库：两个服务使用相同的数据库实例
前端H5应用：能够通过header标识请求来源
Nginx反向代理：负责根据规则将请求路由到不同的后端服务

核心设计原理

1. 数据库共享策略

由于两个服务使用相同的数据库，在灰度发布过程中需要特别注意：

数据库变更先行：任何涉及数据库结构的变更必须先于服务部署执行
代码兼容性：新版本代码必须能够兼容旧版本的数据结构
数据一致性：确保灰度环境和生产环境不会因为数据操作相互干扰

2. 流量分流机制

Nginx作为流量入口，根据多种条件将请求路由到不同的后端：

在这里插入图片描述

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


# 上游服务定义 
upstream fbdm {
    server 10.0.0.1:8081 fail_timeout=5 max_fails=2;
    server 10.0.0.2:8081 fail_timeout=5 max_fails=2;
    keepalive 2000;
}
 
upstream grayfbdm {
    server 10.0.1.1:8081 fail_timeout=5 max_fails=2;
    keepalive 2000;
}
 

3. 路由判断条件

Nginx通过以下条件判断是否将请求路由到灰度环境：

HTTP Header：检查appenv=gray
URL参数：检查returnUrl或appEnv参数
Origin Header：检查请求来源是否为灰度域名

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


set $target http://fbdm;
if ($http_appEnv = "gray" ) {
    set $target http://grayfbdm;
}
if ($arg_returnUrl ~* "^https?%3A%2F%2Fmfbdgray\.xxxxx\.com" ) {
    set $target http://grayfbdm;
}
if ($arg_appEnv ~* "^gray" ) {
    set $target http://grayfbdm;
}
if ($http_origin ~* "https?://mfbdgray\.xxxxx\.com" ) {
    set $target http://grayfbdm;
}

4.完整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
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80


# 定义 upstream（正式服务 & 灰度服务）
upstream fbdm {
	server 10.0.0.1:8081 fail_timeout=5 max_fails=2;
	server 10.0.0.2:8081 fail_timeout=5 max_fails=2;
	keepalive 2000;
}
upstream grayfbdm {
	server 10.0.1.1:8081 fail_timeout=5 max_fails=2;
	keepalive 2000;
}

# 80 端口跳转到 HTTPS
server {
	listen 80;
	server_name prod.example.com;
	location / {
		rewrite ^/(.*)$ https://$host/$1 permanent;
	}
}

# 443 HTTPS 端口配置（灰度智能路由）
server {
	listen 443 ssl;
	server_name prod.example.com;
	ssl_certificate /path/to/cert.pem;
	ssl_certificate_key /path/to/key.pem;
	include ssl.conf;

	location / {
		set $target http://fbdm;

		# 灰度判断逻辑
		if ($http_appEnv = "gray") {
			set $target http://grayfbdm;
		}
		if ($arg_returnUrl ~* "^https?%3A%2F%2Fgray\.example\.com") {
			set $target http://grayfbdm;
		}
		if ($arg_appEnv ~* "^gray") {
			set $target http://grayfbdm;
		}
		if ($http_origin ~* "https?://gray\.example\.com") {
			set $target http://grayfbdm;
		}

		proxy_pass $target;
		include https_proxy.conf;
		proxy_next_upstream error timeout invalid_header http_403 http_404 http_500 http_502 http_503 http_504;

		# 黑名单控制（引用外部白名单/黑名单配置）
		include /opt/nginx/conf/whitelist/login.conf;
	}

	# 登录、发送验证码等接口灰度策略保持一致
	location ~* ^(/api/auth/sendCode|/api/user/login|/api/user/checkMobile)$ {
		set $target http://fbdm;

		if ($http_appEnv = "gray") {
			set $target http://grayfbdm;
		}
		if ($arg_returnUrl ~* "^https?%3A%2F%2Fgray\.example\.com") {
			set $target http://grayfbdm;
		}
		if ($arg_appEnv ~* "^gray") {
			set $target http://grayfbdm;
		}
		if ($http_origin ~* "https?://gray\.example\.com") {
			set $target http://grayfbdm;
		}

		proxy_pass $target;
		include https_proxy.conf;
		proxy_next_upstream error timeout invalid_header http_403 http_404 http_500 http_502 http_503 http_504;

		# 黑名单控制
		include /opt/nginx/conf/whitelist/mesg.conf;
		include /opt/nginx/conf/whitelist/login.conf;
		allow all;
	}
}

灵活灰度判断：通过 Header、Query 参数与 Origin 三层判断方式，确保请求正确识别；
接口隔离保护：关键接口如登录与验证码单独配置，防止因路由失误导致异常；
白名单机制：通过 include 引用外部配置，统一黑白名单管理；
自动 HTTPS 跳转：防止未加密请求造成信息泄露。

成功案例

在一次重大架构升级中，灰度发布机制帮助我们：

提前发现代码的bug，测试人员多轮验证，未影响正常用户
可以任何时间段发版，让测试人员测试，提升工作效率和速度

后续实践

版本兼容性：确保灰度版本代码能够回滚，避免因数据库变更导致生产环境不可用
监控与日志：为灰度环境设置独立的监控和日志收集，便于问题排查
流量比例控制：可以通过Nginx配置实现按比例的灰度发布
自动化测试：灰度环境应配备完整的自动化测试套件
用户标识策略：除了测试人员，可以考虑基于用户ID、设备ID等进行灰度分流