P2P 与分布式存储 / 系统课时

选择路径网关与子域网关

选择路径网关与子域网关

同一个 IPFS CID 可以通过路径网关或子域网关转换为浏览器可访问的 HTTP URL,但两种形式在浏览器同源策略、Cookie 隔离和静态站点部署方面存在明显差异。本课通过实际请求对比两种地址,判断何时可以使用路径形式,以及为什么公开托管不可信内容时应优先选择子域形式。

学习目标

  • 使用路径形式和子域形式的 HTTP 网关访问同一个 CID,并验证返回内容。
  • 解释两种 URL 对浏览器 Origin、Cookie 和脚本隔离的影响。
  • 根据静态站点、可信资源和用户上传内容的场景选择合适的网关形式。

两种网关 URL 如何定位同一份内容

IPFS 网关负责把 HTTP 请求映射到 IPFS 内容路径。CID 标识内容,而网关域名决定浏览器通过哪个 HTTP 服务获取内容。以下使用公开网关 ipfs.io 演示,实际请求需要网络能够访问该网关。

路径网关把 CID 放在 URL 路径中:

https://ipfs.io/ipfs/<CID>

子域网关把 CID 放在主机名中:

https://<CID>.ipfs.dweb.link/

这里的 <CID> 是占位符,实际请求时必须替换为真实 CID。ipfs.io 和 ipfs.dweb.link 是两个不同的网关域名,不能仅通过修改 URL 路径就假定同一网关支持子域访问。

比较项目 路径网关 子域网关
CID 位置 /ipfs/<CID> <CID>.ipfs.dweb.link
浏览器 Origin 相同协议、主机和端口下共享 不同 CID 通常对应不同主机名和 Origin
相对路径 在 CID 根路径下解析 在对应 CID 的站点根路径下解析
适合场景 简单读取、调试、可信内容 静态站点、隔离不同内容源
部署要求 网关支持路径解析 DNS、TLS 和网关支持子域寻址

需要注意:子域网关不改变 CID 所标识的数据,也不会自动保证数据可获取。两种地址都依赖网关能找到并读取对应内容。

用 HTTP 请求验证两种访问形式

先选用一个已知的 CIDv1。下面以 IPFS 官方常见的测试 CID bafybeigdyrzt5sfp7udm7hu76uh7y26nfqvudckl3w4pt6w7t3jdb3e7xi 为例。该示例 CID 对应的内容是否能被当前公共网关获取,取决于网络和提供者状态。

在安装了 curl 的终端执行以下 Bash 示例。使用 -L 跟随重定向,-sS 保留错误提示,-o 保存响应体,-w 输出 HTTP 状态码和最终地址。

bash
CID='bafybeigdyrzt5sfp7udm7hu76uh7y26nfqvudckl3w4pt6w7t3jdb3e7xi'

curl -sSL -o path-result.bin -w 'path_status=%{http_code}\npath_url=%{url_effective}\n' "https://ipfs.io/ipfs/$CID"

curl -sSL -o subdomain-result.bin -w 'subdomain_status=%{http_code}\nsubdomain_url=%{url_effective}\n' "https://$CID.ipfs.dweb.link/"

# 两个响应体都成功取得后,再比较字节是否一致
cmp -s path-result.bin subdomain-result.bin && echo 'content_equal=true' || echo 'content_equal=false'

预期结果:当两个网关均成功返回相同文件内容且没有发生改变内容的 HTTP 转换时,状态码均为 200,最终 URL 分别位于路径网关和子域网关,比较结果为:

text
path_status=200
path_url=https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nfqvudckl3w4pt6w7t3jdb3e7xi
subdomain_status=200
subdomain_url=https://bafybeigdyrzt5sfp7udm7hu76uh7y26nfqvudckl3w4pt6w7t3jdb3e7xi.ipfs.dweb.link/
content_equal=true

这是成功情况下的示例输出,并非公共网关的实时检测结果。实际请求可能出现重定向、404、429、502、504 或连接错误。%{url_effective} 会显示实际跟随重定向后的地址。

如果两个请求都成功,但字节比较失败,应检查响应头中的 Content-Type、Content-Encoding 和最终 URL,并确认没有拿到网关错误页面。对目录 CID,比较默认首页的 HTTP 响应并不等于验证整个目录 DAG 完全一致。

为什么子域网关更适合浏览器隔离

浏览器 Origin 由协议、主机名和端口组成,不包含 URL 路径。假设同一个路径网关托管两个不同 CID:

  • https://ipfs.io/ipfs/CID_A/
  • https://ipfs.io/ipfs/CID_B/

只要两者均使用 HTTPS 默认端口,它们就属于同一个 Origin。即使 CID 不同,浏览器也不会因为路径中的 CID 自动建立同源隔离。恶意 HTML 或 JavaScript 如果能在共享 Origin 下执行,就可能接触该 Origin 范围内的部分浏览器状态和同源资源,具体还受到 Cookie 属性、路径和其他安全机制限制。

子域形式则不同:

  • https://CID_A.ipfs.dweb.link/
  • https://CID_B.ipfs.dweb.link/

这两个地址的主机名不同,因此属于不同 Origin。通常情况下,一个子域的脚本不能直接读取另一个子域的 DOM 或同源存储。

路径网关与子域网关的浏览器同源隔离对比

静态站点部署时如何选择

假设一个静态网站包含 index.html、style.css 和 app.js,打包后作为 UnixFS 目录导入 IPFS,得到目录根 CID。页面使用以下相对路径引用资源:

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>IPFS Demo</title>
  <!-- 使用相对路径,避免固定依赖网关域名 -->
  <link rel="stylesheet" href="./style.css">
</head>
<body>
  <h1>IPFS Demo</h1>
  <script src="./app.js"></script>
</body>
</html>

这是 HTML 文件片段示例,依赖同一目录中存在 style.css 和 app.js。将整个目录导入 IPFS 后,通过目录 CID 访问 index.html,浏览器应能请求到相应的 CSS 和 JavaScript 文件。若使用根路径 /style.css,请求会指向 HTTP Origin 的根目录,路径网关下尤其容易脱离原 CID 路径。

在支持目录首页解析的网关上,推荐通过带尾部斜杠的子域 URL 访问站点:

https://<CID>.ipfs.dweb.link/

这种形式把站点根目录映射到 URL 根路径,更适合使用绝对路径资源引用、前端路由和独立 Origin 的静态站点。实际部署仍须确认网关对目录首页、资源 MIME 类型和路由回退的支持。

部署需求 建议形式 原因
命令行读取文件 路径或子域 两者均可完成内容获取
浏览器打开可信的单个文件 路径或子域 根据使用便利性选择
托管不同用户的 HTML 子域 将不同 CID 放入不同 Origin
使用根路径资源的静态站点 子域 站点资源路径更接近常规网站
需要固定域名与更新内容 自有域名结合 IPNS 或 DNSLink CID 不可变,需要额外的可变命名机制

排查子域网关访问失败

如果路径 URL 可以读取内容,而子域 URL 无法打开,应按以下顺序检查,而不是立即判断 CID 已失效。

  1. 检查 CID 表示形式。CIDv0 常以 Qm 开头,公开子域网关通常要求使用适合 DNS 主机名的 CIDv1 Base32 表示。可以使用 Kubo 的 ipfs cid base32 <CID> 转换表示形式;转换编码不会修改底层内容。
  2. 检查 DNS 解析。子域网关必须让包含 CID 的主机名正确解析到网关服务,不能假定所有 HTTP 网关均提供该功能。
  3. 检查 HTTPS 证书。网关需要提供覆盖相应子域的有效 TLS 配置;浏览器证书错误不是 IPFS 内容哈希错误。
  4. 检查网关是否支持子域请求和对应命名空间。路径模式可用,不代表该服务已经配置子域模式。
  5. 检查内容获取状态。若两个地址均无法获取,继续调查内容提供者、网络连接及网关超时,而不是只调整 URL。

可以用以下命令查看响应头和重定向位置,其中 CID 使用前面示例的实际值:

bash
CID='bafybeigdyrzt5sfp7udm7hu76uh7y26nfqvudckl3w4pt6w7t3jdb3e7xi'
curl -sS -I -L --max-time 20 "https://$CID.ipfs.dweb.link/"

预期结果:网关可用且内容获取成功时,响应头最终包含成功状态,例如:

text
HTTP/2 200

实际可能出现多个重定向响应头块,且 HEAD 请求的处理行为可能与 GET 不同;若 HEAD 不受支持,应改用 GET 验证。响应头中的日期、服务器信息及缓存字段属于动态值,不应据此判断内容是否一致。

最终选择原则是:简单内容读取可以使用路径网关;需要在浏览器中运行 HTML、部署独立静态站点或隔离不同内容源时,优先选择正确配置的子域网关。同时记住,网关提供的是 HTTP 访问入口,内容真实性仍应由 CID 与实际取得的内容共同验证。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

选择路径网关与子域网关

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通