从零开始用 Docker 部署 Hoppscotch：自建 API 调试平台的完整教程

一、hoppscotch 应用是什么？

一款开源、轻量、跨平台的一站式 API 开发调试生态工具

主打极速、无臃肿、轻量化运行，替代传统重型接口测试工具。支持 Web、桌面、CLI 多端使用，完整覆盖 HTTP、WebSocket、GraphQL、SSE、MQTT 等主流接口协议，无需客户端繁重安装，支持浏览器直接访问、离线使用、私有化自托管部署，具备接口调试、文档生成、模拟请求、团队协作等全链路能力。

完全开源免费且无核心功能阉割

1、常见API协议架构

2、以REFTful为例，有哪些Http方法？

一般用于Http和Https协议，获取最新数据、发送更新和删除请求

1.1、hoppscotch功能特点

轻量化极速运行，基于现代化技术构建，无冗余插件，启动响应速度快，资源占用极低
全协议支持，兼容 HTTP、HTTPS、WebSocket、GraphQL、SSE、MQTT、Socket.IO 主流接口协议
完整接口调试能力，支持 11 种 HTTP 请求方法，适配路径参数、查询参数、请求头、Cookie、多种请求体格式
智能数据格式化，自动美化 JSON、XML、HTML 响应内容，支持树状预览、数据折叠、编码转换
离线本地优先存储，默认数据存储于浏览器本地，支持私有化部署持久化存储，保障数据安全可控
支持接口文档自动生成、接口Mock模拟、CORS跨域调试、请求批量测试等进阶功能
开源协议宽松，支持个人、企业商用，可私有化部署、二次定制开发

1.2、使用场景介绍

适配个人开发、团队协作、线上线下调试等多种研发场景，覆盖 API 全生命周期使用需求

后端接口开发调试：后端开发人员开发接口时，快速验证接口可用性、参数合法性、响应数据准确性，排查接口报错、超时、参数异常等问题，替代传统代码自测、Postman 重型工具调试方式
前端对接接口测试：前端开发人员在后端接口未完全上线时，通过 Mock 功能模拟接口响应，完成前端页面开发；同时可实时调试接口跨域、请求头、参数匹配问题，验证前后端数据对接一致性
除了常规的GET、POST请求外，还可以支持API自定义的请求方法
作为PWA运行在设备上，内存、CPU占用都很低
能生成10+种语言和框架的请求代码片段
除了REST API方法，还能与WebSocket、SocketIO、MQTT服务端建立通信，支持GraphQL查询。、
可以使用自定义代理，隐藏真实IP地址
支持插入请求脚本，可以在发送请求前和得到相应后自定义一些自己期望的行为
可以很方便地生成API文档
支持环境变量，将值存储在变量中，可以在多个不同的请求之间引用变量
支持导入 postman 导出的接口数据

导入 Postman / curl

从 Postman 导出或直接贴 curl 命令，秒转成请求

1.3、和同类别产品对比

对比维度	Hoppscotch	Postman	Insomnia	Bruno
开源属性	完全开源免费，商用无限制	核心功能免费，团队协作、私有化部署需付费	开源免费，部分企业功能收费	完全开源免费
部署方式	支持浏览器直接使用、Docker私有化部署、桌面端	云端为主，私有化仅企业付费版支持	本地客户端为主，私有化支持有限	本地文件存储，无服务端部署
资源占用	超轻量，低内存低CPU占用	重型客户端，资源占用高，启动慢	中等资源占用	轻量，本地文件存储无服务开销
协议支持	HTTP/WS/GraphQL/MQTT/SSE 全协议覆盖	仅基础 HTTP、GraphQL、WebSocket	仅基础 HTTP、GraphQL、WebSocket	仅基础 HTTP 协议
团队协作	免费无限团队成员、无限工作区	免费版仅3人团队，扩容需付费	免费协作功能有限	依赖Git手动同步，无原生协作
离线使用	完整离线支持，无网络可正常使用	离线功能受限，需登录同步	有限离线支持	完全离线

二、安装部署实践

2.1、创建本地文件夹目录

在服务器 /opt 目录下创建 Hoppscotch 专属部署目录、数据持久化目录，用于存放配置文件、容器数据，避免容器删除数据丢失

复制代码

# 创建项目根目录
mkdir -p /opt/hoppscotch
# 创建数据持久化目录
mkdir -p /opt/hoppscotch/data
# 进入项目目录
cd /opt/hoppscotch

2.2、Docker Compose 配置

在 /opt/hoppscotch 目录创建 docker-compose.yml 配置文件，完整配置如下：

复制代码

version: '3.8'
services:
  hoppscotch:
    image: hoppscotch/hoppscotch:latest
    container_name: hoppscotch
    restart: always
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - HOPPSCOTCH_DISABLE_TELEMETRY=true
      - HOPPSCOTCH_ALLOW_ALL_ORIGINS=true
networks:
  default:
    driver: bridge

参数说明：

image：指定 Hoppscotch 官方最新镜像，保证功能最新、漏洞最少
container_name：自定义容器名称，方便后续容器管理操作
restart: always：设置容器开机自启、异常退出自动重启，保障服务常驻
ports：端口映射，服务器3000端口映射容器3000端口，可根据需求修改宿主机端口
NODE_ENV=production：设置生产环境模式，优化运行性能、关闭调试日志
HOPPSCOTCH_DISABLE_TELEMETRY=true：关闭遥测数据上报，保护服务隐私
HOPPSCOTCH_ALLOW_ALL_ORIGINS=true：允许所有跨域请求，适配前后端联调场景

启动服务命令：

复制代码

# 后台启动服务
docker-compose up -d
# 查看运行状态
docker-compose ps

2.3、Docker 命令安装方式

提供单条 Docker 命令快速部署，无需编写配置文件，适合快速测试、临时部署场景，执行以下命令直接创建并启动容器：

复制代码

docker run -d --name hoppscotch --restart always -p 3000:3000 hoppscotch/hoppscotch:latest

参数说明：

-d：后台守护进程运行容器，不占用终端窗口
--name：定义容器唯一名称，便于启停、删除、查看日志
--restart always：配置容器重启策略，保障服务稳定运行
-p：宿主机与容器端口映射，对外开放访问端口
末尾镜像名称：拉取官方最新稳定版 Hoppscotch 镜像

部署完成后，浏览器访问 http://服务器IP:3000 即可进入 Hoppscotch 控制台

三、使用教程

3.1、初始化配置

首次访问私有化部署的 Hoppscotch 服务，无需注册登录账号，开箱即用

3.2、基础操作流程

1、新建接口请求

进入主界面后，选择左侧API接口类型，默认Restful，可切换 WebSocket、GraphQL、MQTT 等协议模式。

以Restful为例：点击+「New Request」新建请求任务，自定义请求名称，选择对应的请求协议与请求方法。支持 GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS、CONNECT、TRACE 等全部 HTTP 方法

2、配置请求参数

在请求配置区填写目标 API 地址，可按需配置路径参数、查询参数、请求头、Cookie 信息。请求体支持多种格式：JSON、Form-Data、Urlencoded、Binary、Raw，适配各类接口请求场景，参数支持自动编码、一键清空、批量编辑。

3、发送请求与查看结果

参数配置完成后，点击右上角「Send」按钮发送请求，下方实时展示响应结果，包含响应状态码、请求耗时、响应体积、响应头、响应体。系统自动美化 JSON、XML 数据格式，支持数据折叠、搜索、复制、导出，快速定位接口异常问题。

4、接口集合管理

支持创建项目集合、分类管理接口请求，可将同一业务、同一模块的接口统一收纳，支持批量保存、批量运行、导入导出接口配置，方便接口迭代与复用。

3.3、团队协作使用

私有化部署版本支持多人共享服务，团队成员通过统一服务器地址访问系统，可互相共享接口集合、测试用例。支持创建多工作区，区分不同项目、不同环境（开发、测试、生产）接口资源，实现团队标准化接口测试管理。

四、使用技巧

4.1、端口与访问优化

默认 3000 端口可根据服务器端口占用情况自定义修改，修改 Compose 配置或 Docker 启动命令中的宿主机端口即可。可搭配 Nginx 配置反向代理、HTTPS 证书，实现域名访问、外网安全访问，同时配置端口白名单，仅允许内网或指定 IP 访问，提升服务安全性。

4.2、接口高效调试优化

支持请求预设模板，可将常用请求头、鉴权参数（Token、Cookie、Authorization）保存为全局模板，新建接口自动复用，无需重复配置。针对高频调试接口，可开启请求重试、超时自定义配置，适配弱网、高延迟接口场景；支持接口响应对比，快速迭代验证接口修改效果。

4.3、离线与隐私优化

私有化部署版本完全支持离线使用，服务器部署完成后，内网无网络环境下可正常调试接口。默认关闭遥测上报，杜绝数据外发，所有接口测试数据仅留存本地服务器，相比云端工具大幅提升数据安全性，适配企业内网涉密开发场景。