Hoppscotch这个API调试工具，我用了快三年，从它还叫Postwoman那会儿就开始关注。当时吸引我的就一点：轻。浏览器里打开就能用，发请求、看响应、测WebSocket，完全不用像Postman那样装一个笨重的桌面客户端，也不用登录什么云账号去同步数据。后来团队做接口联调，需要在内网环境统一一套API测试工具，我自然想到了自托管Hoppscotch。从Docker Compose部署、源码构建到云端平台折腾了个遍，期间踩了不少坑，也积累了一些实际经验。这篇指南就把Hoppscotch的安装与部署完整写出来，包含部署前的选型思路、三种部署方式的详细步骤、环境变量配置要点，以及部署后常见问题的排查思路，给想自托管API调试工具的个人或团队做个参考。
1. Hoppscotch是什么，为什么值得自己部署
1.1 它到底解决了什么问题
Hoppscotch最早叫Postwoman，是个开源项目，定位非常明确——做Postman的开源替代品。项目至今仍在持续迭代，核心能力包括这几块：
- REST API调试：最常用的场景。输入URL、配好Header和Body，就能发GET/POST/PUT/DELETE请求，状态码、耗时、响应体一屏看完。
- GraphQL支持：可以直接在请求面板里写GraphQL查询语句和变量，调试GraphQL接口不需要再另外开工具。
- 实时协议调试：WebSocket、SSE（Server-Sent Events）、Socket.IO都能测，做消息推送类接口联调时特别好用。
- 集合（Collections）与环境（Environments）管理：按项目分组的接口集合，配合环境变量在dev、staging、prod之间一键切换。
- 历史记录与键盘快捷键：发过的请求自动保留，配合快捷键操作，效率比鼠标点来点去高不少。
它的核心卖点是轻量、快速、开源。前端基于Vue/Nuxt构建，页面响应速度比Electron套壳的桌面应用快一个量级，用起来不肉。我也不是说Postman不好，Postman胜在生态成熟、团队协作功能完善，如果你的团队已经在Postman上沉淀了大量接口数据，迁移成本确实不低。但如果是新团队起步，或者受够了客户端越来越臃肿、启动越来越慢的体验，Hoppscotch值得认真试试。
1.2 自部署的价值：数据可控与内网可达
Hoppscotch有公共在线版（hoppscotch.io），浏览器直接访问就能用。那为什么还要自己部署？我总结下来有三个很现实的原因：
第一，数据不出内网。公共在线版虽然可以把数据存在浏览器本地，但一旦登录账号或者使用云同步，请求记录、环境变量、集合数据就会上第三方服务器。很多公司内部的接口信息、合作伙伴的业务数据都牵扯敏感内容，数据放别人平台在合规上就是问题。自部署后，所有数据都落在自己的PostgreSQL数据库里，可备份、可迁移、可销毁，完全可控。
第二，内网接口只有内网能访问。公共在线版跑在浏览器上，你的浏览器能访问公司内网IP，不代表公共网站的JavaScript也能访问——浏览器跨域限制和混合内容安全策略会把请求挡掉。而把Hoppscotch部署到内网服务器，团队所有人访问同一个地址，调试内网接口就是顺理成章的事。
第三，可以做二次开发。源码全部开放，改主题、改logo、接公司现有的OAuth登录体系、甚至魔改后端逻辑都不受限制。
当然，自部署也有代价：你需要维护服务器、处理数据库升级、定期做备份。所以我的建议是——个人偶尔用，直接用公共版就够；团队正式使用，优先自部署。
| 对比项 | Hoppscotch自部署 | Hoppscotch公共版 | Postman客户端 |
|---|---|---|---|
| 数据存储 | 自建PostgreSQL | 浏览器本地/云同步 | 云端账号 |
| 内网API调试 | 完全支持 | 受限 | 本机可调 |
| 部署成本 | 需一台服务器 | 免费 | 需安装客户端 |
| 二次开发 | 开源可改 | 不可改 | 插件扩展 |
| 协作方式 | 自建用户体系 | 单机为主 | 团队云协作 |
2. 部署方式选型：Docker、源码还是云平台
2.1 三条路线怎么选
Hoppscotch自部署目前主流有三条路线，没有绝对好坏，主要看你的条件和目的。
Docker部署是我最推荐给大多数团队的方式。官方提供了Web端和Server端的Docker镜像，配一个PostgreSQL服务，用Docker Compose就能把三个服务一次性编排起来，整个过程大概十来分钟。不需要懂Node.js，也不需要手动装数据库，非常适合没有专职运维、又想快速用起来的小团队。
源码部署就是从GitHub拉代码，自己安装依赖、构建前端、启动后端。优点是能改代码、能精确锁定版本，缺点是流程长、坑多——Node版本不对、原生模块编译失败都可能让你卡一下午。适合要做二次开发的团队，或者出于安全要求需要对代码做审计的场景。
云端平台部署适合没有服务器的人。用Railway、Render这类PaaS平台，可以选Hoppscotch模板一键拉起，前端、后端、数据库都给你托管好，还有免费额度。适合个人开发者快速体验自部署，或者临时搭一套给别人演示。
我的建议排序是：长期团队使用选Docker；只是个人尝鲜或演示选云端平台；明确要改代码了再走源码部署。不要一上来就源码编译，那往往不是最高效的路。
2.2 环境准备清单
不管选哪条路，先搞明白Hoppscotch部署架构的三大件：
- 前端（hoppscotch-web）：Nuxt构建的静态站点，需要nginx这类Web服务器托管，用户打开浏览器看到的就是它。
- 后端（hoppscotch-server）：NestJS框架写的Node.js服务，处理登录、用户、集合、历史记录等API请求，并和数据库打交道。
- 数据库（PostgreSQL）：所有用户数据、集合数据、环境变量配置都存在这里，是整个系统里唯一需要持久化的部分。
硬件要求不用太紧张。一套最小部署（PostgreSQL + Server + Web）大概占用600MB到1GB内存，1核2G的入门云主机就能跑得很舒服。数据量大的团队主要关注磁盘，PostgreSQL的数据目录要给足空间，并提前规划备份策略。
软件方面，Docker方式要求Docker Engine 20+和Docker Compose v2；源码方式要求Node.js 18+（我推荐20 LTS）、npm或pnpm 8+、PostgreSQL 13+。这里我要专门强调一句：很多人在源码部署时卡在Node版本上，新版Hoppscotch对Node版本要求不低，老版本Node 16跑起来会报各种奇怪的错。动手前先装个nvm把Node切到18或20，能省掉一半的排查时间。
2.3 端口规划提前想好
默认情况下，Web静态站监听80端口（Docker容器内），Server后端监听3000端口。如果你本机80端口已经被别的服务占了，可以在映射时改成其他宿主机端口，比如8080:80。3000端口同理，可以映射成3001:3000。
端口规划会影响后面环境变量里的URL配置。动手之前先想清楚：对外最终用什么地址访问？Web和Server要不要同一个域名？这些决定了CORS配置要不要额外处理，也会影响TOKEN_SECRET、WEB_URL等环境变量的取值。别小看这一步，我见过不少部署完连不上、最后发现是端口映射和URL配置不一致导致的。
3. Docker部署：十分钟跑通一条生产级链路
3.1 编写docker-compose.yml
Docker方式最稳妥的做法，是用Docker Compose编排三个服务。先创建一个目录用来放配置和数据：
mkdir -p /opt/hoppscotch && cd /opt/hoppscotch然后创建docker-compose.yml文件，下面是我在生产环境验证过的版本，加了注释方便理解：
version: "3.8" services: postgres: image: postgres:15-alpine restart: unless-stopped environment: POSTGRES_USER: hoppscotch POSTGRES_PASSWORD: hoppscotch_pass POSTGRES_DB: hoppscotch volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U hoppscotch"] interval: 5s timeout: 5s retries: 12 server: image: hoppscotch/hoppscotch-server:latest restart: unless-stopped depends_on: postgres: condition: service_healthy environment: PORT: 3000 DATABASE_URL: postgresql://hoppscotch:hoppscotch_pass@postgres:5432/hoppscotch TOKEN_SECRET: "请改成足够长的随机字符串" WEB_URL: "http://localhost:8080" ports: - "3000:3000" web: image: hoppscotch/hoppscotch-web:latest restart: unless-stopped depends_on: - server environment: VITE_API_URL: "http://localhost:3000" ports: - "8080:80" volumes: postgres_data:这个文件里有几个关键点想单独说一下。
第一，我给postgres加了healthcheck健康检查，server启动前会等数据库完全就绪。很多部署失败的场景就是server先于数据库启动、连不上数据库直接退出，然后无限重启。用depends_on配合condition: service_healthy能干净地解决这个问题。这是我加的最实用的一处改动。
第二，TOKEN_SECRET是后端签发JWT用的密钥，千万不能是示例里的值。生产环境务必改成足够长的随机字符串，直接执行openssl rand -hex 32生成一个。如果这个密钥泄露，别人就可以伪造令牌冒充合法用户，后果比数据库密码泄露还严重。
第三，WEB_URL要填前端最终对外访问的地址。比如你打算通过http://192.168.1.10:8080访问，就填这个。Server会用这个地址做CORS校验和回调跳转，填错了登录、请求都会有奇怪的表现。
3.2 启动与首次验证
配置文件写好之后，直接执行：
docker compose up -d docker compose ps正常情况下三个服务的状态都会是running。第一次启动需要拉镜像，耐心等一会儿。启动后可以看一眼server的日志：
docker compose logs -f server看到类似Application started successfully或者Server is listening on port 3000的日志，说明后端已经起来了。然后打开浏览器访问http://你的服务器IP:8080，就能看到Hoppscotch的登录注册界面。
首次使用直接注册一个本地账号即可。注册成功后，顺手做个最简单的验证：在请求地址栏输入https://httpbin.org/get，点发送，能正常返回JSON就说明整条链路已经通了。如果公司内网访问不了外网，也可以随便请求一个内网的健康检查接口做验证。
3.3 生产环境上线前要补的几件事
如果这套Docker部署要长期给团队用，我建议再补三件事：
- 改掉所有默认密码。包括PostgreSQL的密码和TOKEN_SECRET，不要用示例文件里的值。
- 给Web端加HTTPS。最简单的做法是前面再套一层nginx或Caddy做TLS终止，这个在后面的排错章节我会给出配置示例。
- 配置PostgreSQL自动备份。用cron定时执行
pg_dump，备份文件存到独立目录或对象存储里，别跟数据库数据盘放在一起。
4. 源码部署：二次开发的完整路线
4.1 拉代码与安装依赖
如果你要改代码、做代码审计，或者Docker镜像在当前环境拉不下来，就走源码路线。Hoppscotch是一个monorepo仓库，前端在packages/hoppscotch-web目录，后端在packages/hoppscotch-server目录。
拉取代码并安装依赖：
git clone https://github.com/hoppscotch/hoppscotch.git cd hoppscotch cp .env.example .env nvm use 20 # 确保Node在18以上，推荐20 LTS npm install这里先讲讲依赖安装的坑。Hoppscotch的依赖数量不少，npm安装可能要花好几分钟，中间偶尔会遇到某个原生模块编译失败的情况。多数时候是node-gyp相关的问题，先确认系统装了python3和build-essential。另外把npm registry切到国内镜像能明显加快速度：
npm config set registry https://registry.npmmirror.com如果安装过程中遇到"node版本不兼容"之类报错，先回头检查Node版本。实测下来Node 16跑新版Hoppscotch几乎必挂，Node 18是底线，Node 20 LTS最稳。
4.2 数据库准备与环境变量
源码部署同样需要PostgreSQL。建议单独建一个数据库给Hoppscotch使用：
sudo -u postgres psql CREATE USER hoppscotch WITH PASSWORD 'hoppscotch_pass'; CREATE DATABASE hoppscotch OWNER hoppscotch; \q然后在.env文件里配置连接信息。需要关注的核心变量：
DATABASE_URL或PG_DATABASE_URL：PostgreSQL连接串，格式是postgresql://用户名:密码@主机:端口/数据库名。TOKEN_SECRET：JWT密钥，改成随机长字符串。WEB_URL：前端最终访问的URI。PORT：后端监听端口。
另外一个容易被忽略的是SMTP配置。新版Hoppscotch后端在注册用户时，如果配置了SMTP会发送验证邮件；如果没配SMTP，部分版本会跳过邮件验证直接放行，部分版本则可能导致注册后的账号无法正常登录。我建议在.env里把SMTP相关变量也填上——没有企业邮箱就用测试邮件服务。如果你用的是旧版本且关闭了邮件验证，确认一下行为是否符合预期，免得部署完发现注册不了账号，那就尴尬了。
4.3 构建与启动
开发模式调试可以直接：
npm run dev前端默认跑在localhost:3000，后端端口看.env配置。开发模式支持热更新，改代码即时生效，做二次开发时很顺手。
生产模式则需要先构建再启动：
npm run build npm run start构建前端资源比较吃内存，2G内存的机器构建时可能会卡甚至被OOM杀掉。建议构建环境内存给到4G，或者设置NODE_OPTIONS="--max-old-space-size=2048"限制Node堆内存。构建产物在packages/hoppscotch-web/dist目录下，用nginx指过去就能托管。
给个总结性建议：如果不是为了改代码，真没必要走源码这条路线——依赖安装和版本兼容的坑能占掉你一个下午。但如果你要接公司登录系统、改品牌样式，源码路线是绕不开的。
5. 云端平台部署：没有服务器也能跑起来
5.1 整体思路：三个组件各司其职
云端部署不等于"点一下就好"。Hoppscotch的web、server、postgres三个组件都需要有地方跑。像Vercel这种纯静态托管平台只能部署前端，server和数据库还得另找地方。所以更实际的选择是Railway、Render这类支持完整后端托管的PaaS平台，它们可以同时创建Node服务和PostgreSQL数据库。
以Railway为例，它支持一键模板部署Hoppscotch：在Dashboard里搜索Hoppscotch模板，点Deploy，平台会自动创建PostgreSQL实例、Server服务和Web服务，并把环境变量串联好。这是目前云端部署里最省心的方式。
如果你不用模板，手动创建也简单，核心是把下面三个环境变量配置正确：
| 服务 | 关键环境变量 | 说明 |
|---|---|---|
| postgres | POSTGRES_USER / PASSWORD / DB | 创建数据库实例时自动生成 |
| server | PORT=3000、DATABASE_URL、TOKEN_SECRET、WEB_URL | 连接数据库实例，配置JWT密钥 |
| web | VITE_API_URL | 指向server服务的公网域名 |
5.2 域名与HTTPS配置
云端平台一般都会自动分配一个HTTPS域名，比如xxx.up.railway.app。如果你希望用自定义域名，需要在平台绑定域名，并在DNS服务商那里加一条CNAME记录。这里有个容易踩的坑：换成自定义域名之后，之前设置的WEB_URL和VITE_API_URL必须同步更新成最终域名，否则会出现页面能打开、但发请求报CORS错误的情况。
5.3 免费额度的边界
Railway和Render的免费额度对轻量使用是够的，但要注意：免费实例如果长时间没有请求可能会休眠，下一次访问要等冷启动，体验上会有明显延迟。Hoppscotch是高频工具类应用，团队使用的话还是建议上付费实例，或者干脆迁回自建Docker部署，长期成本更低。
有人问过能不能把Hoppscotch全站部署到Vercel。答案是Vercel只适合托管Web静态文件，Server后端必须放在支持常驻Node进程的平台。如果已经用Vercel托管了Web，Server可以放到Railway，再把VITE_API_URL指向Railway的Server地址，同样能用，但跨域要自己处理。我觉得不如直接用Railway模板省事。
6. 部署之后的高频翻车现场与排查思路
6.1 Server无限重启：多半是数据库没连上
这是Docker部署最常见的翻车现场。现象是server容器一直处于Restarting状态，查看日志会看到connection refused或Unable to connect to database之类的错误。
原因通常有两个：一是postgres还没就绪，server就启动了，连接被拒；二是DATABASE_URL里的用户名、密码或数据库名和postgres容器里创建的不一致。
排查思路：
# 查看server日志确认错误 docker compose logs server # 检查postgres是否健康 docker compose ps docker exec -it 你的postgres容器名 psql -U hoppscotch -d hoppscotch -c "select 1;"如果确认postgres正常但server还是连不上，重点检查连接串里的host是不是postgres（Compose服务名），端口是不是5432，密码是否一致。连接串里host一定不要写成localhost——在Compose网络里，各服务之间要互相通过服务名访问，写localhost指向的是容器自己，不是数据库容器。
6.2 前端能打开但发请求报CORS错误
表现是页面能打开、登录也正常，但发送请求时浏览器控制台报Access to XMLHttpRequest ... CORS错误。这个坑我也踩过，本质是Web前端所在域名和后端API所在域名不一致，浏览器出于安全策略拦截了跨域响应。
常规解法是在nginx上做反向代理，让前端和后端同源。nginx配置示意：
server { listen 80; server_name your.domain.com; location / { proxy_pass http://127.0.0.1:8080; # 指向web容器 proxy_set_header Host $host; } location /api/ { proxy_pass http://127.0.0.1:3000; # 指向server容器，具体路径前缀按你的版本调整 proxy_set_header Host $host; } }把对外暴露的端口改成80，由nginx统一转发，浏览器看到的前端页面和API请求就都是同一个域名了，CORS问题自然消失。这时VITE_API_URL也可以配置成同源路径，比如/api。需要注意的是，不同版本的前端访问后端的具体路径前缀可能不一样，动手前先看server日志确认实际请求路径。
6.3 注册后无法登录：SMTP验证的锅
如果你是源码部署，或者用了某些精简镜像，可能会发现注册账号流程走完，回头登录却提示账号未验证或无法登录。这大概率是SMTP邮件验证导致的。
解决方式有两个方向：一是配置SMTP，让验证邮件正常发出，用户点邮件里的链接完成验证；二是确认当前版本是否有"跳过验证"的开关，测试环境可以用它临时绕开。我生产环境是老老实实配了SMTP，用企业邮箱的SMTP服务，配置项在.env里填好，重启server就生效了。
6.4 版本升级与数据备份
自部署服务迟早要面临升级。Hoppscotch版本迭代比较快，建议升级前先备份数据库：
docker exec -t 你的postgres容器名 pg_dump -U hoppscotch hoppscotch > backup_$(date +%Y%m%d).sql然后拉取新镜像并重建容器：
docker compose pull docker compose up -d升级后如果遇到数据库结构变更，server启动时会自动执行迁移（大部分版本内置了迁移逻辑），但迁移本身有风险，生产环境务必先备份再升级。万一升级后发现问题，用旧镜像tag可以快速回滚。所以线上环境不建议一直用latest标签，尽量锁到具体版本号，比如hoppscotch-server:2024.xx.xx这种格式。
7. 部署完成后的实用建议
7.1 用Hoppscotch调试本地大模型API
部署好之后，工具本身还要会用。我最近经常用Hoppscotch调试本地部署的大语言模型API。比如用Ollama在本地跑了一个模型，默认监听http://localhost:11434，通过OpenAI兼容格式直接发POST请求即可。请求方法选POST，URL填http://localhost:11434/v1/chat/completions，Header加Content-Type: application/json，Body写：
{ "model": "llama3", "messages": [ { "role": "user", "content": "你好，简单介绍一下你自己" } ], "stream": false }点发送就能看到返回的JSON。调试本地模型接口用Hoppscotch比写Python脚本或curl一行行敲直观得多。公司内部的大模型API、GPU服务器上部署的推理服务，也都可以用Hoppscotch统一调试。包括现在比较火的免费大模型API、DeepSeek这类服务，把Key配到环境变量里，用Hoppscotch做调用量验证和参数对比，体验很好。
7.2 集合、环境与团队协作的三个习惯
自部署之后，团队可以共用一套服务。建议从一开始就养三个习惯：
- 把常用接口按项目拆成集合（Collections），用文件夹做模块分组，接口多了不迷路。
- 用环境变量管理不同环境的域名和密钥，dev一套、prod一套，切换环境就切换变量组。
- 在集合里维护一条"接口文档说明"的请求，把约定和数据格式写在里头，当作轻量级文档用。
这样新人接手时不用翻聊天记录，打开共享集合就能看到所有接口的请求方式和参数结构。
7.3 浏览器扩展与Interceptor的边界
Hoppscotch有一个官方的浏览器扩展（Interceptor），用来解决浏览器请求的跨域限制。装上扩展之后，Hoppscotch会通过扩展代理请求，从而绕过浏览器CORS限制，调第三方公开API时很好用。不过要注意，浏览器扩展本质上是在浏览器和API之间加了代理层，涉及敏感数据的请求要慎重，结合自己公司的安全规范来判断是否可用。
7.4 导入Postman集合，迁移零成本
如果你是从Postman迁过来的团队，Hoppscotch支持导入Postman Collection格式的导出文件。迁移路径是：在Postman里导出集合为JSON，然后在Hoppscotch里选择导入，接口、请求参数、环境变量基本都能带过来。实测迁移一个几十条接口的集合非常顺利，几乎没有手工调整的负担。我自己现在的工作流是：本地开发环境同时开着Hoppscotch和OpenAPI文档，先用OpenAPI确认接口定义，再用Hoppscotch做实际调试，比在IDE里写测试代码快得多。
 管理文档渲染器注册表)
