# Gateway

> 运行 NeuroChain gateway——位于节点前方的 Node.js 服务，提供 REST 和 WebSocket、按分片路由、广播实时事件、限流，并托管可选的 AI 工具；包括部署、配置和安全说明。

Source: https://docs.nro.world/zh/operate/gateway

Gateway 是位于用户与节点之间的 Node.js（Fastify）服务。Web 应用、SDK 和 MCP 服务器都与它通信。

| 功能 | 详情 |
|---------|---------|
| 提供 REST API | 大多数路径代理到节点；少数是它自己的——参见 [REST](/zh/reference/rest) |
| 提供 WebSocket | `/ws`——实时区块、交易、AI 事件、余额订阅；参见 [WebSocket](/zh/reference/websocket) |
| 按分片路由 | 把每笔交易发送到负责发送方所在分片的节点 |
| 监视链 | 轮询节点，把变化转换为事件，发出合约活动告警 |
| 限流 | 按 IP，分为全局限流和 AI 端点限流 |
| 托管 AI 工具 | 合约审计代理、合约生成（SmartForge）、文档助手 |

Gateway 从不决定任何链上状态：签名、余额和 AI 评分都来自节点。

## 运行

```bash
cd neurochain/gateway
npm install
NODE_RPC_URL=http://localhost:9933 node src/index.js
```

```bash
curl -s http://localhost:3000/health
# {"status":"ok","network":"neurochain-mainnet-1","height":11,"peers":0,"round":0,"mempool":0}
```

它在所有网络接口上监听 `PORT`（3000）端口。

## 配置 {#configuration}

### 连接

| 变量 | 默认值 | 含义 |
|----------|---------|---------|
| `PORT` | `3000` | 监听端口 |
| `NODE_RPC_URL` | `http://localhost:9933` | 节点的 RPC |
| `NEUROCHAIN_SHARD_NODES` | — | 分片路由，例如 `0=http://n0:9933,1=http://n1:9934` |
| `SHARD_NODE_URLS` | — | 同上，按位置排列（索引 = 分片），在上一项未设置时使用 |
| `NETWORK_ID` | `neurochain-mainnet-1` | 在 `/health` 中报告的网络名称 |
| `CORS_ALLOWED_ORIGINS` | `*` | 允许的浏览器来源——生产环境中请设为你站点的来源 |
| `TLS_CERT`, `TLS_KEY` | — | 直接提供 HTTPS 时使用的 PEM 路径 |

### 限制

| 变量 | 默认值 | 含义 |
|----------|---------|---------|
| `GLOBAL_RL_MAX_RPS` | 200 | 每个 IP 每秒的请求数 |
| `AI_RL_MAX_RPM` | 10 | 每个 IP 每分钟的 AI 端点请求数 |
| `WS_MAX_MSG_BYTES` | 65 536 | WebSocket 消息的最大长度 |
| `WS_MAX_SUBS_PER_CLIENT` | 50 | 每个连接的余额订阅数 |
| `WS_RPC_MAX_RPS` | 30 | 每个连接每秒的 RPC 调用数 |

### 链监视

| 变量 | 默认值 | 含义 |
|----------|---------|---------|
| `POLL_NODE_INTERVAL_MS` | 2000 | 向节点轮询新区块的间隔 |
| `SENTINEL_CHECK_INTERVAL_MS` | 30000 | 合约活动检查 |
| `SENTINEL_SPIKE_LOW_THRESHOLD` / `_HIGH_THRESHOLD` | 10 / 50 | 每个间隔内触发中级 / 高级告警的调用次数 |
| `SENTINEL_LOW_SCORE_THRESHOLD` | 60 | 安全评分低于此值的合约开始被调用时告警 |
| `ALERT_COOLDOWN_MS` | 60000 | 同一合约两次告警之间的最小间隔 |
| `PROTOCOL_PARAMS_REFRESH_MS` | 60000 | 从节点重新读取协议参数的间隔 |

### 水龙头（测试网络）

| 变量 | 默认值 | 含义 |
|----------|---------|---------|
| `FAUCET_AMOUNT` | 50 NRO | 每次请求的金额 |
| `FAUCET_COOLDOWN_SECS` | 86400 | 按地址和 IP 计算 |
| `REDIS_URL` | `redis://localhost:6379` | 可选——在 gateway 重启后保留水龙头冷却状态；没有 Redis 时保存在内存中 |

### AI 工具

| 变量 | 默认值 | 含义 |
|----------|---------|---------|
| `ANTHROPIC_API_KEY` | — | 启用基于 Claude 的 SmartForge 合约生成；未设置时使用内置的模板生成器 |
| `SMARTFORGE_MODEL`, `SMARTFORGE_MAX_TOKENS` | — | SmartForge 使用的模型和长度 |
| `AI_EXPORT_TOKEN` | — | 设置后，`/api/v1/ai/export/*` 需要提供该令牌 |
| `ASSISTANT_ENABLED` | `0` | 文档助手（`POST /api/v1/assistant/ask`）；用 `npm run assistant:index` 重建其索引 |

包含全部默认值的完整列表见仓库中的 `.env.example`。

## 安全说明

- 让节点的 RPC 保持私有，只暴露 gateway（置于带 TLS 的反向代理之后，或使用 `TLS_CERT` / `TLS_KEY`）。
- 将 `CORS_ALLOWED_ORIGINS` 设为你自己的来源。
- `POST /api/v1/wallet/derive-address` 会接收恢复助记词；节点在 mainnet 上会拒绝它，而且公共 gateway 上绝不应允许访问它。
- `/api/v1/network/status` 中的部分字段（`tps_peak`、`block_time_ms`、`crypto` 列表、AI 模型数据）是固定的描述性取值，并非实测值。

## 测试

```bash
cd neurochain/gateway
npm test            # HTTP API 测试；完整测试集需要节点处于运行状态
```