# node版本分布式网关

**Repository Path**: ChinaMars/node-gateway

## Basic Information

- **Project Name**: node版本分布式网关
- **Description**: 线上部署网关程序后,在任意可连接外网的内网运行子程序，就可以把本地程序暴漏在外网端口
- **Primary Language**: JavaScript
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Distributed Gateway Workspace

分布式网关系统的独立工作区，包含主网关、边缘节点、设计文档和联调脚本。

## 目录结构

```text
distributed-gateway-workspace/
  docs/
  edge-node/
  gateway/
  scripts/
  docker-compose.yml
```

## 包含内容

- `gateway/`
  - Phase 1 PoC 主网关
  - 提供 HTTP 代理入口和节点 WebSocket 接入
- `edge-node/`
  - Phase 1 PoC 边缘节点
  - 提供自动注册、心跳和本地接口处理
- `docs/`
  - 系统架构与开发文档
- `scripts/`
  - 本地联调冒烟脚本

## 先理解怎么工作

这个 PoC 的调用链路是：

1. 启动 `gateway`
2. 启动一个或多个 `edge-node`
3. `edge-node` 通过 WebSocket 主动连接 `gateway`
4. 节点连接成功后发送 `REGISTER` 报文，把自己支持的 API 列表注册到网关
5. 你访问网关的 `/proxy/:serviceName/*`
6. 网关把 HTTP 请求转成 `INVOKE` 消息发给某个在线节点
7. 节点执行本地 handler，再把结果通过 `RESPONSE` 回传
8. 网关把 `RESPONSE` 再转换成普通 HTTP 响应返回给你

## 使用前提

- Node.js 20 或更高版本
- npm 10 或更高版本
- 如果你想跑容器版，还需要安装 Docker

## 本地运行

建议开两个终端窗口。

### 1. 启动网关

```bash
cd gateway
npm install
npm run start
```

启动成功后，默认监听：

- HTTP: `http://127.0.0.1:8080`
- Node WebSocket: `ws://127.0.0.1:8080/ws/nodes`

### 2. 启动边缘节点

```bash
cd edge-node
npm install
npm run start
```

默认情况下，节点会：

- 使用 `sample-service` 作为服务名
- 使用 `dev-node-token` 作为接入令牌
- 自动连接 `ws://127.0.0.1:8080/ws/nodes`
- 自动编译并扫描 `src/services/*.ts`
- 自动注册示例服务里的 3 个接口：
  - `GET /status`
  - `POST /echo`
  - `POST /fetch`

如果你要写自己的节点接口，直接看：

- [`edge-node/README.md`](./edge-node/README.md)

### 3. 确认节点是否成功注册

浏览器或命令行访问：

```bash
curl -X POST http://127.0.0.1:8080/admin/login ^
  -H "content-type: application/json" ^
  -d "{\"username\":\"admin\",\"password\":\"admin123456\"}"
```

登录成功后，再带上 Cookie 访问 `GET /admin/nodes`。如果返回里能看到 `sample-service` 和你的 `instanceId`，说明接入已经成功。

### 4. 打开后台管理页面

浏览器访问：

```text
http://127.0.0.1:8080/admin
```

第一次打开会先进入登录页：

```text
http://127.0.0.1:8080/admin/login
```

默认开发账号密码：

- 账号：`admin`
- 密码：`admin123456`

建议你立刻在 `gateway/.env` 中修改：

- `ADMIN_USERNAME`
- `ADMIN_PASSWORD`

页面里可以直接看：

- 在线节点总数
- 服务摘要
- 路由注册情况
- 挂起请求
- 节点详情
- 手动断开某个节点
- 给节点写备注
- 直接复制 API URL 和 `curl`

### 5. 调用示例接口

```bash
curl http://127.0.0.1:8080/proxy/sample-service/status
```

```bash
curl -X POST http://127.0.0.1:8080/proxy/sample-service/echo ^
  -H "content-type: application/json" ^
  -d "{\"hello\":\"gateway\"}"
```

`/status` 用来看当前调用落到了哪个节点。  
`/echo` 用来观察网关是否正确透传了 `headers / query / body`。  
`/fetch` 用来让边缘节点代替网关请求一个外部网页：

```bash
curl -X POST http://127.0.0.1:8080/proxy/sample-service/fetch ^
  -H "content-type: application/json" ^
  -d "{\"url\":\"https://example.com\"}"
```

## 多节点怎么用

你可以同时启动多个 `edge-node`，只要它们的：

- `SERVICE_NAME` 相同
- `INSTANCE_ID` 不同

那么它们会被视为同一个服务的多个实例，网关会按当前的轮询策略分发请求。

例如你可以启动第二个节点：

```bash
cd edge-node
set SERVICE_NAME=sample-service
set INSTANCE_ID=node-2
npm run start
```

然后多次访问：

```bash
curl http://127.0.0.1:8080/proxy/sample-service/status
```

返回中的 `instanceId` 会在多个节点之间轮换。

## 怎么看后台

可直接访问这些管理接口：

- `GET /healthz`
  - 查看网关进程是否正常
- `GET /admin/overview`
  - 查看在线节点数、服务数、路由数、挂起请求数
- `GET /admin/nodes`
  - 查看节点明细
- `GET /admin/routes`
  - 查看当前聚合出的接口列表
- `GET /admin/pending`
  - 查看正在等待回包的请求

注意：

- 所有 `/admin/*` 管理接口都需要先登录
- 浏览器访问 `/admin` 会自动进入登录页

如果你不想看原始 JSON，就直接打开：

- `GET /admin`
  - 可视化后台管理页面
- `GET /admin/login`
  - 后台登录页

## 怎么停掉一个节点

可以直接关闭节点进程，也可以通过管理接口手动摘除：

```bash
curl -X POST http://127.0.0.1:8080/admin/nodes/sample-service/node-2/disconnect ^
  -H "content-type: application/json" ^
  -d "{\"reason\":\"manual disconnect\"}"
```

## 怎么修改配置

两个服务都支持环境变量。

网关常用变量：

- `PORT`
- `HOST`
- `GATEWAY_ID`
- `NODE_ACCESS_TOKEN`
- `REQUEST_TIMEOUT_MS`
- `HEARTBEAT_INTERVAL_MS`

节点常用变量：

- `GATEWAY_URL`
- `ACCESS_TOKEN`
- `SERVICE_NAME`
- `INSTANCE_ID`
- `MAX_CONCURRENT`

参考：

- `gateway/.env.example`
- `edge-node/.env.example`

## 冒烟测试

```bash
node scripts/smoke-test-distributed-gateway.js
```

这个脚本会自动：

1. 启动一个测试网关
2. 启动一个测试节点
3. 验证后台未登录拦截
4. 登录后台
5. 等待节点注册
6. 调用 `/echo` 和 `/status`
7. 成功后输出 `Smoke test passed`

## Docker Compose

```bash
docker compose up --build
```

启动后可访问：

- 网关健康检查：`http://127.0.0.1:8080/healthz`
- 后台登录页：`http://127.0.0.1:8080/admin/login`

## 文档

- 开发文档：`docs/distributed-api-gateway-development.md`

## 建议你先这样上手

如果你是第一次用这套系统，建议按这个顺序：

1. 先启动 `gateway`
2. 再启动一个 `edge-node`
3. 登录后台后访问 `/admin` 看注册是否成功
4. 调 `/proxy/sample-service/status` 理解请求转发路径
5. 调 `/proxy/sample-service/echo` 看数据透传
6. 再启动第二个节点，观察轮询负载效果