源码地图

主线位置：三条主线经过的 crate 和它们之间的边。请求主线几乎全在 pingora-core 和 pingora-proxy 里，上游连接池单独在 pingora-pool；服务主线在 pingora-core 的 server、services 两个目录和 pingora-runtime 里；缓存主线从 pingora-proxy 的 proxy_cache.rs 进入 pingora-cache。本页说明这些 crate 谁依赖谁、每个从哪个文件读起、各有多大。

flowchart TB
  fac["pingora 门面"] --> proxy["pingora-proxy"]
  fac --> lb["load-balancing"]
  fac --> cache["pingora-cache"]
  fac --> core["pingora-core"]
  lb --> core
  lb --> ketama["pingora-ketama"]
  proxy --> cache
  proxy --> core
  cache --> core
  cache --> lru["pingora-lru"]
  cache --> hs["header-serde"]
  core --> pool["pingora-pool"]
  core --> rt["pingora-runtime"]
  core --> tls["pingora-openssl 等"]
  core --> http["pingora-http"]
  core --> tmo["pingora-timeout"]
  pool --> tmo
  http --> err["pingora-error"]
  mem["memory-cache"] --> ufo["TinyUFO"]
  lim["pingora-limits"]

图里只画了 pingora 自己的 crate 之间的主要依赖边，完整的边见下表。pingora-error 几乎被每个 crate 依赖，只画了一条；memory-cache 和 limits 两个是孤立的，门面 crate 不依赖它们。下面逐条核实。

依赖图：cargo tree 核实

依赖关系按实验项目 intro-run（模板的拷贝：pingora 开 openssl、proxy、lb、cache、time、connection_filter、upstream_modules）实际解析出来的看，命令是 cargo tree --offline -e normal -p <crate>@0.9.0 --depth 1，只取 pingora 自己的 crate：

从表里能读出四条：

• 门面 crate 只转发。 pingora 的 lib.rs 全文 101 行，pub use pingora_core::* 之后是 http、cache、lb、proxy、time 五个模块别名和一个 prelude。读源码时直接去对应的 crate。

• pingora-proxy 无条件依赖 pingora-cache。 pingora-proxy/Cargo.toml 里这一行没有 optional。只开 proxy 的 intro-notls 里反查：

  Copy

  pingora-cache v0.9.0
  └── pingora-proxy v0.9.0
      └── pingora v0.9.0
          └── intro-notls v0.1.0 (~/exp-pingora/intro-notls)
  

  所以每个 pingora 代理都编译了缓存状态机，process_request 里的 proxy_cache 每个请求都会走一遍（不开缓存时只调 request_cache_filter 和 is_purge，实测见一次请求）。门面上的 cache feature 只决定有没有 pingora::cache 这个路径。

• 没有 hyper。 cargo tree -p pingora@0.9.0 里一个 hyper 都没有：HTTP/1 的解析和编码是 pingora-core 在 httparse 之上自己写的，HTTP/2 直接用 h2。intro-run 里能看到 hyper，那是实验自己写上游和客户端用的。这一点和 hyper 卷 的对照放在 09 设计取舍。

• 有两个 crate 门面不管。 pingora-limits（限流计数器）和 pingora-memory-cache（带读穿锁的内存缓存，底下是 TinyUFO）谁都不依赖它们，要用就自己在 Cargo.toml 里写，见 07 限流 和 08 TinyUFO 与内存缓存。pingora-lru 只被缓存的淘汰用，pingora-ketama 只被负载均衡的一致性哈希用。

整棵树（-p pingora@0.9.0，去重后）在模板的 feature 下是 171 个包，只开 proxy 时是 160 个。

pingora-core 里的九个目录

pingora-core 的 src/ 有 47501 行，占全部 crate src/ 的一半多。lib.rs 声明了十个模块，其中 offload 是 pub(crate)：

另有 lib.rs（131 行）和 offload.rs（107 行，TLS 握手和上游连接的卸载线程池）。protocols/ 一个目录就占了 pingora-core 的 69%，其中 HTTP/1 的服务端和客户端（http/v1/）比整个 pingora-proxy 的 src/ 还大。

每个 crate 从哪读起

行数是 tag 上 <crate>/src/ 下所有 .rs 文件的行数，含 #[cfg(test)] 模块，不含 tests/、benches/、examples/。卷目录（plans/）里的规模数字含 benches/ 和 examples/，所以 pingora-core 是 48168、pingora-proxy 是 13444，比下表大。

真正做事的代码集中在前四个 crate：core、proxy、cache、load-balancing 加起来 79569 行，是全部 22 个 crate src/（95981 行）的 83%。

上游文档对应本卷哪一页

仓库 docs/ 下有一篇 quick start 和 user guide 的 19 篇（含目录页 index.md）。它们是使用说明，本卷引用前先核实：

index.md 的「Advanced topics (WIP)」下还列着「Pingora async runtime and threading model」「Background Service」「Blocking code in async context」等六个标题，都没有链接，还没写。线程模型见运行时，后台服务见一个 Server 的一生。

仓库里不讲的部分

• pingora-boringssl、pingora-s2n：另两个 TLS 后端，本机没有它们的依赖缓存；讲 openssl 后端时对照一句。
• pingora-prometheus（131 行）：把 prometheus 的默认 registry 暴露成一个 HTTP 服务。
• pingora-foundations（414 行，0.9.0 新增）：接 Cloudflare 的 foundations 遥测库，MSRV 1.88，比工作区其他 crate 的 1.85 高；六个遥测 feature 一个都不开时 compile_error!。
• pingora-core 里的 sentry、dial9 集成和 protocols/windows.rs。
• pingora-proxy/src/subrequest/ 和 pingora-core/src/protocols/http/subrequest/：子请求只在缓存页里讲到为止。

小结

• 依赖方向：门面 → proxy / lb / cache → core → pool、runtime、timeout、http、error；TLS 后端是 core 的可选依赖，同时只能有一个。
• pingora-proxy 无条件依赖 pingora-cache，每个代理都编译、都走一遍 proxy_cache；门面的 cache feature 只加模块路径。
• 依赖树里没有 hyper；HTTP/1 在 pingora-core/src/protocols/http/v1/（13212 行），HTTP/2 用 h2。
• pingora-limits、pingora-memory-cache（加 TinyUFO）不在门面依赖里，要自己加。
• pingora-core 47501 行，protocols/ 占 69%；核心四个 crate 占全部 src/ 的 83%。
• Prometheus 在 0.9.0 从 core 里搬到 pingora-prometheus（5e5a374 / #612、842ddd9），依赖方向反了过来。