运行只读 RPC 节点

本页覆盖运行只读 OXN RPC 节点的流程。先读硬件要求——SGX 硬件是硬前置。

文档状态

下面的分步命令是基于当前节点架构的指引。具体镜像 tag、配置路径、命令 flag 可能变化；查看 OXN releases 或通过支持渠道问团队获取最新。

前置

确认你有：

• SGX 硬件，/dev/sgx_enclave 与 /dev/sgx_provision 都在。
• Docker 已安装（20.10 或更新）。
• 足够磁盘空间（测试网 100+ GB）。
• Intel DCAP QCNL 已配置（/etc/sgx_default_qcnl.conf）。

验证 SGX 设备节点：

ls -la /dev/sgx_enclave /dev/sgx_provision
# 预期：两个字符设备节点，属主正确

基于 Docker 的部署

推荐通过 Docker 运行 OXN 节点。拉节点镜像：

docker pull zkpchain/sapphire-localnet:latest    # 占位 tag；参考最新 release

在主机上准备数据目录：

sudo mkdir -p /data/oxn-node
sudo chown $USER /data/oxn-node

启动容器：

docker run -d \
  --name oxn-rpc-node \
  --restart unless-stopped \
  -v /data/oxn-node:/serverdir/node \
  -v /var/run/aesmd:/var/run/aesmd \
  -v /etc/sgx_default_qcnl.conf:/etc/sgx_default_qcnl.conf:ro \
  --device /dev/sgx_enclave \
  --device /dev/sgx_provision \
  -p 8545:8545 \
  zkpchain/sapphire-localnet:latest

关键 flag：

• -v /data/oxn-node:/serverdir/node——持久链状态。
• -v /var/run/aesmd:/var/run/aesmd——SGX AESM service 套接字。
• --device /dev/sgx_enclave --device /dev/sgx_provision——SGX 访问。
• -p 8545:8545——JSON-RPC 端点。

等待同步

初始同步要时间——测试网新节点通常 5 分钟以上，取决于链大小。监控：

docker logs -f oxn-rpc-node

看到 Total: 或 Available: 之类的行说明链到达就绪。

节点起来后查询：

curl http://localhost:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","id":1}'
# 预期：{"jsonrpc":"2.0","id":1,"result":"0xba"}

暴露给你的应用

如果 dApp 跑在同一台机器，指向 http://localhost:8545。远程访问时前面放一层反向代理（nginx、Caddy），加 TLS：

server {
    listen 443 ssl;
    server_name your-node.example.com;

    ssl_certificate /etc/letsencrypt/live/your-node.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-node.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8545;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_buffering off;
        proxy_read_timeout 1d;
    }
}

不要无认证、无 IP 限制地暴露节点——任何人打它都能消耗你的节点资源。

配置选项

默认配置提供标准 eth_* JSON-RPC 方法。你可能想调整：

• 归档 vs 修剪——控制历史状态保留。
• CORS 策略——供浏览器 dApp 直连节点。
• debug_* 与 trace_* 方法——默认关闭；调试需要时启用。
• WebSocket 端点——单独端口，某些配置默认关闭。

具体配置路径与语法取决于节点镜像 release。当前具体值通过支持渠道问团队。

监控

基本健康检查：

# 最新区块高度
curl -s http://localhost:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","id":1}' | jq .

# 同步状态
curl -s http://localhost:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_syncing","id":1}' | jq .

持续监控时，如果节点暴露 Prometheus metrics 端点就 scrape。告警项：

• 节点停止同步（区块高度不推进）。
• 磁盘使用超阈值。
• 日志里的 SGX enclave 错误。
• 容器重启循环。

升级

新节点镜像发布时：

1. 读 release note 了解破坏性变更。
2. 停当前容器：docker stop oxn-rpc-node。
3. 拉新镜像。
4. 用同样的 volume 重建容器。
5. 验证节点同步并对外服务。

状态跨升级保留，因为它住在主机挂载的 volume 里。

常见问题

"容器 SGX 错误起不来。" 确认 /dev/sgx_enclave 与 /dev/sgx_provision 存在，容器有访问权。检查 BIOS SGX 设置与内核版本。

"节点卡在 0 或很低的高度。" 同步中。测试网初始同步要几分钟。查 docker logs 看错误。

"eth_chainId 返回错误值。" 你可能误连到本地 Hardhat network。确认打的是 OXN 节点端口。

"日志里有 AESM service 错误。" 主机上装 sgx-aesm-service，确认套接字在 /var/run/aesmd/aesm.socket。

下一步

• 节点运营概览
• 公共 RPC 端点——替代方案