企业官网建设流程全解析

在 k8s v1.10 里为了搞清 Resource Quota 的创建流程，沿cmd/kube-apiserver/app的 main 一路追到 go-restful 初始化，最容易卡住的地方不是模型能不能读源码，而是 Route 注册顺序与 webservice 挂载对不上：APIInstaller.Install已经生成了ws，registerResourceHandlers也把 POST/namespaces/{namespace}/resourcequotas的 handler 拼进了routes，可你回头在调试器里看ws的 route 列表，却发现 POST 不在里面。这时用 Codex 带着现象去读源码行不行？可以，前提是先把 Codex 的请求通道配通：打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建 API Key，把~/.codex/config.toml里的base_url填成https://taotoken.net/api，再把 go-restful 的 container/webservice/route 片段贴给 Codex。TaoToken 只负责供 Key 和统一入口，不替 Codex 判断源码。下面按原文的追源码路径走一遍，把 Route 对不上的问题拆开。

1. kube-apiserver v1.10 追 main：Route 对不上先看 go-restful Container

1.1 背景：Resource Quota 和 go-restful 的三层对象

这次排障的起点很具体：工作中要引入 k8s Resource Quota，于是从 API Server 源码看 resource quota 的创建流程。源码版本是 v1.10，Go 版本 1.10.5，etcd 3.0+，IDE 用 IDEA 或 GoLand 都可以。1.10 及以上的 k8s 对 Go 版本有要求，本地编译 kube-apiserver 常用命令是进入./go/src/k8s.io/kubernetes后执行make WHAT=cmd/kube-apiserver all，先启动 etcd，再本地启动 api-server 进 debug。如果遇到编译期 nil 不兼容，把 nil 改成对应类型的 0 值继续调。

k8s 的 RESTful 架构靠 go-restful 这类第三方模块落地。它有三个必须分清的对象：Route 对应一个请求和一个处理函数；Webservice 由多个 Route 组成；Container 由多个 Webservice 组成。原文给的官方 demo 里，ws.Route(ws.GET("/hello").To(hello))是往ws里塞 Route，restful.Add(ws)或container2.Add(ws2)才是把 Webservice 挂到 Container。Route 对不上时，第一步不是怀疑模型，而是确认你看的是 Route 的构造、Webservice 的挂载，还是 Container 的最终路由表。

1.2 从 main 到 NewAPIServerHandler 的调用链

kube-apiserver 的入口在cmd/kube-apiserver/app的 main。它先app.NewAPIServerCommand()创建 cobra command，然后把command.Execute()作为总入口。ExecuteC里大部分是参数标准化、help/version 处理，真正进入Run后，链路如下：

cmd/kube-apiserver/app main -> app.NewAPIServerCommand() -> command.Execute() -> Run() -> CreateServerChain() -> CreateKubeAPIServer() -> completedConfig.New() -> c.GenericConfig.New() -> NewAPIServerHandler()

CreateServerChain里会先创建 node dialer、CreateKubeAPIServerConfig，再创建apiExtensionsServer，然后才进入CreateKubeAPIServer。到CreateKubeAPIServer时，kubeAPIServerConfig.Complete(versionedInformers).New(delegateAPIServer)会创建 master 对应的 server 结构，并在completedConfig.New里调用c.GenericConfig.New("kube-apiserver", delegationTarget)。

真正创建 go-restful Container 的地方在NewAPIServerHandler。这里gorestfulContainer := restful.NewContainer()，设置ServeMux、CurlyRouter、RecoverHandler、ServiceErrorHandler，然后返回APIServerHandler，里面带FullHandlerChain、GoRestfulContainer、NonGoRestfulMux、Director。如果你在源码里搜restful.NewContainer()，只看到这里，就说明 kube-apiserver 并没有用 go-restful 的默认全局 container，而是自己维护了一个 container。

1.3 为什么这条路最容易把“未注册”看成“通道不行”

Director决定一个 HTTP 请求是进goRestfulContainer还是nonGoRestfulMux。如果资源路由确实没进 container 的 route 表，请求就会落到 NonGoRestfulMux 的 404，或者被 discovery 的 webservice 抢走匹配。很多人在调试时看到 POST/api/v1/namespaces/default/resourcequotas返回 404，第一反应是“Codex 走通道读源码是不是读错了”。其实通道只负责把请求转发给模型，源码里的ws.Route(route)有没有执行、container.Add(ws)有没有加对 container，Codex 不会替你改变。

所以用 Codex 排查前，先把问题描述成源码事实：kube-apiserver v1.10，resource quota 的 POST route 在ws中看不到，或者container注册的 webservice 数量不对。然后贴NewAPIServerHandler、InstallLegacyAPIGroup、InstallREST三段片段。这样 Codex 才能沿着container -> webservice -> route的层次帮你对齐，而不是凭空猜一个“通道不兼容”。

2. InstallLegacyAPIGroup 到 APIInstaller.Install：WebService 和 discovery 谁先挂

2.1 installAPIResources 遍历 GroupVersion

completedConfig.New里会判断apiv1.SchemeGroupVersion是否启用，然后构造LegacyRESTStorageProvider，调用m.InstallLegacyAPI。InstallLegacyAPI里先通过legacyRESTStorageProvider.NewLegacyRESTStorage(restOptionsGetter)得到legacyRESTStorage和apiGroupInfo。apiGroupInfo里最重要的字段是VersionedResourcesStorageMap，它是一个两层 map：第一层 key 是版本号，core 组当前是v1；第二层 key 是资源名，value 是该资源对应的 storage。resource quota 会在这里以resourcequotas为 key 对应到resourceQuotaStorage。

接着调用m.GenericAPIServer.InstallLegacyAPIGroup。这个方法先检查apiPrefix是否在允许的 legacy 前缀里，再调用s.installAPIResources(apiPrefix, apiGroupInfo)。installAPIResources会遍历apiGroupInfo.GroupMeta.GroupVersions，如果某个版本没有任何 storage，就跳过并打 warning。对启用的版本，它会用s.getAPIGroupVersion把apiGroupInfo重新封装成apiGroupVersion，然后执行apiGroupVersion.InstallREST(s.Handler.GoRestfulContainer)。

这里 Route 对不上的第一层原因就出现了：InstallREST接收的是s.Handler.GoRestfulContainer，也就是前面NewAPIServerHandler创建的那个 container。如果你打断点时看的是restful.DefaultContainer，那当然对不上。

2.2 InstallREST 里 ws 的创建、discovery 挂载和 container.Add

APIGroupVersion.InstallREST的关键动作是拼 prefix：prefix := path.Join(g.Root, g.GroupVersion.Group, g.GroupVersion.Version)。core 组 group 为空，version 是 v1，所以最终前缀通常是/api/v1。然后构造APIInstaller{ group:g, prefix:prefix, ... }，调用installer.Install()。

Install()返回apiResources, ws, registrationErrors。此时ws已经由APIInstaller.newWebService()创建，并且ws.Path(prefix)会把/api/v1挂到 webservice 上。然后InstallREST做两件容易看错顺序的事：先versionDiscoveryHandler.AddToWebService(ws)，把版本发现用的 route 加到同一个ws；再container.Add(ws)，把这个 webservice 挂进 container。

注意，这里并不是“discovery 先覆盖了资源路由”，而是同一个 webservice 里既有 discovery route，也有资源 route。资源 route 是在更早的installer.Install()内部由registerResourceHandlers加进去的。如果你在container.Add(ws)处才看ws，应该已经能看到资源 route 和 discovery route。如果看不到 POST/namespaces/{namespace}/resourcequotas，问题不在container.Add，而在registerResourceHandlers的某一步没有把 route 追加进ws。

2.3 用 Codex 对照 container/webservice 片段时的验收点

把下面这类片段贴给 Codex 时，让它只回答“调用顺序”和“对象归属”，不要让它扩写成 k8s 整体架构：

apiResources, ws, registrationErrors := installer.Install() versionDiscoveryHandler.AddToWebService(ws) container.Add(ws)

你要 Codex 检查的验收点有四个。第一，ws是不是APIInstaller.newWebService()创建的那个，而不是另外 new 出来的。第二，ws.Path(prefix)是否已经设置，prefix 是否等于你请求路径的前缀/api/v1。第三，registerResourceHandlers里ws.Route(route)的循环是否在Install()返回前执行。第四，container.Add(ws)加的是不是s.Handler.GoRestfulContainer。这四点对齐后，再看 POST route 缺失才有意义。

3. registerResourceHandlers 的 POST 分支：resourcequotas 的 Route 在哪一步进 ws.Route

3.1 storage 接口断言决定 actions 里有没有 POST

APIInstaller.Install里会先ws := a.newWebService()，然后取出a.group.Storage的所有 key，排序后逐个调用a.registerResourceHandlers(path, a.group.Storage[path], ws)。resource quota 的 path 就是resourcequotas，storage 就是前面NewLegacyRESTStorage生成的resourceQuotaStorage。

进入registerResourceHandlers后，第一组关键代码是接口断言：creater, isCreater := storage.(rest.Creater)、namedCreater, isNamedCreater := storage.(rest.NamedCreater)、lister, isLister := storage.(rest.Lister)、getter, isGetter := storage.(rest.Getter)等等。resource quota 创建时不能带 name，所以它走的是restfulCreateResource，对应rest.Creater。如果isCreater是 false，后面的 actions 数组就不会加入 POST，自然也不会有ws.POST(action.Path)。这是 Route 对不上时最该先看的断言。

3.2 namespace scope 下的 path 模板

k8s 资源分 root scope 和 namespace scope。resource quota 是有 namespace 区分的资源，所以 switch 会进入meta.RESTScopeNameNamespace。这里会构造：

namespaceParam := ws.PathParameter(scope.ArgumentName(), scope.ParamDescription()).DataType("string") namespacedPath := scope.ParamName() + "/{" + scope.ArgumentName() + "}/" + resource resourcePath := namespacedPath itemPath := namespacedPath + "/{name}"

其中scope.ParamName()通常是namespaces，scope.ArgumentName()是namespace。所以 collection 路径会变成namespaces/{namespace}/resourcequotas，item 路径会变成namespaces/{namespace}/resourcequotas/{name}。再配合ws.Path(prefix)的/api/v1，最终请求路径就是/api/v1/namespaces/{namespace}/resourcequotas。

如果 Codex 只说“POST 路由应该在 resourcequotas”，但没有把 prefix 和 namespace 模板拼起来，就很容易误判。你贴片段时要包含namespacedPath、resourcePath、itemPath这三行，以及ws.Path(prefix)的设置点。

3.3 ws.POST 只是构造，ws.Route(route) 才算注册

actions 数组会通过appendIf加入各种操作。POST 这一项大致是：

actions = appendIf(actions, action{"POST", resourcePath, resourceParams, namer, false}, isCreater)

随后代码遍历 actions，按 verb 分支构造 route。POST 分支里：

handler = restfulCreateResource(creater, reqScope, a.group.Typer, admit) handler = metrics.InstrumentRouteFunc(action.Verb, resource, subresource, requestScope, handler) route := ws.POST(action.Path).To(handler). Doc(doc). Operation("create" + namespaced + kind + operationSuffix). Returns(http.StatusCreated, "Created", producedObject) routes = append(routes, route)

注意，ws.POST(action.Path).To(handler)返回的是一个*restful.RouteBuilder或 route 对象，此时它只是被追加到局部变量routes数组里，还没有进ws的 route 表。所有 action 处理完后，代码才会统一循环：

for _, route := range routes { route.Metadata(ROUTE_META_GVK, metav1.GroupVersionKind{...}) route.Metadata(ROUTE_META_ACTION, strings.ToLower(action.Verb)) ws.Route(route) }

所以你在 POST case 里单步时看ws，POST route 不在是正常的；要走到最后ws.Route(route)循环结束，才是真正注册。这个时机差是 k8s 源码里最经典的“Route 对不上”错觉。

3.4 CurlyRouter 与 prefix 拼接的核对方法

NewAPIServerHandler里设置的是gorestfulContainer.Router(restful.CurlyRouter{})。CurlyRouter 对/namespaces/{namespace}/resourcequotas这类模板路径有匹配规则。你要核对的是：APIInstaller.newWebService()里ws.Path(prefix)设置的 prefix 是否和你实际请求的/api/v1一致；registerResourceHandlers生成的action.Path是否是不带 prefix 的相对路径；两者拼起来是否正好是请求路径。

一个实用的本地调试动作：在registerResourceHandlers的 POST 分支打断点，看action.Path；在for _, route := range routes的ws.Route(route)处打断点，看ws里 route 数量；在InstallREST的container.Add(ws)处看 container 的RegisteredWebServices()。这三个点连起来，Route 到底在哪一层丢失就清楚了。Codex 能做的是根据你贴的这三段代码解释变量含义，不能替你打断点。

4. Codex 接入 TaoToken 通道：~/.codex/config.toml 怎么填才能读源码

4.1 创建 Key 和模型 ID 的取法

前面说的排障请求要发给 Codex，得先让 Codex 能正常调用模型。打开 TaoToken 注册账号，在控制台创建 API Key，复制后先别写进代码，用占位符YOUR_API_KEY代替。模型 ID 不要凭记忆写gpt-5或随便加日期后缀，去模型广场看当时上架列表，选一个适合代码阅读和长上下文分析的模型 ID，再填到 Codex 配置里。

接口 Base URL 是https://taotoken.net/api，末尾不要加/v1。官网落地页https://taotoken.net/?utm_source=taotoken_aicg_blog_end只用于注册、创建 Key、看模型广场、看用量，不要把它填进 Codex 的base_url。这两个地址各管各的，混用会导致 404 或 HTML 解析错误。

4.2 config.toml 与环境变量

Codex 的配置文件在~/.codex/config.toml。一个可复制的写法如下：

model = "YOUR_MODEL_ID" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"

model写你在模型广场选定的模型 ID。model_provider指向下面的model_providers.taotoken。base_url就是https://taotoken.net/api，不要加 UTM，也不要加/v1。env_key指定 Codex 从哪个环境变量读 Key。然后在 shell 里导出：

export TAOTOKEN_API_KEY=YOUR_API_KEY

Windows PowerShell 可以写：

$env:TAOTOKEN_API_KEY="YOUR_API_KEY"

保存后启动codex，先发一条简单消息，让它回答“你是否能读到当前会话”。这一步只验证通道和模型 ID，不验证源码结论。通道通了以后，再把 k8s 源码片段贴进去。

4.3 给 Codex 的提问模板和边界

贴源码时不要只丢一句“Route 对不上怎么办”。更有效的模板是：

现象：kube-apiserver v1.10，resourcequota 的 POST /api/v1/namespaces/{namespace}/resourcequotas 在调试时看不到 route，或请求返回 404。 我贴三段： 1. APIInstaller.Install 里创建 ws、遍历 storage、调用 registerResourceHandlers 的代码； 2. registerResourceHandlers 中 namespace scope 分支和 POST action 的代码； 3. InstallREST 里 versionDiscoveryHandler.AddToWebService(ws) 和 container.Add(ws) 的顺序。 请只根据这些代码说明：POST route 从 ws.POST(...) 到 ws.Route(route) 的追加时机，以及 container.Add(ws) 与 discovery 挂载的先后关系。 不要猜版本外实现，不要给修复补丁，只列核对点。

同时把边界说清楚：Codex 只生成解释、对照代码和 SQL 类文本时也一样，真正编译 kube-apiserver、启动 etcd、打断点查看变量，都由你在本地执行。TaoToken 通道只负责把这次请求转发出去，不会替 Codex 判断源码，也不应该把生产库或生产机器交给模型直接操作。

5. 从 registerResourceHandlers 到 etcd：resourcequota 的 storage 何时初始化

5.1 NewLegacyRESTStorage 到 resourcequotastore.NewREST

Route 对上了以后，问题 2 和问题 3 会接着出现：handler 怎么创建 resource quota？对象怎么落到 etcd？回到NewLegacyRESTStorage，找到 resource quota 的部分，它会调用resourcequotastore.NewREST(restOptionsGetter)，返回resourceQuotaStorage和resourceQuotaStatusStorage。

NewREST里创建的是genericregistry.Store，关键字段包括NewFunc、NewListFunc、DefaultQualifiedResource、CreateStrategy、UpdateStrategy、DeleteStrategy、ReturnDeletedObject。其中NewFunc返回空的api.ResourceQuota{}，NewListFunc返回api.ResourceQuotaList{}。然后构造generic.StoreOptions{RESTOptions: optsGetter}，调用store.CompleteWithOptions(options)。这一步完成后，Store才拥有真正的e.Storage。

5.2 CompleteWithOptions 里 e.Storage 的真实来源

CompleteWithOptions会做很多检查：DefaultQualifiedResource是否为空，NewFunc、NewListFunc是否设置，KeyRootFunc和KeyFunc是否成对，CreateStrategy或UpdateStrategy是否设置。对 namespace scope 的 resource quota，它会设置KeyRootFunc为NamespaceKeyRootFunc，设置KeyFunc为NamespaceKeyFunc，这样资源在 etcd 里的 key 会带 namespace。

最关键的一段是：

if e.Storage == nil { e.Storage, e.DestroyFunc = opts.Decorator( opts.StorageConfig, e.NewFunc(), prefix, keyFunc, e.NewListFunc, attrFunc, triggerFunc, ) }

opts来自SimpleRestOptionsFactory.GetRESTOptions。如果启用了 watch cache，ret.Decorator会被设为genericregistry.StorageWithCacher(cacheSize)；否则是generic.UndecoratedStorage。k8s 默认通常启用缓存，所以e.Storage实际是一个 Cacher 包装层。

5.3 Cacher.Create 到 etcd：问题 2 和问题 3 的落点

StorageWithCacher里先s, d := generic.NewRawStorage(storageConfig)创建原始存储后端，再用storage.NewCacherFromConfig包装：

cacherConfig := storage.CacherConfig{ Storage: s, Versioner: etcdstorage.APIObjectVersioner{}, Type: objectType, ResourcePrefix: resourcePrefix, KeyFunc: keyFunc, NewListFunc: newListFunc, GetAttrsFunc: getAttrsFunc, TriggerPublisherFunc: triggerFunc, Codec: storageConfig.Codec, } cacher := storage.NewCacherFromConfig(cacherConfig)

Cacher实现了storage.Interface，它的Create方法最终会调用c.storage.Create(ctx, key, obj, out, ttl)，其中c.storage就是前面创建出来的原始存储。再往上追，POST 请求进入restfulCreateResource后，会走到handlers.CreateResource，再到createHandler。createHandler里先r.New()创建空对象用于反序列化，然后解码请求 body，做 admission，最后r.Create(ctx, name, obj, ...)。这里的r就是resourceQuotaStorage对应的Store，Store.Create里再调用e.Storage.Create。所以问题 2 的 handler 创建在registerResourceHandlers，问题 3 的 etcd 落盘在Cacher.Create到 raw storage 这一段。

要让 Codex 帮你核对这条链，贴Store.New、Store.Create、CompleteWithOptions的e.Storage初始化、Cacher.Create四个点即可。至于 etcd 里实际 key 长什么样，用你本地的etcdctl查，把输出贴回对话，不要让模型直接连接生产 etcd。

6. 验证、排障与下一步：让 Codex 的结论回到本地断点

6.1 验证 Codex 通道和 Route 注册

配置完~/.codex/config.toml后，先启动codex发一条普通消息，确认没有 401，也没有模型不存在的报错。然后打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=k8s_route_verify 看一眼这次调用有没有正常记上。通道没问题后，回到 k8s 源码里打断点：在APIInstaller.Install里观察paths排序后resourcequotas的位置；在registerResourceHandlers的 POST 分支看isCreater是否 true；在最后的ws.Route(route)循环看 route 数量；在InstallREST的container.Add(ws)看 webservice 数量。

如果你在 POST case 里看到ws没有 route，不要慌，那只是构造阶段。如果你在ws.Route(route)循环后仍然没有 POST，才需要检查actions是否包含 POST、action.Path是否被覆盖、ws.Path(prefix)是否设置正确。验证的顺序应该是先本地断点，再让 Codex 解释变量关系，而不是直接把报错丢给模型让它猜。

6.2 Route 对不上的排查顺序

第一，确认你看的 container 是s.Handler.GoRestfulContainer，不是 go-restful 默认 container。第二，确认installer.Install()返回的ws和container.Add(ws)是同一个 webservice。第三，确认registerResourceHandlers里isCreater为 true，POST 被appendIf加入 actions。第四，确认ws.POST(action.Path)构造出的 route 被 append 到routes，并且最后执行了ws.Route(route)。第五，确认CurlyRouter匹配的最终路径是/api/v1/namespaces/{namespace}/resourcequotas，而不是少了/api/v1或多了/v1。

Codex 配置侧也要排一次：报 401 就检查TAOTOKEN_API_KEY是否导出成功，env_key是否写错；报模型不存在就回模型广场核对模型 ID；如果请求路径异常，再检查base_url是否误写成官网落地页，或者给https://taotoken.net/api后面加了/v1。这些错误和源码里的 Route 对不上是两回事，不要混在一起查。

6.3 下一步：把这次调用记到控制台

配通之后，可以先在 TaoToken 模型对话 里用同一把 Key 发一条测试消息，确认模型 ID 和 Base URL 没填错。若你后面要长期用 Codex 读 k8s、Kubernetes controller、etcd storage 这类大段源码，可以打开 Coding Plan 看套餐是否够用。Key 在 控制台 API Keys 创建，官网入口仍然是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 。把这次APIInstaller.Install、registerResourceHandlers、container.Add(ws)三个断点的结果整理成一段描述，再让 Codex 对照，下一轮就不用从“Route 对不上”重新猜起了。