三种部署模式

1. 本地开发模式

make download-zmq   安装 libzmq，cgo 依赖
make build          go 编译生成 bin/llm-d-kv-cache
make run            直接运行二进制

不涉及 Docker。Go 代码通过 cgo 链接 libzmq，宿主机必须安装 ZeroMQ。

一个进程包含三个组件：KVCache Indexer、EventsPool、HTTP Server(8080)。

make build 生成两个示例二进制：

offline 自己模拟 vLLM 发事件，没有 HTTP 服务，用来演示 index 到 scoring 的完整流程。online 连接真实 vLLM 的 ZMQ 端点，有 HTTP 服务，作为真实服务持续运行。

make run-example offline 流程：

1. Docker 启动 Python tokenizer 容器（gRPC 50051）
2. 运行 bin/examples/offline，Go 二进制在宿主机执行
3. 结束后清理 tokenizer 容器

Docker 只是为了提供 tokenizer 服务，KV Cache Manager 本身不在容器里跑。

2. Docker 容器模式

make image-build    构建镜像
make image-push     推送镜像到 registry

Dockerfile 两阶段构建：

Builder 阶段用 golang:1.24，安装 zeromq-devel 开发库，下载 Go 依赖，make build 编译。

Final 阶段用 ubi9 基础镜像，只装 zeromq 运行时，从 Builder 阶段拷贝编译好的二进制到 /app/kv-cache-manager，以非 root 用户 65532 运行。

Builder 装开发包用于编译，Final 只装运行时减小体积。

–platform 硬编码 linux，因为 macOS 的 GOOS 是 darwin，没有对应的容器镜像。

3. 线上模式（Kubernetes Kustomize）

先通过 make image-build 构建镜像，再通过 make install-k8s 部署。

kustomize build 读取 deploy 下所有 yaml 并合并，envsubst 把变量占位符替换成环境变量实际值，kubectl apply 从标准输入读取并创建资源。

当前 deploy 目录是 scaffold 阶段，kustomization.yaml 引用了不存在的文件（service.yaml、openshift、rbac 等），实际执行会失败。

线上运行时是三进程架构：vLLM Pod 通过 ZMQ 发送 KV 事件，KV Cache Manager StatefulSet 接收事件维护全局索引并提供 HTTP 打分接口，外部 Scheduler 调用打分接口做路由决策。

Helm 部署（vllm-setup-helm）

这是一个一键部署脚本，把 vLLM、KV Cache Manager 等所有组件打包成一条命令。

默认配置下生成 6 个 K8s 资源：

vLLM Deployment + Service：跑 vLLM 推理，通过 –kv-events-config 把 ZMQ 事件发到 KV Cache Manager 的 Service 地址。Service 提供固定 DNS 名字，Pod IP 变了也不影响。

KV Cache Manager Deployment + Service：接收 vLLM 事件，提供 HTTP 打分接口。Pod 里有 manager 容器和 tokenizer-uds sidecar 容器，通过 emptyDir 共享卷用 UDS socket 通信。

PVC：50Gi ReadWriteMany，挂载到 vLLM 容器 /data，缓存模型权重。

Secret：存储 Hugging Face token。

Redis Deployment + Service 默认关闭，是 LMCache 已废弃的方案。

Deployment 和 Service 的区别：Deployment 管理 Pod 的生命周期（创建、销毁、替换、扩缩容），Service 提供固定 DNS 和负载均衡（Pod IP 随时变化，Service 永远不变）。Deployment 是工厂负责生产和替换工人，Service 是前台总机负责转接电话。