hoop 详细指南

版本 1.150.1~1.150.1 ｜分类 gate ｜安全（已审查）｜素材：项目官方文档（英文 README/docs）+ 本市场实测（2026-08-28）
配套：站内文档（manifest + guide + 证据）｜快速版：站内文档

1. 场景：什么时候会用它

Hoop（hoophq 出品，MIT，约 800 星）是统一协议网关：MCP、LLM、数据库访问走同一个策略面。它的客户端叫 hsh（Hoop Shell Plugins）：CLI + shell 集成（ssh/kubectl 插件），配合特权守护进程 hsh-tunneld 提供本地隧道（*.hoop 域名）与临时 kubeconfig 签发。

一句话：把"谁能碰哪个数据库/模型"收敛到一个网关，客户端负责丝滑接入。

这个工具解决什么问题：你的 MCP、LLM、数据库连接散在各处，每条通道的安全策略都不一样，管起来很累。Hoop 把「谁能连什么」收成一个策略面：一个网关（hsh）统一管 MCP/LLM/数据库连接，配合特权隧道守护进程（hsh-tunneld）提供本地隧道与临时 kubeconfig 签发。

什么时候用：

你要给多套数据库/服务统一入口和审计，而不是每个工具各配各的；
你要临时拿一个受限的 kubeconfig（hsh kubeconfig）而不是直接碰生产集群凭证；
你要通过 *.hoop 域名把本地服务暴露给团队（需要守护进程）。

什么时候别用：只有一两个直连通道、没有共享入口需求时，网关本身就是多余的一层。

安装形态说明：CLI 层（hsh，Bun 二进制，非特权，实测）与完整形态（CLI + hsh-tunneld 守护进程，需 systemd + sudo，未实测）。先装 CLI 层就能完成大多数日常操作；隧道相关功能需要守护进程。

2. 能力清单

能力	作用
统一网关（MCP/LLM/DB）	见 Agent 执行版 guide
shell 插件（ssh/kubectl）	见 Agent 执行版 guide
临时 kubeconfig 签发	见 Agent 执行版 guide
本地隧道（*.hoop 域名）	见 Agent 执行版 guide
shell 集成（shell-init）	见 Agent 执行版 guide

3. 快速安装

note: CLI 层实测路径；国内 GitHub 直连慢必须 gh-proxy 加速

# 来源: Trove 详细指南 · 验证于 2026-08-28
curl -sL -o hsh.tar.gz https://gh-proxy.com/https://github.com/hoophq/hsh/releases/download/v0.3.2/hsh-linux-x64.tar.gz
tar xzf hsh.tar.gz
./hsh-linux-x64/hsh --version

预期输出: 0.3.2 (hsh-tunneld 1.86.0)

第 1 步：确认版本与解压完整

讲解：--version 同时显示 hsh 与配套 tunneld 版本，是对「下载完整、解压成功」最直接的确认。

# 来源: Trove 详细指南 · 验证于 2026-08-28
./hsh-linux-x64/hsh --version

预期输出: 0.3.2 (hsh-tunneld 1.86.0)

卡住怎么办：

版本号对不上 → 重新下载并检查 tarball 完整性；
命令不存在 → 回到第 1 步确认解压目录路径。

第 2 步：确认配置与状态面

讲解：hsh config set api-url 后，hsh status 能显示你配置的网关地址与插件列表，说明 CLI 层的读写链路正常。

# 来源: Trove 详细指南 · 验证于 2026-08-28
hsh status

预期输出: Version 0.3.2 + API URL（已配置）+ Auth（未认证）+ Plugins（ssh, kubectl）

卡住怎么办：

status 显示未配置 → 先 hsh config set api-url ... 再查；
需要登录 → hsh login 走认证流程（需网关侧账号，本环境未实测）。

安装变体

路径	命令	实测
主路径（实测）	`curl -sL -o hsh.tar.gz https://gh-proxy.com/https://github.com/hoophq/hsh/releas…`	✅ 本市场实测
镜像/代理	见快速版与 semi_auto_note；国内安装按 hoop 指引	实测

半自动说明：实测命令 = hsh CLI tarball（2026-08-28 本环境验证，hsh 0.3.2，gh-proxy 加速）；完整形态 = hsh CLI（Bun 二进制，非特权）+ hsh-tunneld 守护进程（Go，需 systemd + sudo，install.sh 安装到 /etc/hsh/ + /var/run/hsh/，本环境未执行特权安装）；hoop 仓库 release 1.150.1（2026-08-27）提供 hsh-tunneld + install/uninstall 脚本；hsh CLI 仓库 hoophq/hsh v0.3.2（2026-06-03）提供全平台 tarball

非 Linux x86_64：官方提供 darwin 等平台 tarball（本机未实测，命令面一致）；CLI 层零特权、不写系统目录，解压即用。
完整安装（守护进程层）：需要 systemd + sudo（写 /etc/hsh/、/var/run/hsh/），本环境只实测 CLI 层；日常操作与卸载走 CLI 层即可。
想全局用：把解压目录放进 PATH 或软链到 /usr/local/bin（实测用相对路径调用，未做全局安装）。

4. 为什么会这样（机制与共享面）

它怎么工作：Hoop 由两部分组成——

hsh：网关 CLI（tarball 分发，非特权），负责 status / config set / login / kubeconfig / tunnel 等操作；
hsh-tunneld：特权隧道守护进程（Go，官方 install.sh 安装到 /etc/hsh/ + /var/run/hsh/，写 systemd 单元），负责隧道与特权端口。

关键概念：

认证：hsh login 走网关认证流程，token 存在 ~/.hsh/；
临时 kubeconfig：hsh kubeconfig <名字> 按需签发，用完即弃，避免长期持有集群凭证；
shell 插件：ssh/kubectl 走统一策略面。

装完它动哪里：~/.hsh/（认证/配置）；守护进程形态写 /etc/hsh/、/var/run/hsh/ 与 systemd 单元（需 sudo）。

实测命令 = hsh CLI tarball（2026-08-28 本环境验证，hsh 0.3.2，gh-proxy 加速）；完整形态 = hsh CLI（Bun 二进制，非特权）+ hsh-tunneld 守护进程（Go，需 systemd + sudo，install.sh 安装到 /etc/hsh/ + /var/run/hsh/，本环境未执行特权安装）；hoop 仓库 release 1.150.1（2026-08-27）提供 hsh-tunneld + install/uninstall 脚本；hsh CLI 仓库 hoophq/hsh v0.3.2（2026-06-03）提供全平台 tarball

5. 常用操作

第 1 步：装 CLI 层（为什么先 CLI：非特权、可完整卸载、覆盖日常操作）

讲解：CLI 层是 Bun 单二进制 tarball，解压即用，不写系统目录、不起后台进程。国内访问 GitHub 直连慢，所以下载地址统一走 gh-proxy 前缀加速——这是本环境实测通过的路径。装完 --version 会同时显示 hsh 与配套 tunneld 的版本号。

# 来源: Trove 详细指南 · 验证于 2026-08-28
curl -sL -o hsh.tar.gz https://gh-proxy.com/https://github.com/hoophq/hsh/releases/download/v0.3.2/hsh-linux-x64.tar.gz
tar xzf hsh.tar.gz
./hsh-linux-x64/hsh --version

预期输出: 0.3.2 (hsh-tunneld 1.86.0)

装好确认：

--version 输出 0.3.2 (hsh-tunneld 1.86.0)；
./hsh-linux-x64/hsh status 能跑（见日常使用）。

卡住怎么办：

curl 下载超时 → 确认网络能到 gh-proxy（可先 curl -I 探测）；换代理或镜像前缀重试；
tar 解压报错 → 检查下载文件完整性（重新下载），确认系统有 xz 支持；
想在 PATH 里直接用 hsh → 把解压目录放进 PATH，或软链到 /usr/local/bin（实测用相对路径调用，未做全局安装）。

第 2 步：跑通配置与状态查看（不需要守护进程）

讲解：hsh config set api-url 把网关地址写进 ~/.hsh/；hsh status 查看当前连接状态。这两条命令是日常排障的第一步——先看「有没有配置、认没认证」，再决定下一步。

# 来源: Trove 详细指南 · 验证于 2026-08-28
hsh config set api-url https://your-hoop-gateway

预期输出: 配置写入 ~/.hsh/

# 来源: Trove 详细指南 · 验证于 2026-08-28
hsh status

预期输出: Version 0.3.2 + API URL（未配置）+ Auth（未认证）+ Plugins（ssh, kubectl）

装好确认：

status 能看到 API URL 已变成你配置的地址；
Plugins 列表出现 ssh、kubectl。

卡住怎么办：

status 显示未配置 → 先 hsh config set api-url ... 再查；
需要登录 → hsh login 走认证流程（需网关侧账号）。

启动与入口

CLI 无常驻进程，直接用 hsh 子命令；隧道/特权功能需守护进程（完整安装）。

常用操作

操作一：查看状态（本环境实测）

# 来源: Trove 详细指南 · 验证于 2026-08-28
hsh status

预期输出: Version 0.3.2 + API URL（未配置）+ Auth（未认证）+ Plugins（ssh, kubectl）

操作二：配置网关地址

# 来源: Trove 详细指南 · 验证于 2026-08-28
hsh config set api-url https://your-hoop-gateway

预期输出: 配置写入 ~/.hsh/

操作三：登录（需网关）

# 来源: Trove 详细指南 · 验证于 2026-08-28
hsh login

预期输出: 认证流程（token 存 ~/.hsh/）

操作四：签发临时 kubeconfig（需认证 + 连接）

# 来源: Trove 详细指南 · 验证于 2026-08-28
hsh kubeconfig prod-db

预期输出: 临时 kubeconfig 路径（供 k9s/helm/kubectl 使用）

操作五：隧道控制（需守护进程）

# 来源: Trove 详细指南 · 验证于 2026-08-28
hsh tunnel status

预期输出: hsh-tunneld 守护进程状态（未安装时提示）

数据与目录

配置与认证：~/.hsh/；
守护进程：/etc/hsh/config.toml（sudo）、/var/run/hsh/、systemd 单元 hsh-tunneld。

6. 冲突逐条（摘要）

与工具页矩阵同源，共 19 对（2 实测兼容 / 17 推断可能兼容 / 0 推断可能冲突）；完整对子、状态与证据见冲突对子（共装矩阵）。

7. 排障速查

暂无独立排障手册；安装/卸载问题先看 Agent 执行版 guide 注意事项

8. 卸载与残留检查

# 来源: Trove 详细指南 · 验证于 2026-08-28
rm -rf ~/.hsh; sudo rm -f /usr/local/bin/hsh /usr/local/bin/hsh-tunneld; sudo systemctl stop hsh-tunneld 2>/dev/null || true

note: CLI 层自动清理（删二进制 + ~/.hsh/）；守护进程层用官方 uninstall.sh（本环境未执行特权安装，未实测 systemd 单元清理）

# 来源: Trove 详细指南 · 验证于 2026-08-28
rm -rf ~/.hsh
rm -f /usr/local/bin/hsh /usr/local/bin/hsh-tunneld
sudo systemctl stop hsh-tunneld 2>/dev/null || true
command -v hsh >/dev/null 2>&1 && echo '残留: hsh 仍存在' || echo 'hoop removed: OK'

预期输出: hoop removed: OK

手动确认清单（如需彻底清理）：

/etc/hsh/config.toml（sudo 清理）；
systemd 单元与 /var/run/hsh/（守护进程安装残留）。

9. FAQ

运行环境预检（Linux x86_64；完整安装需 systemd + sudo）
官方 tarball（本环境实测 CLI 层）；国内 GitHub 直连慢必须 gh-proxy 加速
每条操作 = 一个命令块 + 预期输出
CLI 层自动清理；守护进程层用官方 uninstall.sh（本环境未实测特权安装）
重档条目：完整形态需 systemd + sudo + TUN（特权守护进程）；纯 CLI 形态轻量

问：只装 CLI 层够用吗？答：日常 status/config/login/kubeconfig 都够；隧道与特权端口功能需要守护进程（完整安装）。
问：国内下载慢怎么办？答：所有下载地址已带 gh-proxy 前缀；仍失败先探测网络到 gh-proxy 的连通性。
问：hsh 命令找不到？答：本指南用相对路径 ./hsh-linux-x64/hsh 调用；想全局用需手动加入 PATH 或软链。
问：卸载后残留？答：CLI 层删 ~/.hsh/ + 二进制即可；守护进程层残留（systemd 单元 / /etc/hsh/）需 sudo 手动清理，本环境未实测特权安装。
问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

版本：[1.150.1, 1.150.1]（hsh-tunneld 锁定；hsh CLI 0.3.2 配套）。
环境：Linux x86_64；完整安装需 systemd + sudo；CLI 层零特权要求。
网络：GitHub 直连慢，必须 gh-proxy 前缀（实测路径）。
写面：~/.hsh/（CLI 层）；/etc/hsh/、/var/run/hsh/、systemd（守护进程层）。
共装：冲突矩阵暂无对子（写面与常用工具不重叠）。

10. 出处

条目签名：hoophq/hoop（MIT，原样收录 hsh-tunneld 1.150.1 + hsh CLI 0.3.2）

实测：实测记录（本地留存）（2026-08-28 CLI 冒烟）；实测记录（本地留存）（装/卸循环）；实测记录（本地留存）（网络预检）。
未实测：守护进程完整安装（需 root + systemd）——命令来自官方 install.sh，如实标注。

外部教学（来源未实测）

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

官方 README：How it works + Quick Start（拦截模型 / 安装 / config / login / shell 插件） [官方文档 · hoop 官方 · 2026-08-30（v0.3.2 README）]
拦截模型——`ssh production-server` 被 hsh 截获 → 检查本地 JWT → 在 Hoop API 找连接 → 生成临时会话 token → 经 Hoop gateway 连入（SSH 显示 token 提示）；Kubernetes 更顺滑（hsh 直接把 proxy+token 注入 kubeconfig，kubectl 直接可用）。Quick Start 四步：①下载 Releases 归档（含 hsh CLI + hsh-tunneld 守护 + 安装脚本，Linux install.sh 注册 systemd / macOS hsh-tunneld install 注册 LaunchDaemon，安装器把你加进 hsh 组）②`hsh config set api-url https://<公司>.hoop.dev` ③`hsh login`（浏览器 OAuth）④shell 配置加 `eval "$(hsh shell-init)"`（fish 用 hsh shell-init --shell fish | source）
官方 README：SSH / Kubernetes 插件用法 [官方文档 · hoop 官方 · 2026-08-30（v0.3.2 README）]
SSH 插件——装好 hsh 后直接 `ssh <连接名>`（旧方式要在 web UI 找连接/复制 token/手动 ssh gateway，hsh 一步到位）；Kubernetes 插件——hsh 注入 kubeconfig，kubectl 命令无缝走 Hoop gateway（含审批/审计/策略）

收录来源（已合并）

本页内容由多篇来源文章按哈希去重、实测验证、AI 重写后合并而来——来源不散落，全部挂在这一个页面上。

暂无已合并来源：本页为本地实测与多来源重写的沉淀；来源与验证细节见站内对应方案页。

← 返回 hoop 方案页｜网关与路由问题域