Day 18 / 共 20 天 · 第 4 周 AI 网关/部署

hgctl CLI

前面几天都在讲 Higress"里面"的原理；今天换个视角，看你怎么操作它——hgctl 是 Higress 的命令行工具。核心命令：install（K8s/Docker 两条路径）、plugin build（容器编译 Wasm，正是 Day 12-14 你写的那些插件的构建工具）、gateway-config（看 Envoy 配置）、2025 新增的 agent/mcp（AI Agent 部署）。

📍 你在第 4 周（AI 网关 / 部署）的位置
D16 ai-proxy→ D17 AI 增强插件→ D18 hgctl CLI→ D19 部署→ D20 收官
🤔 痛点：懂了原理，可"装它、发个插件、看它现在啥状态"该敲什么命令？ 原理再清楚，落地还是得动手：怎么把 Higress 装到集群？怎么把 Day 12-14 写的插件编译成 .wasm 推上去？配置没生效想看 Envoy 实况怎么办？如果每一步都要手写一堆 helm/kubectl/docker/port-forward，门槛太高。需要一个把这些封装好的官方工具。
💡 先兜住今天（"hgctl = 网关的瑞士军刀"） hgctl 就是 Higress 递给你的一把瑞士军刀：一个工具、多把刀——install 是"安装向导"（选套餐一键装）、plugin 是"插件代工厂"（从空白脚手架到编译、测试、上架一条龙）、gateway-config 是"听诊器"（贴上去听 Envoy 现在到底是什么配置）、dashboard 是"总开关"（一键打开各种监控台）。它和 istioctl 是"同门师兄弟"（都用 cobra、都能 dump Envoy 配置），但更贴心——比如安装能选"生产/开发/试用"三种套餐。
L01

命令树

// hgctl/cmd/hgctl/main.go:24 → hgctl/pkg/root.go:27 GetRootCommand
// 子命令（root.go:35）：version / gateway-config(gc) / install / uninstall / upgrade
//   / profile / dashboard / manifest / plugin / completion / code-debug / mcp / agent
读法：又是 cobra 命令树（和 istioctl/higress serve 一样）。核心命令：install（装 Higress）、plugin（管 Wasm 插件）、gateway-config（调试 Envoy）、agent/mcp（AI 特性）。
L02

install 三 Profile

// hgctl/pkg/install.go:38 三种 Profile：k8s / local-k8s / local-docker
// install()（:122）：交互选 profile → helm.GenerateConfig → Validate
//   → installer.NewInstaller → Install()
三种安装场景 k8s——装到现有 K8s 集群（生产）；local-k8s——本地 K8s（kind/minikube，开发）；local-docker——纯 Docker 单机（最轻量，试用）。你交互选一种，hgctl 生成对应的 Profile（配置模板）、校验、安装。三种覆盖了"生产/开发/试用"——降低不同场景的上手门槛。这是产品化 CLI 的贴心设计（对比 istioctl 只装 K8s）。
Profile装在哪套餐类比适合
k8s现有 K8s 集群正式开业的连锁店生产环境
local-k8s本地 kind/minikube后厨试菜的样板间本地开发调试
local-docker纯 Docker 单机路边尝一口的试吃摊最快上手试用
L03

K8s vs Docker

// hgctl/pkg/installer/installer.go:54 NewInstaller 按 profile 分派
// K8s（installer_k8s.go:40）：helm 渲染三组件（Higress/Istio base/GatewayAPI）→ kubectl apply
//   Profile 存 higress-profile ConfigMap
// Docker（standalone.go:44）：下载 get-higress.sh → 跑 docker-compose
//   Profile 存本地文件 ~/.hgctl/profiles/
//   （实际编排脚本在独立仓库 higress-standalone）
读法：K8s 安装 = helm 渲染 + kubectl apply（Higress core + Istio base + Gateway API 三个 chart）。Docker 安装 = 下载脚本跑 docker-compose（all-in-one 容器）。Profile 存储位置也不同：K8s 存 ConfigMap（集群内共享）、Docker 存本地文件。安装前用 IsHigressInstalled 检查避免和 helm 冲突。
L04

plugin build

// hgctl/pkg/plugin/plugin.go:29 子命令 build/install/uninstall/ls/test/config/init
// build（build/build.go:181）：用官方 TinyGo builder 镜像（wasm-go-builder）在容器里编译 Wasm
//   产物可为 files 或 oras push 成 OCI 镜像（:433）
// test（test/start.go:97）：docker compose Up 起本地 envoy+插件环境
// install（install/install.go）：从 Go 源码一键构建并下发 WasmPlugin CR
hgctl plugin：写插件的一条龙代工厂 init生成脚手架 写代码Day 12-14 的套路 buildTinyGo 容器编译.wasm test本地起 Envoy 测 install推 OCI+下发 CR 编译在官方 TinyGo 容器里跑 → 免装工具链、环境一致；install 后 Envoy 从 OCI 仓库拉 .wasm（Day 11）
图注：从空白到上线一条龙。你 Day 12-14 写的插件，就是靠这条流水线变成集群里跑着的 .wasm 的。
hgctl plugin = "插件开发全流程工具" 写 Higress Wasm 插件（Day 12-14）的全流程都靠它：init（生成脚手架）→ 写代码 → build（在容器里用 TinyGo 编译成 .wasm，环境一致免装工具链）→ test（本地起 Envoy+插件测试）→ install（构建 + 推 OCI 镜像 + 下发 WasmPlugin CR 到集群）。oras push 把 .wasm 当 OCI 镜像推到镜像仓库（Envoy 从那拉取，Day 11）。这套工具让插件开发像写普通程序一样顺畅——降低了 Wasm 插件的门槛。
L05

gateway-config

// hgctl/pkg/config_cmd.go:37（类 istioctl proxy-config）
// 子命令 all/bootstrap/cluster/endpoint/listener/route
// gateway_config.go retrieveConfigDump（:105）：selector app=higress-gateway 找 Pod
//   → 端口转发到 Envoy admin :15000 → GET /config_dump → configdump.ConfigWriter 打印
读法：和 istioctl proxy-config（Istio 课 Day 18）一模一样——直连 Higress Gateway（Envoy）的 admin 口 15000，dump 出实际生效的配置。排查"配置没生效"的第一利器：直接看 Envoy 现在是什么配置。复用了 istio 的 configdump 打印工具。
📝 举个例子：用它排查"我配的路由怎么不生效" 你写了个 Ingress 路由 /api → svc-a，但访问 404。别瞎猜——用听诊器直接听 Envoy：hgctl gateway-config route 打印 Envoy 现在真正加载的路由表。
→ 如果里面压根没有 /api：说明配置还没下发到 Envoy（问题在控制面翻译/MCP 链路，回看 Day 05/19）；
→ 如果有但指向了别的 cluster：说明路由匹配/优先级写错了（问题在你的配置）。一看实况，问题在哪一层立刻分清。
L06

dashboard

hgctl/pkg/dashboard.go:69：port-forward 到 prometheus(9090)/grafana(3000)/console(8080)/controller(8888)/envoy(15000)，开浏览器。

读法：一键打开各监控/管理界面——省去手动 port-forward。和 istioctl dashboard 同思路。console 就是下一站要讲的 Higress 控制台。
L07

agent / mcp（2025 新增）

hgctl/pkg/agent/：把 Claude Code / Qodercli 作为外部 "Agentic Core" 调用。hgctl agent new/deploy/add 创建/部署 AI Agent（支持阿里云函数计算 AgentRun、本地 AgentScope）。hgctl mcp add 把 MCP Server 发布到 Higress Console/Himarket。

hgctl 也在"AI 化" 2025 年 Higress 加了 agent/mcp 命令——把 hgctl 从"网关管理工具"扩展成"AI Agent 部署工具"：能创建、部署 AI Agent（跑在函数计算或本地），能把 MCP Server 发布到市场。这呼应 Higress"AI 原生"的定位——连它的 CLI 都在往 AI 方向演进。体现了 Higress 想做的不只是"AI 网关"，而是"AI 应用的基础设施"（网关 + Agent + MCP 工具生态）。本系列不深入这块（较新、独立），了解方向即可。
L08

今日小结 + 动手

🧠 今天你应该能回答

  • hgctl 的核心命令有哪些？
  • install 三种 Profile 各适合什么场景？
  • K8s vs Docker 安装的区别？
  • plugin build 怎么支撑插件开发全流程？
  • gateway-config 怎么调试？agent/mcp 体现什么方向？

✋ 动手

cd /Users/bitmart/work/codes/github/higress-group/higress
grep -n 'func GetRootCommand' hgctl/pkg/root.go
grep -n 'k8s\|local-docker\|func install' hgctl/pkg/install.go | head
grep -n 'func.*build\|wasm-go-builder\|oras' hgctl/pkg/plugin/build/build.go | head
明天预告 · Day 19：部署 + 内嵌 istio/envoy——Higress 怎么打包 istiod + Envoy？helm 伞形 chart、一 Pod 双容器（higress + discovery）、内嵌 Istio/Envoy 的 fork 与构建胶水。
← Day 17 AI 增强 Day 19 · 部署 + 内嵌 istio/envoy →