🌐 HTTP转发模式使用指南

🎯 概述

HTTP转发模式允许文件服务器作为代理网关，将文件操作请求（上传、下载、删除等）转发到其他文件服务器。通过HTTP转发模式，您可以：

✅ 实现服务代理：作为统一入口，转发请求到后端文件服务器
✅ 负载均衡：通过Nacos服务发现实现多实例负载均衡
✅ 灰度发布：支持通过请求头实现灰度版本路由
✅ 业务隔离：通过metadata实现业务类型级别的实例选择
✅ 完整功能支持：支持所有文件操作（上传、下载、删除、分片上传/下载、HEAD请求）
✅ 透明转发：保持原始请求和响应格式，对客户端透明

配置说明

基本配置

yaml

files:
- business-type: remote
  file-type: http
  http-forward-url: http://192.168.1.100:9830

负载均衡配置

yaml

files:
- business-type: images
  file-type: http
  http-forward-url: lb://file-server

配置参数说明

参数	说明	必填	示例
`business-type`	业务类型标识	是	`remote`
`file-type`	文件类型，HTTP模式固定为 `http`	是	`http`
`http-forward-url`	目标文件服务器的基础地址或负载均衡地址	是	`http://192.168.1.100:9830` 或 `lb://file-server`

配置说明

普通HTTP模式：直接指定目标服务器地址，如 http://192.168.1.100:9830
负载均衡模式：使用 lb:// 前缀，如 lb://file-server，系统会从Nacos获取服务实例
URL格式：支持 http:// 和 https:// 协议（注意：当前实现使用 http:// 构建目标URL）
端口配置：必须包含端口号，如 http://192.168.1.100:9830

🔄 工作原理

请求转发规则

HTTP模式支持以下所有文件操作的转发：

操作类型	本服务接口	转发到目标服务器	说明
普通上传	`POST /upload/{businessType}`	`POST {http-forward-url}/upload/{businessType}`	单文件上传
分片上传初始化	`POST /upload/chunk/init/{businessType}`	`POST {http-forward-url}/upload/chunk/init/{businessType}`	分片上传初始化
分片上传	`POST /upload/chunk/{businessType}`	`POST {http-forward-url}/upload/chunk/{businessType}`	上传单个分片
合并分片	`POST /upload/merge/{businessType}`	`POST {http-forward-url}/upload/merge/{businessType}`	合并所有分片
普通下载	`GET /download/{businessType}/{path}`	`GET {http-forward-url}/download/{businessType}/{path}`	支持Range请求
HEAD请求	`HEAD /download/{businessType}/{path}`	`HEAD {http-forward-url}/download/{businessType}/{path}`	获取文件元数据
分片下载信息	`GET /download/chunk/info/{businessType}/{path}`	`GET {http-forward-url}/download/chunk/info/{businessType}/{path}`	获取分片下载信息
分片下载	`GET /download/chunk/{businessType}/{path}`	`GET {http-forward-url}/download/chunk/{businessType}/{path}`	下载指定范围
删除文件	`POST /delete/{businessType}/{path}`	`POST {http-forward-url}/delete/{businessType}/{path}`	删除单个文件
批量删除	`POST /delete/batch/{businessType}`	`POST {http-forward-url}/delete/batch/{businessType}`	批量删除文件

转发流程

普通HTTP模式示例

假设配置：

business-type: remote
http-forward-url: http://192.168.1.100:9830

则请求转发如下：

本服务请求	转发到目标服务器
`POST /upload/remote`	`POST http://192.168.1.100:9830/upload/remote`
`GET /download/remote/2024/01/15/10/file.jpg`	`GET http://192.168.1.100:9830/download/remote/2024/01/15/10/file.jpg`
`HEAD /download/remote/2024/01/15/10/file.jpg`	`HEAD http://192.168.1.100:9830/download/remote/2024/01/15/10/file.jpg`
`GET /download/chunk/info/remote/2024/01/15/10/file.jpg`	`GET http://192.168.1.100:9830/download/chunk/info/remote/2024/01/15/10/file.jpg`
`GET /download/chunk/remote/2024/01/15/10/file.jpg?start=0&end=1048575`	`GET http://192.168.1.100:9830/download/chunk/remote/2024/01/15/10/file.jpg?start=0&end=1048575`
`POST /delete/remote/2024/01/15/10/file.jpg`	`POST http://192.168.1.100:9830/delete/remote/2024/01/15/10/file.jpg`
`POST /delete/batch/remote`	`POST http://192.168.1.100:9830/delete/batch/remote`

负载均衡模式

当 http-forward-url 以 lb:// 开头时，系统会启用负载均衡模式，通过Nacos服务发现实现动态路由。

URL格式

lb://serviceName

serviceName: Nacos中注册的服务名称（去掉 lb:// 前缀，截取到第一个 / 之前）

工作原理

服务发现：通过Nacos获取指定服务的健康实例列表
实例过滤：根据metadata中的 business-type 过滤匹配的实例
灰度支持：支持通过 wueasy-gray-version 请求头实现灰度版本路由
请求转发：将请求转发到选中的实例

示例

假设配置：

business-type: images
http-forward-url: lb://file-server

系统会：

从Nacos获取 file-server 服务的健康实例
检查实例的metadata中 business-type 是否匹配 images
如果请求头包含 wueasy-gray-version，优先选择匹配的灰度版本实例
转发请求到选中的实例

目标服务器配置

目标文件服务器需要在Nacos中注册时设置metadata：

yaml

# 目标服务器的Nacos配置
nacos:
  discovery:
    metadata:
      business-type: images  # 指定业务类型，用于实例过滤
      version: v1.0.0        # 可选：版本号，用于灰度发布

灰度发布支持

通过请求头实现灰度版本路由：

bash

# 请求时添加灰度版本头
curl -H "wueasy-gray-version: v2.0.0" \
     -X POST http://proxy-server:9830/upload/images

系统会优先选择metadata中 version 匹配 v2.0.0 的实例，如果没有匹配的实例，则选择其他健康实例。

负载均衡策略

当前实现使用Nacos的健康检查机制：

只选择健康（healthy）的实例
根据metadata过滤匹配的实例
如果多个实例匹配，Nacos会返回其中一个（具体策略取决于Nacos配置）

📋 使用场景

场景1: 统一网关入口

作为统一入口，转发所有文件操作请求到后端服务器：

yaml

files:
- business-type: images
  file-type: http
  http-forward-url: lb://file-server  # 使用负载均衡

- business-type: documents
  file-type: http
  http-forward-url: lb://file-server

优势：

客户端只需连接一个入口服务器
后端服务器可以动态扩容
支持服务发现和负载均衡

场景2: 负载均衡

配置多个文件服务器，通过HTTP模式实现负载均衡：

yaml

files:
- business-type: images
  file-type: http
  http-forward-url: lb://file-server  # 自动负载均衡

- business-type: documents
  file-type: http
  http-forward-url: lb://file-server

目标服务器配置（多个实例）：

yaml

# 实例1
nacos:
  discovery:
    metadata:
      business-type: images

# 实例2
nacos:
  discovery:
    metadata:
      business-type: images

场景3: 业务隔离

不同业务使用不同的文件服务器：

yaml

files:
- business-type: user-avatars
  file-type: http
  http-forward-url: http://avatar-server:9830

- business-type: product-images
  file-type: http
  http-forward-url: http://product-server:9830

- business-type: documents
  file-type: http
  http-forward-url: http://doc-server:9830

场景4: 跨地域部署

就近访问文件服务器，降低延迟：

yaml

files:
# 亚洲区域
- business-type: asia
  file-type: http
  http-forward-url: http://file-server-asia:9830

# 欧洲区域
- business-type: europe
  file-type: http
  http-forward-url: http://file-server-europe:9830

场景5: 灰度发布

通过请求头实现灰度版本路由：

yaml

files:
- business-type: images
  file-type: http
  http-forward-url: lb://file-server

使用方式：

bash

# 生产版本请求
curl -X POST http://proxy-server:9830/upload/images

# 灰度版本请求
curl -H "wueasy-gray-version: v2.0.0" \
     -X POST http://proxy-server:9830/upload/images

目标服务器配置：

yaml

# 生产实例
nacos:
  discovery:
    metadata:
      business-type: images
      version: v1.0.0

# 灰度实例
nacos:
  discovery:
    metadata:
      business-type: images
      version: v2.0.0

场景6: 混合存储

部分业务使用HTTP转发，部分业务使用本地存储：

yaml

files:
# 使用HTTP转发
- business-type: remote-files
  file-type: http
  http-forward-url: lb://file-server

# 使用本地存储
- business-type: local-files
  file-type: local
  root-path: /srv/file/data

✨ 功能特性

1. 完整功能支持

HTTP模式支持所有文件操作：

✅ 文件上传：普通上传、分片上传（初始化、上传分片、合并）
✅ 文件下载：普通下载、分片下载、HEAD请求（获取文件元数据）
✅ 文件删除：单文件删除、批量删除
✅ HTTP Range支持：自动转发Range请求头，支持断点续传
✅ 查询参数转发：自动转发所有查询参数（如 fileName、start、end 等）

2. 自动URL构建

系统会根据配置的 http-forward-url 自动构建完整的请求URL：

自动处理URL拼接（自动添加 / 分隔符）
自动转发路径参数和查询参数
自动转发请求头（如 User-Agent、wueasy-gray-version 等）

3. 响应透传

目标服务器的响应会直接透传给客户端：

保持原始响应格式（JSON、二进制流等）
转发所有响应头（Content-Type、Content-Disposition、Content-Range等）
保持原始状态码（200、206、404等）

4. 负载均衡和灰度发布

服务发现：通过Nacos自动发现服务实例
健康检查：只选择健康的实例
业务隔离：通过metadata实现业务类型级别的实例选择
灰度发布：支持通过请求头实现灰度版本路由

5. 错误处理

网络错误：连接失败时返回详细错误信息
服务不可用：没有可用实例时返回错误提示
状态码处理：目标服务器返回非200状态码时返回错误信息
详细日志：记录所有转发请求和错误信息，便于排查问题

6. 超时控制

上传超时：120秒（支持大文件上传）
下载超时：120秒（支持大文件下载）
HEAD请求超时：30秒（仅获取元数据）
可根据实际需求调整超时时间

⚠️ 注意事项

1. 网络连接

✅ 确保代理服务器能够访问目标文件服务器
✅ 检查防火墙和网络策略
✅ 确保目标服务器端口可访问

2. Nacos配置（负载均衡模式）

✅ 确保Nacos服务发现功能已正确配置
✅ 目标服务器必须在Nacos中注册
✅ 确保metadata配置正确（特别是 business-type）
✅ 确保目标服务器实例状态为健康（healthy）

3. 超时设置

⏱️ 上传超时：120秒（支持大文件上传）
⏱️ 下载超时：120秒（支持大文件下载）
⏱️ HEAD请求超时：30秒（仅获取元数据）
💡 可根据实际网络环境和文件大小调整超时时间

4. 路径安全

🔒 转发时会进行路径安全检查，防止路径遍历攻击
🔒 自动清理路径中的危险字符（..、~ 等）
🔒 自动去除多余的斜杠

5. 响应处理

📤 会转发目标服务器的所有响应头
📤 保持原始响应格式（JSON、二进制流等）
📤 保持原始状态码（200、206、404等）

6. 文件验证

✅ 上传时会检查文件大小限制（如果配置了 max-size）
✅ 上传时会检查文件类型限制（如果配置了 allowed-upload-suffix）
⚠️ 注意：验证在代理服务器进行，目标服务器可能也有自己的验证规则

7. 负载均衡

🔄 负载均衡模式下，Nacos会自动处理实例选择
🔄 只选择健康（healthy）的实例
🔄 根据metadata中的 business-type 过滤实例
🔄 支持灰度版本路由（通过 wueasy-gray-version 请求头）

8. 请求头转发

📋 自动转发 User-Agent 请求头
📋 支持 wueasy-gray-version 请求头（用于灰度发布）
📋 支持 Range 请求头（用于断点续传）
⚠️ 其他自定义请求头需要根据实际需求决定是否转发

9. 错误处理

❌ 网络连接失败：返回 "HTTP上传请求失败" 或类似错误
❌ 服务不可用：返回 "没有可用的服务实例"
❌ 目标服务器错误：透传目标服务器的错误响应
📝 所有错误都会记录详细日志

📊 监控和日志

HTTP模式的请求会在日志中记录以下信息：

日志内容

请求转发日志：记录转发的目标URL和请求方法
服务发现日志：负载均衡模式下，记录从Nacos获取的实例信息
响应状态：记录目标服务器的响应状态码
错误信息：记录所有错误和异常情况
网络状态：记录连接超时、连接失败等网络问题

日志示例

[INFO] 从Nacos获取服务实例: 192.168.1.100:9830
[INFO] HTTP上传请求成功，状态码: 200
[ERROR] HTTP上传请求失败: connection timeout
[ERROR] 获取Nacos服务实例失败: serviceName=file-server, businessType=images, error=no healthy instance

监控建议

📈 监控请求转发成功率
📈 监控目标服务器响应时间
📈 监控服务发现成功率（负载均衡模式）
📈 监控错误率和错误类型

🔧 故障排除

常见问题

Q: 连接超时怎么办？

A: 检查以下几个方面：

网络连接

bash

# 测试网络连通性
ping 192.168.1.100
telnet 192.168.1.100 9830

目标服务器地址
- 确认目标服务器地址和端口正确
- 检查是否有DNS解析问题
防火墙设置
- 检查代理服务器到目标服务器的防火墙规则
- 确认目标服务器端口已开放
超时设置
- 如果文件较大，可能需要增加超时时间
- 检查网络延迟是否过高

Q: 404错误怎么办？

A: 检查以下几个方面：

API路径
- 确认目标服务器支持对应的API路径
- 检查路径拼接是否正确
业务类型配置
- 确认 business-type 配置正确
- 检查目标服务器是否支持该业务类型
文件路径
- 确认文件路径格式正确
- 检查文件是否存在于目标服务器

Q: 上传失败怎么办？

A: 检查以下几个方面：

目标服务器支持
- 确认目标服务器支持文件上传接口
- 检查目标服务器是否正常运行
文件限制
- 检查文件大小是否超过限制（代理服务器和目标服务器）
- 检查文件类型是否在允许列表中
网络问题
- 检查网络连接是否稳定
- 确认上传超时时间是否足够
权限问题
- 检查目标服务器是否有写入权限
- 确认存储空间是否充足

Q: 删除失败怎么办？

A: 检查以下几个方面：

目标服务器支持
- 确认目标服务器支持文件删除接口
- 检查目标服务器是否配置了 allow-delete: true
文件路径
- 确认文件路径正确
- 检查文件是否存在于目标服务器
权限问题
- 检查目标服务器是否有删除权限
- 确认业务类型是否允许删除

Q: 负载均衡模式下没有可用实例？

A: 检查以下几个方面：

Nacos配置
- 确认Nacos服务发现功能已正确配置
- 检查Nacos连接是否正常
服务注册
- 确认目标服务器已在Nacos中注册
- 检查服务名称是否正确（lb:// 后的服务名）
实例状态
- 确认实例状态为健康（healthy）
- 检查实例是否被标记为不健康
Metadata配置
- 确认metadata中的 business-type 与配置匹配
- 检查metadata配置格式是否正确

示例配置：

yaml

# 目标服务器Nacos配置
nacos:
  discovery:
    metadata:
      business-type: images  # 必须与配置中的business-type匹配

Q: 灰度发布不生效？

A: 检查以下几个方面：

请求头设置
- 确认请求头名称正确：wueasy-gray-version
- 检查请求头值是否与目标服务器metadata中的 version 匹配
目标服务器配置
- 确认目标服务器metadata中配置了 version
- 检查版本号是否匹配
实例可用性
- 确认灰度版本的实例状态为健康
- 如果没有匹配的灰度实例，系统会回退到普通实例

示例：

bash

# 请求时添加灰度版本头
curl -H "wueasy-gray-version: v2.0.0" \
     -X POST http://proxy-server:9830/upload/images

Q: Range请求（断点续传）不工作？

A: 检查以下几个方面：

目标服务器支持
- 确认目标服务器支持HTTP Range请求
- 检查目标服务器版本是否支持Range功能
请求头转发
- 确认 Range 请求头已正确转发
- 检查响应头 Content-Range 是否正确返回
响应状态码
- Range请求应返回 206 Partial Content
- 检查目标服务器是否正确处理Range请求

Q: 响应格式不正确？

A: 检查以下几个方面：

响应透传
- HTTP模式会透传目标服务器的原始响应
- 如果响应格式不正确，可能是目标服务器的问题
响应头
- 确认响应头已正确转发
- 检查 Content-Type 是否正确
状态码
- 确认状态码已正确透传
- 检查是否有中间件修改了响应

🌐 HTTP转发模式使用指南 ​

🎯 概述 ​

配置说明 ​

基本配置 ​

负载均衡配置 ​

配置参数说明 ​

🔄 工作原理 ​

请求转发规则 ​

转发流程 ​

普通HTTP模式示例 ​

负载均衡模式 ​

URL格式 ​

工作原理 ​

示例 ​

目标服务器配置 ​

灰度发布支持 ​

负载均衡策略 ​

📋 使用场景 ​

场景1: 统一网关入口 ​

场景2: 负载均衡 ​

场景3: 业务隔离 ​

场景4: 跨地域部署 ​

场景5: 灰度发布 ​

场景6: 混合存储 ​

✨ 功能特性 ​

1. 完整功能支持 ​

2. 自动URL构建 ​

3. 响应透传 ​

4. 负载均衡和灰度发布 ​

5. 错误处理 ​

6. 超时控制 ​

⚠️ 注意事项 ​

1. 网络连接 ​

2. Nacos配置（负载均衡模式） ​

3. 超时设置 ​

4. 路径安全 ​

5. 响应处理 ​

6. 文件验证 ​

7. 负载均衡 ​

8. 请求头转发 ​

9. 错误处理 ​

📊 监控和日志 ​

日志内容 ​

日志示例 ​

监控建议 ​

🔧 故障排除 ​

常见问题 ​

🌐 HTTP转发模式使用指南

🎯 概述

配置说明

基本配置

负载均衡配置

配置参数说明

🔄 工作原理

请求转发规则

转发流程

普通HTTP模式示例

负载均衡模式

URL格式

工作原理

示例

目标服务器配置

灰度发布支持

负载均衡策略

📋 使用场景

场景1: 统一网关入口

场景2: 负载均衡

场景3: 业务隔离

场景4: 跨地域部署

场景5: 灰度发布

场景6: 混合存储

✨ 功能特性

1. 完整功能支持

2. 自动URL构建

3. 响应透传

4. 负载均衡和灰度发布

5. 错误处理

6. 超时控制

⚠️ 注意事项

1. 网络连接

2. Nacos配置（负载均衡模式）

3. 超时设置

4. 路径安全

5. 响应处理

6. 文件验证

7. 负载均衡

8. 请求头转发

9. 错误处理

📊 监控和日志

日志内容

日志示例

监控建议

🔧 故障排除

常见问题