免费为Hugging Face Spaces绑定自定义域名：Cloudflare Origin Rules实战

很多人第一次用 Hugging Face Spaces 部署应用时都会盯着那串huggingface.co的默认域名发愁。做个小工具或 demo 还好真要放到作品集、个人网站或者对外展示一长串英文子域名确实显得不够专业也不方便记忆。更麻烦的是某些场景下还需要把 Spaces 应用当作正式服务来用这时候绑定一个自己的域名就成了刚需。这个问题我前前后后折腾过几次也踩过不少坑。网上关于这块的教程要么语焉不详要么只讲了付费方案要么就默认你已经懂了很多前置知识。这篇文章就专门讲清楚一件事怎么不花一分钱把 Hugging Face Spaces 上的应用绑定到自己名下任意一个域名全程用免费工具一步步操作该解释的原理说透该避的坑都标出来。这套方案适合三类人正在用 Spaces 部署 Gradio 或 Streamlit 应用、想换掉默认域名显得更专业的开发者手里有闲置域名想挂个 AI 小工具但不想买服务器的个人站长以及被网上各种收费教程忽悠过、想搞清楚免费方案到底怎么落地的新手。看完你就能自己动手搞定不用再求人。1. 内容整体设计与思路拆解先说结论实现免费绑定自定义域名核心思路是借助Cloudflare 的免费 CDN 代理 Origin Rules源站规则来转发请求配合 Hugging Face Spaces 提供的域名验证机制把你的自定义域名“挂”到 Spaces 应用前面。1.1 为什么要用 Cloudflare 而不是直接改 DNS 的 A 记录很多人第一反应是既然要绑定域名那直接把 DNS 解析到 Hugging Face 的服务器 IP 不就行了这个想法在常规场景下是对的但放到 Hugging Face Spaces 上就行不通了。Spaces 应用托管在动态负载均衡后面没有对外暴露固定 IP。也就是说你通过nslookup查到的那个 IP 随时可能变直接绑 A 记录等于把域名拴在一个随时可能失效的地址上结果就是应用时不时打不开。CNAME 记录才是正解因为 CNAME 指向的域名背后可以由平台动态解析到当前有效的服务器。但这里又冒出一个新问题CNAME 只能指向域名没法指定端口。Spaces 应用默认跑在 7860 端口如果你只想让用户访问https://yourdomain.com而不是https://yourdomain.com:7860就得有一个中间层来做端口映射和反向代理。Cloudflare 恰好免费提供了这套能力。它的橙色云代理Proxied不仅能隐藏源站、加速访问还能配合Origin Rules重写请求的 Host 头和端口让 Spaces 平台把请求正确路由到你的应用容器上。这一套组合拳打下来整个链路就通了用户访问你的域名 → Cloudflare 接收请求 → 改写目标地址为 Spaces 应用地址 → Hugging Face 返回内容 → Cloudflare 回传给你的访客。1.2 免费方案和付费方案的本质区别Hugging Face 官方其实支持自定义域名但那是在Pro 订阅每月 9 美元或企业版才提供的功能。免费用户想免费用官方功能是不可能的于是就有了 Cloudflare 这套曲线救国的办法。两者在体验上有什么区别官方方案是在 Hugging Face 后台直接填报域名平台帮你自动配置 SSL 证书整个流程非常顺滑。Cloudflare 方案则需要你自己完成域名验证、DNS 解析、SSL 模式切换、Origin Rule 配置这四个环节每一个环节出了问题最终都会表现为“域名打不开”或者“页面报错”。但从成本角度说Cloudflare 方案只要求你有一个域名.com、.xyz、.top 这种便宜的一年也就几十块配合它的免费 CDN 服务实际上是零成本实现了付费功能。对于个人开发者、学生党、独立创作者来说这笔账算下来非常划算。1.3 这套方案的适用范围与潜在限制我先把丑话说在前头Cloudflare 方案虽然免费但不是一好百好它有明确的适用边界。适合的场景个人作品集展示、工具类应用、demo 演示、小型生产服务日访问量几千以内。这些场景下Cloudflare 代理的稳定性和速度完全够用。不太适合的场景对延迟极其敏感的应用比如实时语音交互多一层代理终究会多 20-50ms 的延迟、需要 WebSocket 双向长连接且依赖特定端口的服务、以及访问量非常大的生产应用。Cloudflare 免费版对 CDN 流量有使用限制虽然通常够用但万一被刷流量Cloudflare 会暂停你的代理服务。另外还要注意一点绑定自定义域名并不会让 Spaces 应用本身的资源限制消失。免费版 Spaces 应用是 CPU 基础型休眠策略依然生效。所以如果你想让应用保持一直在线还得在 Spaces 设置里把休眠时间调到最大其实默认就是 48 小时或者用一些保活手段比如定期发起请求。2. 核心细节解析与实操要点2.1 域名验证拿到你的 Spaces 子域名身份Hugging Face Spaces 平台有一个我猜测很多人没注意过的机制每个用户或组织下的 Space 应用都会对应一个${username}.hf.space这样的内部子域名。比如你的用户名是abc创建了一个叫my-demo的 Space那么后台实际分配的地址是https://abc-my-demo.hf.space对外展示的https://huggingface.co/spaces/abc/my-demo只是个门户页面真正承载应用流量的内部域名就是hf.space下那串地址。为什么我要特意强调这个因为绑定自定义域名的关键一步就是让你的自定义域名CNAME 指向这个内部子域名。这样 Hugging Face 平台在收到请求、检查 Host 头时才能识别出“这是发给 abc-my-demo 这个 Space 的请求”从而正确路由到你的应用容器。具体的查找方式是进入你的 Space 页面 → 点右上角 “Settings” → 往下滑找到 “Domains” 或直接在页面源码里找hf.space字符串。通常情况下你就能看到类似abc-my-demo.hf.space的地址。把这一整串完整记下来后面配置 DNS 时要原样使用。2.2 DNS 解析CNAME 记录的“正确写法”拿到内部域名后去你的域名注册商或 DNS 服务商后台添加一条 CNAME 记录。这里有两个细节容易出错**第一主机记录Name填什么取决于你要用哪个子域名。**如果你希望用户访问www.example.com访问应用主机记录就填www如果希望用demo.example.com就填demo。如果你手里只有一个裸域名example.com想让用户不带前缀直接访问那就要在注册商那里处理“根域名 CNAME”的问题但有些服务商不支持根域名 CNAME这时候最省事的做法是默认用www子域名再单独配一条显性 URL 转发把根域名重定向到www那个地址。第二CNAME 的值必须是你刚找到的那个完整hf.space内部域名比如abc-my-demo.hf.space。不要填huggingface.co也不要填abc-my-demo.hf.space之外的任何东西。有人会在这里凭感觉填错导致后面怎么调都不通。配置完成后要等 DNS 生效。国内解析一般几分钟到几小时不等可以用ping或在线 DNS 查询工具验证如果www.example.com已经解析到 Cloudflare 的 IP通常是104.16.x.x、172.67.x.x这类段说明 CNAME 已生效。2.3 域名验证的第二个坑CNAME 指向后的所有权确认这里有一个非常容易被忽略的环节Hugging Face 需要确认这个自定义域名确实是你控制下的。严格来说把 CNAME 指向你的 Spaces 内部域名就等同于你在声明“这个域名归我管”。但 Hugging Face 收到 Host 头为www.example.com的请求后为了安全并不会直接把应用内容返回给你。你需要先在 Spaces 后台的Settings → Domains中把这个自定义域名登记上去。系统会给你一个验证值或者让你等一会儿状态变成Valid之后才算绑定成功。我在实际操作中发现这一步“等一会儿”的时长不太确定。快的时候一两分钟就通过了慢的时候需要十来分钟。所以做完 CNAME 配置后别急着测试域名先去 Spaces 后台把域名填上看状态变化这样后面出问题也容易定位。2.4 SSL/TLS 设置证书问题全因模式没选对Cloudflare 在默认设置下SSL/TLS 加密模式是“Flexible”灵活。这个模式的坑在于Cloudflare 到你访客的链路是 HTTPS但 Cloudflare 到你的源站也就是 Hugging Face的链路是 HTTP。虽然你的应用可能依然能打开但浏览器可能会报警告某些情况下 Spaces 前端还会报“混合内容”错误。正确操作是在 Cloudflare 后台SSL/TLS → Overview概述里把加密模式改成Full (strict)完全严格。为什么必须是 Full (strict) 而不是普通的 Full因为 Full (strict) 要求源站有有效的 SSL 证书而 Hugging Face 平台所有子域名都配置了有效的证书*.hf.space和*.huggingface.co都有通配符证书所以完全满足 strict 的要求。这样设置后从访客到 Cloudflare、从 Cloudflare 到 Hugging Face全链路都是加密 HTTPS安全性和稳定性都更有保障。这里提醒一句如果你用的是自己的域名做 CNAME而源站的证书是针对*.hf.space的那么Host Header 重写就成了必须做的一步。等下一个小节细说。2.5 不能绕过的一环Origin Rules 与 Host Header 重写这一节是整个方案的灵魂也是绝大多数教程懒得讲清楚的地方。想想看你的访客访问的是www.example.comCloudflare 替你把请求转发到abc-my-demo.hf.space。但 Hugging Face 后端收到的请求其 Host 头默认是www.example.com因为浏览器一开始发请求时填的就是这个而 Hugging Face 平台只会认*.hf.space这类 Host 头。如果直接把原始请求转发过去Hugging Face 一看 Host 不对就会返回 404 或者直接拒绝服务。Origin Rules 的作用就是在 Cloudflare 转发阶段把 Host 头重写成你的 Spaces 内部域名让 Hugging Face 认出这是谁的请求。操作路径Cloudflare 后台Rules → Origin Rules源站规则→ Create Rule创建规则。规则条件选择Hostname主机名等于 www.example.com操作选择Host Header主机标头→ Rewrite to重写为→ abc-my-demo.hf.space。保存即可。实际测试下来这个规则生效后访问www.example.com就能看到应用本体了。这一步如果漏掉最常见的表现是域名能打开、浏览器没报错但内容要么转圈圈要么出现“Invalid URL”或“Page not found”的提示。2.6 管理后台登录与 Spaces 数据交互不受影响这里延伸讲一个容易让新手困惑的点绑定自定义域名之后Spaces 应用里的 Gradio/Streamlit 界面能正常用但如果你在 Gradio 应用里做了用户认证比如通过gr.ChatInterface配合带鉴权的函数那这些认证逻辑是发生在应用内部的和域名绑定完全无关。换句话说绑域名不会影响你的应用内部逻辑它只是让流量换个入口进来。如果应用里需要请求 Hugging Face 的 API比如调用 Inference API那就更没问题了因为请求是从你的后端服务器发出的与应用的外部域名无关。只有一种情况需要注意如果你的 Space 里嵌了 iframe 加载另一个.hf.space资源浏览器可能因为跨域策略拦截但这种情况不常见遇到了再去处理 CSP 头就行。3. 实操过程与核心环节实现这一章给出一份从零到一的完整操作手册。假设你的条件如下域名demo.example.com以下统称“你的域名”Hugging Face 用户名hfuserSpace 名称my-appSpace 内部域名hfuser-my-app.hf.spaceSpace 框架GradioStreamlit 同理操作完全一致3.1 第一步确认 Spaces 内部域名并登记自定义域名登录 Hugging Face进入你的 Space。在 Space 页面的右上角齿轮图标进入Settings。往下滑到Domains区块你会看到类似这样的一行提示Custom domains are supported on PRO. If you are on the free plan, you can use your own domain by setting a CNAME to hfuser-my-app.hf.space如果你没看到这句话可以打开 Space 的详情页在浏览器开发者工具里CtrlF搜索hf.space字符串一定能找到一个https://hfuser-my-app.hf.space的地址。记下来。接着在Domains区块找到输入框如果有的话把你的域名demo.example.com填进去。如果当前页面没有填写入口也没关系先跳过这步等 CNAME 配置好后再回来看状态。有些界面布局会随平台改版变动但不影响最终方案。3.2 第二步在 Cloudflare 添加域名并修改 DNS 记录如果你还没有把域名托管到 Cloudflare先注册一个免费账号cloudflare.com点击Add a site按提示输入你的域名。Cloudflare 会自动扫描你当前的 DNS 记录这时候确认有没有一条 CNAME 指向hfuser-my-app.hf.space没有的话手动新建。在DNS → Records记录页面Type: CNAME Name: demo Target: hfuser-my-app.hf.space Proxy status: Proxied橙色云图标务必开启这里有一个容易忽略的小细节Proxy status 必须选 Proxied也就是橙色云状态。如果选了 DNS only灰色云Cloudflare 就只是纯 DNS 解析不会帮你做 Host Header 重写那样 Origin Rules 也就不会生效。很多人前面都配好了最后发现还是不通十有八九是栽在这个灰云/橙云上面。添加完记录后回到 Cloudflare 的Overview页面它会提示你到域名注册商那边更换 Nameserver。去你的域名注册商阿里云、腾讯云、GoDaddy、Namecheap 等都行后台把原来的 NS 记录换成 Cloudflare 分配给你的两个地址。改完之后等 DNS 全球生效这个过程通常 10 分钟到 24 小时不等。3.3 第三步配置 SSL 模式与 Origin Rule进入 Cloudflare 后台SSL/TLS → Overview把加密模式改为Full (strict)。然后进入Rules → Origin Rules → Create ruleRule name: hf-space-host-rewrite If requests match: Hostname equals demo.example.com Then: Host Header Rewrite to hfuser-my-app.hf.space保存后这条规则就生效了。它的执行逻辑很简单所有带着demo.example.com这个 Host 头进来的请求在向源站转发时Cloudflare 会把 Host 头替换成hfuser-my-app.hf.space。这样一来Hugging Face 平台就会正确识别目标 Space并返回对应应用页面。3.4 第四步回到 Hugging Face 验证域名状态配置完成 Cloudflare 后再回到 Spaces 的Settings → Domains看一下刚才登记的域名状态。如果一切正常状态会变为Valid或直接显示域名已连接。接着打开浏览器访问https://demo.example.com。第一次访问可能稍微慢一点因为 Cloudflare 需要回源拉取资源并建立缓存但等一会儿就正常了。页面打开后应该能看到和https://hfuser-my-app.hf.space完全一致的 Gradio 界面。到这里整个免费绑定就完成了。3.5 一些值得加餐的进阶配置根域名跳转如果你希望访问example.com时也跳到demo.example.com可以在 Cloudflare 的Rules → Redirect Rules里加一条规则请求 Hostname 为example.com的301 重定向到https://demo.example.com。注意这里用 Redirect Rules 而不是 DNS 的 URL 转发因为 DNS 转发在 Cloudflare 免费版里功能比较基础用量容易超额。添加页面规则控制缓存如果 Spaces 应用本身是动态的比如每次都请求新的数据而你发现 Cloudflare 缓存了旧内容可以在Caching → Cache Rules里创建规则当 Hostname 等于demo.example.com时Cache level设置为Bypass。Gradio 这类交互式应用默认大部分响应是 no-cache 的但如果你在 Space 里配置了静态页面可能还是需要手动绕过缓存避免用户看到过期数据。用自定义域名访问特定子路由如果你的同一个 Space 里起了多个 Gradio 应用通过多页面方式那 Host Header 重写规则也只作用在整个应用层面。子路由由前端框架自己处理不受影响。换句话说demo.example.com/app2路由依然能正常访问app2页面。部署多个 Space 到同一个域名不同的子路径这个不建议用免费方案硬做因为 Cloudflare 免费版不支持按路径回源到不同源站。真有这个需求要么用多个子域名要么上 Cloudflare Workers 做路径分发这个展开讲又是一篇长文了需要的朋友可以留言讨论。4. 常见问题与排查技巧实录我在反复部署、被坑、填坑的过程中积累了一些排查套路按出现频率从高到低列出来。花 5 分钟看完这个清单能省下你几个小时瞎折腾的时间。4.1 域名打不开页面一直转圈或报 521/522 错误遇到这个先别急着怀疑 Cloudflare按顺序排查检查 Cloudflare 的 DNS 记录里 CNAME 是否指向了正确的hf.space地址。一个常见的低级错误是填成了huggingface.co或者填成了带https://前缀的完整 URL。CNAME 的值必须是不带协议的裸域名即hfuser-my-app.hf.space。检查 Space 是否处于运行状态。如果 Space 已经休眠Sleeping访问时 Hugging Face 需要花十几秒甚至更久去唤醒应用。免费版 Spaces 的休眠策略是 48 小时无访问自动休眠唤醒时间相对长。所以遇到首次访问慢的情况刷新几次再看看。确认 Cloudflare 的 SSL 模式是 Full (strict)。如果还是 FlexibleCloudflare 到源站走 HTTPHugging Face 那边会拒绝报 521 这类错误。检查 Origin Rules 是否真的生效。Rule 创建后有一个“部署”动作如果你创建完没点Deploy规则实际上没启用。4.2 域名打开了但显示 Hugging Face 默认 404 页面这个现象说明请求已经到达 Hugging Face但平台没认出这是哪个 Space。根本原因几乎一定是Host Header 没被重写。打开浏览器开发者工具看一下Network面板里请求的Host字段。如果显示的是demo.example.com说明 Origin Rules 没起作用如果显示的是hfuser-my-app.hf.space说明重写成功了这时候再往别处查。Origin Rules 没起作用的常见原因有规则条件写的是demo.example.com的 IP 而不是 Hostname把条件选错了规则被其他规则覆盖了路径重写规则优先级高于普通 Origin Rule检查一下有没有别的规则在“捣乱”用了多级 CNAME 链中间某个环节把 Host 头重置了。4.3 能打开但浏览器报证书错误这种一般是两种情况第一种是你的浏览器本地缓存了 Cloudflare 之前用 Flexible 模式签发的证书老证书快过期或者与源站证书不匹配了。去SSL/TLS → Edge Certificates里看看有没有Cloudflare 证书未激活之类的提示有的话点重新签发。第二种情况是你把 SSL 模式调到 Full (strict)但源站Hugging Face那段链路因为某些原因证书校验失败。理论上*.hf.space是有效的通配符证书不会触发校验失败。但如果你填的 CNAME 值里带了多余的http://或路径会导致实际访问的 URL 解析错误证书自然会不匹配。检查 CNAME 值的写法。4.4 应用能打开但图片/附件上传失败Gradio 应用里如果用了gr.Image、gr.File这类组件上传文件时会通过 POST 请求发到服务器。绑定自定义域名后如果 Cloudflare 默认的请求体大小限制被触发免费版默认 100MB大文件上传会失败。检查 Cloudflare 的Network → Request body limit如果请求体超过 100MB一般不太可能但某些音频视频文件就可能需要把 Spaces 应用换成 2 vCPU 以上的实例付费才能绕过。免费方案下解决不了可以考虑在应用层做压缩或分片上传。更常见的其实是“混合内容”问题你的页面通过 HTTPS 打开但页面里的某些资源或上传接口却引用了http://协议浏览器直接拦截。这种情况在 Gradio 应用里比较少见但如果你自己在 Space 里写了前端页面或引用了外部资源就要检查一下资源引用路径是不是用了相对路径或正确的 https 协议。4.5 域名验证一直没通过状态始终为 Pending如果在 Spaces 后台Settings → Domains里看到状态一直是 Pending/Unverified可以这样做确认 CNAME 记录确实存在且生效。用在线工具dns.google查一下demo.example.com的解析结果看是否真的指向hfuser-my-app.hf.space。确认 Cloudflare 代理已经生效。如果是灰云状态DNS 会解析到源站地址而源站是受保护的验证请求会被 Cloudflare 拦截吗不验证请求走的是 CNAME 直接解析灰云状态下 Hugging Face 能看到请求但响应头里可能没有正确标记。多点几次“Check status”按钮有时候是平台那边验证有延迟。等 10-15 分钟再点。4.6 Space 更新后自定义域名访问到的还是旧内容这个大多是缓存问题。Spaces 应用每次 push 代码后会重新构建构建成功后才会有新版本。但 Cloudflare 边缘节点可能缓存了旧版 HTML/CSS/JS。处理方式有两种一种是在 CloudflareCaching → Configuration里把Browser Cache TTL和Edge Cache TTL调短一些或者直接设置Cache Level: Bypass。另一种更省事Gradio 应用本身每次加载页面时都会带版本戳资源路径带 hash 的话Cloudflare 会自动回源拉新版本不需要额外处理。如果你做了自定义前端没带版本戳那就得用规则绕过缓存了。4.7 免费方案与官方方案的共存万一以后升级了 Pro如果你的 Spaces 是付费版或者以后升级了 ProHugging Face 支持在平台内直接配置自定义域名而且不限制绑定的域名数量。相比之下Cloudflare 方案更像是“免费临时方案”稳定性和体验都比官方方案稍弱一点。但两者也可以同时用比如你用官方方案把app.example.com绑到 Space A再用 Cloudflare 方案把demo.example.com绑到同一个 Space B互不影响。不过同一个域名建议不要同时在 Hugging Face 后台和 Cloudflare 规则里配置会冲突。4.8 免费的 Cloudflare 会不会突然把代理停掉这是不少人担心的问题。Cloudflare 免费版的适用范围其实很广个人开发者的流量远够用。唯一要留意的是如果你绑定的域名被 Cloudflare 判定为高风险域名比如涉及违规内容代理可能会被停掉。正常情况下只要你的 Space 内容合规整个方案可以长期稳定运行。我自己有一个 Spaces 应用用这套免费方案跑了大半年中间还经历了 Cloudflare 规则界面改版、Hugging Face 后台布局调整但核心机制一直没变。这也说明这套方案很稳定经得起时间考验。5. 避坑经验与几点使用心得做完了以上配置你的域名绑定基本就成了。但操作中还有几个容易反复折腾的地方再单独拿出来总结一下。5.1 动手前先把“三件套”确认清楚我发现很多人在配置过程中卡住根本不是因为方案有问题而是动手前没把信息准备齐全。建议你在开始之前先把这三样东西写在纸上完整的 Spaces 内部域名格式username-space-name.hf.space你的自定义域名包含子域名前缀Cloudflare 后台的登录凭据以及域名注册商的登录凭据这三样确认好整体操作时间能控制在 20 分钟内。如果缺少任何一样中途再去查资料、找账号就容易陷入“改了 A 结果影响 B”的连锁问题。5.2 有关 DNS 生效速度的认知纠正DNS 生效速度受很多因素影响大多数情况下 10 分钟左右就能全球同步但某些小众 TLD比如.xyz、.top的 NS 记录更新有时会慢到十几分钟到半小时。这期间反复去测试域名状态没有意义反而会让自己焦虑。我的建议是配置完 DNS 和 Origin Rule 后先去干别的事过 20 分钟再回来看。如果那时候还是不通再开始排查。测试的时候用浏览器的隐身模式访问避免本地缓存干扰判断。5.3 关于“免费”的边界最后说几句实在话。这套方案实现的功能是用你自有的域名访问 Hugging Face 托管的免费应用服务。免费的“域”指的是不需要为了绑定域名本身额外掏钱也不需要在 Cloudflare 上买付费套餐。但你仍然需要有一个自己的域名域名本身有年费成本这没法省。网上有人卖“免费域名绑定教程”几百块一份教的内容就是这篇文章说的这套东西。说实话信息差确实存在但也说明这个需求是真实存在的而且对很多人来说并不难。希望你看完这篇文章能自己搞定省下这笔冤枉钱。6. 写在最后的扩展方向绑定自定义域名这件事只是扩大 Spaces 应用影响力的第一步。做完之后你完全可以把这套流程延伸出去多子域名矩阵如果你有多个 Space 应用比如一个做 AI 对话机器人、一个做 OCR 识别工具、一个做图像生成 demo你可以分别用chat.example.com、ocr.example.com、draw.example.com来指代它们每个应用独立绑定互不干扰。这样一套域名体系下来整个作品集的专业感直接拉满。和 Cloudflare 其他免费功能组合绑好域名之后你还可以顺手给域名加上Email Routing邮件转发、Web Analytics访问统计、Turnstile人机验证。这些功能哪怕是免费版也包含基础能力配合你的 Spaces 应用完全能搭建出一个“小产品”级别的服务体系。我个人在实际操作中的体会是这套免费方案最值钱的地方不在于省下了那 9 美元月费而在于让你把“自定义域名”这个看似高端的能力内化成了自己的技能。下次再部署任何 Web 应用无论是 Vercel、Netlify、还是 GitHub Pages只要理解了这套“DNS CDN 代理 Host 重写”的通用逻辑你都能举一反三快速搞定。知识一旦打通了就不太容易再被卡住了。配置好之后记得在你的项目 README 里也记一笔部署地址、自定义域名、以及这套配置的几个关键要点。三个月后再回来看你会感谢当初留下笔记的自己。