开发环境搭建

Nantian Gateway 的控制面用 Go 编写，数据面用 Rust 编写，管理界面用 Next.js 编写。本页带你从零搭建本地开发环境，完成编译、运行和调试的全流程。

前置要求

必需工具

工具	版本要求	用途
Go	≥ 1.21	控制面编译
Rust	≥ 1.85	数据面编译
Docker	≥ 24.0	本地集群和容器化运行
kubectl	≥ 1.28	Kubernetes 集群操作
Helm	≥ 3.12	Chart 打包和部署
protoc	≥ 3.21	Protobuf 编译
Node.js	≥ 18	管理界面和文档站

推荐工具

工具	用途
Kind	本地 Kubernetes 集群
just	命令运行器（CI 和任务自动化）
golangci-lint	Go 代码 Lint
cargo-watch	Rust 热重载开发

快速验证环境

# 验证 Go
go version
# 预期: go version go1.21.x ...

# 验证 Rust
rustc --version
# 预期: rustc 1.88.x ...

# 验证 Docker
docker version

# 验证 kubectl
kubectl version --client

# 验证 Helm
helm version

# 验证 protoc
protoc --version

# 验证 Node.js
node --version

克隆仓库

# Fork 主仓库，然后克隆你的 Fork
git clone https://github.com/<your-username>/gateway.git
cd gateway

# 添加主仓库为 upstream
git remote add upstream https://github.com/nantian-gw/gateway.git

搭建本地 Kubernetes 集群

开发环境推荐使用 Kind 搭建本地集群：

# 创建 Kind 集群
kind create cluster --name nantian-dev

# 验证集群状态
kubectl cluster-info
kubectl get nodes

安装 Gateway API CRD

# 安装 Gateway API v1.5.1 CRD
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml

编译和运行控制面

控制面使用 Go 编写，入口在 gateway/cmd/manager/main.go。

# 进入控制面目录
cd gateway

# 安装依赖
go mod download

# 编译控制面
go build -o bin/manager ./cmd/manager

# 本地运行控制面（需要先安装 Nantian Gateway CRD）
kubectl apply -f deploy/crds/
./bin/manager --config configs/controlplane/config.yaml

manager 二进制只接受一个参数 --config（YAML 配置文件路径）。所有运行时行为——监听地址、主从选举、认领的 GatewayClass——都在该配置文件里设置，而非命令行参数。

控制面关键配置项

配置项	默认值	说明
grpcAddr	:18080	gRPC xDS 服务器地址
adminAddr	:18081	Admin API / HTTP 地址
metricsAddr	:18082	Prometheus 指标地址
healthProbeAddr	:18083	健康与就绪探针地址

完整 schema（含主从选举与 GatewayClass 名称）见 控制面配置 参考文档。

本地开发技巧

本地开发时运行单个实例，并在配置文件中关闭主从选举，manager 会立即成为活跃实例。生产环境请保持主从选举开启以实现高可用。

编译和运行数据面

数据面使用 Rust 编写，位于 dataplane/ 目录。

# 进入数据面目录
cd dataplane

# 编译数据面（debug 模式）
cargo build

# 编译数据面（release 模式，性能优化）
cargo build --release

# 运行数据面
cargo run -p ntgw-app -- --config configs/dataplane/config.yaml

ntgw-app 二进制同样只接受一个 --config 参数。节点标识、控制面地址、admin/代理监听地址都来自配置文件。节点标识也可以通过 NANTIAN_GW_NODE_ID 环境变量注入，Helm chart 会用 Pod 名称设置它。

数据面关键配置项

配置项	默认值	说明
nodeId	dp-local	节点标识
xds.serverAddress	http://127.0.0.1:18080	控制面 gRPC 地址
runtime.adminAddress	0.0.0.0:19080	Admin API 和指标地址
runtime.listenAddress	0.0.0.0:8080	HTTP 代理监听地址

完整 schema 见 数据面配置 参考文档。

编译 Protobuf

修改 proto/ 目录下的 .proto 文件后，需要重新生成 Go 和 Rust 代码：

# 生成 Go 代码
cd proto
buf generate

# 生成 Rust 代码（在 dataplane 目录下）
cd ../dataplane
# 代码生成已集成在 dataplane 的 build.rs 中
cargo build

运行管理界面

管理界面是基于 Next.js 的 Web 应用：

cd dashboard

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 浏览器访问 http://localhost:3000

运行文档站

文档站使用 Astro + Starlight：

cd website

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 浏览器访问 http://localhost:4321

使用 Docker Compose 一键启动

项目提供了 docker-compose.yml 用于快速启动完整的开发环境：

docker compose up -d

这会启动：

• 控制面实例
• 数据面实例
• 管理界面

调试技巧

Go 控制面调试

使用 Delve 调试 Go 代码：

# 安装 Delve
go install github.com/go-delve/delve/cmd/dlv@latest

# 调试模式运行控制面
dlv debug ./cmd/manager -- --config configs/controlplane/config.yaml

VS Code 用户可以安装 Go 扩展，在 .vscode/launch.json 中配置调试目标。

Rust 数据面调试

Rust 数据面支持 RUST_LOG 环境变量控制日志级别：

# 启用详细日志
RUST_LOG=debug cargo run -p ntgw-app -- --config configs/dataplane/config.yaml

# 仅查看特定模块日志
RUST_LOG=ntgw_http=trace cargo run -p ntgw-app -- --config configs/dataplane/config.yaml

常用的日志级别：error、warn、info、debug、trace。

查看 xDS 通信

在开发过程中，可以查看控制面和数据面之间的 xDS 通信来验证配置是否正确传递：

# 查看控制面 Admin API 中已连接的数据面节点
curl http://localhost:18081/v1/nodes | jq

# 查看数据面 Admin API 中的节点状态（含 xDS 流状态）
curl http://localhost:19080/v1/node | jq

下一步

• 查看 测试指南 了解如何运行测试
• 查看 架构概述 了解系统设计
• 查看 贡献概述 了解贡献流程