企业官网建设流程全解析

• API网关
• 后端
• 微服务

本篇指南以 Ocelot 官方文档首页（docs/index.rst）为骨架，系统梳理 Ocelot 25.0 的文档体系与核心内容：从面向微服务架构的"大图景"设计、快速上手三行配置，到两大主特性（配置与路由），再到 27 项按字母序排列的功能特性和构建流程。读完本文，你将掌握 Ocelot 文档的导航逻辑、各特性章节的主题与定位，并了解如何结合仓库源码（src/、samples/、test）快速定位实现细节，为选型与落地提供完整路径图。

一、这份文档索引是什么：Ocelot 25.0 的"特性地图"

docs/index.rst是 Ocelot 官方文档（基于 Sphinx/reStructuredText 构建，参见 docs/readme.md）的入口页面。它本身不讲解某个具体功能，而是承担三层职责：

1. 版本指引：明确当前文档对应 Ocelot25.0版本；
2. 阅读路线建议：给新用户推荐 Introduction 章节（docs/introduction/bigpicture.rst），给生产环境用户强调升级前必读 发布说明；
3. 完整目录树（toctree）：按Welcome / Introduction / Features / Building Ocelot四组，列出全部 27 个特性章节与 3 个构建章节。

这份索引的价值在于：它揭示了项目团队对文档的组织方式——所有特性按字母序排列，并明确指出Configuration（配置）与 Routing（路由）是两大 primary features（主特性），其余特性围绕它们扩展。阅读仓库中的任一功能代码时，先回到这张"特性地图"定位对应章节，是最高效的路径。

二、Ocelot 的定位与"大图景"（Introduction 章节）

2.1 适用场景与技术底座

按 大图景章节 的说明，Ocelot 面向使用 .NET 构建微服务（SOA）架构、需要一个统一入口（API Gateway）的团队；它只要求上下游通信走 HTTP(S)，可在 ASP.NET Core 支持的任意平台上运行。

从实现上看，Ocelot 本质上是一组按特定顺序排列的 ASP.NET Core 中间件：

• 它会按配置不断改写HttpRequest对象，直到某个"请求构建中间件"将其转换为HttpRequestMessage；
• 真正发起下游请求的中间件是管道中最后一个节点，不再调用下一个中间件；
• 下游响应沿管道原路返回，由专门的中间件把HttpResponseMessage映射回HttpResponse返回给客户端。

这一机制在源码中对应 OcelotPipelineExtensions.cs（管线组装）与 DownstreamUrlCreatorMiddleware.cs、Requester 中间件（请求构建与发送）等实现。

2.2 四种典型部署拓扑

bigpicture.rst用 4 张架构图说明常见部署形态（图片位于 docs/images/）：

其中多实例 + Consul 场景正是 服务发现特性 的典型用途，Consul 同时还能充当配置 KV 存储（见下文"配置的多种存储形态"）。

三、快速上手：从空项目到第一条路由

Getting Started 章节 给出了完整的上手路径，配套真实可运行的 Basic 示例。

3.1 目标框架与安装

Ocelot 25.0 面向 ASP.NET Core，目标框架为 .NET 8（LTS）、.NET 9（STS）与 .NET 10（LTS）。安装方式：

dotnet add package Ocelot

推荐使用"ASP.NET Core Empty"模板创建最小 API 项目，但不要添加app.Map*端点映射方法——Ocelot 的中间件管线与 Minimal API 端点不兼容（这也是入门章节强调的硬性约束）。

3.2 最小配置：四段式 JSON

入门章节给出了两个配置文件。第一份是"能启动但什么都不做"的最小骨架：

{ "Aggregates": [], // optional "Routes": [], // required section "DynamicRoutes": [], // optional section "GlobalConfiguration": { // required "BaseUrl": "https://api.mybusiness.com" } }

第二份是真正转发请求的示例（与 samples/Basic/ocelot.json 一致）：

{ "Routes": [ { "UpstreamHttpMethod": [ "Get" ], "UpstreamPathTemplate": "/ocelot/posts/{id}", "DownstreamPathTemplate": "/todos/{id}", "DownstreamScheme": "https", "DownstreamHostAndPorts": [ { "Host": "jsonplaceholder.typicode.com", "Port": 443 } ] } ], "GlobalConfiguration": { "BaseUrl": "https://api.mybusiness.com" } }

BaseUrl是最需要留意的属性：Ocelot 需要知道自身对外的 URL，用于 Header 查找替换（HeaderFindAndReplace）和部分管理 API（Administration）配置。它应填客户端实际访问的外部地址——例如容器内 Ocelot 跑在http://123.12.1.2:6543，前面有 nginx 以https://api.mybusiness.com对外响应，则BaseUrl填https://api.mybusiness.com。多实例部署时建议通过脚本在命令行注入真实 IP。

3.3 启动代码：Program.cs 三步走

入门章节给出的 Program.cs 完整代码如下（仓库中 Basic 示例与文档完全一致）：

using Ocelot.DependencyInjection; using Ocelot.Middleware; var builder = WebApplication.CreateBuilder(args); // Ocelot Basic setup builder.Configuration .SetBasePath(builder.Environment.ContentRootPath) .AddOcelot(); // single ocelot.json file in read-only mode builder.Services .AddOcelot(builder.Configuration); // Add your features if (builder.Environment.IsDevelopment()) { builder.Logging.AddConsole(); } // Add middlewares aka app.Use*() var app = builder.Build(); await app.UseOcelot(); await app.RunAsync();

关键点：

• builder.Configuration.AddOcelot()：以只读方式加载单个ocelot.json；
• builder.Services.AddOcelot(builder.Configuration)：向 DI 容器注册 Ocelot 必需与默认服务；
• await app.UseOcelot()：组装全部 Ocelot 中间件，必须先 await 再RunAsync()；
• 不要调用app.MapGet()等端点方法。

四、两大主特性之一：Configuration（配置）

配置章节 是索引页点名的两大主特性之首，内容也最厚（超过 1200 行）。核心脉络如下。

4.1 四大配置区块与各自职责

{ "Routes": [], // static routes：网关如何对待上游请求的静态对象 "DynamicRoutes": [], // 动态路由：配合服务发现 provider 使用 "Aggregates": [], // 聚合路由（BFF）：把多个普通路由响应合成一个 JSON 对象 "GlobalConfiguration": {} // 全局配置：可覆盖静态路由级设置的"兜底区" }

各区块的 JSON 模型类分别位于 src/Configuration/File/：FileRoute.cs、FileDynamicRoute.cs、FileAggregateRoute.cs、FileGlobalConfiguration.cs。

4.2 Route 完整 Schema

文档给出了FileRoute（src/Configuration/File/FileRoute.cs）对应的全部顶层属性（完整 31 项），下面按用途分组列出：

• 路由匹配：UpstreamPathTemplate、UpstreamHttpMethod、UpstreamHost、UpstreamHeaderTemplates、RouteIsCaseSensitive、Priority；
• 下游转发：DownstreamPathTemplate、DownstreamScheme、DownstreamHostAndPorts、DownstreamHttpMethod、DownstreamHttpVersion、DownstreamHttpVersionPolicy；
• 请求/响应改写：AddClaimsToRequest、AddHeadersToRequest、AddQueriesToRequest、ChangeDownstreamPathTemplate、UpstreamHeaderTransform、DownstreamHeaderTransform、RouteClaimsRequirement；
• 横切能力：AuthenticationOptions、CacheOptions、HttpHandlerOptions、LoadBalancerOptions、QoSOptions、RateLimitOptions、SecurityOptions、Timeout、RequestIdKey、DangerousAcceptAnyServerCertificateValidator；
• 扩展与标识：DelegatingHandlers、Key、Metadata、ServiceName、ServiceNamespace。

重要弃用提示：FileCacheOptions（旧缓存配置段）自 24.1 起弃用，25.0 中已移除，请改用CacheOptions。这一点在FileRoute.cs源码中直接用[Obsolete("Use CacheOptions instead of FileCacheOptions! ...")]特性标注（src/Configuration/File/FileRoute.cs#L40-L41），与文档互为印证。

4.3 多环境配置与配置合并

与任何 ASP.NET Core 项目一样，Ocelot 支持环境化配置文件：

var builder = WebApplication.CreateBuilder(args); builder.Configuration .SetBasePath(builder.Environment.ContentRootPath) .AddJsonFile("ocelot.json") // primary config file .AddJsonFile($"ocelot.{builder.Environment.EnvironmentName}.json"); builder.Services .AddOcelot(builder.Configuration);

更 Ocelot 化的做法是使用AddOcelot(builder.Environment)：它按正则^ocelot\.(.*?)\.json$发现并合并所有ocelot.*.json文件（跳过环境专属文件），合并结果写回ocelot.json作为运行时的唯一事实来源；若想设置GlobalConfiguration，必须准备一个ocelot.global.json文件。合并逻辑的实现见 ConfigurationBuilderExtensions.cs，其中MergeOcelotJson枚举（ToFile/ToMemory）控制"写回磁盘"还是"仅驻留内存"（src/DependencyInjection/MergeOcelotJson.cs）。

合并到内存的典型场景是无磁盘写权限的云环境（Azure/AWS/GCP）与 Docker：

builder.Configuration .SetBasePath(builder.Environment.ContentRootPath) .AddOcelot(builder.Environment, MergeOcelotJson.ToMemory);

合并时机注意：合并只发生在应用启动阶段，启动后ocelot.json即保持静态；运行期热更新请改用配置重载（见 4.5）。

4.4 配置的多种存储形态

文档把配置来源归纳为四类，互相补充：

"从零构建"形态的最终 .NET 8+ 写法：

using Ocelot.Configuration.File; using Ocelot.DependencyInjection; using Ocelot.Middleware; var builder = WebApplication.CreateBuilder(args); var config = new FileConfiguration(); // create new or read static state from anywhere // ... initialize or rewrite props: add routes, global config, etc. builder.Configuration .SetBasePath(builder.Environment.ContentRootPath) .AddOcelot(config) // MergeOcelotJson.ToFile : writing config JSON back to disk .AddOcelot(config, builder.Environment, MergeOcelotJson.ToMemory); // merging to memory builder.Services .AddOcelot(builder.Configuration); var app = builder.Build(); await app.UseOcelot(); await app.RunAsync();

AddOcelot的全部重载签名都可以在 ConfigurationBuilderExtensions.cs 中找到（含optional、reloadOnChange可选参数）。

4.5 热重载与变更响应

重载（reload on change）：自 23.2 起，AddOcelot系列方法提供reloadOnChange参数，推荐用它代替原生AddJsonFile：

config.AddOcelot(env, mergeTo, optional: false, reloadOnChange: true);

主动响应变更（React to Changes）：从 DI 容器解析IOcelotConfigurationChangeTokenSource（实现位于 src/Configuration/ChangeTracking/），既可轮询ChangeToken.HasChanged，也可注册RegisterChangeCallback回调。文档提供了完整的BackgroundService轮询示例与回调类示例（见 配置章节 的 React to Changes 小节）。

4.6 常用路由级选项速查

HttpHandlerOptions（基于SocketsHttpHandler）：

"HttpHandlerOptions": { "AllowAutoRedirect": false, "MaxConnectionsPerServer": 2147483647, // max integer "PooledConnectionLifetimeSeconds": 120, "UseCookieContainer": false, "UseProxy": false, "UseTracing": false }

各选项默认值：AllowAutoRedirect=false（是否跟随 3xx 重定向）、MaxConnectionsPerServer=2147483647（到单一下游服务器的最大连接数）、PooledConnectionLifetimeSeconds=120（连接池中连接可复用的存活秒数，默认值硬编码在 src/Configuration/HttpHandlerOptions.cs 的DefaultPooledConnectionLifetimeSeconds常量）、UseCookieContainer=false（注意：开启后 Ocelot 会为每个下游服务缓存HttpMessageInvoker，同一下游的所有请求将共享 Cookie，文档明确建议非必要不开启）、UseProxy=false、UseTracing=false（开启后接入 Tracing 特性）。

SSL 错误：路由级设置"DangerousAcceptAnyServerCertificateValidator": true可忽略自签名证书的 SSL 校验，但文档强烈不推荐用于生产——仅限本地开发（https/wss自签名场景），生产环境必须使用权威签发的真实证书。

DownstreamHttpVersion/DownstreamHttpVersionPolicy：可指定下游代理请求使用的 HTTP 版本（1.0/1.1/2.0）；DownstreamHttpVersionPolicy（对应 .NET 的HttpVersionPolicy枚举）用于规避 HTTP/2 场景下的PROTOCOL_ERROR——典型解法是把VersionPolicy设为RequestVersionOrHigher：

{ "DownstreamHttpVersion": "2.0", "DownstreamHttpVersionPolicy": "RequestVersionOrHigher" }

Timeout体系（四层，优先级从高到低）：QoS 超时（毫秒）→ 路由级超时（秒）→ 全局超时（秒）→ 绝对默认值 90 秒（由DownstreamRoute.DefaultTimeoutSeconds静态属性定义，可在 Program.cs 中修改）。注意 QoS 与路由级 Timeout 同时配置时路由级会被忽略并触发警告日志。超时实现的核心是 TimeoutDelegatingHandler.cs。

Metadata扩展：路由与全局均可定义任意键值对，供中间件、Delegating Handler 等在运行时读取（Metadata 特性），全局值会被路由级同名键覆盖。

五、两大主特性之二：Routing（路由）

路由章节 从概念、占位符、通配、优先级到查询串路由、上游主机/头路由、IP 安全选项，完整覆盖了 Ocelot 的转发核心。

5.1 基础路由与占位符

一条路由由UpstreamPathTemplate（匹配入站 URL）、UpstreamHttpMethod（区分同 URL 的不同动词，留空则匹配所有方法）以及DownstreamPathTemplate/DownstreamScheme/DownstreamHostAndPorts（定义转发目标）构成：

{ "UpstreamHttpMethod": [ "Get", "Post" ], "UpstreamPathTemplate": "/posts/{postId}", "DownstreamPathTemplate": "/api/posts/{postId}", "DownstreamScheme": "https", "DownstreamHostAndPorts": [ { "Host": "localhost", "Port": 80 } ] }

占位符{something}必须同时出现在上、下游模板中，运行时 Ocelot 会把上游路径中的值代入下游模板。路由匹配默认不区分大小写，可用"RouteIsCaseSensitive": true按路由开启。

嵌入占位符（23.4+）：支持同一路径段内嵌入多个占位符，例如模板/api/invoices_{url0}/{url1}-{url2}_abcd/{url3}?urlId={url4}对上/api/invoices_super/123-456_abcd/789?urlId=987时，{url0}=super、{url1}=123、{url2}=456、{url3}=789、{url4}=987。

空占位符（23.0+）：占位符值为空串属于受支持的边界情况——/invoices/与省略末尾斜杠的/invoices都能正确路由到下游/api/invoices。

5.2 Catch All 与 Priority

{ "UpstreamPathTemplate": "/{catchAll}", "DownstreamPathTemplate": "/{catchAll}" }

Catch All 路由的占位符名称无意义（任何名称均可），其优先级恒为 0（硬编码）。配合Priority属性可精确控制匹配顺序：

{ "UpstreamPathTemplate": "/goods/delete", "Priority": 1 }

当请求/goods/delete时，/goods/delete（Priority=1）会优先于/goods/{catchAll}（Priority=0）被匹配——这在路由列表顺序不可控的场景下非常关键。

5.3 查询串路由与参数合并

查询参数同样支持占位符双向传递：

• 路径 → 查询串：UpstreamPathTemplate: /api/units/{subscription}/{unit}/updates→DownstreamPathTemplate: /api/subscriptions/{subscription}/updates?unitId={unit}；
• 查询串 → 路径：UpstreamPathTemplate: /api/subscriptions/{subscriptionId}/updates?unitId={uid}→DownstreamPathTemplate: /api/units/{subscriptionId}/{uid}/updates；
• Catch All 查询串：/contracts?{query}→/apipath/contracts?{query}（适合原样透传复杂查询，如 OData 过滤器）。

参数合并算法（由DownstreamUrlCreatorMiddleware实现，见 src/DownstreamUrlCreator/DownstreamUrlCreatorMiddleware.cs）按三步构造最终下游 URL：先放下游模板中显式定义的参数，其次追加{query}捕获的全部参数，最后追加其余替换出的占位符值。由此带来两个实用技巧：

1. 保留参数：占位符与参数名不同名（如{serverId}→server参数），参数被保留；
2. 删除参数：占位符与参数名同名（如{userId}→userId参数），参数被消除（比较区分大小写）。

注意 ASP.NET 数组模型绑定的selectedCourses=1050&selectedCourses=2000形式会被合并丢失，上游应改用selectedCourses[0]=1050&selectedCourses[1]=2000。

5.4 上游主机与上游头路由

UpstreamHost：按客户端Host头匹配路由；未设置时任意 Host 均可匹配，且两条除UpstreamHost外完全相同的路由，设置了值的那条优先。

UpstreamHeaderTemplates：要求请求包含指定头且值匹配才命中：

{ "UpstreamPathTemplate": "/", "UpstreamHeaderTemplates": { "country": "uk", "version": "v1" } }

头模板还支持特殊占位符{header:placeholdername}把整个请求头值注入下游路径模板，例如"version": "{header:versionnumber}"+"DownstreamPathTemplate": "/{versionnumber}/api"。该字典同样适用于聚合路由。

5.5 SecurityOptions：IP 黑白名单

基于IPAddressRange库支持六种 IP 规则格式：单 IP、IP 区间（192.168.1.1-192.168.1.250）、短区间（192.168.1.1-250）、子网（192.168.1.0/255.255.255.0）、CIDR IPv4（192.168.1.0/24）、CIDR IPv6（fe80::/10）。

"SecurityOptions": { "IPBlockedList": [ "192.168.0.0/23" ], "IPAllowedList": ["192.168.0.15", "192.168.1.15"], "ExcludeAllowedFromBlocked": true }

要点：名单在配置加载时求值；ExcludeAllowedFromBlocked（默认 false）允许"大范围封锁 + 子范围放行"；该特性仅支持静态路由，不适用于动态路由；自 25.0 起对 WebSocket 升级请求（CONNECT 方法）同样生效。实现见 src/Security/。

5.6 动态路由

动态路由（DynamicRoutes区块）配合服务发现特性使用，免去手工逐条配置路由的负担；其完整参考见服务发现章节的 Dynamic Routing 小节。

5.7 路由错误速查（499 与 504）

文档专门收集了两个高频异常场景：

• 499（Client Closed Request）：由OperationCanceledException触发，典型原因 A）客户端主动取消请求，B）浏览器刷新/关闭页面导致下游请求中断。建议保证客户端稳定，并视场景调整路由Timeout；
• 504（Gateway Timeout）：由TimeoutException触发，典型原因是下游服务响应缓慢或大请求压垮慢下游。建议调大路由Timeout。

完整错误与状态码体系见 错误码章节。

六、27 项功能特性全景（Features 目录）

索引页按字母序列出全部特性章节（对应 docs/features/ 目录下的 27 个.rst文件），本文按业务域归类并给出源码落点：

网关核心

• Configuration（主特性，见第四节）
• Routing（主特性，见第五节）
• Administration：管理 API，对应 src/Administration/
• Error Codes：错误码枚举在 src/Errors/OcelotErrorCode.cs

安全与身份

• Authentication、Authorization：中间件见 src/Authentication/、src/Authorization/
• Security：IP 安全策略，见 src/Security/
• Claims Transformation、Headers Transformation、Method Transformation：请求改写族

通信与流量治理

• Load Balancer：实现见 src/LoadBalancer/
• Rate Limiting：实现见 src/RateLimiting/
• Quality of Service：熔断器 CircuitBreakerDelegatingHandler.cs
• Caching：输出缓存中间件 OutputCacheMiddleware.cs
• Delegating Handlers：请求管道注入，见 src/Requester/
• Timeout：见 4.6

聚合与 BFF

• Aggregation：聚合中间件与聚合器接口在 src/Multiplexer/
• GraphQL：GraphQL 聚合示例见 samples/GraphQL/

服务发现与云原生

• Service Discovery：provider 工厂见 src/ServiceDiscovery/
• Service Fabric、Kubernetes：示例分别见 samples/ServiceFabric/、samples/Kubernetes/

可观测性与扩展

• Logging、Tracing：实现见 src/Logging/
• RequestId：链路标识见 src/RequestId/
• Metadata：路由元数据扩展，见 src/Metadata/
• Middleware Injection：自定义中间件注入，见 src/Middleware/
• Dependency Injection：IOcelotBuilder扩展体系，见 src/DependencyInjection/

协议与传输

• WebSockets：代理中间件 WebSocketsProxyMiddleware.cs（25.0 起支持，含wss与 IP 名单约束）

明确不支持的能力（notsupported.rst）：Chunked Encoding（Ocelot 总是回填Content-Length）、转发Host头、原生 Swagger 生成（替代方案：Postman 或社区包MMLib.SwaggerForOcelot）。

七、构建 Ocelot 的流程（Building 章节）

索引页第三组链接指向构建流程文档：

• building.rst：本地编译 Ocelot 的步骤；
• devprocess.rst：开发流程规范（是发布流程的一部分）；
• releaseprocess.rst：版本发布流程。

仓库同时提供Ocelot.slnx（主解决方案）与Ocelot.Samples.slnx（示例解决方案），示例项目覆盖 Basic、Configuration、GraphQL、Kubernetes、Metadata、ServiceDiscovery、ServiceFabric、WebSocket 等场景（samples/）。

八、从文档到源码的查证路径

阅读本仓库时，建议按"文档章节 → 对应src/模块 → 对应unit/或acceptance/测试"的三步法定位实现与验证：

• 配置模型：文档给出的 Schema 与 src/Configuration/File/ 下的FileRoute、FileDynamicRoute、FileAggregateRoute、FileGlobalConfiguration一一对应；
• DI 扩展：AddOcelot全家族签名在 src/DependencyInjection/ConfigurationBuilderExtensions.cs，MergeOcelotJson枚举与合并逻辑亦在其中；
• 管线与中间件：组装顺序见 src/Middleware/OcelotPipelineExtensions.cs；
• 可运行示例：Basic 示例（samples/Basic/Program.cs、samples/Basic/ocelot.json）可直接dotnet run验证第一节的最小路由。

升级提醒：生产环境升级前务必查阅 发布说明（索引页特别强调），并留意 24.1→25.0 的破坏性变更——FileCacheOptions与RateLimitRule旧配置段已在 25.0 移除，务必迁移到CacheOptions与RateLimitOptions。

• API网关
• 后端
• 微服务