Hoppscotch 自托管部署：10 分钟跑起你自己的完整 API 调试工具-育师

Hoppscotch 自托管部署：10 分钟跑起你自己的完整 API 调试工具

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch

Hoppscotch 是一个开源的 API 调试工具，支持 REST、GraphQL、WebSocket、MQTT 等协议，也有 CLI 形态。读完这篇，你能用一条命令在服务器上起一个自托管实例，并看懂一个请求在代码里是怎么走完整个流程的。

上图是主界面：左侧集合树，中间 URL 与请求参数，右侧响应状态和耗时。

桌面端内置"切换实例"，同一客户端既能连官方云，也能连你自己的自托管后端。

它解决的是什么问题

同类工具里 Postman 偏 SaaS，请求和数据默认走对方服务器；Insomnia 是闭源桌面应用。Hoppscotch 的三点差异：

轻：浏览器打开即用，可装成 PWA 离线使用
全协议：REST、GraphQL、WebSocket、SSE、Socket.IO、MQTT 共用一套界面
可自托管：后端、PostgreSQL、管理面板都能跑在你的机器上，集合和环境数据不出内网

谁适合用它

后端联调：多环境（测试/预发/生产）来回切，环境变量替换省掉改 URL
数据合规团队：接口定义属于敏感资产，需要私有化部署
前端/全栈开发：同一个界面测 REST 和 WebSocket，不用换工具
想把接口集合接进 CI 的团队：命令行工具可以批量跑集合

最短路径跑起来 🐳

主路径只有一条，用 Docker：

git clone https://gitcode.com/GitHub_Trending/ho/hoppscotch && cd hoppscotch拿到仓库。成功标志：目录里有docker-compose.yml和.env.example。
cp .env.example .env生成配置文件。注意 docker-compose.yml 里每个服务都声明了env_file: ./.env，没有这个文件服务起不来。成功标志：.env文件存在。
docker compose --profile default up默认档一次拉起 All-in-One 容器 + PostgreSQL + 自动迁移。成功标志：访问http://localhost:3000打开应用本体，http://localhost:3100是管理面板。

想改代码就跑本地开发环境：pnpm install && pnpm dev，package.json 已锁定 pnpm 版本，pnpm dev会并行启动各子包的开发服务器。

验证动作：登录后切到 REST 标签，输入GET https://echo.hoppscotch.io点 Send，状态码 200 即部署成功。

功能走查：发一个真实请求

输入 URL 点 Send。你看到右侧状态码、耗时、Response Body 三个区域亮起来。
把请求存进集合：点 Save，填名称选集合。你看到左侧集合树多出一条可折叠的记录。
建一个 Environment，把 URL 里的域名写成{{baseUrl}}。你看到 URL 中的变量显示为高亮样式。
切换到另一个 Environment。你看到同一请求自动指向新地址，不用手动改 URL。

另外右上角 Import 菜单支持导入 cURL 和 Postman 集合（入口在 ImportCurl.vue），存量 Postman 集合可以整体迁过来。

源码导读：一个请求的生命周期

入口：Request.vue 是 REST 标签页组件，URL、参数、Header 都在这一层编辑。
发送：点 Send 后走 RequestRunner.ts，它先做环境变量的变量替换，再执行 Pre-request 脚本和 Test 断言，脚本运行在 hoppscotch-js-sandbox 的隔离沙箱里。
网络层：hopp-fetch.ts 把请求转成 RelayRequest，交给拦截器决定走浏览器、代理、扩展还是桌面原生通道，绕开 CORS 限制。
渲染：Response.vue 负责状态码、耗时和 Body 展示。
落库：集合和环境存在 collections.ts 与 environments.ts，登录后经 helpers/backend/ 的 GraphQL 文件同步到后端，由 NestJS + Prisma 写入 PostgreSQL。

推荐阅读顺序：Request.vue 看界面 → RequestRunner.ts 看流程 → hopp-fetch.ts 看网络 → 最后翻 backend 里的 GraphQL 文件看数据怎么回写。

部署与配置

核心配置文件只有一个：根目录 .env.example 复制成的.env。其余保持默认即可，只改下面这几个：

变量	作用	默认值风险
`DATA_ENCRYPTION_KEY`	32 位落库加密密钥	示例值是明文占位，不改等于敏感数据未加密
`DATABASE_URL`	PostgreSQL 连接串	默认指向 compose 内置库，接外部库要同步改 compose 里的同名变量
`VITE_BACKEND_GQL_URL`	前端连后端的 GraphQL 地址	换了端口没改这里，页面会一直转圈连不上后端

桌面端连接自托管实例后的实际界面，与 Web 版共用同一套代码。

容易踩的坑

容器起不来 → 忘了cp .env.example .env，env_file指向的文件缺失 → 先建文件再跑 compose。
登录后数据同步一直失败 →VITE_BACKEND_GQL_URL还指向http://localhost:3170/graphql，但部署环境域名不同 → 按实际后端地址改.env后重建容器。
升级后页面报错、接口类型对不上 → 后端 schema 变了但前端 GraphQL 类型没重新生成 → 重跑依赖里的 codegen（配置在 gql-codegen.yml），细节以仓库最新版本为准。
改了端口却访问不通 → 端口映射写在 docker-compose.yml，.env里的VITE_*是前端视角的地址，两边都要改。