你会遇到什么

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

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

什么时候别用：只有一两个直连通道、没有共享入口需求时，网关本身就是多余的一层。 安装形态说明：CLI 层（hsh，Bun 二进制，非特权，实测）与完整形态（CLI + hsh-tunneld 守护进程，需 systemd + sudo，未实测）。先装 CLI 层就能完成大多数日常操作；隧道相关功能需要守护进程。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：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）。

一步步来

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

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

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 查看当前连接状态。这两条命令是日常排障的第一步——先看「有没有配置、认没认证」，再决定下一步。

hsh config set api-url https://your-hoop-gateway

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

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 走认证流程（需网关侧账号）。

怎么确认修好了

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

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

./hsh-linux-x64/hsh --version

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

卡住怎么办：

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

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

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

hsh status

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

卡住怎么办：

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

其它环境的表现（常见变体）

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

日常使用

启动与入口

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

常用操作

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

hsh status

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

操作二：配置网关地址

hsh config set api-url https://your-hoop-gateway

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

操作三：登录（需网关）

hsh login

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

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

hsh kubeconfig prod-db

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

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

hsh tunnel status

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

数据与目录

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

卸载与清理

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

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/（守护进程安装残留）。

依赖警告

• 版本：[0.3.2, 0.3.2]（hsh CLI；配套 tunneld 1.86.0）。注意 1.150.1 是平台版本号，与 CLI 无关——早期版本行误标为 CLI 版本，2026-08-31 修正。
• 环境：Linux x86_64；完整安装需 systemd + sudo；CLI 层零特权要求。
• 网络：GitHub 直连慢，必须 gh-proxy 前缀（实测路径）。
• 写面：~/.hsh/（CLI 层）；/etc/hsh/、/var/run/hsh/、systemd（守护进程层）。
• 共装：冲突矩阵暂无对子（写面与常用工具不重叠）。

FAQ（常见问题）

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