Headlamp 以子路径 base-url 部署运行指南开发、静态构建、Docker 与 Kubernetes 全场景配置【免费下载链接】headlampA Kubernetes web UI that is fully-featured, user-friendly and extensible项目地址: https://gitcode.com/GitHub_Trending/he/headlampHeadlamp 默认部署在域名的根路径下但通过-base-url参数可以让它在类似/headlamp的子路径下运行适合与反向代理、其他 Web 应用共享同一域名或同一端口的场景。本文以仓库内 base-url.md 为核心结合后端 Go 源码与前端 Vite 构建配置系统讲解 base-url 的适用场景、四种部署模式下的完整配置方法、底层实现原理及常见的同源冲突风险帮助你在一台服务器上安全、正确地托管 Headlamp。base-url 是什么根路径与子路径的差别默认情况下 Headlamp 运行在域名的根路径例如根路径模式https://headlamp.example.com/base-url 模式https://example.com/headlamp/两种模式在功能上等价差别仅在于 Web 资源页面、API、插件静态文件所挂载的 URL 前缀。启用 base-url 后后端服务器会把所有路由挂载到该前缀之下同时前端构建产物中的所有静态资源引用也会被改写为带前缀的相对路径从而保证在子路径下页面能正确加载。在仓库中该能力由后端命令行参数-base-url提供。其定义位于 backend/pkg/config/config.go核心校验逻辑要求该参数必须以/开头否则启动时报错base-url needs to start with a / or be empty见 backend/pkg/config/config.go。这一设计保证了 base-url 一定是合法的 URL 路径前缀例如-base-url /headlamp。同域多应用警告使用 base-url 前必须评估的风险将多个 Web 应用托管在**同一源same origin即相同协议 域名 端口**下彼此之间会存在潜在冲突每个应用都能读取对方存储在同源下的 Cookie、LocalStorage 等数据每个应用都能以该源的权限向对方发起请求因此同域托管的所有应用必须一起测试、相互信任并且应为每个应用规划兼容的 Content-Security-PolicyCSP防止某一方的脚本策略影响另一方。如果无法满足上述条件例如另一方是不可信或不受你控制的第三方应用官方建议让 Headlamp 独占一个源独立域名或独立端口不要使用-base-url选项。也就是说base-url 是共享域名场景下的便利方案而不是默认推荐项。前端如何感知 base-urlPUBLIC_URL 与 headlampBaseUrlbase-url 不只是后端的事前端构建也必须知道最终挂载的子路径。Headlamp 前端通过PUBLIC_URL环境变量把路径传给 Vite 构建工具见 frontend/vite.config.ts 的base: process.env.PUBLIC_URL同时在运行时通过getBaseUrl()统一读取若运行在 Electron 桌面环境直接返回空字符串桌面应用无子路径概念见 frontend/src/helpers/getBaseUrl.ts否则优先读取window.headlampBaseUrl由后端在启动时写入 index.html再退回读取import.meta.env.PUBLIC_URL若值为./、.或/则归一化为空字符串即根路径见 frontend/src/helpers/getBaseUrl.ts。window.headlampBaseUrl这个全局变量的占位符存在于 frontend/index.html构建后形如headlampBaseUrl __baseUrl__;。后端启动时若指定了-base-url会用实际前缀替换该占位符详见下文底层实现原理这就解释了为什么前端构建时传PUBLIC_URL、后端启动时传-base-url两者必须保持一致。方式一开发模式Dev mode开发调试时需要同时启动后端与前端开发服务器并分别指定 base-url./backend/headlamp-server -dev -base-url /headlamp PUBLIC_URL/headlamp npm run frontend:start第一条命令启动 Go 后端headlamp-server-dev开启开发模式-base-url /headlamp让后端 API 与页面挂在子路径下第二条命令在前端目录frontend/启动 Vite 开发服务器PUBLIC_URL/headlamp使开发服务器以该路径为资源基址。Vite 开发服务器默认监听 3000 端口见 frontend/vite.config.ts并已配置了指向后端的代理。启动完成后在浏览器访问http://localhost:3000/headlamp/注意路径末尾的斜杠——访问/headlamp不带斜杠时部分静态资源相对路径可能解析异常因此文档与后续探针配置中均强调保留尾斜杠。方式二静态构建模式Static build mode生产形态之一是将前端构建为静态文件由后端直接托管npm run frontend:build ./backend/headlamp-server -dev -base-url /headlamp -html-static-dir frontend/build第一步执行前端构建。仓库中frontend:build对应的脚本为cross-env PUBLIC_URL./ ... vite build见 frontend/package.json即构建时默认使用相对路径./这样静态文件本身不绑定具体前缀第二步启动后端并指定-html-static-dir frontend/build对应配置项StaticDir见 backend/pkg/config/config.go后端在启动时会重写 index.html 中所有资源引用注入headlampBaseUrl与资源前缀该模式下后端默认监听 4466 端口-dev模式下不使用 TLS 的默认端口。随后访问http://localhost:4466/headlamp/方式三Docker 模式使用官方容器镜像时只需在docker run命令末尾追加--base-url /headlamp参数注意这里多了一个短横线Docker 参数风格为双横线docker run --name headlamp -p 4466:4466 \ ghcr.io/headlamp-k8s/headlamp:latest \ --base-url /headlamp容器内 Headlamp 进程即会收到与裸机启动等价的-base-url参数。若同时使用 Nginx、Traefik 等反向代理将/headlamp/转发到该容器还需在代理层保证X-Forwarded-Proto等头正确传递后端会据此推断请求协议详见下文反向代理与 OIDC 注意事项。方式四Kubernetes 部署手动修改 Deployment在 Kubernetes 中你可以直接修改 Deployment 文件为容器 args 追加-base-url并同步更新存活探针livenessProbe与就绪探针readinessProbe的探测路径使其匹配 base-urlargs: - -in-cluster - -plugins-dir/headlamp/plugins - -base-url/headlamp livenessProbe: httpGet: path: /headlamp/ # note the trailing slash readinessProbe: httpGet: path: /headlamp/两个要点args中-in-cluster让 Headlamp 使用集群内 ServiceAccount 访问 Kubernetes API探针路径必须带尾斜杠/headlamp/而非/headlamp否则探针可能因资源重定向而判定不健康。仓库内的部署参考文件 kubernetes-headlamp.yaml 可作为基线清单在此基础上调整。使用官方 Helm Chart仓库自带的 Helm Chartcharts/headlamp已内置对 base-url 的支持在 values 中设置config.baseURL即可见 charts/headlamp/values.yaml渲染 Deployment 时会自动生成-base-url{{ . }}参数见 charts/headlamp/templates/deployment.yamlconfig: inCluster: true baseURL: /headlamp底层实现原理路由挂载与 index.html 重写base-url 的落地依赖后端两个环节的协同均可在源码中找到直接证据。环节一路由前缀挂载后端在初始化 HTTP 路由时backend/cmd/headlamp.go根据config.BaseURL决定路由器形态var r *mux.Router if config.BaseURL { r mux.NewRouter() } else { baseRoute : mux.NewRouter() r baseRoute.PathPrefix(config.BaseURL).Subrouter() }当设置了 base-url 时所有 API 路由如/clusters/{clusterName}/portforward、/metrics、插件路由等都被挂载到PathPrefix(config.BaseURL)的子路由器下外部请求必须携带该前缀才能命中。环节二index.html 资源引用重写指定了-html-static-dir时后端启动会调用rewriteIndexHTMLbackend/cmd/headlamp.go对静态目录中的index.html做三类替换核心逻辑在makeBaseURLReplacementsbackend/cmd/headlamp.go将占位符headlampBaseUrl __baseUrl__替换为headlampBaseUrl /headlampbase-url 为空时替换为/避免之前运行过其他 base-url 时残留旧值将资源引用中的./前缀替换为${baseURL}/将 CSS 中不带./的url(...)引用统一插入${baseURL}/前缀。同时后端会把未改写的原始index.html备份为index.baseUrl.html每次启动都从这份原始副本重新替换保证重复启动或切换 base-url不会叠加污染。这一行为在 backend/cmd/headlamp_test.go 中有对应的单元测试覆盖包括空 base URL 替换为/与自定义 base URL 注入两种用例。OIDC 回调地址也会带上 base-url若配置了 OIDC 登录后端在动态生成回调地址时会自动拼接 base-url见 backend/cmd/headlamp.go将config.BaseURL去除首尾斜杠后追加到 Host 之后得到形如https://example.com/headlamp/oidc-callback的地址。这意味着启用 OIDC 时IdP 侧配置的回调 URL 必须包含 base-url 前缀否则回调将无法命中。反向代理与 OIDC 注意事项综合上述实现使用 base-url 并配合反向代理时建议检查以下几点路径透传代理需将/headlamp/前缀后的请求原样转发给 Headlamp不可剥离前缀否则后端路由无法匹配协议头后端在无 TLS 场景下会优先读取X-Forwarded-Proto推断请求协议backend/cmd/headlamp.go请确保代理正确设置该头否则 OIDC 回调可能错误地生成http地址CSP如前文所述同域托管多应用时需为各应用规划兼容的 Content-Security-Policy探针与入口Kubernetes 场景下 Ingress 的路径规则、Service 探针路径都要与 base-url 对齐并保留尾斜杠。验证配置是否生效完成部署后可通过以下方式验证 base-url 是否生效浏览器访问域名/headlamp/页面应正常渲染而非 404打开开发者工具查看页面源码确认headlampBaseUrl变量值等于配置的前缀如/headlamp检查静态资源JS、CSS、图片的请求 URL 均带/headlamp/前缀在 base-url 模式下访问 API如/headlamp/apis相关端点应返回正常 JSON而非重定向或 404。总结Headlamp 的 base-url 能力由后端-base-url参数与前端PUBLIC_URL环境变量共同构成二者必须保持一致后端负责路由挂载与 index.html 资源改写前端负责以该前缀作为资源基址。开发、静态构建、Docker 与 Kubernetes 四种模式下的配置方式均已在上文给出可直接复用的命令与清单。部署前请务必评估同源多应用的安全风险若无法保证互信与兼容的 CSP更稳妥的选择是让 Headlamp 独占域名或端口。【免费下载链接】headlampA Kubernetes web UI that is fully-featured, user-friendly and extensible项目地址: https://gitcode.com/GitHub_Trending/he/headlamp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考