一、Hoppscotch 定位与选型逻辑

Hoppscotch 是一个 MIT 协议的开源 API 开发生态系统。它不只是 Postman 的免费替代品——更准确地说，它是一个可自托管的 API 研发协作平台，覆盖从单机调试到团队协作、从手工测试到 CI 自动化的完整链路。

选型时 vs Postman 的关键差异

维度	Hoppscotch	Postman
协议	MIT	闭源 + 免费版限制
部署	自托管 / Cloud / PWA / Desktop	Cloud-only（桌面端也走云端）
数据主权	数据在你自己服务器上	数据在 Postman 云
定价	免费	$12–$49/人/月
团队协作	RBAC + 无限团队	免费版 3 人团队
CLI	@hoppscotch/cli	Newman
内网 API	自托管天然支持	需要 Postman Agent
多协议	REST + GraphQL + WS + SSE + MQTT + Socket.IO	REST + GraphQL + WS

核心选型理由：如果你的团队需要调试内网 API、对数据主权有要求、或不想为 10 人团队每月付 $200+，Hoppscotch 自托管是唯一正确解。

---

二、自托管部署

Docker Compose 一键部署

Hoppscotch 官方提供了完整的 Docker Compose 配置。以下为生产可用的精简版：

version: '3.8'

services:
  # PostgreSQL — 团队协作、用户数据存储
  hoppscotch-db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: hoppscotch
      POSTGRES_PASSWORD: <your_db_password>
      POSTGRES_DB: hoppscotch
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hoppscotch"]
      interval: 5s
      retries: 5

  # Backend — NestJS + GraphQL
  hoppscotch-backend:
    image: hoppscotch/hoppscotch-backend:latest
    restart: unless-stopped
    environment:
      DATABASE_URL: postgresql://hoppscotch:<your_db_password>@hoppscotch-db:5432/hoppscotch
      JWT_SECRET: <random_64_char_string>
      TOKEN_SALT_COMPLEXITY: 10
      MAGIC_LINK_TOKEN_VALIDITY: 3
      REFRESH_TOKEN_VALIDITY: 604800000
      SESSION_SECRET: <another_random_64_char_string>
      VITE_ALLOWED_AUTH_PROVIDERS: EMAIL
      ALLOW_SECURE_COOKIES: "false"
      REDIRECT_HTTPS_TO_HTTP: "true"
      RATE_LIMIT_TTL: 60
      RATE_LIMIT_MAX: 100
      WHITELISTED_ORIGINS: https://hoppscotch.your-domain.com
      VITE_BASE_URL: https://hoppscotch.your-domain.com
    depends_on:
      hoppscotch-db:
        condition: service_healthy

  # Frontend — Vue 3 + Vite
  hoppscotch-frontend:
    image: hoppscotch/hoppscotch-frontend:latest
    restart: unless-stopped
    environment:
      VITE_BACKEND_GQL_URL: https://hoppscotch.your-domain.com/graphql
      VITE_BACKEND_WS_URL: wss://hoppscotch.your-domain.com/graphql
      VITE_BACKEND_API_URL: https://hoppscotch.your-domain.com/v1
    depends_on:
      - hoppscotch-backend

  # Admin dashboard — 用户和团队管理
  hoppscotch-admin:
    image: hoppscotch/hoppscotch-admin:latest
    restart: unless-stopped
    environment:
      VITE_ADMIN_BACKEND_GQL_URL: https://hoppscotch.your-domain.com/graphql
      VITE_ADMIN_BACKEND_API_URL: https://hoppscotch.your-domain.com/v1
    depends_on:
      - hoppscotch-backend

volumes:
  pgdata:

Nginx 反向代理

自托管环境下建议通过 Nginx 统一入口并处理 HTTPS：

server {
    listen 443 ssl;
    server_name hoppscotch.your-domain.com;

    ssl_certificate     /etc/ssl/certs/hoppscotch.pem;
    ssl_certificate_key /etc/ssl/private/hoppscotch.key;

    # Frontend
    location / {
        proxy_pass http://hoppscotch-frontend:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Backend GraphQL + REST
    location /graphql {
        proxy_pass http://hoppscotch-backend:3170;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /v1 {
        proxy_pass http://hoppscotch-backend:3170;
    }

    # Admin
    location /admin {
        proxy_pass http://hoppscotch-admin:3100;
    }
}

初始化

docker compose up -d

# 等待 PostgreSQL 就绪后创建管理员
docker exec -it hoppscotch-backend npx prisma migrate deploy

然后访问 https://hoppscotch.your-domain.com 注册第一个账号（自动成为管理员），在 /admin 面板管理用户和团队。

---

三、核心使用场景

3.1 环境变量与动态请求

把不同环境的 API 地址抽象为环境变量是团队协作的基础：

// Environment: "Production"
{
  "base_url": "https://api.your-company.com",
  "auth_token": "eyJhbG...",
  "user_id": "12345"
}

在请求中使用 <<variable>> 语法：

GET <<base_url>>/users/<<user_id>>
Authorization: Bearer <<auth_token>>

创建四套环境（dev / staging / prod / local），切换环境即切换所有请求的目标。

3.2 Pre-request Script — 动态签名

调试需要签名的 API 时（如 语音通知接口 的 MD5 鉴权），Pre-request Script 可以在发送前自动计算签名：

// 设置动态时间戳
const timestamp = Date.now().toString();
pw.env.set("timestamp", timestamp);

// 计算 HMAC-SHA256 签名
const body = pw.body.getRaw();
const secret = "your-app-secret";
const signature = CryptoJS.HmacSHA256(timestamp + body, secret).toString();
pw.env.set("signature", signature);

然后在 Headers 中引用 <<signature>> 即可。Postman 的 Pre-request Script 功能在 Hoppscotch 中完全有等价的实现。

3.3 集合管理 — API 文档即请求集

标准做法是给每个微服务/模块建一个 Collection：

Platform API
├── Auth
│   ├── POST /login
│   └── POST /refresh
├── Users
│   ├── GET /users
│   ├── GET /users/:id
│   └── POST /users
└── Orders
    ├── GET /orders
    └── POST /orders

Collection 可以导出为 JSON 文件，纳入 Git 版本管理，或通过 GitHub Gist 分享给团队。

---

四、CLI 自动化测试

安装

npm install -g @hoppscotch/cli

编写测试脚本

Hoppscotch 使用 .hoppscotch.json 格式的集合文件（从 Web UI 导出）：

# 导出集合
# Web UI → Collections → Export → 保存为 my-api.json

# 运行集合测试
hopp test my-api.json \
  --env dev-env.json \
  --delay 100

CI/CD 集成 — GitHub Actions

name: API Tests
on: [push, pull_request]

jobs:
  api-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Hoppscotch CLI
        run: npm install -g @hoppscotch/cli
      
      - name: Run API tests
        run: |
          hopp test api-tests/collections/*.json \
            --env api-tests/envs/ci.json \
            --reporter json \
            > test-results.json
      
      - name: Upload results
        uses: actions/upload-artifact@v4
        with:
          name: api-test-results
          path: test-results.json

测试断言

在集合的请求中通过 Headers 添加断言：

X-Hopp-Test: response.status == 200 && response.body.success == true

CLI 会根据断言判断测试通过/失败，返回非零退出码。

---

五、Proxy 模式 — 调试内网 API

自托管版最实用的功能之一是内置 Proxy：

启用方式：Settings → Enable Proxy → 填写自托管 Proxy URL

当你从本地浏览器访问 Hoppscotch Web UI 时，浏览器无法直接访问 http://192.168.1.100:8080 这样的内网地址（CORS 限制）。Proxy 模式让 Hoppscotch 后端代替浏览器发起请求：

浏览器 → Hoppscotch 前端 → Hoppscotch 后端(Proxy) → 内网 API

官方提供了 Proxyscotch 作为独立代理服务，自托管时也可以用同一个后端实例的 /v1/proxy 端点。

---

六、团队协作与权限控制

RBAC 模型

自托管版支持完整的角色权限：

角色	权限
Owner	完全控制：管理团队、成员、集合、删除团队
Editor	编辑集合、请求、环境变量
Viewer	只读：查看集合和请求，无法修改

工作流示例

1. 后端开发写完接口 → 在 Hoppscotch 中创建对应 Collection + 请求
2. 导出为 JSON → 提交到项目 Git 仓库（api-tests/ 目录）
3. 前端开发导入集合 → 配置本地环境变量 → 联调
4. QA 拉取集合 → 补充异常参数测试 → CI 中自动运行
5. 新成员 on-board → 一键导入所有集合和环境配置

「代码即文档」在这里变成了「请求集即接口文档」——可以拿来直接跑，不是死的 Markdown。

---

七、从 Postman 迁移

集合迁移

# 1. Postman 导出集合为 JSON (v2.1)
# Postman → Collections → Export → v2.1

# 2. Hoppscotch 导入
# Settings → Import/Export → 选择 Postman JSON 文件

环境和变量会自动转换，Pre-request Script 语法兼容（都是 JavaScript）。

迁移检查清单

• Collections 全部导入，嵌套结构和文件夹层次保持
• 环境变量逐环境导入确认
• Pre-request Script 逐一验证（特别是 pm.* 写法需改为 pw.*）
• OAuth 2.0 flow 重新配置（两家的实现略有差异）
• CLI 脚本从 newman 改为 hopp test

---

八、架构总览

Hoppscotch 是一个 pnpm monorepo，核心分层：

前端层 (Vue 3 + Vite + PWA)
    │
    │ GraphQL / REST
    ▼
后端层 (NestJS + GraphQL + Prisma)
    │
    │ SQL
    ▼
数据层 (PostgreSQL)
    │
    ├── CLI 层 (@hoppscotch/cli) — 独立 npm 包
    ├── Desktop 层 (Tauri) — 桌面端原生壳
    └── Relay 层 — Agent 与 Proxy 辅助服务

主要 packages：

包	作用
hoppscotch-common	前端核心公共模块，多协议请求逻辑
hoppscotch-backend	NestJS 后端，GraphQL API + 鉴权 + 数据管理
hoppscotch-selfhost-web	自托管 Web 版，对接自建后端
hoppscotch-cli	CLI 测试工具，hopp test 命令
hoppscotch-desktop	Tauri 桌面端，自带系统级代理能力
hoppscotch-sh-admin	自托管管理后台（用户管理、配置）

---

九、总结

Hoppscotch 解决了两个关键问题：

1. 数据主权：API 请求日志、Token、内部 URL 全部留在你自己的服务器上，不经过第三方云
2. 团队成本归零：一个 docker compose up，无限成员、无限集合、内网 API 原生可达，无需为此付费

如果团队规模 3 人以上、需要调试内网接口、或已经在用 Docker 做基础设施——Hoppscotch 自托管版是目前性价比最高的 API 平台选择。