Hoppscotch 开源生态全景解析：从 Monorepo 架构到自托管部署的实战指南

Hoppscotch 是一个开源的 API 开发生态系统，提供 Web、桌面端与 CLI 三种客户端形态，支持 REST、GraphQL、WebSocket、Socket.IO、MQTT 与 Server-Sent Events 等多种协议的调试、协作与自动化测试。本文以仓库根目录的 README.md 为主体，结合源码与配置文件的实际证据，系统梳理其功能全景、请求工作流、Monorepo 包结构、Kernel 平台抽象层、Docker Compose 自托管方案以及 Hoppscotch CLI 在 CI 中的用法，帮助读者快速建立从"上手使用"到"本地开发、自托管部署"的完整技术图景。

项目定位与核心特性

README.md 将 Hoppscotch 定位为 "Open Source API Development Ecosystem"（开源 API 开发生态系统），运行形态覆盖 Offline（离线）、On-Prem（本地私有部署）与 Cloud（云端），客户端覆盖 Web、Desktop 与 CLI。官方建议将 Hoppscotch Documentation 之外的应用细节以文档站点为准，而本文聚焦于仓库内可以证实的工程事实。

设计与性能取向

• Lightweight（轻量）：采用极简 UI 设计；
• Fast（快速）：发送请求并实时获取响应；
• Theming（主题）：背景/前景/强调色可自由组合，支持 System、Light、Dark、Black 四种基础主题，以及 Green、Teal、Blue、Indigo、Purple、Yellow、Orange、Red、Pink 九种强调色，并提供 Zen 无干扰模式；自定义主题会与云端/本地会话同步。主题变量在 packages/hoppscotch-common/assets/themes 下的 base-themes.scss 与 accent-themes.scss 中维护；
• PWA：支持 Service Worker 秒开、离线、低内存占用、添加到主屏与桌面 PWA，相关能力由 packages/hoppscotch-common/src/composables/pwa.ts 等组合式 API 驱动。

支持的 HTTP 方法

README 完整列出了请求方法及其语义，这里全部继承：

方法	语义
GET	检索资源信息
POST	服务端在数据库中创建新条目
PUT	更新已有资源
PATCH	与 PUT 类似，但只做部分更新
DELETE	删除资源或其相关组件
HEAD	获取与 GET 相同的响应头，但不带响应体
CONNECT	建立到目标资源所标识服务器的隧道
OPTIONS	描述目标资源的通信选项
TRACE	沿路径执行消息回环测试
<custom>	自定义方法，例如某些 API 使用的 LIST，可直接输入

多协议支持

README 将 Hoppscotch 的协议能力概括为六类，与前端依赖相互印证（见 packages/hoppscotch-common/package.json）：

• Request（REST）：核心三步——选择 method、输入 URL、点击 Send；支持复制/分享公共 Share URL、生成 10+ 语言与框架的请求代码片段（依赖 @hoppscotch/httpsnippet 与 quicktype-core）、导入 cURL、给请求打标签；
• WebSocket：在单一 TCP 连接上建立全双工通信；
• Server-Sent Events：通过 HTTP 连接持续接收服务器推送，无需轮询；
• Socket.IO：与 Socket.IO 服务器收发数据；前端同时内置 v2/v3/v4 三代客户端（socket.io-client-v2/v3/v4 依赖别名）；
• MQTT：向 MQTT Broker 的主题订阅与发布（依赖 paho-mqtt）；
• GraphQL：设置 endpoint 后拉取 schema、多栏文档布局、自定义请求头、查询 schema 并获得响应。GraphQL 语法高亮由仓库内的独立包 packages/codemirror-lang-graphql 提供。

认证体系

README 列出五种认证模式：None、Basic、Bearer Token、OAuth 2.0、OIDC Access Token/PKCE。从源码结构看，OAuth 流程的具体实现位于 packages/hoppscotch-common/src/services/oauth/flows 下，分别有 authCode.ts、clientCredentials.ts、implicit.ts、password.ts 四个标准 OAuth 2.0 授权流文件，与 packages/hoppscotch-common/src/composables/oauth2 中的组合式逻辑配合完成令牌获取。

请求的完整要素链

README 对请求/响应各要素的说明如下，可视为一次 API 调试的完整数据链路：

• Headers（请求头）：描述请求体的传输格式；
• Parameters（参数）：通过 URL 参数设置请求中的可变部分；
• Request Body（请求体）：设置 Content Type，支持 FormData、JSON 等多种类型，可在键值对（key-value）与 RAW 原始输入两种模式间切换；
• Response（响应）：包含状态行、响应头与消息体，支持复制到剪贴板、下载为文件、查看响应头，以及对 HTML、图片、JSON、XML 响应做原始/预览双视图。

组织与协作

• History（历史）：请求条目与云端/本地会话存储同步；
• Collections（集合）：用集合与嵌套文件夹组织请求并一键复用，支持不限数量的集合/文件夹/请求，可导出/导入为文件或 GitHub gist，并与云端/本地会话存储同步；
• Pre-Request Scripts（预请求脚本）：请求发送前执行的代码片段，可设置环境变量、在请求头中写入时间戳、在 URL 参数中附加随机字母数字串，并可调用任意 JavaScript 函数；
• Post-Request Tests（后置测试）：响应返回后执行，可按整数断言状态码、过滤响应头、解析响应数据、设置环境变量、编写任意 JavaScript；
• Environments（环境变量）：不限数量地存储可复用变量，可在预请求脚本中初始化，支持以 GitHub gist 方式导出/导入；README 特别强调变量价值——存一处、引多处、改一处、降错误；
• Bulk Edit（批量编辑）：键值对批量编辑规则为——条目以换行分隔、键值以 : 分隔、行首加 # 表示该行保留但保持禁用状态；
• Teams（团队）：不限数量的团队、共享集合与成员，支持基于角色的访问控制（RBAC）、云端同步与多设备使用；
• Workspaces（工作区）：将个人与团队的集合、环境组织进工作区，可在个人工作区与团队工作区间切换以管理多项目；
• Admin dashboard（管理面板）：提供洞察（Insights）、用户管理与团队管理、成员邀请能力，对应仓库中的 packages/hoppscotch-sh-admin 子应用；
• Keyboard Shortcuts：面向效率优化的全局快捷键体系；
• i18n：应用内建 37 种语言文件，位于 packages/hoppscotch-common/locales（如 en.json、cn.json、ja.json 等），翻译流程见 TRANSLATIONS.md。

认证与云同步

README 的 "Auth + Sync" 部分说明：登录后可在所有设备间实时同步数据，同步范围覆盖 Workspaces、History、Collections、Environments、Settings。支持的登录方式为 GitHub、Google、Microsoft、Email，以及 SSO（企业版特性）。从后端源码看，对应的 Passport 策略在 packages/hoppscotch-backend/package.json 的依赖中明确列出：passport-github2、passport-google-oauth20、passport-microsoft、passport-local、passport-jwt，与 README 描述一一对应。

官方 Add-ons

README 列出三个官方扩展，均在 Hoppscotch 组织下开发维护：

• Hoppscotch CLI：命令行接口，源码就在本仓库 packages/hoppscotch-cli；
• Proxy：为 Hoppscotch 创建的简单代理服务器（独立仓库），用于隐藏 IP、修复 CORS 问题、访问非 HTTPS 端点；
• Browser Extensions：Firefox 与 Chrome 扩展，用于修复浏览器中的 CORS 问题。

使用方式：三步完成一次请求

README 的 Usage 章节给出了最简工作流，这也是所有协议页面的通用交互范式：

1. 在 URL 字段中填入 API endpoint；
2. 点击 "Send" 发送请求；
3. 查看响应。

对于 REST 请求，请求的组装遵循上文的"方法 → URL → Headers → Parameters → Body → 认证"链路；对于 WebSocket/MQTT 等实时协议，则替换为连接地址与订阅主题等协议特有要素。

Monorepo 架构：12 个包的职责划分

根目录 package.json（name: hoppscotch-app，版本 3.0.1）声明这是一个基于 pnpm 的私有工作区，packageManager 固定为 pnpm@10.33.4，workspaces 指向 ./packages/*；pnpm-workspace.yaml 进一步将包范围扩展到 packages/**，并配置了 minimumReleaseAge: 4320（依赖新发布版本的等待期）策略。根脚本揭示了工程化的关键动作：

• pnpm dev：pnpm -r do-dev，递归启动各包的开发模式；
• pnpm gen-gql：递归执行 generate-gql-sdl，把后端 GraphQL SDL 汇总到 gql-gen/backend-schema.gql，供前端做 GraphQL Codegen；
• pnpm generate / pnpm start：构建各包产物，并用 http-server 在 3000 端口托管 packages/hoppscotch-selfhost-web/dist；
• pnpm lint / typecheck / test：递归执行各包的 lint、类型检查与测试。

各包的核心定位（依据各包 package.json 与目录结构）：

包	定位	关键技术栈证据
hoppscotch-common	核心 Web 应用（Vue 3 SPA）	Vue 3.5、Vite、CodeMirror 6、Monaco、vue-i18n、urql、Tauri API
hoppscotch-backend	自托管后端 API 服务	NestJS 11、@apollo/server、Prisma 7、Passport、argon2
hoppscotch-selfhost-web	自托管 Web 应用壳 + Go 版 webapp-server	Vite + Caddyfile + Go
hoppscotch-sh-admin	自托管管理面板（README 中的 Admin dashboard）	Vue 3、Caddyfile、多端口/子路径 Caddy 配置
hoppscotch-desktop	Tauri 2 桌面客户端	src-tauri、tauri-plugin-appload、relay
hoppscotch-cli	CI 中运行测试脚本的 CLI	commander、isolated-vm、vitest
hoppscotch-data	请求/环境/集合等数据模型层	TypeScript，被 common 与 CLI 共同依赖
hoppscotch-kernel	Web/桌面平台抽象的 Kernel	io/relay/store/log 四组版本化 API
hoppscotch-relay	跨平台的请求转发层（Rust 实现）	Cargo + relay crate
hoppscotch-js-sandbox	预/后置脚本的沙箱执行	web/node 双端实现 + isolated-vm
hoppscotch-agent	Tauri 桌面代理应用	Rust 后端 + Vue 前端
codemirror-lang-graphql	CodeMirror 的 GraphQL 语言包	Lezer 语法定义

后端技术栈值得展开：从 packages/hoppscotch-backend/package.json 可见，它使用 NestJS 11 + Apollo Server 5 提供 GraphQL API，Prisma 7 + pg 访问 PostgreSQL，graphql-redis-subscriptions 提供基于 Redis 的订阅，@nestjs/terminus 做健康检查、@nestjs/throttler 做限流，密码哈希使用 argon2（另有 bcrypt 兼容），邮件通知走 nodemailer + Handlebars 模板（src/mailer/templates）。数据模型定义在 packages/hoppscotch-backend/prisma/schema.prisma，22 个增量迁移位于 packages/hoppscotch-backend/prisma/migrations，覆盖团队、团队集合、团队环境、团队邀请、个人访问令牌、Mock Server、已发布文档（含 slug 与环境）等能力演进。

Kernel 与 Relay：一次抽象，Web 与桌面两端复用

Hoppscotch 的 Web 端与桌面端共享同一套 Vue 应用代码（hoppscotch-common），差异通过 Kernel 抽象层抹平。packages/hoppscotch-kernel/src/index.ts 定义了 KernelAPI 接口，由四组版本化能力构成：

• io：文件读写、打开外部链接等系统 I/O；
• relay：请求的跨平台转发（网络请求统一走 Relay）；
• store：持久化存储（Web 端 localStorage 系、桌面端 Tauri Store）；
• log：结构化日志。

initKernel(mode)（该文件 L46-L78）根据 "web" | "desktop" 模式装配对应实现，并把结果挂到 window.__KERNEL__ 上供全局访问；getKernelMode() 则回退为默认的 "web" 模式。桌面端则通过 packages/hoppscotch-desktop 中的 tauri-plugin-appload 与 tauri-plugin-relay（见 plugin-workspace/ 目录）把请求经由 Rust 侧的 hoppscotch-relay crate 发出，从而突破浏览器同源与 CORS 限制——这也解释了 README 中 PWA/桌面端"低资源占用、离线支持"等描述背后的工程机制。

自托管部署：Docker Compose Profiles 实战

README 的 Developing 章节指向官方 self-host 文档；仓库内则提供了可直接落地的两份 Compose 文件与多阶段生产镜像 prod.Dockerfile。docker-compose.yml 的头部注释即是一份精炼的部署手册，核心是使用 profiles 管理不同部署场景以避免端口冲突：

Profile	启动内容	适用场景
default	AIO 单容器 + PostgreSQL + 自动迁移	推荐，多数用户
default-no-db	AIO 单容器，无数据库	已有外部数据库
backend	仅后端服务	单独部署后端
app	主应用 + webapp server	单独部署应用
admin	仅自托管管理面板	单独部署管理台
database	仅 PostgreSQL	单独提供数据库
just-backend	除 webapp 外全部服务	本地开发
deprecated	旧版服务组合	仅向后兼容，不推荐

典型命令（直接来自 Compose 文件注释）：

# 推荐默认部署：AIO + 数据库 + 自动迁移
docker compose --profile default up

# 不带数据库（外部库）
docker compose --profile default-no-db up

# 仅后端 / 仅应用 / 仅管理台 / 仅数据库
docker compose --profile backend up
docker compose --profile app up
docker compose --profile admin up
docker compose --profile database up

从 Compose 配置可提取的部署要点：

• 端口规划：AIO 容器暴露 3000（应用）、3100（管理台）、3170（后端 API）、3200（webapp server）、3080（Caddy 80 端口的代理）；独立部署时，后端为 3170/3180，应用为 3000/3080/3200，管理台为 3100/3280，数据库为 5432；
• 数据库：预置 postgres:15，默认账号 postgres/testpass、库名 hoppscotch，并带 pg_isready 健康检查（5s 间隔、5s 超时、10 次重试）；注释明确提醒必须修改默认密码；
• 自动迁移：hoppscotch-migrate 服务在数据库健康后执行 pnpm exec prisma migrate deploy，实现开箱即用的 Schema 迁移；
• 外部数据库：修改 DATABASE_URL（示例为 postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch?connect_timeout=300）并同步 .env 文件即可；
• 注释同时警告：default 与 default-no-db 不应与单服务 profile 混用，否则会端口冲突。

除容器化路线外，仓库还提供了 Nix 开发环境：devenv.nix + devenv.yaml（fenix 管理 Rust 工具链、rust-overlay 加速构建），配合根脚本即可完成前后端与 Rust 组件的联合开发。

Hoppscotch CLI：在 CI 中运行集合测试

README 将 CLI 列为官方 Add-on 之一；packages/hoppscotch-cli/package.json 给出了其工程事实：包名 @hoppscotch/cli（当前 0.31.3），自述为 "A CLI to run Hoppscotch test scripts in CI environments"，二进制名为 hopp，要求 node >= 22，脚本沙箱依赖 isolated-vm（与 Web 端共享 packages/hoppscotch-js-sandbox）。

其唯一核心命令 test 的实现位于 packages/hoppscotch-cli/src/commands/test.ts，从源码可确认的参数与校验逻辑包括：

• delay：请求间延迟，经 parseDelayOption 解析；
• env：环境变量数据，经 parseEnvsData 解析为 HoppEnvs（含 global 与 selected 两组）；
• iterationCount：迭代次数，必须是大于 0 的整数（isSafeInteger 校验，否则抛 INVALID_ARGUMENT）；
• iterationData：CSV 迭代数据文件，要求扩展名为 .csv（否则 INVALID_DATA_FILE_TYPE），用 PapaParse 按表头解析后转换为 IterationDataItem 数组，空行会被过滤；
• reporterJunit：JUnit 格式报告输出；
• legacySandbox：启用旧版沙箱的兼容开关。

解析完成后交由 collectionsRunner（见 packages/hoppscotch-cli/src/utils/collections.ts）执行集合内的全部请求与测试脚本。测试用例位于 src/__tests__/ 下，包含 58 个端到端快照场景与 17 个函数级测试，覆盖认证（AWS 签名等）、迭代、报告器等路径。

开发、贡献与工程保障

• 贡献流程：遵循 GitHub Flow——创建分支、提交、发起 PR；细则见 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md；
• 本地开发：pnpm dev 通过 -r do-dev 递归拉起各包（common 包内还会并行跑 vite 与 GraphQL Codegen 的 watch 模式，见 packages/hoppscotch-common/package.json 的 dev 脚本）；
• 质量门禁：根级 pre-commit 脚本会递归执行 do-lint 与 do-typecheck；依赖 husky + @commitlint（conventional commits 规范，见 commitlint.config.js）与 lint-staged；
• CI：README 声明使用 GitHub Actions 做持续集成，测试徽标指向 tests.yml 工作流；各包的测试框架并不统一——后端与 CLI 用 Jest/Vitest（CLI 的 do-test 会先 pnpm run build 再跑 vitest run），common 包用 Vitest；
• 变更历史：见 CHANGELOG.md；
• 许可证：MIT License，见 LICENSE。

小结

以 README.md 为骨架、以仓库源码为注脚，Hoppscotch 的技术轮廓可以归纳为三点：一是"一份前端代码、多端复用"——通过 Kernel/Relay 抽象让 Web 与 Tauri 桌面端共享 hoppscotch-common 应用；二是"功能即依赖"——README 中每一项协议与认证能力，都能在 hoppscotch-common 与 hoppscotch-backend 的依赖清单和服务目录中找到对应实现；三是"自托管开箱即用"——docker-compose.yml 的 profiles + AIO 镜像 + Prisma 自动迁移，让私有部署只需一条命令。对读者而言，从三步完成一次请求的使用者视角，到读懂 12 个包职责划分的开发者视角，再到用 Compose profile 编排私有集群的运维视角，本仓库提供了完整且可验证的技术闭环。