简介：面向前端开发者与接口测试人员的 Hoppscotch 开源 API 调试工具源码包，基于 Vue 与 Node.js 构建，提供直观界面与多种 HTTP 请求方法支持，适合日常接口联调、问题定位与 API 调用过程优化，对具备一定前后端基础的初中级开发者尤为友好。压缩包共 1376 个文件、约 5.28MB，以 592 个 TypeScript 文件与 211 个 Vue 组件为主体，构成核心业务逻辑与界面层；另有 203 个 GraphQL 文件、120 个 JSON 配置、69 个 SVG 图标及若干 JS、SCSS、Dockerfile、Caddyfile 与 Prisma 相关文件，覆盖接口定义、样式资源、容器化部署与自托管配置等环节。已有 914 人学习下载。借助完整的工程目录，读者可梳理前后端分层结构、请求处理链路与 GraphQL 查询组织方式，并参考 Docker、Caddy 配置完成本地运行与自托管实践，也可据此二次开发或定制调试界面。
1. 从一次「请求打不开」说起：开源 API 调试工具 Hoppscotch 到底该装哪一版
上周帮人看一个联调现场，接口在本机用 curl 打是通的，换到浏览器里打开调试页面，一按发送就是一片红，控制台里全是跨域和 404。折腾半小时才发现，问题不在接口，在装法：那台机器上跑的是自托管的一套 Hoppscotch，前端容器起来了，后端地址还停在默认的 localhost，页面能打开，请求全打到空处。
开源 API 调试工具 Hoppscotch 就这点容易让人翻车。它不是双击就能用的单文件工具，而是三条完全不同的安装路线：浏览器里直接用的 Web 版、装在本机的桌面客户端、以及用 Docker 自己拉起来的一整套服务端加前端。三条路线的依赖、配置项、坏掉之后的救法都不一样，装错一条，后面全是无用功。这篇笔记按我自己反复装过的顺序，把环境清单、安装步骤、参数取舍和排查方式一次写清，适合要长期做接口联调、要跑集合回归、或者团队想自己托管一套调试面板的人照着走。
2. 三条安装路线的取舍：Web 版、桌面端与自托管分别要准备什么环境
动手之前得先决定装哪一套，这一步选错，后面改起来比重装还费劲。三条路线的差别不在功能多少，而在数据放在哪、谁能访问、坏了谁负责。我一般按「团队规模」和「接口数据敏不敏感」两个维度来定，而不是按「哪个看起来方便」。
2.1 Web 版、桌面端与自托管服务的边界
浏览器 Web 版就是打开官方站点直接用，零安装，请求记录存在浏览器本地存储里。好处是换台机器登录就能接着用，坏处是数据在你自己的浏览器里，清个缓存就没了，也没法给同事共享一个集合。
桌面客户端是把同一套界面打包成 Electron 应用，装在 Windows、macOS 或 Linux 上。它和 Web 版共用账号体系，但多了一层本地能力：不受浏览器同源策略影响，读本地文件、导入导出集合更顺，断网时也能翻看已经同步下来的内容。日常一个人调接口，我基本只用桌面端。
自托管是真正意义上的「部署」：用 Docker 把后端服务、管理后台、前端页面、PostgreSQL 和 Redis 一起拉起来，数据落在自己的数据库里，团队成员用同一个域名登录，集合和环境变量能共享。代价是要维护容器、要配邮件服务、要考虑升级，装一次大概半小时到一小时。
提示：只想调几个接口，别碰自托管。桌面端加 CLI 已经够用，自托管的价值在「多人共享」和「数据不出内网」，没有这两个需求，多出来的维护成本全是负担。
2.2 依赖盘点：Node、Docker、PostgreSQL 与端口占用
三条路线的依赖差别很大，装之前先把下面这张表对一遍，缺什么补什么，比装到一半再回头找要快得多。
| 路线 | 必需依赖 | 建议版本 | 是否需要数据库 |
|---|---|---|---|
| 浏览器 Web 版 | 现代浏览器 | 近两年内的 Chrome / Edge / Firefox | 否 |
| 桌面客户端 | 系统运行库 | Windows 10 以上 / macOS 12 以上 / 主流 Linux 发行版 | 否 |
| 自托管服务 | Docker 与 Compose 插件 | Docker 20.10 以上，Compose V2 | 是，容器内自带 PostgreSQL |
| CLI 跑测 | Node.js | 18 LTS 或 20 LTS | 否 |
自托管这条路线对端口比较挑。默认情况下后端服务占 3170，管理后台占 3100，前端页面占 3000，PostgreSQL 占 5432，Redis 占 6379。一台机器上如果已经跑着别的数据库或者别的 Node 服务，5432 和 3000 是最容易撞的两个。装之前先跑一遍ss -lntp看一眼，撞了就在 compose 文件里改宿主机侧端口，别去改容器内端口，否则前端里写死的后端地址会跟着一起错。
Node 版本这块有个血泪经验：CLI 在 Node 16 上装得上但跑测试集合时会报模块解析错误，18 LTS 是底线。机器上如果同时有几个项目，建议用 nvm 或 fnm 管版本，别去动系统自带的那个。
2.3 版本选择与下载渠道的确认
Hoppscotch 的发布节奏比较快，桌面端和自托管镜像的版本号不一定同步，所以「装最新版」这句话要拆开看。
桌面端从项目的 Releases 页面下载对应平台的安装包，Linux 一般给.deb、.rpm和.AppImage三种，macOS 给.dmg，Windows 给.exe。我一般选.deb或.rpm，走系统包管理器，卸载干净、依赖也自动补齐；.AppImage适合没有 root 权限的机器，chmod 加执行权限就能跑，但不会自动建桌面图标。
自托管不从 Releases 下二进制，而是拉源码仓库，用仓库里自带的docker-compose.yml构建或者拉现成镜像。这里有个取舍：跟主分支构建能拿到最新功能，但接口和数据库结构偶尔会变；跟打好的 tag 走，稳妥但功能滞后。生产环境我一律锁 tag，测试机才跟主分支。
CLI 走 npm 全局安装，包名是@hoppscotch/cli。装之前确认npm config get prefix指向的目录在 PATH 里，否则装完会提示命令找不到。
版本这块最容易忽略的是「桌面端和服务端的兼容性」。自托管服务端升级到新的大版本后，旧版桌面端登录可能会提示接口不匹配，这时候要么一起升，要么先在服务端把兼容开关打开，别单升一头。
3. Docker Compose 拉起自托管服务：Hoppscotch 后端、前端与数据库的完整配置
自托管是这套工具里最值得写细的部分，因为它的失败模式几乎全在配置上，而不是在安装动作上。整个流程可以拆成四步：拿代码、改环境变量、起容器、挂前置转发。下面每一步我都会说明白改的是哪个值、为什么改、改错了会看到什么现象。
3.1 拉取仓库与 docker-compose 文件的结构
先找一个有 Docker 权限的目录，把仓库拉下来。不要用sudo拉，否则后面挂载卷的时候文件属主会乱。
# 拉取仓库，锁定到发布 tag 而不是主分支 git clone --depth 1 --branch <发布tag> https://github.com/hoppscotch/hoppscotch.git cd hoppscotch # 看一眼 compose 文件里定义了哪些服务 grep -n "image:\|container_name:\|ports:" docker-compose.yml--depth 1只拉最近一次提交，仓库历史比较大，全量拉会慢很多。--branch后面换成具体的 tag 名，别直接跟main，主分支的 compose 文件偶尔会引用还没发布的镜像。
grep那一步是为了确认服务名。不同版本的 compose 文件里，服务可能叫backend、hoppscotch-backend或者带前缀的别的名字，后面看日志、进容器都要用这个名字，先记下来比事后猜强。典型的一套服务大概长这样：
- 一个后端服务，承载 GraphQL 接口和 WebSocket
- 一个管理后台，独立端口，用来管用户和全局设置
- 一个前端页面服务，就是用户看到的那个界面
- 一个 PostgreSQL 容器，存用户、集合、环境变量
- 一个 Redis 容器，做会话和短期缓存
前端、后端、管理后台是三个独立容器，这点很多人第一次装会搞混，以为只有一个。三个都起来了，页面才完整。
3.2 环境变量与数据库连接参数
仓库根目录一般带一个.env.example，复制成.env再改。这一步是整套部署里最容易出错的地方，因为变量名在不同版本之间改过，抄网上的配置经常对不上。
cp .env.example .env # 生成一个强随机密钥，别用默认值，也别手打 openssl rand -base64 32 # 生成后填进 .env 里的 JWT_SECRETJWT_SECRET是签发登录令牌用的，默认值必须换掉，否则任何人拿到默认值就能伪造令牌。openssl rand -base64 32出来的字符串直接整段粘进去，不要自己加引号，也不要留换行。
下面几个变量是我每次都会逐条确认的：
| 变量 | 作用 | 常见写法 |
|---|---|---|
DATABASE_URL | 后端连 PostgreSQL 的连接串 | postgresql://用户:密码@postgres:5432/库名 |
JWT_SECRET | 登录令牌签名密钥 | 上面生成的随机串 |
REDIS_URL | 会话缓存地址 | redis://redis:6379 |
VITE_BASE_URL | 前端访问入口地址 | https://你的域名 |
VITE_BACKEND_GQL_URL | 前端请求后端的 GraphQL 地址 | https://你的域名/backend/graphql |
VITE_BACKEND_WS_URL | WebSocket 地址 | wss://你的域名/backend/graphql |
带VITE_前缀的这几个是在前端构建时写进静态文件的，改完必须重新构建前端镜像，光重启容器不生效。这是第一个大坑，后面排查章里还会提到。
DATABASE_URL里的主机名要写 compose 文件里的服务名，不是localhost。容器之间走的是内部网络，写localhost等于让后端去连自己容器里的 5432，那里什么都没有，表现就是启动日志里反复重连数据库。
注意：
.env不要提交到任何仓库，也不要在 compose 文件里把密码写死。团队部署时把.env单独发给运维，其他人只拿docker-compose.yml。
3.3 启动、查看日志与首次初始化
配置改完就可以起了。第一次起建议前台跑，能直接看到初始化输出。
# 第一次前台启动，观察建表和迁移日志 docker compose up # 确认没问题之后改成后台 docker compose up -d # 只看后端日志，服务名按 3.1 里查到的填 docker compose logs -f backend前台启动时会看到 PostgreSQL 初始化、数据库迁移、后端监听端口这几段输出。迁移那一段最值得盯：如果它卡住或者报 relation 不存在的错，说明DATABASE_URL指向的库和迁移脚本用的库不是同一个，或者数据库卷是上一次没清干净的旧数据。
首次启动还要建管理员账号。有的版本会在后端启动时打印一个初始管理员邮箱和密码，有的版本需要进管理后台手动创建。管理后台在 3100 端口，进去之后第一件事是建用户、确认全局设置里的「允许注册」是不是你要的状态。
还有一个必须配的东西：邮件服务。自托管默认用邮件魔法链接登录，不配 SMTP 的话，用户在登录页输入邮箱，页面提示「已发送」，但邮件永远发不出来。表现特别迷惑，因为前端不报错。要么把 SMTP 参数补齐，要么在管理后台直接给用户建密码，走密码登录。
# 确认容器都处于运行状态，而不是 exit 或者 restarting docker compose ps # 进数据库看表有没有建出来 docker compose exec postgres psql -U <用户> -d <库名> -c "\dt"docker compose ps输出里如果某个服务状态是restarting，基本可以断定是环境变量不对导致启动即崩，直接看那个服务的日志，别去看前端的报错。psql那条是最后一道确认，表建出来了，说明迁移跑完了。
3.4 前置转发与 HTTPS 的基本配置
自托管服务默认是 HTTP，浏览器里用 HTTP 访问会有两个后果：一是密码明文传输，二是部分浏览器特性在非安全上下文里会被限制。所以还得在前面挂一层 Nginx 做转发和证书。
server { listen 443 ssl; server_name api.example.internal; ssl_certificate /etc/nginx/certs/fullchain.pem; ssl_certificate_key /etc/nginx/certs/privkey.pem; # 前端页面 location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; } # 后端接口，路径要和 VITE_BACKEND_GQL_URL 对上 location /backend/ { proxy_pass http://127.0.0.1:3170/; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header X-Forwarded-Proto $scheme; } }三处要特别注意。第一，location /backend/的路径前缀必须和.env里VITE_BACKEND_GQL_URL的路径部分一致，前端是按那个地址发请求的，前缀对不上就是 404。第二，proxy_pass结尾带不带斜杠语义不同，带斜杠会把这个前缀从转发路径里去掉，这里要保持和前端配置的路径逻辑一致。第三，Upgrade和Connection这两行是给 WebSocket 用的，Hoppscotch 的部分功能依赖长连接，少了这两行，页面能开但实时功能会静默失效。
改完配置先nginx -t验一遍语法再 reload，别直接重启，语法错会导致整个网关起不来，连带其他站点一起挂。
4. 桌面端与 CLI 补全本地链路：Hoppscotch 客户端的安装与集合跑测
自托管解决的是团队共享，日常一个人调接口，桌面端加 CLI 的组合效率更高。这一章讲这两样怎么装、装完怎么和自托管服务对接，以及数据怎么在几台机器之间搬。
4.1 Linux 桌面端的安装与首启动
Debian 系和 Red Hat 系分别用对应的包，装完在应用菜单里能找到图标。
# Debian / Ubuntu sudo dpkg -i hoppscotch-desktop_<版本>_amd64.deb sudo apt-get install -f # 补齐可能的依赖缺失 # Fedora / RHEL sudo rpm -ivh hoppscotch-desktop-<版本>.x86_64.rpm # 没有 root 权限时用 AppImage chmod +x Hoppscotch-<版本>.AppImage ./Hoppscotch-<版本>.AppImagedpkg -i报依赖错误是常事，接着跑apt-get install -f让它自动修，别一条条手动装依赖。AppImage 方式要注意：直接双击可能因为缺少 FUSE 而启动失败，装libfuse2或者加--appimage-extract-and-run参数都能绕过。
首次启动会让你选「本地模式」还是「登录账号」。本地模式数据只在这台机器上，不联网；登录模式会跟服务端同步。团队里用自托管的，要在这里把服务端地址改成自己的域名，否则会连到官方服务上去，登录不上还以为是账号问题。
Linux 下还有一个细节：桌面端默认使用系统钥匙串存令牌，某些精简版发行版没有 gnome-keyring，表现是登录成功后重启又退回未登录状态。装一个gnome-keyring或者kwallet就能解决。
4.2 hoppscotch-cli 的安装与集合跑测
CLI 是把集合当测试用例跑的工具，适合接到流水线里做接口回归。
# 全局安装，注意 Node 版本至少 18 npm install -g @hoppscotch/cli # 确认装上了 hopp --version装完先跑一次hopp --version，如果提示命令不存在，多半是 npm 全局 bin 目录不在 PATH 里，用npm config get prefix看一下实际路径，加进 PATH 再试。
跑集合的基本命令是这样：
# 跑一个导出的集合文件，指定环境文件 hopp test ./collections/order-api.json \ --env ./envs/staging.json \ --reporter-junit ./reports/hopp.xml \ --delay 200 # 数据驱动：用一份 JSON 数组做多轮迭代 hopp test ./collections/order-api.json \ --iteration-data ./data/cases.json \ --iteration-count 5--env指定环境变量文件，里面的变量名要和集合里引用的对上，对不上会直接报变量未定义。--reporter-junit输出 JUnit 格式，Jenkins、GitLab CI 这类流水线都能直接解析，比看控制台输出可靠。--delay是每轮请求之间的间隔毫秒数，接口有频率限制时必须加，不加就是一片 429。--iteration-data配合--iteration-count做参数化，适合拿一份用例表跑同一组接口。
集合文件从桌面端导出，导出时记得勾上「包含环境变量」，否则变量会变成空值。环境文件里的敏感信息（token、密码）别提交到仓库，用 CI 的变量注进去。
4.3 数据导入导出与跨机器迁移
Hoppscotch 支持的导入格式比较全：自家导出的 JSON、OpenAPI/Swagger 文档、Postman 集合、curl 命令，都能直接粘进去。桌面端和 Web 版在导入入口上略有差别，桌面端还能直接从本地文件读。
跨机器迁移有两个思路。一是走账号同步：在 A 机器登录，集合自动同步到服务端，B 机器登录同一个账号就能看到。前提是服务端跑着，且同步开关是开的。二是走文件：在 A 机器导出集合 JSON，拷到 B 机器导入。前者省事，后者不依赖网络，我一般在迁移前两种都做一遍，文件当备份。
导入 Postman 集合时有个已知差异：Postman 的预请求脚本语法和 Hoppscotch 的脚本环境不完全兼容，复杂脚本会被跳过或者报错。导入后别急着跑，先打开几个关键请求看一眼脚本有没有被正确识别。
5. 装完起不来怎么救：Hoppscotch 部署里最常见的五类翻车
下面这五条都是我自己踩过或者帮人处理过的，按出现频率排。每条都按「看到什么现象、根子在哪、怎么处理」写，照着对号入座基本能定位。
5.1 容器全绿但页面 502
现象：docker compose ps里所有服务都是 Up，浏览器打开域名却是 502 Bad Gateway。
原因：前置 Nginx 转发到的宿主机端口和容器实际映射出来的端口对不上。compose 文件里ports:写的是3000:3000，容器内是 3000，宿主机也是 3000，但 Nginx 里写成了别的端口；或者容器起来的其实是另一个 compose 项目的同名服务。
解决：先用docker compose port <服务名> <容器内端口>确认实际映射，再核对 Nginx 的proxy_pass。改完nginx -t再 reload。顺手用curl -I http://127.0.0.1:3000从宿主机直连一次，能通说明问题在网关，不通说明问题在容器。
5.2 后端反复重启，日志停在数据库连接
现象：后端容器状态一直restarting，日志最后一行是连接 PostgreSQL 超时或者认证失败。
原因：三种可能。DATABASE_URL里的主机名写成了localhost；密码里有@、#这类特殊字符没做 URL 编码；或者上一次部署留下的数据卷里存的是旧密码，新配置对不上。
解决：先docker compose exec postgres psql -U <用户> -d <库名>手动连一次，连不上就是认证问题。密码含特殊字符的，用 URL 编码后的形式写进连接串。数据卷冲突的，确认没有重要数据后docker compose down -v清卷重来，注意这个-v会把库一起删掉。
5.3 改了前端地址但页面还连旧后端
现象：.env里的VITE_BACKEND_GQL_URL已经改成新域名，重启容器后前端请求还是发到旧地址。
原因：VITE_前缀的变量在构建阶段就被打进静态文件了，运行时的环境变量对它无效。只重启容器不会重新构建镜像。
解决：加--build参数重新构建前端镜像，docker compose up -d --build web-app。构建完清一下浏览器缓存再打开，否则加载的还是旧 JS。这一点最容易让人误判成「配置没生效」，实际是构建产物没换。
5.4 登录后立刻掉线，或者一直提示未授权
现象：能进登录页，验证码或密码提交成功，跳回首页又变成未登录。
原因：走了 HTTPS 但后端没识别出协议，Cookie 的 Secure 属性判定失败；或者 Nginx 没把X-Forwarded-Proto头传下去，后端以为自己是 HTTP。
解决：检查 Nginx 配置里每个 location 都有proxy_set_header X-Forwarded-Proto $scheme;。另外确认前端入口地址和实际访问的协议一致，.env里写http://、实际用https://访问，同样会掉登录。改完前端变量要按上一条重新构建。
5.5 桌面端白屏或者启动即退
现象：AppImage 双击没反应，或者窗口出来一片白。
原因：Linux 下常见的是缺 FUSE、缺系统钥匙串、或者显卡驱动和 Electron 的硬件加速冲突。Windows 下多见于安装包不完整或者被安全软件拦了某个 dll。
解决：AppImage 先试--appimage-extract-and-run，能跑就是 FUSE 问题。白屏的话加--disable-gpu启动一次，能出界面就是硬件加速的问题，可以在启动参数里长期关掉。钥匙串缺失按 4.1 里说的装组件。
6. 验证跑通：用一条真实请求把 Hoppscotch 全链路点一遍
装完不算完，得有一条能从头走到尾的验证路径。我一般不看「页面能打开」这种表面信号，而是拿一条会经过认证、会读写数据库的请求走一遍，链路上任何一环断了都会立刻暴露。
第一步验证服务端。在宿主机上直接打后端的健康检查或者 GraphQL 端点：
# 直连后端容器映射出来的端口，绕开网关 curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3170/ # 再走一遍网关，两次结果应该一致 curl -s -o /dev/null -w "%{http_code}\n" https://api.example.internal/backend/两次都返回 200 或者 400（GraphQL 对 GET 请求的正常反应）说明转发链路通了；直连通、走网关不通，问题在 Nginx；两次都不通，回去看后端日志。
第二步验证数据链路。在桌面端新建一个集合，发一条 POST 请求打自己的业务接口，然后刷新页面重新登录，看这条记录还在不在。在，说明写入和读取都经过数据库了，会话也没问题。
第三步验证跨端。把这条集合从桌面端导出，用 CLI 跑一遍：
hopp test ./collections/smoke.json --env ./envs/local.jsonCLI 能跑通，说明集合格式、环境变量、认证头这三样在端到端之间是一致的。这一步挂了，通常是环境变量里的 token 过期，或者集合里引用的变量名和 env 文件对不上。
第四步，把所有容器的重启策略设成unless-stopped，然后docker compose restart一次，等两分钟再重复第一步。很多配置问题是「第一次能跑、重启就崩」，不特意重启一遍根本发现不了。
从那以后我每次装完这套，不管多急，都强制走一遍「直连、走网关、桌面端读写、CLI 跑测、重启复验」这五步，一步不省。有次赶时间跳过了重启复验，第二天早上容器全挂，排查下来是数据卷权限在重启后变了，前面四步全绿也没用。希望这套流程能帮到你，少走一遍我踩过的弯路。
本文还有配套的精品资源，点击获取
