P2P 与分布式存储 / 系统课时
限制 RPC 和网关的暴露范围
限制 RPC 和网关的暴露范围
同一台 Kubo 节点既能通过 RPC 管理仓库,也能通过 HTTP 网关读取 CID 内容。把两个端口一并开放,会把原本用于内部管理的能力交给不可信请求。本篇完成本机监听收紧、只读网关反向代理和外部访问验证。
学习目标
- 区分 RPC、内容网关与 P2P 端口的权限边界。
- 配置回环监听、网关获取策略和反向代理入口。
- 从监听地址、HTTP 状态码与容器端口映射检查暴露风险。
识别应当公开的入口
以 Kubo 0.43.x 的典型配置为例,三个端口承担不同职责,不能因为都属于 IPFS 就采用同一条防火墙规则。
| 入口 | 常见地址或端口 | 允许的访问者 | 风险 |
|---|---|---|---|
| 管理 RPC | 127.0.0.1:5001,/api/v0/* |
本机运维进程、可信后端 | 可执行配置、Pin 等管理操作 |
| HTTP 网关 | 127.0.0.1:8080,/ipfs/*、/ipns/* |
经受控反向代理的读取客户端 | 可能触发远程取回并消耗带宽 |
| libp2p Swarm | 通常使用 TCP/UDP 4001 | 按节点联网需求开放给对等节点 | 是 P2P 传输入口,不是 HTTP 管理口 |
推荐的部署是:外部用户仅到达 HTTPS 网关;反向代理只转发到 8080;5001 留在主机回环网络,由同机管理进程使用。不要将外部请求的 /api/v0/ 转发到 5001。

将管理端口固定到回环地址
前提是已初始化 Kubo,且命令运行在节点所在主机;以下使用默认仓库和 IPv4 回环地址。先把示例域名换成实际网关域名,停止正在运行的 daemon,或修改后通过原有服务管理方式重启,使监听配置真正生效。
# RPC 和网关都只在本机监听,避免直接绑定公网网卡
ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001
ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8080
# 公开自有内容时,不允许访客请求触发任意外部 CID 检索
ipfs config --json Gateway.NoFetch true
# 为公开路径网关显式声明域名;先换成自己的实际域名
ipfs config --json Gateway.PublicGateways '{"gateway.example.com":{"UseSubdomains":false,"Paths":["/ipfs","/ipns"]}}'
ipfs config Addresses.API
ipfs config Addresses.Gateway
ipfs config Gateway.NoFetch预期输出:
/ip4/127.0.0.1/tcp/5001
/ip4/127.0.0.1/tcp/8080
true上述命令修改的是仓库配置,不能替代 daemon 重启。Gateway.PublicGateways 命令会覆盖原有域名映射;已经部署多个域名时应合并条目,不能直接覆盖。若节点使用自定义 IPFS_PATH,须在相同仓库上下文中操作。Gateway.NoFetch=true 适合只发布已导入、Pin 或位于 MFS 中的内容;需要代用户从全网检索任意 CID 的网关不能直接套用该选项。
如果可信后端确实需要跨主机调用 RPC,优先通过私网、VPN 或 SSH 隧道接入,并用 API.Authorizations 的 AuthSecret 和 AllowedPaths 收紧身份及路径权限;必须跨不可信网络时还要使用 TLS。不要把 CORS 允许列表当作身份认证,也不要给浏览器提供全权限管理令牌。
通过 Caddy 单独发布内容网关
以下是 Caddy 2 的 Caddyfile 配置示例。先把 gateway.example.com 换成自己控制、已正确解析到服务器的域名,并确保 80/443 可供证书签发与 HTTPS 服务使用。文件位置可为 /etc/caddy/Caddyfile;反向代理和 Kubo 运行在同一台主机。
gateway.example.com {
@content path /ipfs/* /ipns/*
handle @content {
# 保留原始 Host,供网关按域名匹配规则
reverse_proxy 127.0.0.1:8080
}
handle {
respond 404
}
}配置生效后,https://gateway.example.com/ipfs/<CID> 能被转发给网关;/api/v0/* 不属于允许路径,返回 404,绝不会代理至 5001。这里使用路径网关,多个 CID 内容共享同一浏览器 Origin;若面向不可信 HTML 应用提供网页浏览,应改为具备独立 Origin 的子域网关,并配套 Gateway.PublicGateways、通配域名和 TLS 证书,而非把路径网关当作隔离方案。
从监听与外部请求验证边界
在采用 systemd 管理 Caddy 的 Linux 主机上验证配置并重载;Kubo 监听修改后也要先按本机的进程管理方式重启。以下命令中的示例域名须替换成已启用 HTTPS 的真实域名。
caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
ss -lnt | grep -E '127\.0\.0\.1:(5001|8080)\b'
curl -sS -o /dev/null -w '%{http_code}\n' https://gateway.example.com/api/v0/version预期结果:Caddy 配置校验通过,重载成功;监听检查应列出仅绑定 127.0.0.1:5001 和 127.0.0.1:8080 的条目,格式因系统而异;最后一条命令输出:
404还应从另一台不可信网络中的设备检查公网 IP 的 TCP 5001、8080 无法直连,并访问一个事先 Pin 的有效 CID 确认网关返回内容。不能仅以浏览器出现 403 认定 RPC 安全:403 可能只是 Origin 检查,而非网络隔离。
排除常见的部署绕过
| 现象 | 需要检查的原因 | 修复方向 |
|---|---|---|
| 外网仍可直连 5001 | Addresses.API 是 0.0.0.0,或容器/端口转发对外发布了 5001 |
改回回环监听,取消公开映射,收紧安全组与防火墙 |
| 网关请求返回 404 | 开启 Gateway.NoFetch 但本机没有目标块 |
先导入并 Pin 内容;确需全网检索则另行设计限流与滥用防护 |
| 代理后内容路径异常 | 反代改写 Host,或路径规则不匹配 |
保留原始 Host,核对 /ipfs/* 与 /ipns/* |
| 加了 CORS 仍有管理风险 | CORS 不限制非浏览器客户端,也不替代鉴权 | RPC 保持非公开,必要时启用明确的认证授权 |
容器部署时还要逐项检查 Docker ports、宿主机 IPv4/IPv6 监听和云防火墙规则。最终验收标准是:公网仅按业务需要到达 HTTPS 内容入口,RPC 仅供本机可信管理进程访问;确需跨机管理时,必须验证身份并限制允许调用的路径。任何不可信主机都不应能够直连 Kubo 的 5001 管理端口。可交叉核对 Kubo RPC 安全说明 与 Kubo Gateway 部署说明。