一台自托管 nginx 上往往挤着官网、GitLab、Grafana 好几个服务域名和证书都是现成的谁都想搭这趟车。偏偏 RustFS 的控制台默认挂在 9001 端口的根路径上要让人访问它就得再开一个端口、再签一张证书或者为它单买一个子域名。这篇文章讲的是怎么用一个环境变量把控制台挪进主域名的子路径比如https://ops.example.com/console/配上十几行 nginx 配置就完事。RustFS 侧的真实参数名、默认值和校验规则都是从仓库源码和 PR diff 里核出来的文末给了出处nginx 侧是通用配置任何反代都适用。三种挂法摆在一起比把控制台交给用户访问常见就三条路成本差得不少。端口直暴最省事9001 开放出去直接访问。代价是这个端口要单独进防火墙策略、单独做访问控制URL 里还带着一个非标准端口贴到工单和文档里都不体面公司网络出口一收紧九千多的端口段经常是第一批被封的。子域名干净console.example.com一指就完事。但 DNS 要加记录证书要么续期时多带一个域名要么直接上泛域名证书内部没有自动化签发流程的团队每新增一个服务都要把这套流程走一遍。服务一多子域名就成了纯粹的重复劳动。子路径是复用度最高的主域名的证书、DNS、WAF 策略全部照用但前提是放行规则里把/console/这条前缀带上别让 WAF 把控制台接口拦在门外浏览器视角还是同源不牵扯跨域。它唯一的门槛在后端——服务自己得支持挂在任意路径下跑前端资产引用、登录跳转、API 路径都要跟着前缀走。这恰恰是很多自托管服务的短板也是 RustFS 这次补上的那块。顺带一提子路径同源之后跨域问题基本消失。RustFS 侧本来就有RUSTFS_CONSOLE_CORS_ALLOWED_ORIGINS这个控制台 CORS 开关默认*走子路径部署的话这个配置大概率一辈子不用碰。Cookie 也是同理子域名方案下登录态的 Cookie 属于console.example.com主站拿不到也管不着子路径方案下 Cookie 挂在主域名上和主站的其他服务共享同一个域好处是单点登出、统一会话这类东西好做了代价是别的服务出个安全问题时作用域也大到整个域Cookie 的Path属性值得设细一点。两个 PR 凑出来的能力1.0.0 就有了RustFS 的控制台原本是编译进二进制的静态前端URL 前缀写死为/rustfs/console想换位置只能自己动手。2026 年 9 月 10 日两个 PR 同一天进了主干#7634 把前缀改成启动时可配置新增环境变量RUSTFS_CONSOLE_PREFIX#7636 补上了编译期配置OEM 厂商可以在构建时把默认前缀嵌进二进制。这两个改动都在 1.0.0 GA2026 年 9 月 16 日之前合入我核对过 1.0.0 的 tag 里已经有RUSTFS_CONSOLE_PREFIX所以只要你跑的是正式版这个能力就在手里不存在要等 1.0.1的问题。两个变量的分工值得分开讲。RUSTFS_CONSOLE_PREFIX是运行时变量改完重启就生效绝大多数人只需要它。RUSTFS_CONSOLE_BASE_PATH是编译期变量配合前端构建参数NEXT_PUBLIC_BASE_PATH使用典型用途是二次发行版把控制台默认挂到/nuofans/console这类自有路径。运行时变量优先级更高OEM 二进制跑起来后设了RUSTFS_CONSOLE_PREFIX就会覆盖编译期默认值。反过来对一个已经编译好的普通二进制去设RUSTFS_CONSOLE_BASE_PATH是无效的PR 里写得很明白想改编译期默认值就得连前端一起重新构建普通用户直接忽略这个变量。还有一个隐藏的好处经常被忽略前缀改了之后前端资产引用是 RustFS 服务端自己改写的源码里的rewrite_console_asset会把 HTML、JS、CSS 里的旧前缀替换成新前缀外部链接保持原样。这意味着 nginx 侧不需要sub_filter之类的文本替换手段反代可以写得非常薄。很多前端应用挪路径都要靠反代层做字符串替换替换规则一多性能和正确性都是隐患RustFS 把这件事收在了服务端。RustFS 侧一行环境变量加几条硬规矩配置本身没有花样把环境变量设上、重启进程dockerrun-d\-p9000:9000-p9001:9001\-eRUSTFS_CONSOLE_PREFIX/console\rustfs/rustfsRUSTFS_CONSOLE_PREFIX/console生效后控制台就从http://host:9001/挪到了http://host:9001/console/。9001 端口本身不变RUSTFS_CONSOLE_ADDRESS只管监听地址和端口跟前缀是两回事。另外默认前缀设计成/rustfs/console而不是裸的/本身就是为了给路径留出命名空间控制台、S3 API、管理接口各走各的段互不踩脚。但这个变量在启动时校验得相当严参数填错服务直接起不来规矩列一下能省不少排障时间必须是非根绝对路径/本身不支持末尾多写一个斜杠会被自动去掉/console/等价于/console总长不超过 256 字节每段只能用 ASCII 字母、数字和-、_、.、~编码字符和点段一律拒绝不能和保留路由重叠admin、RPC、health、profiling、浏览器入口、图标这些路径都被占着撞上了启动时直接报RUSTFS_CONSOLE_PREFIX overlaps a reserved server route嵌套前缀没问题/management/console这种两层的写法是官方测试覆盖过的场景官方文档还有一句提醒别让前缀和 S3 桶路径撞车。如果你的桶恰好叫console/console这个前缀就得换比如改用/mgmt-console。校验放在启动阶段做是好事配置错误在进程起来前就暴露不会等到用户点开登录页才发现哪里不对。代价是改配置必须重启这条写在官方文档里热加载不存在。二进制部署的直接重启进程容器部署的注意docker exec进去改环境是改不动的环境变量得重建容器才能带上。nginx 侧原样转发别替它改路径RustFS 已经在/console下提供服务nginx 要做的只是把这条路径原封不动递过去。完整配置长这样server { listen 443 ssl; server_name ops.example.com; # ssl_certificate / ssl_certificate_key 按你的现有配置来 # 无斜杠入口补一刀重定向 location /console { return 301 /console/; } # 控制台注意 proxy_pass 末尾不带路径 location /console/ { proxy_pass http://127.0.0.1:9001; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 同一张证书顺手把 S3 API 也带上可选 location / { proxy_pass http://127.0.0.1:9000; proxy_set_header Host $host; client_max_body_size 0; # 大对象上传不受限 } }这套写法的核心是proxy_pass http://127.0.0.1:9001;末尾不带任何路径。nginx 的规则是proxy_pass带了 URI就会把location匹配到的前缀剥掉再拼上 URI不带 URI请求路径原样透传。RustFS 在/console下等着路径就一个字节都不能动。那几行proxy_set_header也不是仪式性代码。X-Forwarded-Proto告诉后端外面是 https少了它后端生成的跳转可能落回 http浏览器一跳就报混合内容或者连不上Host保真了后端按域名生成的东西才不会串。这四行是反代的标准动作照抄不亏。浏览器重定向这块也不用操心。RustFS 的登录跳转、OIDC 控制台回跳用的都是带前缀的相对路径前缀改成什么它就发什么nginx 不需要配proxy_redirect去改写Location头。前端资产同理前面说过服务端已经改写完了。还有一个零配置的保底方案默认前缀/rustfs/console本身就是个带命名空间的路径如果只想控制台进主域名连环境变量都可以不设nginx 直接照上面的写法转发/rustfs/console/即可。/console这种短前缀属于锦上添花不是必需项。排障时有个小技巧nginx 的访问日志里直接看$uri和后端返回状态码如果/console/的 HTML 是 200、后面的资产请求却跑到别的location上去了日志里一眼就能看出来比在浏览器里猜快得多。这几个坑提前知道第一坑两边前缀不一致页面白屏。只在 nginx 配了/console/转发、RustFS 却保持默认值是最常见的翻车方式。浏览器拿到 HTML 后会去请求/rustfs/console/_next/...之类的资产路径这个路径不在 nginx 的location /console/里落到了 S3 那条location /上返回的自然不是 JS 文件。排查方法是打开浏览器开发者工具看网络面板凡是资产请求 404 或者返回了 XML 错误文档先对一遍两边前缀。第二坑proxy_pass手滑带了个斜杠。proxy_pass http://127.0.0.1:9001/;和不带斜杠是两个行为带了斜杠意味着把/console/剥掉、以/为根转发RustFS 那边收到的全是/、/login这类裸路径全部 404。这个坑的迷惑性在于 nginx 不会报任何错nginx -t也是通过的只有打开页面才会发现。第三坑OIDC 用户容易改错回调地址。控制台前缀变更时浏览器侧的 OIDC 跳转跟着前缀走但身份提供方IdP侧的回调路径固定为/rustfs/admin/v3/oidc/callback/...官方文档明确写了这部分不变。也就是说 IdP 里已经注册好的回调 URL 别手痒去改成新前缀改了反而断。管理 API 的路径同样不受前缀影响。第四坑改了变量没重启。这个前缀是启动时读取并校验的改完配置不重启行为不会有任何变化。容器场景尤其容易犯改完 compose 文件忘了docker compose up -d重建服务还跑在旧配置上然后开始怀疑人生。上线前花两分钟过一遍curl -sI http://127.0.0.1:9001/console/预期 200 或 30x确认 RustFS 侧新前缀已生效这一步跳过的话后面查的全是 nginx 的账curl -sI https://ops.example.com/console预期 301 到/console/确认 nginx 的补刀重定向在工作浏览器打开https://ops.example.com/console/登录一次刷新页面确认会话不丢开发者工具的网络面板过滤rustfs/console不应该有任何残留请求都走新前缀才对用 S3 客户端跑一次上传下载确认同域名下的 S3 API 没被控制台配置波及。五条全绿这条链路就算交付了。想看参数的权威定义RustFS 仓库里 crates/config 的 README 有完整的校验规则PR #7634 和 #7636 记录了实现细节部署相关的端口与容器参数见官方 Docker 安装文档。