Table of Contents

五分钟跑起来

本页目标：从零得到一个能转发请求的 KernLab.Traffic 节点——启动 worker、写入两条路由、 发布、用 curl 验证直应与代理两条路径。全部命令与回执在当轮源码上逐字验证。

前置条件

  • .NET SDK 8（global.json 钉定 8.0.422）
  • 仓库已构建出 worker 宿主程序 traffic-worker：
dotnet build src/KernLab.Traffic.Worker/KernLab.Traffic.Worker.csproj -c Release
# 产物：src/KernLab.Traffic.Worker/bin/Release/net8.0/KernLab.Traffic.Worker.exe
  • 一个可访问的上游服务（本页用 python -m http.server 充当；端口 8010）。

1. 编写最小 worker.json

{
  "volume": "memory:",
  "listen": { "port": 5010 },
  "admin":  { "listen": "127.0.0.1:7901" }
}

三个字段的含义：

字段 含义
volume 存储卷（TierFs）。memory: ＝内存卷（开发用；重启即清）；生产推荐 virtual:// 虚拟文件系统——自持崩溃一致性、数据损坏面不依赖 OS 文件系统（见单机部署的介质选型）
listen.port 数据口——客户端流量入口
admin.listen 管理口（ip:port）——CLI/REST/UI 的管理面入口

端口无任何代码级默认值——不配置即启动拒绝。若数据口被占用，worker 以退出码 11（绑定失败）退出； 配置字段拼错（未知字段）以退出码 10（引导失败）退出。全部退出码见 部署与运维 · 故障排查。

2. 干跑验证配置

traffic-worker validate --config worker.json
{"ok":true,"exitCode":0,"warnings":[]}

validate 与正式启动共用同一装载器与校验链（同配置两态同结果），干跑通过再启动。

3. 启动 worker

traffic-worker run --config worker.json
traffic-worker 就绪：data=http://127.0.0.1:5010 admin=http://127.0.0.1:7901

另开一个终端验证两个口：

curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7901/healthz   # → 200（管理口健康探针）
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:5010/          # → 503（尚未发布任何配置）

4. 写入配置实体（draft）

一切实体先写 draft（可改的候选态），发布后才成为 published（服务中）。 写实体走管理 REST（与 CLI/UI 同一契约）：

# 上游集群：把请求转发到哪
curl -s -X POST http://127.0.0.1:7901/api/v1/default/config/set/cluster/demo-upstream \
  -H "Content-Type: application/json" \
  -d '{ "targets": ["127.0.0.1:8010"] }'
{"logicalAddress":"0000000000000000d800000000000000","generation":0}

# 代理路由：/api/ 前缀 → demo-upstream；order 越大越优先
curl -s -X POST http://127.0.0.1:7901/api/v1/default/config/set/route/demo-api \
  -H "Content-Type: application/json" \
  -d '{ "cluster": "demo-upstream", "pathPrefix": "/api/", "order": 10 }'

# 直应路由：命中即返回固定响应（无需上游；不配置路径条件＝全匹配兜底）
curl -s -X POST http://127.0.0.1:7901/api/v1/default/config/set/route/hello \
  -H "Content-Type: application/json" \
  -d '{ "directResponse": { "statusCode": 200, "body": "hello from KernLab.Traffic" } }'

回执中的 logicalAddress（地址指纹）与 generation（世代号）是配置版本戳； URL 路径中的 default 是租户名（多租户见概念 · 租户与键空间）。

偏好命令行的，同一操作走 worker 自带 TUI 族（-f 读文件、管道走 stdin）：

traffic-worker config set cluster demo-upstream -f cluster.json --admin http://127.0.0.1:7901
echo '{ "targets": ["127.0.0.1:8010"] }' | traffic-worker config set cluster demo-upstream
traffic-worker config list route --admin http://127.0.0.1:7901     # 读操作

5. 发布（draft → published）

draft 写多少条都不影响线上流量——发布才生效：

traffic-worker publish dry-run          # 干跑：编译预检，零副作用
success              true
candidateGeneration  1
issues               []
planned              ["route/demo-api","route/hello","cluster/demo-upstream"]

traffic-worker publish go               # 正式发布
ok          true
generation  1
planned     ["route/demo-api","route/hello","cluster/demo-upstream"]

planned 列出本世代覆盖的实体；generation 递增即热装载完成，不停机、不断连接。

6. 验证数据面

# 代理路由：原样路径到达上游
curl -s http://127.0.0.1:5010/api/index.html
{"service":"demo-upstream","ok":true}

# 直应路由
curl -s http://127.0.0.1:5010/hello
hello from KernLab.Traffic

# 未命中其他条件时：hello 路由无路径条件＝全匹配兜底
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:5010/anything   # → 200

下一步

Edit this page