HTTP
概述
HTTP 路由用于将外部请求转发到应用组件,支持域名绑定、负载均衡、HTTPS、WebSocket 等功能。
前提条件
- 已完成 Rainbond 安装并创建应用
- 应用中至少有一个运行中的组件
快速开始
场景一:使用默认域名
- 开启对外端口:进入组件详情页面,在端口选项中,开启需要对外暴露的端口。
- 访问验证:使用默认域名
xxx.nip.io访问您的应用。
无需配置域名解析,快速体验应用访问能力。如无法访问,请阅读应用无法访问故障排查指南。
场景二:自定义域名
最简单的路由配置只需 3 步:
- 进入网关管理 → 点击"新增路由"
- 填写域名 → 如
demo.example.com(需将域名解析到网关 IP) - 选择组件 → 选择要绑定的应用组件和端口
- 域名需要先解析到网关 IP 才能访问
- 本文档分为基础配置和高级配置,按需查看
新增 HTTP 路由
第一步:进入网关管理
- 进入应用视图
- 点击左侧菜单 网关管理
- 点击 新增路由 按钮
第二步:基础配置
1. 域名
填写域名(如 demo.example.com),页面会提示需要将域名解析到的 IP 地址。
📖 域名配置详细说明
支持的域名类型:
- 自定义域名:
demo.example.com - 通配符域名:
*.example.com - 系统默认域名(无需配置 DNS)
域名解析步骤:
- 登录域名服务商控制台
- 添加 A 记录,指向网关 IP(页面会提示具体 IP)
- 等待 DNS 生效(5-10 分钟)
2. 路径
配置访问路径,默认 /* 表示匹配所有路径。
📖 路径配置详细说明
| 路径格式 | 说明 |
|---|---|
/* | 匹配所有路径(默认) |
/api/* | 只匹配 /api/ 开头的请求 |
/app/user/* | 匹配多级路径 |
3. 服务来源
选择要绑定的应用组件和端口。
基础配置:
- 应用名称 → 组件名称 → 端口号
- 权重:多组件时按权重分配流量(默认 100)
📖 负载均衡配置
当需要将流量分配到多个组件时:
- 配置第一个组件,设置权重(如 80)
- 点击 + 添加第二个组件,设置权重(如 20)
- 流量将按权重比例分配(80:20)
示例:实现灰度发布
- web-v1:权重 90(90% 流量)
- web-v2:权重 10(10% 流量)
4. 高级配置(可选)
点击页面上的 更多 按钮可展开以下高级配置选项。
- ✅ 需要限制特定 HTTP 方法(如只允许 GET、POST)
- ✅ 需要限制访问 IP(如仅允许办公网访问)
- ✅ 需要基于 Header/Cookie 进行流量路由
- ✅ 需要配置超时时间
- ❌ 简单的域名绑定不需要高级配置
路径配置(高级)
- 支持添加多个路径规则,点击 + 按钮可添加更多
- 点击 取消 可折叠高级配置面板
- 每个路径规则独立生效
HTTP 方法过滤
选择允许通过的 HTTP 方法,支持多选:
| 方法 | 说明 |
|---|---|
| GET | 获取资源 |
| POST | 提交数据 |
| PUT | 更新资源 |
| DELETE | 删除资源 |
| OPTIONS | 预检请求 |
| HEAD | 获取响应头 |
| PATCH | 部分更新 |
| TRACE | 追踪请求 |
配置说明:
- 默认允许所有 HTTP 方法
- 点击方法名称可选中/取消选中
- 已选中的方法会显示 × 标记,点击可取消
- 未选中的方法请求会被拒绝(返回 405 Method Not Allowed )
来源 IP 白名单
限制只有特定 IP 或 IP 段才能访问该路由。
配置说明:
- 输入允许访问的 IP 地址或 CIDR 格式的 IP 段
- 点击 + 按钮可添加多个 IP/IP 段
- 留空表示不限制来源 IP
IP 格式示例:
- 单个 IP:
192.168.1.100 - IP 段(CIDR):
192.168.1.0/24 - 多个 IP:通过添加多条规则实现
高级条件匹配
基于请求特征进行精细化路由控制,支持以下类型:
匹配类型:
| 类型 | 说明 | 示例 |
|---|---|---|
| Header | 根据请求头匹配 | X-Version: v2 |
| Cookie | 根据 Cookie 匹配 | user_type: vip |
| Query | 根据 URL 参数匹配 | debug: true |
比较运算符:
| 运算符 | 说明 | 示例 |
|---|---|---|
| 等于 | 完全匹配 | name == "admin" |
| 不等于 | 不匹配 | env != "prod" |
| 包含 | 字符串包含 | user-agent 包含 "Mobile" |
| 正则匹配 | 正则表达式 | path 匹配 "^/api/.*" |
配置步骤:
- 选择匹配类型(Header/Cookie/Query)
- 输入名称(name)
- 选择比较运算符
- 输入匹配值(value )
- 点击 + 添加更多条件
使用场景:
场景 1:灰度发布
通过 Header 或 Cookie 将特定用户导流到新版本:
类型: Header
名称: X-Version
运算符: 等于
值: beta
场景 2:移动端/PC 端分流
根据 User-Agent 区分设备类型:
类型: Header
名称: User-Agent
运算符: 包含
值: Mobile
将移动端请求路由到移动端优化的组件。
场景 3:A/B 测试
根据 Cookie 值进行 A/B 测试:
类型: Cookie
名称: ab_test
运算符: 等于
值: group_a
超时设置
配置与后端服务通信的超时时间,包含三个参数(单位:秒):
| 参数 | 说明 | 默认值 | 建议值 |
|---|---|---|---|
| 连接超时 | 建立连接的最长等待时间 | 60s | 5-60s |
| 读超时 | 读取响应数据的最长等待时间 | 60s | 60-300s |
| 发送超时 | 发送请求数据的最长等待时间 | 60s | 60-180s |
配置建议:
- API 接口:连接 5s,读 60s,发送 60s
- 文件上传:连接 10s,读 300s,发送 300s
- 长轮询:连接 10s,读 600s,发送 60s
- WebSocket:使用较长的超时时间
- 超时时间过短可能导致正常请求被中断
- 超时时间过长可能占用连接资源
- 根据实际业务场景合理设置
5. WebSocket(可选)
如果应用需要 WebSocket 支持(实时聊天、数据推送等),开启 websocket 开关。
第三步:提交配置
检查配置无误后,点击 确定 按钮完成创建。
路由管理操作
访问验证
创建路由后,在浏览器访问配置的域名:
http://demo.example.com/
或使用 curl 测试:
curl http://demo.example.com/
编辑路由
在网关管理列表中,点击路由的 编辑 按钮修改配置。
删除路由
点击 删除 按钮可删除路由。删除后该域名将无法访问。
网关插件配置
网关提供丰富的插件功能,实现流量管理、安全防护和性能优化。
插件使用说明:
- 在创建/编辑路由时,点击 添加插件 按钮
- 选择需要的插件并配置参数
- 一个路由可以添加多个插件
- 插件按添加顺序执行
limit-req
使用漏桶算法限制单个客户端对服务的请求速率。
配置参数
| 字段 | 参数 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|---|
| 请求速率 | rate | 是 | 数字 | 指定每秒请求速率。超过 rate 但未超过 rate + burst 的请求会被延时处理。 | 10 |
| 突发请求数 | burst | 是 | 数字 | 请求速率超过 rate + burst 后会被直接拒绝。 | 20 |
| 限流 Key 类型 | key_type | 否 | 下拉选择 | 限流 Key 的类型。 | var |
| 限流 Key | key | 否 | 下拉选择 | 用来区分限流对象的依据。 | remote_addr |
| 拒绝状态码 | rejected_code | 否 | 数字 | 请求超过阈值被拒绝时返回的 HTTP 状态码。 | 503 |
| 拒绝响应内容 | rejected_msg | 否 | 字符串 | 请求超过阈值被拒绝时返回的响应体。 | 请求过于频繁 |
| 不延迟处理 | nodelay | 否 | 开关 | 开启后,超过 rate 但未超过 rate + burst 的请求不会被延迟处理。 | 关闭 |
| 允许降级放行 | allow_degradation | 否 | 开关 | 限速插件临时不可用时,是否允许请求继续访问。 | 关闭 |
限流 Key 可选值
remote_addr:客户端 IP 地址server_addr:服务端 IP 地址http_x_real_ip:X-Real-IP请求头http_x_forwarded_for:X-Forwarded-For请求头consumer_name:Consumer 的用户名
limit-count
基于固定时间窗口的请求计数限流,可以限制指定时间内的请求数量。
配置参数
| 字段 | 参数 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|---|
| 请求次数上限 | count | 是 | 数字 | 时间窗口内允许的最大请求数量。 | 100 |
| 时间窗口 | time_window | 是 | 数字 | 计数时间窗口,单位为秒。超过该时间后重新开始计数。 | 60 |
| 计数 Key 类型 | key_type | 否 | 下拉选择 | 计数 Key 的类型。 | var |
| 计数 Key | key | 否 | 字符串 | 用来区分计数对象的依据。为空时默认使用 remote_addr。 | remote_addr |
| 拒绝状态码 | rejected_code | 否 | 数字 | 请求超过阈值被拒绝时返回的 HTTP 状态码。 | 503 |
| 拒绝响应内容 | rejected_msg | 否 | 字符串 | 请求超过阈值被拒绝时返回的响应体。 | 请求过于频繁 |
| 计数策略 | policy | 否 | 下拉选择 | 计数器存储策略。当前表单支持本地计数。 | local |
| 显示限额响应头 | show_limit_quota_header | 否 | 开关 | 开启后在响应头中显示 X-RateLimit-Limit 和 X-RateLimit-Remaining。 | 开启 |
计数 Key 类型可选值
var:使用 Nginx 变量,如remote_addr、http_x_forwarded_forvar_combination:使用变量组合,如$remote_addr $consumer_nameconstant:使用常量值,对所有请求统一限流
计数策略可选值
local:本地限流,仅在当前网关节点生效
limit-conn
限制同一时刻的并发连接数,防止服务器过载。
配置参数
| 字段 | 参数 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|---|
| 最大并 发数 | conn | 是 | 数字 | 允许的最大并发请求数。超过 conn 但低于 conn + burst 的请求会被延迟处理。 | 10 |
| 突发并发数 | burst | 是 | 数字 | 超过 conn + burst 的请求会被直接拒绝。 | 5 |
| 默认延迟时间 | default_conn_delay | 是 | 数字 | 默认的连接或请求处理延迟时间,单位为秒。 | 1 |
| 仅使用默认延迟 | only_use_default_delay | 否 | 开关 | 开启后严格按照 default_conn_delay 进行延迟处理。 | 关闭 |
| 限流 Key 类型 | key_type | 否 | 下拉选择 | 限流 Key 的类型。 | var |
| 限流 Key | key | 否 | 字符串 | 用来区分限流对象的依据。 | remote_addr |
| 拒绝状态码 | rejected_code | 否 | 数字 | 请求超过阈值被拒绝时返回的 HTTP 状态码。 | 503 |
| 拒绝响应内容 | rejected_msg | 否 | 字符串 | 请求超过阈值被拒绝时返回的响应体。 | 连接数过多 |
| 允许降级放行 | allow_degradation | 否 | 开关 | 限速插件临时不可用时,是否允许请求继续访问。 | 关闭 |
限流 Key 类型可选值
var:使用 Nginx 变量,如remote_addr、http_x_forwarded_forvar_combination:使用变量组合
proxy-rewrite
在将请求转发到后端服务前,重写请求的 URI、请求方法、请求头等信息。
配置参数
| 字段 | 参数 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|---|
| 目标 URI | uri | 否 | 字符串 | 转发到上游的新 URI,支持 NGINX 变量。 | /new/path |
| 请求方法 | method | 否 | 下拉选择 | 将路由请求代理为指定请求方法。 | GET |
| 正则 URI 重写 | regex_uri | 否 | 字符串数组 | 使用正则表达式匹配客户端 URI,并替换为上游 URI。 | ["^/api/v1/(.*)", "/$1"] |
| 目标 Host | host | 否 | 字符串 | 转发到上游的新 Host。 | backend.example.com |
| 追加请求头 | headers.add | 否 | 键值对 | 添加新的请求头;如果请求头已存在,则追加到末尾。 | {"X-Custom-Header":"value"} |
| 设置请求头 | headers.set | 否 | 键值对 | 设置或覆盖请求头。 | {"X-Real-IP":"$remote_addr"} |
| 移除请求头 | headers.remove | 否 | 字符串数组 | 删除指定请求头。 | ["X-Forwarded-For"] |
| 使用原始请求 URI | use_real_request_uri_unsafe | 否 | 开关 | 使用 NGINX 原始 $request_uri,会绕过 URI 规范化,仅在明确需要时开启。 | 关闭 |
请求方法可选值
- GET
- POST
- PUT
- DELETE
- PATCH
- HEAD
- OPTIONS
- TRACE
cors
配置 CORS(Cross-Origin Resource Sharing)策略,允许跨域请求访问。
配置参数
| 字段 | 参数 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|---|
| 允许来源 | allow_origins | 否 | 字符串 | 允许跨域访问的源,多个源用逗号分隔。 | * 或 https://example.com |
| 允许方法 | allow_methods | 否 | 字符串 | 允许跨域的请求方法,多个方法用逗号分隔。 | GET,POST,PUT |
| 允许请求头 | allow_headers | 否 | 字符串 | 允许跨域请求中携带的请求头,多个请求头用逗号分隔。 | Content-Type,Authorization |
| 暴露响应头 | expose_headers | 否 | 字符串 | 允许浏览器读取的响应头,多个响应头用逗号分隔。 | X-Custom-Header |
| 预检缓存时间 | max_age | 否 | 数字 | 预检请求结果缓存时间,单位为秒。设置为 -1 可禁用缓存。 | 5 |
| 允许携带凭据 | allow_credentials | 否 | 开关 | 是否允许请求携带 Cookie 等凭据。开启后其他 CORS 字段不能使用 * 允许所有值。 | 关闭 |
| 来源正则匹配 | allow_origins_by_regex | 否 | 字符串数组 | 使用正则表达式匹配允许跨域访问的源。 | [".*\\.example\\.com$"] |
| 来源元数据引用 | allow_origins_by_metadata | 否 | 字符串数组 | 从插件元数据中引用允许跨域访问的源。 | ["EXAMPLE"] |
real-ip
从代理服务器的请求头中提取客户端的真实 IP 地址,适用于应用部署在 CDN、负载均衡器或多层代理后的场景。
配置参数
| 字段 | 参数 | 必填 | 类型 | 说明 | 示例值 |
|---|---|---|---|---|---|
| 真实 IP 来源 | source | 是 | 字符串 | 从 APISIX 视角动态设置客户端 IP 地址、端口或主机名。 | http_x_forwarded_for |
| 可信地址 | trusted_addresses | 否 | 字符串数组 | 受信任的代理服务器地址列表。 | ["10.0.0.0/8", "192.168.0.0/16"] |
| 递归查找 | recursive | 否 | 开关 | 开启后从可信代理链中递归查找最后一个非受信任地址。 | 关闭 |
真实 IP 来源常用值
| 值 | 说明 | 使用场景 |
|---|---|---|
arg_realip | 从 URL 参数中获取 | 测试环境、特殊场景 |
http_x_forwarded_for | 从 X-Forwarded-For 请求头获取 | CDN、负载均衡器(最常用) |
http_x_real_ip | 从 X-Real-IP 请求头获取 | Nginx 代理 |
http_cf_connecting_ip | 从 Cloudflare 特定请求头获取 | Cloudflare CDN |
http_true_client_ip |