视频加载失败

GitHub热门项目！Hoppscotch Docker私有部署实战指南

2070 字
10 分钟
GitHub热门项目！Hoppscotch Docker私有部署实战指南
2026-06-12
docker
开发工具
/
私有部署
/
团队协作
浏览量加载中...
GitHub热门项目！Hoppscotch Docker私有部署实战指南

朋友们！API测试工具选对了吗？#

作为开发者，你是不是每天都要和各种 API 打交道？测试接口、调试接口、文档化接口…市面上的 API 测试工具不少，但要么收费太贵，要么数据不安全，要么功能不够用。

作为一个资深开发者，我试过很多工具：Postman 功能强大但收费高，Insomnia 不错但团队协作不方便，curl 太麻烦…直到遇到了 Hoppscotch！这是一个完全开源的 API 开发生态系统，功能媲美 Postman，而且可以私有部署，数据完全可控！

这两天我研究了一下它的 Docker 部署方案，发现部署起来其实很简单。今天我就来手把手教大家如何在自己的服务器上部署 Hoppscotch，打造一个专属的 API 测试平台！

✨ 什么是 Hoppscotch？#

Hoppscotch 是一个开源的 API 开发生态系统，被誉为”开源版 Postman”。它支持 REST、GraphQL、WebSocket、MQTT 等多种协议，提供团队协作、环境变量、前置脚本等强大功能。

🎯 核心功能#

  • 🚀 全协议支持: REST、GraphQL、WebSocket、Server-Sent Events、Socket.IO、MQTT
  • 👥 团队协作: 创建团队、共享集合、角色权限控制
  • 📁 工作空间: 组织个人和团队项目到不同工作空间
  • 🌱 环境变量: 支持多环境配置，方便切换开发/测试/生产环境
  • 📜 前置/后置脚本: 支持 JavaScript 编写测试脚本
  • 🔐 多种认证: Basic Auth、Bearer Token、OAuth 2.0、OIDC
  • 📱 跨平台: Web、桌面应用、CLI 工具

📋 前置准备#

环境要求#

依赖版本要求说明
Docker20+容器运行环境
Docker Compose2+容器编排工具
Node.js18+可选，用于开发模式
pnpm6+可选，用于开发模式
Git任意克隆代码仓库

服务器配置建议#

配置项最低配置推荐配置
CPU2核4核+
内存4GB8GB+
存储20GB50GB+
系统Linux (Ubuntu/Debian/CentOS)Linux

🚀 部署实战#

方式一：使用官方 AIO 容器（推荐）#

优点: 单容器部署，简单快捷，适合快速体验

1. 创建目录结构#

Terminal window
mkdir -p /opt/hoppscotch/data
mkdir -p /opt/hoppscotch/config
cd /opt/hoppscotch

2. 创建 .env 配置文件#

Terminal window
cat > /opt/hoppscotch/config/.env << 'EOF'
#-----------------------Backend Config------------------------------#
# Prisma Config - 使用内置SQLite数据库
DATABASE_URL=file:./data/db.sqlite


# 数据加密密钥（32位字符）
DATA_ENCRYPTION_KEY=your-32-character-encryption-key-here


# 允许的来源（根据需要添加你的域名）
WHITELISTED_ORIGINS=http://localhost:3000,http://localhost:3100,http://localhost:3170,app://localhost_3200,app://hoppscotch


#-----------------------Frontend Config------------------------------#
# 应用基础URL
APP_URL=http://localhost:3000


# API基础URL
API_URL=http://localhost:3170


#-----------------------Auth Config------------------------------#
# JWT密钥（32位字符）
JWT_SECRET=your-32-character-jwt-secret-here


# 密码重置密钥（32位字符）
PASSWORD_RESET_SECRET=your-32-character-reset-secret-here


#-----------------------SMTP Config（可选）------------------------------#
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# [email protected]
# SMTP_PASSWORD=your-email-password
# SMTP_FROM_NAME=Hoppscotch
# [email protected]
EOF

3. 运行 AIO 容器#

Terminal window
docker run -d \
  --name hoppscotch-aio \
  -p 3000:3000 \
  -p 3170:3170 \
  -v /opt/hoppscotch/data:/app/data \
  -v /opt/hoppscotch/config/.env:/app/.env \
  --restart unless-stopped \
  hoppscotch/hoppscotch:latest

4. 访问应用#

打开浏览器访问 http://your-server-ip:3000

方式二：使用 Docker Compose 多容器部署（生产推荐）#

优点: 服务分离，便于扩展和维护，适合生产环境

1. 克隆项目代码#

Terminal window
git clone https://github.com/hoppscotch/hoppscotch.git
cd hoppscotch

2. 创建 .env 配置文件#

Terminal window
cat > .env << 'EOF'
#-----------------------Backend Config------------------------------#
# PostgreSQL数据库配置
DATABASE_URL=postgresql://hoppscotch:hoppscotch@hoppscotch-db:5432/hoppscotch


# 数据加密密钥（32位字符，必须修改！）
DATA_ENCRYPTION_KEY=your-32-character-encryption-key-here


# 允许的来源
WHITELISTED_ORIGINS=http://localhost:3000,http://localhost:3100,http://localhost:3170,app://localhost_3200,app://hoppscotch


#-----------------------Frontend Config------------------------------#
APP_URL=http://localhost:3000
API_URL=http://localhost:3170


#-----------------------Auth Config------------------------------#
# JWT密钥（32位字符，必须修改！）
JWT_SECRET=your-32-character-jwt-secret-here


# 密码重置密钥（32位字符，必须修改！）
PASSWORD_RESET_SECRET=your-32-character-reset-secret-here


#-----------------------SMTP Config------------------------------#
SMTP_HOST=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-email-password
SMTP_FROM_NAME=Hoppscotch
[email protected]


#-----------------------OAuth Config（可选）------------------------------#
# GitHub OAuth
# GITHUB_CLIENT_ID=your-github-client-id
# GITHUB_CLIENT_SECRET=your-github-client-secret


# Google OAuth
# GOOGLE_CLIENT_ID=your-google-client-id
# GOOGLE_CLIENT_SECRET=your-google-client-secret


# Microsoft OAuth
# MICROSOFT_CLIENT_ID=your-microsoft-client-id
# MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
EOF

3. 创建 docker-compose.yml#

version: '3.8'


services:
  hoppscotch-db:
    image: postgres:15-alpine
    container_name: hoppscotch-db
    environment:
      POSTGRES_USER: hoppscotch
      POSTGRES_PASSWORD: hoppscotch
      POSTGRES_DB: hoppscotch
    volumes:
      - hoppscotch-db-data:/var/lib/postgresql/data
    networks:
      - hoppscotch-network
    restart: unless-stopped


  hoppscotch-backend:
    image: hoppscotch/hoppscotch-backend:latest
    container_name: hoppscotch-backend
    depends_on:
      - hoppscotch-db
    environment:
      DATABASE_URL: postgresql://hoppscotch:hoppscotch@hoppscotch-db:5432/hoppscotch
      DATA_ENCRYPTION_KEY: ${DATA_ENCRYPTION_KEY}
      WHITELISTED_ORIGINS: ${WHITELISTED_ORIGINS}
      JWT_SECRET: ${JWT_SECRET}
      PASSWORD_RESET_SECRET: ${PASSWORD_RESET_SECRET}
      SMTP_HOST: ${SMTP_HOST}
      SMTP_PORT: ${SMTP_PORT}
      SMTP_USERNAME: ${SMTP_USERNAME}
      SMTP_PASSWORD: ${SMTP_PASSWORD}
      SMTP_FROM_NAME: ${SMTP_FROM_NAME}
      SMTP_FROM_EMAIL: ${SMTP_FROM_EMAIL}
    volumes:
      - ./config:/app/config
    networks:
      - hoppscotch-network
    restart: unless-stopped
    ports:
      - "3170:3170"


  hoppscotch-frontend:
    image: hoppscotch/hoppscotch-frontend:latest
    container_name: hoppscotch-frontend
    depends_on:
      - hoppscotch-backend
    environment:
      APP_URL: ${APP_URL}
      API_URL: ${API_URL}
    networks:
      - hoppscotch-network
    restart: unless-stopped
    ports:
      - "3000:3000"


  hoppscotch-admin:
    image: hoppscotch/hoppscotch-admin:latest
    container_name: hoppscotch-admin
    depends_on:
      - hoppscotch-backend
    environment:
      VITE_API_URL: ${API_URL}
    networks:
      - hoppscotch-network
    restart: unless-stopped
    ports:
      - "3100:3100"


volumes:
  hoppscotch-db-data: ./hoppscotch-db-data


networks:
  hoppscotch-network:
    driver: bridge

4. 启动服务#

Terminal window
# 启动所有服务
docker-compose up -d


# 查看服务状态
docker-compose ps


# 查看日志
docker-compose logs -f

5. 初始化数据库#

Terminal window
# 进入后端容器
docker exec -it hoppscotch-backend sh


# 运行数据库迁移
pnpm prisma migrate deploy


# 退出容器
exit

6. 访问应用#

服务地址说明
主应用http://localhost:3000API测试主界面
管理后台http://localhost:3100管理员仪表盘
API服务http://localhost:3170后端API

⚙️ 高级配置#

1. 配置 OAuth 登录#

GitHub OAuth#

Terminal window
# 在 GitHub 创建 OAuth App: https://github.com/settings/developers
# 回调地址: http://your-domain.com/api/auth/github/callback


# 修改 .env 文件
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

2. 配置 HTTPS（使用 Nginx 反向代理）#

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$server_name$request_uri;
}


server {
    listen 443 ssl;
    server_name api.example.com;


    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;


    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }


    location /api/ {
        proxy_pass http://localhost:3170/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }


    location /admin/ {
        proxy_pass http://localhost:3100/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

3. 配置 Redis 缓存（可选）#

Terminal window
# 添加 Redis 服务到 docker-compose.yml
redis:
  image: redis:7-alpine
  container_name: hoppscotch-redis
  volumes:
    - hoppscotch-redis-data:/data
  networks:
    - hoppscotch-network
  restart: unless-stopped


# 修改 .env 文件添加 Redis 配置
REDIS_URL=redis://hoppscotch-redis:6379

📝 使用教程#

1. 创建账户#

访问 http://localhost:3000，点击”Sign Up”创建账户：

2. 创建第一个请求#

  1. 点击左侧 ”+” 按钮创建新请求
  2. 选择 HTTP 方法（GET/POST/PUT/DELETE 等）
  3. 输入 API 地址
  4. 添加请求头和参数
  5. 点击”Send”发送请求

3. 创建集合#

  1. 点击左侧”Collections”
  2. 点击”New Collection”
  3. 命名集合并添加描述
  4. 将请求拖入集合中

4. 配置环境变量#

  1. 点击右上角环境图标
  2. 点击”Manage Environments”
  3. 创建新环境并添加变量
  4. 在请求中使用 {{变量名}} 引用

5. 团队协作#

  1. 点击左侧”Teams”
  2. 点击”Create Team”创建团队
  3. 邀请成员加入
  4. 共享集合和工作空间

🔥 常见问题#

Q1: 容器启动失败怎么办？#

Terminal window
# 查看日志
docker-compose logs hoppscotch-backend


# 常见问题：数据库连接失败
# 确保数据库服务先启动，检查 DATABASE_URL 是否正确


# 常见问题：端口被占用
# 修改 docker-compose.yml 中的端口映射

Q2: 如何备份数据？#

Terminal window
# 备份 PostgreSQL 数据库
docker exec -it hoppscotch-db pg_dump -U hoppscotch hoppscotch > backup.sql


# 恢复数据库
docker exec -i hoppscotch-db psql -U hoppscotch hoppscotch < backup.sql

Q3: 如何更新版本？#

Terminal window
# 停止服务
docker-compose down


# 拉取最新镜像
docker-compose pull


# 启动服务（会自动运行数据库迁移）
docker-compose up -d

Q4: 如何配置邮件通知？#

确保 .env 中的 SMTP 配置正确：

Terminal window
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-email-password
SMTP_FROM_NAME=Hoppscotch
SMTP_FROM_EMAIL=[email protected]

📝 总结#

Hoppscotch 是一款开源免费的 API 测试工具，功能媲美 Postman。通过 Docker 容器化部署，我们可以轻松搭建企业级私有 API 测试平台。本文介绍了两种部署方式：AIO 单容器适合快速体验，Docker Compose 多容器适合生产环境。配置上支持 OAuth 认证、SMTP 邮件、环境变量等完整功能，无论是 REST、GraphQL 还是 WebSocket 调试，都能高效完成。相比商业工具，Hoppscotch 不仅免费，还支持私有部署，数据安全可控，是团队协作的理想选择。感兴趣的小伙伴可以按照文中步骤实践，根据需求调整配置。今天的分享就到这里，我们下一篇文章见。

🌟 项目资源#

GitHub 地址: https://github.com/hoppscotch/hoppscotch

官方文档: https://docs.hoppscotch.io

官方网站: https://hoppscotch.io

觉得项目不错的话，记得给作者点个 star 支持一下！

项目特色: 开源免费、功能强大、支持多协议、团队协作、私有部署，是企业级 API 测试的首选工具！

🎉 互动时间#

你平时用什么工具测试 API？对 Hoppscotch 有什么期待？欢迎在评论区和我交流分享！

我会定期分享更多好用的开发工具和部署教程，记得关注我哦！

推荐阅读：

如果您觉得这篇文章有帮助，请为小王点点推荐，谢谢！🌹

支持与分享

如果这篇文章对你有帮助，欢迎分享给更多人或打赏支持！

打赏
GitHub热门项目！Hoppscotch Docker私有部署实战指南
https://blog.huhaha.vip/posts/docker/hoppscotch-docker-intro/
作者
小王的博客
发布于
2026-06-12
许可协议
CC BY-NC-SA 4.0
GitHub热门项目！Twinkle Tray：多显示器亮度调节神器
82万星！AI全自动做短视频/图文，躺平变现！
相关文章智能推荐
1
GitHub热门项目！BentoPDF：浏览器端隐私优先的PDF工具箱，50+工具一键搞定
docker所有处理在浏览器端完成，文件不上传服务器，支持50+工具，可自建部署，完全免费开源！
2
GitHub热门项目！yantr：自托管应用商店，不占用系统资源，130+应用一键部署
工具推荐一个容器搞定所有服务！yantr作为应用而非操作系统运行，130+精选应用，一键部署，支持AI、媒体、下载、云存储、安全等多种类型
3
【工具】一行命令激活 JetBrains 全家桶，再也不用东奔西跑了
实用工具网上搜索 JetBrains 激活方法，不是过时就是各种引流，步骤繁琐还未必管用。本文介绍一个干净的方法：一条 PowerShell 命令搞定 JB 全家桶激活，包含 IntelliJ IDEA、PyCharm、GoLand 等所有产品，附详细步骤和注意事项。
4
dotnet9中的认证鉴权学习
DotNetdotnet9中的认证鉴权学习
5
Figma太贵？这个开源设计平台，支持自托管，设计即代码
工具推荐面向团队的开源设计平台，支持实时协作、设计即代码、设计令牌、MCP服务器，可自建部署，完全免费开源！
随机文章随机推荐

评论区

分享你的想法，与大家交流讨论

Profile Image of the Author
小王的博客
一个上了年纪的猿人.
分类
标签
更多
最新动态
站点统计
文章
209
分类
15
标签
161
总字数
478,322
运行时长
0 天
最后活动
0 天前
站点信息
构建平台
Vercel
博客版本
Firefly v6.16.7
文章许可
CC BY-NC-SA 4.0
© 2026小王的博客. All Rights Reserved.RSSSitemap
Powered byAstroFirefly
文章目录
1
朋友们！API测试工具选对了吗？
2
✨ 什么是 Hoppscotch？
3
🎯 核心功能
4
📋 前置准备
环境要求
服务器配置建议
5
🚀 部署实战
方式一：使用官方 AIO 容器（推荐）
1. 创建目录结构
2. 创建 .env 配置文件
3. 运行 AIO 容器
4. 访问应用
方式二：使用 Docker Compose 多容器部署（生产推荐）
1. 克隆项目代码
2. 创建 .env 配置文件
3. 创建 docker-compose.yml
4. 启动服务
5. 初始化数据库
6. 访问应用
6
⚙️ 高级配置
1. 配置 OAuth 登录
GitHub OAuth
2. 配置 HTTPS（使用 Nginx 反向代理）
3. 配置 Redis 缓存（可选）
7
📝 使用教程
1. 创建账户
2. 创建第一个请求
3. 创建集合
4. 配置环境变量
5. 团队协作
8
🔥 常见问题
Q1: 容器启动失败怎么办？
Q2: 如何备份数据？
Q3: 如何更新版本？
Q4: 如何配置邮件通知？
9
📝 总结
10
🌟 项目资源
11
🎉 互动时间