反向代理与网关架构

引言

Nginx 反向代理、API 网关、流量治理与安全防护，从代理转发到统一入口的完整架构设计。

本文作为「互联网基础架构」系列的第 07 篇，围绕「代理」这一主题展开。互联网的每一个基础组件都不是孤立的：它以特定的协议接入、以分层的方式处理、以冗余的方式容错。为了把「代理」背后的机制讲透，本文将使用 18 种不同的 Mermaid 图表类型、共 36 张图来呈现同一主题的不同侧面——从宏观的数据流到微观的报文结构，从状态机到部署拓扑，力求让读者形成立体认知。

阅读提示：每张图都对应一个独立的 Mermaid 语法类型，图与图之间相互补充。建议先通读文字，再逐一对照图表理解。

一、代理的整体定位

在互联网架构中，代理承担着承上启下的职责。理解它的定位，需要同时看清它的输入、核心处理与输出三个环节。

二、流程图（全部语法-1）

1.1 流程总览（流程图）

代理的完整流程可以抽象为「输入 → 核心处理 → 输出」三段。下面的流程图展示了代理在主链路上的关键环节：入口校验、核心处理、状态存储、结果分发，以及失败时的错误记录。图中的菱形节点代表判断分支，圆柱节点代表状态存储，圆角节点代表出入口——这正是 Mermaid 流程图在表示网络组件时的典型用法。

flowchart TB
  classDef z1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef z2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef z3 fill:#e0f7fa,stroke:#00838f,color:#004d40
  classDef z4 fill:#e8f5e9,stroke:#388e3c,color:#1b5e20
  subgraph IN[输入层 入口]
    direction LR
    A((用户代理接入)) --> B[代理接入参数解析]
    B --> C{代理是否合法}
  end
  subgraph CORE[核心层 处理]
    direction LR
    D[网关处理逻辑] --> E[转发转发路由]
    E --> F[(状态网关)]
  end
  subgraph OUT[输出层 响应]
    direction LR
    G[结果转发] --> H{网关是否成功}
    H -->|成功| I[返回代理结果]
    H -->|失败| J[记录网关错误]
  end
  C -->|通过| D
  C -->|拒绝| J
  F --> G
  I --> K((结束转发))
  E -.->|异步| F
  D ==> G
  class A z1
  class D z2
  class F z3
  class I z4
  click A "https://example.com/in" "代理入口"
  click F "https://example.com/state" "网关状态"
  class IN z1
  class CORE z2
  class OUT z3

1.2 变体视角

下面的第二张流程图从另一个视角切入，与上图互为补充，共同构成对「代理」流程图的完整表达。

flowchart TB
  classDef z1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef z2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef z3 fill:#e0f7fa,stroke:#00838f,color:#004d40
  classDef z4 fill:#e8f5e9,stroke:#388e3c,color:#1b5e20
  subgraph IN[输入层 网关]
    direction LR
    A((用户代理请求)) --> B[代理请求参数解析]
    B --> C{代理是否合法}
  end
  subgraph CORE[核心层 调度]
    direction LR
    D[网关校验逻辑] --> E[转发调度路由]
    E --> F[(状态网关)]
  end
  subgraph OUT[输出层 返回]
    direction LR
    G[结果转发] --> H{网关是否成功}
    H -->|成功| I[返回代理结果]
    H -->|失败| J[记录网关错误]
  end
  C -->|通过| D
  C -->|拒绝| J
  F --> G
  I --> K((结束转发))
  E -.->|异步| F
  D ==> G
  class A z1
  class D z2
  class F z3
  class I z4
  click A "https://example.com/in" "代理入口"
  click F "https://example.com/state" "网关状态"
  class IN z1
  class CORE z2
  class OUT z3

二、时序图（类型-2）

2.1 调用时序（时序图）

组件之间的协作顺序是理解代理的钥匙。下面的时序图展示了代理链路中用户端、网关、核心服务与存储之间的完整交互：同步调用的激活与返回、成功与失败分支、重试循环、审计记录与并行处理，以及超时中断的场景。

sequenceDiagram
  autonumber
  participant U as 用户端
  participant G as 代理网关
  participant S as 网关服务
  participant D as 转发存储
  U->>G: 发起代理请求
  activate G
  G->>S: 网关调用
  activate S
  S->>D: 转发读写
  activate D
  D-->>S: 转发返回
  deactivate D
  alt 网关成功
    S-->>G: 成功响应
  else 网关失败
    S-->>G: 失败码
  end
  deactivate S
  G-->>U: 代理最终响应
  deactivate G
  Note over G,S: 同步调用链路
  loop 网关重试
    G->>S: 重试请求
  end
  opt 审计
    S->>D: 记录代理日志
  end
  par 并行转发
    S->>S: 转发校验
    S->>S: 转发组装
  end
  break 超时
    G-->>U: 超时提示
  end

2.2 变体视角

下面的第二张时序图从另一个视角切入，与上图互为补充，共同构成对「代理」时序图的完整表达。

sequenceDiagram
  autonumber
  participant U as 用户端
  participant G as 代理网关
  participant S as 网关服务
  participant D as 转发存储
  U->>G: 发送代理请求
  activate G
  G->>S: 网关调用
  activate S
  S->>D: 转发读写
  activate D
  D-->>S: 转发返回
  deactivate D
  alt 网关成功
    S-->>G: 成功响应
  else 网关失败
    S-->>G: 失败码
  end
  deactivate S
  G-->>U: 代理最终响应
  deactivate G
  Note over G,S: 异步调用链路
  loop 网关重试
    G->>S: 重试请求
  end
  opt 审计
    S->>D: 记录代理日志
  end
  par 并行转发
    S->>S: 转发校验
    S->>S: 转发组装
  end
  break 超时
    G-->>U: 超时提示
  end

二、状态图（类型-3）

3.1 状态流转（状态图）

代理在生命周期内会经历多个状态。下面的状态图描绘了从初始化、就绪、运行到校验、完成的完整状态机，其中包含子状态（复合状态）、条件分支与失败重试回路，注释节点标注了校验条件与成功条件。

stateDiagram-v2
  direction LR
  [*] --> 初始化: 代理开始
  初始化 --> 就绪
  就绪 --> 运行: 触发网关
  state 运行 {
    子态A: 网关阶段一
    子态B: 网关阶段二
    子态A --> 子态B
  }
  运行 --> 校验: 转发完成
  校验 --> 完成: 通过
  校验 --> 重试: 失败
  重试 --> 运行: 再次网关
  完成 --> [*]: 转发结束
  note right of 校验
    网关条件判断
  end note
  note left of 完成
    代理成功转发
  end note

3.2 变体视角

下面的第二张状态图从另一个视角切入，与上图互为补充，共同构成对「代理」状态图的完整表达。

stateDiagram-v2
  direction LR
  [*] --> 初始化: 代理开始
  初始化 --> 就绪
  就绪 --> 处理中: 触发网关
  state 处理中 {
    子态A: 网关阶段一
    子态B: 网关阶段二
    子态A --> 子态B
  }
  处理中 --> 校验: 转发完成
  校验 --> 完成: 通过
  校验 --> 重试: 失败
  重试 --> 处理中: 再次网关
  完成 --> [*]: 转发结束
  note right of 校验
    网关条件判断
  end note
  note left of 完成
    代理成功转发
  end note

二、类图（类型-4）

4.1 组件职责（类图）

从面向对象视角看，代理由若干职责清晰的类协作完成。下面的类图定义了客户端、服务端与存储三类核心对象的属性与方法，并通过继承、组合、聚合、依赖与实现五种关系表达它们之间的耦合方式。

classDiagram
  class Client {
    +String 代理Id
    +int retry
    +send() void
    +retry() void
  }
  class Service {
    +String 网关Type
    -int status
    +process() Result
    +validate() bool
  }
  class Storage {
    +Map data
    +read() Object
    +write() bool
  }
  Client <|-- Service
  Client *-- Storage
  Service o-- Client
  Service ..> Storage
  Client ..|> Storage
  note for Service "代理核心逻辑"

4.2 变体视角

下面的第二张类图从另一个视角切入，与上图互为补充，共同构成对「代理」类图的完整表达。

classDiagram
  class Gateway {
    +String 代理Id
    +int retry
    +send() void
    +retry() void
  }
  class Handler {
    +String 网关Type
    -int status
    +process() Result
    +validate() bool
  }
  class Repo {
    +Map data
    +read() Object
    +write() bool
  }
  Gateway <|-- Handler
  Gateway *-- Repo
  Handler o-- Gateway
  Handler ..> Repo
  Gateway ..|> Repo
  note for Handler "代理核心逻辑"

二、实体关系图（类型-5）

5.1 数据模型（实体关系图）

代理背后的数据需要清晰的实体关系建模。下面的实体关系图定义了三个实体及其主外键，并用基数符号表达「一对多」「多对多」等关联约束，这是数据库表结构设计的直接依据。

erDiagram
  ENTITY_A ||--o{ ENTITY_B : 代理
  ENTITY_B ||--|{ ENTITY_C : 网关
  ENTITY_A {
    string id PK
    string name
    string 代理Key FK
  }
  ENTITY_B {
    string id PK
    string 网关Ref FK
    int count
  }
  ENTITY_C {
    string id PK
    string payload
  }

5.2 变体视角

下面的第二张实体关系图从另一个视角切入，与上图互为补充，共同构成对「代理」实体关系图的完整表达。

erDiagram
  ENTITY_A ||--o{ ENTITY_B : 代理
  ENTITY_B ||--|{ ENTITY_C : 网关
  ENTITY_A {
    string id PK
    string name
    string 代理Key FK
  }
  ENTITY_B {
    string id PK
    string 网关Ref FK
    int count
  }
  ENTITY_C {
    string id PK
    string payload
  }

二、甘特图（类型-6）

6.1 实施排期（甘特图）

工程落地需要排期。下面的甘特图展示了代理从准备、构建、验证到演练、发布的时间安排，任务之间的依赖关系用箭头表达，里程碑标记了关键节点。

gantt
  title 代理实施计划
  dateFormat X
  axisFormat %L
  section 网关一期
    代理准备 :a1, 0, 2
    代理构建 :a2, after a1, 4
    代理验证 :a3, after a2, 2
  section 转发上线
    转发演练 :b1, after a3, 2
    转发发布 :milestone, b2, after b1, 0

6.2 变体视角

下面的第二张甘特图从另一个视角切入，与上图互为补充，共同构成对「代理」甘特图的完整表达。

gantt
  title 代理演进计划
  dateFormat X
  axisFormat %L
  section 网关二期
    代理准备 :a1, 0, 2
    代理构建 :a2, after a1, 4
    代理验证 :a3, after a2, 2
  section 转发优化
    转发演练 :b1, after a3, 2
    转发发布 :milestone, b2, after b1, 0

二、饼图（类型-7）

7.1 构成分析（饼图）

代理的组成并非均质。下面的饼图用比例直观呈现了代理主流程与辅助分支的构成占比，帮助架构师判断优化投入的优先级。

pie showData
  title 代理构成分析
  "代理 主流程" : 45
  "网关 分支" : 30

7.2 变体视角

下面的第二张饼图从另一个视角切入，与上图互为补充，共同构成对「代理」饼图的完整表达。

pie showData
  title 代理分布分析
  "代理 主流程" : 40
  "网关 分支" : 25

二、旅程图（类型-8）

8.1 用户体验（旅程图）

从用户视角看，代理的体验分为多个阶段。下面的旅程图按阶段标注了代理各环节的用户满意度评分，得分越低越需要优化——它是体验导向架构分析的经典工具。

journey
  title 代理核心旅程
  section 网关阶段
    代理发起: 5: 用户
    代理处理: 4: 系统
  section 转发阶段
    代理验证: 3: 用户
    代理交付: 5: 系统

8.2 变体视角

下面的第二张旅程图从另一个视角切入，与上图互为补充，共同构成对「代理」旅程图的完整表达。

journey
  title 代理完整旅程
  section 网关阶段
    代理发起: 5: 用户
    代理处理: 4: 系统
  section 转发阶段
    代理验证: 3: 用户
    代理交付: 5: 系统

二、时间线图（类型-9）

9.1 演进历程（时间线图）

代理并非一蹴而就。下面的时间线图按时间顺序回顾了代理从雏形到标准化的演进脉络，帮助读者建立历史纵深感。

timeline
  title 代理演进历程
  网关初期 : 代理雏形出现
  中期 : 代理标准化
  转发期 : 代理大规模应用
  未来 : 代理持续演进

9.2 变体视角

下面的第二张时间线图从另一个视角切入，与上图互为补充，共同构成对「代理」时间线图的完整表达。

timeline
  title 代理发展历程
  网关初期 : 代理雏形出现
  中期 : 代理标准化
  转发期 : 代理大规模应用
  未来 : 代理持续演进

二、思维导图（类型-10）

10.1 知识地图（思维导图）

代理的知识体系庞大而分散。下面的思维导图以树状结构归纳了代理的输入要素、输出交付与主链路支撑，是复习与自查的便捷索引。

mindmap
  root((代理核心))
    网关输入
      数据源
      配置项
    转发输出
      主结果
      附属结果
    代理主链路
      处理逻辑
      容错机制

10.2 变体视角

下面的第二张思维导图从另一个视角切入，与上图互为补充，共同构成对「代理」思维导图的完整表达。

mindmap
  root((代理总览))
    网关前置
      数据源
      配置项
    转发交付
      主结果
      附属结果
    代理支撑
      处理逻辑
      容错机制

二、 Git 流程图（类型-11）

11.1 版本演进（Git 流程图）

工程协作中，代理的代码演进遵循分支管理规范。下面的Git 流程图模拟了特性分支开发、合入主分支、发布打标签与补丁摘取的完整流程。

gitGraph
  commit id: "base"
  branch feature
  checkout feature
  commit id: "代理-dev"
  commit id: "代理-int"
  checkout main
  merge feature
  commit id: "代理-rel" tag: "v1"
  cherry-pick id: "代理-dev"

11.2 变体视角

下面的第二张 Git 流程图从另一个视角切入，与上图互为补充，共同构成对「代理」Git 流程图的完整表达。

gitGraph
  commit id: "base"
  branch hotfix
  checkout hotfix
  commit id: "代理-dev"
  commit id: "代理-int"
  checkout main
  merge hotfix
  commit id: "代理-rel" tag: "v2"
  cherry-pick id: "代理-dev"

二、象限图（类型-12）

12.1 方案取舍（象限图）

代理的多种方案需要权衡。下面的象限图按「代理程度」与「网关程度」两个维度划分四个象限，不同方案落入不同象限，直观支持选型决策。

quadrantChart
  title 代理优先级象限
  x-axis 低 代理 --> 高 代理
  y-axis 低 网关 --> 高 网关
  quadrant-1 高网关高代理
  quadrant-2 高网关低代理
  quadrant-3 低网关低代理
  quadrant-4 低网关高代理
  代理方案A: [0.2, 0.8]
  代理方案B: [0.75, 0.65]

12.2 变体视角

下面的第二张象限图从另一个视角切入，与上图互为补充，共同构成对「代理」象限图的完整表达。

quadrantChart
  title 代理价值象限
  x-axis 低 代理 --> 高 代理
  y-axis 低 网关 --> 高 网关
  quadrant-1 高网关高代理
  quadrant-2 高网关低代理
  quadrant-3 低网关低代理
  quadrant-4 低网关高代理
  代理方案C: [0.2, 0.8]
  代理方案D: [0.75, 0.65]

二、桑基图（类型-13）

13.1 流量流向（桑基图）

代理链路中的流量存在分流与合流。下面的桑基图用带宽度比例的连线展示代理从输入到处理再到输出的流量流向与损耗，是容量规划的重要参考。由于该图类型的语法限制，节点使用 ASCII 标识（如 dns-req、resolver-proc），语义与正文保持一致。

sankey-beta
  proxy-req,gateway-proc,120
  gateway-proc,fwd-res,60

13.2 变体视角

下面的第二张桑基图从另一个视角切入，与上图互为补充，共同构成对「代理」桑基图的完整表达。

sankey-beta
  proxy-in,gateway-fwd,90
  gateway-fwd,fwd-out,45

二、报文结构图（类型-14）

14.1 报文结构（报文结构图）

协议层面，代理的交互最终体现为固定格式的报文。下面的报文结构图按位域拆解了代理报文的类型、标识、长度与负载字段，是协议设计与抓包分析的基础。

packet-beta
  title 代理请求报文
  0-7: "代理类型"
  8-15: "网关标识"
  16-31: "转发长度"
  32-63: "数据负载"

14.2 变体视角

下面的第二张报文结构图从另一个视角切入，与上图互为补充，共同构成对「代理」报文结构图的完整表达。

packet-beta
  title 代理响应报文
  0-7: "代理类型"
  8-15: "网关标识"
  16-31: "转发长度"
  32-63: "数据负载"

二、块图（类型-15）

15.1 模块拓扑（块图）

系统层面，代理由入口、处理、存储与辅助模块构成。下面的块图以列布局和跨列块表达模块之间的依赖关系，辅助模块（监控、日志）以虚线关联。

block-beta
  columns 3
  A["代理入口"] B["网关处理"] C["转发存储"]
  A-->B
  B-->C
  blockArrowId<["代理流程"]>(up)
  block D["代理辅助模块"]:2
    D1["监控"] D2["日志"]
  end
  C-->D
  B-.->D

15.2 变体视角

下面的第二张块图从另一个视角切入，与上图互为补充，共同构成对「代理」块图的完整表达。

block-beta
  columns 3
  A["代理入口"] B["网关处理"] C["转发存储"]
  A-->B
  B-->C
  blockArrowId<["代理流程"]>(up)
  block D["代理辅助模块"]:2
    D1["监控"] D2["日志"]
  end
  C-->D
  B-.->D

二、 C4 上下文图（类型-16）

16.1 系统上下文（C4 上下文图）

从架构视图看，代理处在用户与依赖系统的中间。下面的C4 上下文图用 Person、System、SystemBoundary 三类元素勾勒出代理系统上下文，明确外部边界与内部核心模块。

C4Context
  title System Context
  Person(user, "User", "代理使用者")
  System(app, "代理App", "对外提供代理能力")
  System(dep, "转发Dep", "数据与网关支撑")
  Rel(user, app, "use", "代理调用")
  Rel(app, dep, "dep", "网关协同")
  System_Boundary(bound, "代理Boundary") {
    System(inner, "网关Core", "内部网关模块")
  }
  Rel(app, inner, "contains", "网关内部")

16.2 变体视角

下面的第二张 C4 上下文图从另一个视角切入，与上图互为补充，共同构成对「代理」C4 上下文图的完整表达。

C4Context
  title External Relation
  Person(user, "User", "代理使用者")
  System(app, "代理App", "对外提供代理能力")
  System(dep, "转发Dep", "数据与网关支撑")
  Rel(user, app, "use", "代理调用")
  Rel(app, dep, "dep", "网关协同")
  System_Boundary(bound, "代理Boundary") {
    System(inner, "网关Core", "内部网关模块")
  }
  Rel(app, inner, "contains", "网关内部")

二、 XY 折线图（类型-17）

17.1 性能曲线（XY 折线图）

量化评估需要曲线。下面的XY 折线图用折线呈现代理吞吐的上升趋势，用柱状图呈现延迟的变化，两者对照即可发现性能拐点。

xychart-beta
    title Throughput Trend
    x-axis [t1, t2, t3, t4, t5]
    y-axis "value" 0 --> 100
    line [20, 45, 60, 75, 90]
    bar [10, 25, 35, 50, 70]

17.2 变体视角

下面的第二张 XY 折线图从另一个视角切入，与上图互为补充，共同构成对「代理」XY 折线图的完整表达。

xychart-beta
    title Latency Trend
    x-axis [t1, t2, t3, t4, t5]
    y-axis "value" 0 --> 100
    line [20, 45, 60, 75, 90]
    bar [10, 25, 35, 50, 70]

二、架构图（类型-18）

18.1 部署拓扑（架构图）

最终，代理以集群形态落地。下面的架构图描绘了代理接入层与处理层的多实例部署、汇聚节点与存储的连线关系，以及实例间的对齐布局——这是生产架构图的核心形态。由于该图类型的语法限制，节点使用 ASCII 标识，语义与正文保持一致。

architecture-beta
    group g1(cloud)[proxy_ClusterA]
    group g2(server)[gateway_ClusterB]
    service s1(server)[proxy_s1] in g1
    service s2(server)[proxy_s2] in g1
    service m(mainframe)[fwd_store] in g2
    service j(junction)[gateway_hub]
    s1:R --> L:j
    s2:R --> L:j
    j:B --> T:m
    align row s1 s2

18.2 变体视角

下面的第二张架构图从另一个视角切入，与上图互为补充，共同构成对「代理」架构图的完整表达。

architecture-beta
    group g1(cloud)[proxy_Ingress]
    group g2(server)[gateway_Process]
    service s1(server)[proxy_s1] in g1
    service s2(server)[proxy_s2] in g1
    service m(mainframe)[fwd_store] in g2
    service j(junction)[gateway_hub]
    s1:R --> L:j
    s2:R --> L:j
    j:B --> T:m
    align row s1 s2

结语

至此，我们通过 18 种图类型、共 36 张图表，从流程、时序、状态、数据、排期、体验、演进、拓扑等多个维度完整审视了「代理」。希望读者能够体会到：代理不是单一组件，而是一张由协议、数据、状态与部署共同织成的网；掌握它，需要的是「多图对照、立体思考」的方法。

下一篇文章将继续深入互联网基础架构的另一个主题，敬请期待。