企业官网建设流程全解析

• 后端
• 微服务

本文基于 JupyterHub 官方文档「Running proxy separately from the hub」，系统讲解如何将默认的 configurable-http-proxy（CHP）从 Hub 进程中解耦，作为独立服务运行。读完后，你可以完成cleanup_servers、should_start、auth_token、api_url四个关键配置的落地，正确拼装 CHP 独立启动命令行，并借助本仓库源码理解 Hub 在启动与关闭时如何与外部 Proxy 协作。

背景：为什么要把 Proxy 独立出来

在 JupyterHub 的架构中，用户浏览器直接连接的对象是 Proxy（默认实现为 configurable-http-proxy，简称 CHP）。Proxy 负责两类转发：把用户重定向到 Hub（用于登录和管理服务器），或转发到用户各自的 single-user server。这意味着只要 Proxy 存活，已有服务器的访问就不会中断——即使 Hub 本身重启或宕机。

初次配置 Hub 时你可能没有意识到这一点，因为默认情况下 Proxy 由 Hub 作为子进程自动管理。这对快速上手乃至大多数场景都很友好，但有一个代价：每次重启 Hub，所有用户连接都会随之重启。而把 Proxy 拆分为独立服务后，你就可以在不中断已运行用户的情况下重新配置 Hub，只有正在等待 notebook server 启动的用户会受到短暂影响。

本指南针对默认 Proxy 即 CHP 的部署。如果你使用的是其他 Proxy（例如基于 Kubernetes ingress 的 Traefik 方案），本文的操作步骤大概率不适用——自定义 Proxy 的实现方式可参考仓库内 docs/source/howto/proxy.md。

Hub 侧的四个配置项

在 Hub 的配置文件（jupyterhub_config.py）中需要设置以下四项：

1.c.JupyterHub.cleanup_servers = False

告诉 Hub 在重启时不要停止用户的 single-user server。这一点即使你不单独运行 Proxy 也很有用。

从源码看，该配置定义在 jupyterhub/app.py，是一个默认值为True的Booltrait，官方帮助文本说明：关闭它可以在拆除 Hub 的同时保留 single-user server 继续运行；Hub 能够从数据库状态中恢复。具体执行逻辑在 jupyterhub/app.py 的cleanup()中：当cleanup_servers为True时，Hub 关闭会遍历所有活跃 spawner 并逐一请求终止；为False时则仅记录 “Leaving single-user servers running”。

2.c.ConfigurableHTTPProxy.should_start = False

告诉 Hub 不要自己启动 Proxy（因为你会自己启动它）。

该 trait 定义在 jupyterhub/proxy.py，默认值为True，帮助文本明确写道：“If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.” 也就是说，它正是为 systemd、Docker 等外部服务管理器设计的。

3.c.ConfigurableHTTPProxy.auth_token = "CONFIGPROXY_AUTH_TOKEN"

设置为一个用于认证 Hub 与 Proxy 之间通信的 token。

注意源码中该 token 的默认值行为（jupyterhub/proxy.py）：默认从环境变量CONFIGPROXY_AUTH_TOKEN读取；只有当should_start为True（即 Hub 自己拉起 Proxy）时才会在缺失时自动生成新 token。一旦你把should_start设为False，Hub 不会再生成 token，jupyterhub/proxy.py 的构造函数会直接抛出ValueError，要求必须显式提供auth_token或CONFIGPROXY_AUTH_TOKEN环境变量。所以独立部署时，必须显式配置该项。

4.c.ConfigurableHTTPProxy.api_url = 'http://localhost:8001'

设置为 Hub 连接Proxy 的 API 端点所用的 URL。

其默认值逻辑见 jupyterhub/proxy.py：默认协议为http、地址为127.0.0.1:8001；若启用了internal_ssl，协议会自动变为https。当你单独管理 Proxy 时，应把api_url显式指向 Proxy API 实际监听的位置。

单独启动 Proxy 的命令与参数

你需要配置一个独立服务（例如 systemd unit，或另一个 Docker 容器）来拉起 Proxy。文档给出的示例启动命令为：

$ configurable-http-proxy --ip=127.0.0.1 --port=8000 --api-ip=127.0.0.1 --api-port=8001 --default-target=http://localhost:8081 --error-target=http://localhost:8081/hub/error

具体如何包装成服务（systemd、docker 等）超出本指南范围。需要牢记的一点是：CHP 没有配置文件，所有配置都通过命令行参数和环境变量完成。

各参数与 Hub 配置的对应关系如下：

最后一项是关键约束：必须定义环境变量CONFIGPROXY_AUTH_TOKEN，且其值与 Hub 配置里c.ConfigurableHTTPProxy.auth_token给出的 token 完全一致。

源码印证：Hub 自己启动 Proxy 时用的正是这些参数

对照 jupyterhub/proxy.py 的start()方法可以看到，当 Hub 管理 Proxy 时，它拼出的命令行与上述独立部署命令是同一套语义：

• 从public_url解析出--ip/--port（或 Unix socket 时为--socket）；
• 从api_url解析出--api-ip/--api-port（或--api-socket）；
• 追加--error-target（指向hub.url + '/error'）和--log-level；
• 环境变量中注入CONFIGPROXY_AUTH_TOKEN（jupyterhub/proxy.py）；
• 若启用了 host-based 路由（subdomain_host），追加--host-routing；若有ssl_key/ssl_cert，追加--ssl-key/--ssl-cert；启用internal_ssl时还会追加一整套--api-ssl-*与--client-ssl-*参数（见 jupyterhub/proxy.py）。

由此得到一个重要的运维结论：原本写在 Hub 配置里、由 Hub 传递给 Proxy 的选项（尤其是 SSL 相关选项），在 Proxy 独立运行时必须移到 Proxy 自身的启动命令中配置。独立部署时还应查阅 CHP 自身的完整选项说明，确认 SSL 等额外参数是否需要在命令行中补上。

Hub 启动时如何验证外部 Proxy 可用

Hub 启动流程中（jupyterhub/app.py）：

1. 若proxy.should_start为False，Hub 记录日志 “Not starting proxy”，完全跳过 Proxy 启动；
2. 紧接着无论 Proxy 由谁管理，Hub 都会执行await self.proxy.get_all_routes()主动拉取一次路由表，以验证与 Proxy 的 API 通信正常——注释写明这是为了避免“无法与 Proxy 通信”这类延迟暴露的故障，即在开始监听前就确认通路；
3. 之后通过check_routes()（jupyterhub/proxy.py）比对数据库中的用户/服务与 Proxy 路由表，补全缺失路由、修正 target 不一致的路由、清理过期路由。

这套对账机制正是“Proxy 独立存活、Hub 可重启”能够成立的底层保障：Hub 每次启动都会自动把自己管理的所有路由恢复到（新）Proxy 上。

Hub 关闭时的行为：它不会去停外部 Proxy

再看 jupyterhub/app.py 的cleanup()：Hub 关闭时仅在cleanup_proxy为True且proxy.should_start为True时才真正调用proxy.stop()；若是外部管理的 Proxy，Hub 只会记录 “I didn't start the proxy, I can't clean it up”。配合cleanup_servers = False，发送SIGTERM/SIGINT给 Hub 就只关闭 Hub 本身，Proxy 与用户服务器全部保持运行。

使用 Docker 镜像运行 CHP

可以直接使用 JupyterHub 官方发布的configurable-http-proxyDocker 镜像来运行独立 Proxy，例如将其作为与 Hub 容器并行的服务，并按上文命令配置监听地址、默认/错误跳转目标与CONFIGPROXY_AUTH_TOKEN环境变量。

在仓库测试代码中的验证方式

本仓库的测试为“独立 Proxy + 重启不丢状态”提供了可参照的配置范式：

• jupyterhub/tests/test_app.py 的new_hubfixture 模拟了外部管理 Proxy 的 Hub：设置ConfigurableHTTPProxy.should_start = False并显式提供auth_token = 'unused'，再执行app.initialize([])。这正是上文“should_start=False时必须提供 token”约束的测试侧印证。
• 同文件的test_resume_spawners测试（jupyterhub/tests/test_app.py）验证了cleanup_servers = False的效果：Hub 停止后原 spawner 进程仍在运行（proc.poll() is None），新 Hub 实例启动后能识别该用户服务器仍running且server不为空——即 Hub 确实“从数据库状态恢复”而不触碰正在运行的服务器。

小结

独立运行 Proxy 的核心是把“Proxy 生命周期管理”从 Hub 剥离：

1. Hub 侧设cleanup_servers = False、ConfigurableHTTPProxy.should_start = False，并显式配置auth_token与api_url；
2. 用 systemd/Docker 等外部服务管理 CHP，命令行参数与 Hub 配置一一对应（API 地址对api_url，用户监听地址对--ip/--port，跳转目标指向 Hub，token 两侧一致）；
3. 原本由 Hub 代管的 SSL 等 CHP 选项需要迁移到 Proxy 自身的启动配置中；
4. Hub 重启后依靠启动时的get_all_routes()连通性检查与check_routes()路由对账自动恢复全部路由，实现“只影响等待启动的用户、不中断已运行的用户”的目标。

• 后端
• 微服务