教程：postman的平替hoppscotch，又叫postwoman，hoppscotch的docker-compose安装过程

Scoful

于 2024-08-21 16:34:06 发布

阅读量1.2k

点赞数 18

分类专栏： Skills 文章标签： postman docker 测试工具 hoppscotch

本文链接：https://blog.csdn.net/Scoful/article/details/141371544

版权

Skills 专栏收录该内容

20 篇文章 5 订阅

订阅专栏

1. 背景

postman强制登录，不登录不给用，登录也就算了，还默认自动同步，这样的话就尴尬了。有些私人的接口啊，私人的账密啊，私人的token啊，真心不敢同步到别人的服务器上，把隐私安全寄托在别人的节操上。

一直在找平替，也有几家国产，现在不都喊着支持国货嘛，试用了一下，也是各种登录，各种同步，各种大版本升级，然后小版本的内容就不见了，寻寻觅觅的，可算是找到了一款开源的平替。

hoppscotch，以前还叫做postwoman，看看这个命名，想干啥懂的都懂。

看了开源代码的文档，只说了原生docker的用法，自带的docker-compose又很多坑，本科普就是把这个过程捋一遍，理论上照着做就行！

2. 前期准备

2.1 准备docker-compose文件，两个版本，一个3合1，一个分开

稍微介绍一下，hoppscotch的服务容器分为4个，1个容器是api测试平台hoppscotch-frontend，端口是3000，(也就是常用的使用界面)，即前台界面，如图，眼熟吧，跟postman差不多，主要使用的也是这个：
1个容器是后端接口hoppscotch-backend，端口是3170，没啥好说，所有核心服务都在这个里
1个容器是后台管理平台hoppscotch-admin，端口是3100，如图
还有一个容器就是postgresql数据库了，hoppscotch不能换数据库，说是用了postgresql的什么json独有的功能，不能换mysql

2.1.1 3合1版本（推荐）

推荐使用这个版本，可以直接把3个服务合成1个启动
只需要确认一下容器hoppscotch-db数据库配置就行，完全可以一点不改，直接拿来就用

# To make it easier to self-host, we have a preset docker compose config that also
# has a container with a Postgres instance running.
# You can tweak around this file to match your instances

services:
  # The service that spins up all 3 services at once in one container
  hoppscotch-aio:
    container_name: hoppscotch-aio
    image: hoppscotch/hoppscotch
    restart: unless-stopped
    env_file:
      - ./.env
    depends_on:
      hoppscotch-db:
        condition: service_healthy
    ports:
      - "3000:3000"
      - "3100:3100"
      - "3170:3170"
      - "3080:80"

  # The preset DB service, you can delete/comment the below lines if
  # you are using an external postgres instance
  # This will be exposed at port 5432
  hoppscotch-db:
    image: postgres:15
    ports:
      - "5432:5432"
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    environment:
      # The default user defined by the docker image
      POSTGRES_USER: postgres
      # NOTE: Please UPDATE THIS PASSWORD!
      POSTGRES_PASSWORD: password
      POSTGRES_DB: hoppscotch
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "sh -c 'pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}'",
        ]
      interval: 5s
      timeout: 5s
      retries: 10

2.1.2 独立版本

这个版本就是多个容器都分开了，各起各的
直接在下面的docker-compose里修改成你自己版本的就行，主要就是改一下数据库连接
hoppscotch-backend容器里的DATABASE_URL，数据库连接，账号是postgresql默认的，可以不改，密码如果想改，要改对应的hoppscotch-db容器里的postgresql配置里的POSTGRES_PASSWORD字段，172.17.0.1这个要看你本地的docker 网络 ip（一般本地开发都用127.0.0.1，这个就是docker自己的本地开发ip，类似的），理论上应该是这个，可以通过ifconfig，找到docker0，复制列出来的ip就行
其实除了172.17.0.1要确认一下是否一样，其他的都可以不改的

# To make it easier to self-host, we have a preset docker compose config that also
# has a container with a Postgres instance running.
# You can tweak around this file to match your instances

services:
  # This service runs the backend app in the port 3170
  hoppscotch-backend:
    container_name: hoppscotch-backend
    image: hoppscotch/hoppscotch-backend
    restart: unless-stopped
    env_file:
      - ./.env
    environment:
      # Edit the below line to match your PostgresDB URL if you have an outside DB (make sure to update the .env file as well)
      - DATABASE_URL=postgresql://postgres:password@172.17.0.1:5432/hoppscotch?connect_timeout=300
    depends_on:
      hoppscotch-db:
        condition: service_healthy
    ports:
      - "3180:80"
      - "3170:3170"

  # The main hoppscotch app. This will be hosted at port 3000
  # NOTE: To do TLS or play around with how the app is hosted, you can look into the Caddyfile for
  #       the SH admin dashboard server at packages/hoppscotch-selfhost-web/Caddyfile
  hoppscotch-frontend:
    container_name: hoppscotch-frontend
    image: hoppscotch/hoppscotch-frontend
    restart: unless-stopped
    env_file:
      - ./.env
    depends_on:
      - hoppscotch-backend
    ports:
      - "3080:80"
      - "3000:3000"

  # The Self Host dashboard for managing the app. This will be hosted at port 3100
  # NOTE: To do TLS or play around with how the app is hosted, you can look into the Caddyfile for
  #       the SH admin dashboard server at packages/hoppscotch-sh-admin/Caddyfile
  hoppscotch-admin:
    container_name: hoppscotch-admin
    image: hoppscotch/hoppscotch-admin
    restart: unless-stopped
    env_file:
      - ./.env
    depends_on:
      - hoppscotch-backend
    ports:
      - "3280:80"
      - "3100:3100"

  # The preset DB service, you can delete/comment the below lines if
  # you are using an external postgres instance
  # This will be exposed at port 5432
  hoppscotch-db:
    image: postgres:15
    ports:
      - "5432:5432"
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    environment:
      # The default user defined by the docker image
      POSTGRES_USER: postgres
      # NOTE: Please UPDATE THIS PASSWORD!
      POSTGRES_PASSWORD: password
      POSTGRES_DB: hoppscotch
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "sh -c 'pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}'",
        ]
      interval: 5s
      timeout: 5s
      retries: 10

2.2 准备安装nginx-proxy-manager（可选）

为什么要安装这个呢，因为hoppscotch起的是3个服务端口，如果用域名的话就是3个二级域名，使用nginx-proxy-manager配置起来简单快速，如果不打算使用域名，可不看
强烈推荐安装这个，简单说就是一个可以通过简单的配置就实现反向代理，https证书安装的神器
假设配置了，那大概就是这样，
- 端口3000对应：https://h-frontend.xxx.xxx
- 端口3170对应：https://h-backend.xxx.xxx
- 端口3100对应：https://h-admin.xxx.xxx
贴一下docker-compose文件，没啥好说的，直接跑起就行

version: '3'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

2.2 准备.env文件

这个是hoppscotch的配置文件，里面配置了所有需要用的字段，标注了必改的必须认真看看
打开源码地址，找到.env.example,把内容复制，在本地随便找个编辑器，粘贴后修改
主要改到的地方有（以下讲解一下各个改到的参数的用途，最后附上改好的全文）：
- DATABASE_URL：必改，数据库连接，具体可参考前面的2.1.2 3个分开版本里面的数据库字段说明
- JWT_SECRET：必改，jwt加密，可以通过Windows自带的powershell自带的函数快速生成，打开powershell，输入 [guid]::NewGuid().ToString()，把生成的直接复制填上就行
- SESSION_SECRET：必改，同上
- REDIRECT_URL：跳转地址，默认是http://localhost:3000，也就是前端api界面服务，如果要配置二级域名，就改成对应的二级域名，假设配置了证书的二级域名，类似这样：https://h-frontend.xxx.xxx
- WHITELISTED_ORIGINS：白名单，必须配置，不然会有cors错误，默认是http://localhost:3170,http://localhost:3000,http://localhost:3100，如果要配置二级域名，就改成对应的二级域名，具体端口对应的，假设配置了证书的二级域名，类似这样：https://h-backend.xxx.xxx,https://h-frontend.xxx.xxx,https://h-admin.xxx.xxx
- VITE_ALLOWED_AUTH_PROVIDERS：配置登录方式，可改可不改，如果没有同步需求的话，不用改，默认是GOOGLE,GITHUB,MICROSOFT,EMAIL，也就是配置了谷歌登录，github登录，微软登录和邮箱登录
  - 后面跟着的是对应的登录方式的配置，具体配置方法可以搜索或问gpt4
  - 需要关注的是***_CALLBACK_URL，每一个登录方式里都有一个回调地址，默认是http://localhost:3170/v1/auth/google/callback，可以看出是用的接口的端口，假设配置了证书的二级域名，类似这样：https://h-backend.xxx.xxx/v1/auth/microsoft/callback
VITE_BASE_URL：必改，前端地址，默认是http://localhost:3000，假设配置了证书的二级域名，类似这样：https://h-frontend.xxx.xxx
VITE_SHORTCODE_BASE_URL：必改，短地址，可以跟前端地址一样，同上
VITE_ADMIN_URL：必改，后台地址，默认是http://localhost:3100，假设配置了证书的二级域名，类似这样：https://h-admin.xxx.xxx
VITE_BACKEND_GQL_URL：必改，默认是http://localhost:3170/graphql，假设配置了证书的二级域名，类似这样：https://h-backend.xxx.xxx/graphql
VITE_BACKEND_WS_URL：必改，默认是ws://localhost:3170/graphql，假设配置了证书的二级域名，类似这样ws://h-backend.lulua.net/graphql
VITE_BACKEND_API_URL：必改，默认是http://localhost:3170/v1，假设配置了证书的二级域名，类似这样https://h-backend.xxx.xxx/v1

2.2.1 默认ip的.env

#-----------------------Backend Config------------------------------#
# Prisma Config
DATABASE_URL=postgresql://postgres:password@172.17.0.1:5432/hoppscotch

# Auth Tokens Config
JWT_SECRET="自己生成"
TOKEN_SALT_COMPLEXITY=10
MAGIC_LINK_TOKEN_VALIDITY= 3
REFRESH_TOKEN_VALIDITY="604800000" # Default validity is 7 days (604800000 ms) in ms
ACCESS_TOKEN_VALIDITY="86400000" # Default validity is 1 day (86400000 ms) in ms
SESSION_SECRET='自己生成'
# Reccomended to be true, set to false if you are using http
# Note: Some auth providers may not support http requests
ALLOW_SECURE_COOKIES=true

# Hoppscotch App Domain Config
REDIRECT_URL="http://localhost:3000"
WHITELISTED_ORIGINS="http://localhost:3170,http://localhost:3000,http://localhost:3100"
VITE_ALLOWED_AUTH_PROVIDERS=GOOGLE,GITHUB,MICROSOFT,EMAIL

# Google Auth Config
GOOGLE_CLIENT_ID="************************************************"
GOOGLE_CLIENT_SECRET="************************************************"
GOOGLE_CALLBACK_URL="http://localhost:3170/v1/auth/google/callback"
GOOGLE_SCOPE="email,profile"

# Github Auth Config
GITHUB_CLIENT_ID="************************************************"
GITHUB_CLIENT_SECRET="************************************************"
GITHUB_CALLBACK_URL="http://localhost:3170/v1/auth/github/callback"
GITHUB_SCOPE="user:email"

# Microsoft Auth Config
MICROSOFT_CLIENT_ID="************************************************"
MICROSOFT_CLIENT_SECRET="************************************************"
MICROSOFT_CALLBACK_URL="http://localhost:3170/v1/auth/microsoft/callback"
MICROSOFT_SCOPE="user.read"
MICROSOFT_TENANT="common"

# Mailer config
MAILER_SMTP_ENABLE="true"
MAILER_USE_CUSTOM_CONFIGS="false"
MAILER_ADDRESS_FROM='"From Name Here" <from@example.com>'

MAILER_SMTP_URL="smtps://user@domain.com:pass@smtp.domain.com" # used if custom mailer configs is false

# The following are used if custom mailer configs is true
MAILER_SMTP_HOST="smtp.domain.com"
MAILER_SMTP_PORT="587"
MAILER_SMTP_SECURE="true"
MAILER_SMTP_USER="user@domain.com"
MAILER_SMTP_PASSWORD="pass"
MAILER_TLS_REJECT_UNAUTHORIZED="true"

# Rate Limit Config
RATE_LIMIT_TTL=60 # In seconds
RATE_LIMIT_MAX=100 # Max requests per IP


#-----------------------Frontend Config------------------------------#


# Base URLs
VITE_BASE_URL=http://localhost:3000
VITE_SHORTCODE_BASE_URL=http://localhost:3000
VITE_ADMIN_URL=http://localhost:3100

# Backend URLs
VITE_BACKEND_GQL_URL=http://localhost:3170/graphql
VITE_BACKEND_WS_URL=ws://localhost:3170/graphql
VITE_BACKEND_API_URL=http://localhost:3170/v1

# Terms Of Service And Privacy Policy Links (Optional)
VITE_APP_TOS_LINK=https://docs.hoppscotch.io/support/terms
VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy

# Set to `true` for subpath based access
ENABLE_SUBPATH_BASED_ACCESS=false

2.2.2 二级域名版的.env(推荐)

#-----------------------Backend Config------------------------------#
# Prisma Config
DATABASE_URL=postgresql://postgres:password@172.17.0.1:5432/hoppscotch

# Auth Tokens Config
JWT_SECRET="自己生成"
TOKEN_SALT_COMPLEXITY=10
MAGIC_LINK_TOKEN_VALIDITY= 3
REFRESH_TOKEN_VALIDITY="604800000" # Default validity is 7 days (604800000 ms) in ms
ACCESS_TOKEN_VALIDITY="86400000" # Default validity is 1 day (86400000 ms) in ms
SESSION_SECRET='自己生成'
# Reccomended to be true, set to false if you are using http
# Note: Some auth providers may not support http requests
ALLOW_SECURE_COOKIES=true

# Hoppscotch App Domain Config
REDIRECT_URL="https://h-frontend.xxx.xxx"
WHITELISTED_ORIGINS="https://h-backend.xxx.xxx,https://h-frontend.xxx.xxx,https://h-admin.xxx.xxx"
VITE_ALLOWED_AUTH_PROVIDERS=GOOGLE,GITHUB,MICROSOFT,EMAIL

# Google Auth Config
GOOGLE_CLIENT_ID="************************************************"
GOOGLE_CLIENT_SECRET="************************************************"
GOOGLE_CALLBACK_URL="https://h-backend.xxx.xxx/v1/auth/google/callback"
GOOGLE_SCOPE="email,profile"

# Github Auth Config
GITHUB_CLIENT_ID="************************************************"
GITHUB_CLIENT_SECRET="************************************************"
GITHUB_CALLBACK_URL="https://h-backend.xxx.xxx/v1/auth/github/callback"
GITHUB_SCOPE="user:email"

# Microsoft Auth Config
MICROSOFT_CLIENT_ID="************************************************"
MICROSOFT_CLIENT_SECRET="************************************************"
MICROSOFT_CALLBACK_URL="https://h-backend.xxx.xxx/v1/auth/microsoft/callback"
MICROSOFT_SCOPE="user.read"
MICROSOFT_TENANT="common"

# Mailer config
MAILER_SMTP_ENABLE="true"
MAILER_USE_CUSTOM_CONFIGS="false"
MAILER_ADDRESS_FROM='"From Name Here" <from@example.com>'

MAILER_SMTP_URL="smtps://user@domain.com:pass@smtp.domain.com" # used if custom mailer configs is false

# The following are used if custom mailer configs is true
MAILER_SMTP_HOST="smtp.domain.com"
MAILER_SMTP_PORT="587"
MAILER_SMTP_SECURE="true"
MAILER_SMTP_USER="user@domain.com"
MAILER_SMTP_PASSWORD="pass"
MAILER_TLS_REJECT_UNAUTHORIZED="true"

# Rate Limit Config
RATE_LIMIT_TTL=60 # In seconds
RATE_LIMIT_MAX=100 # Max requests per IP


#-----------------------Frontend Config------------------------------#


# Base URLs
VITE_BASE_URL=https://h-frontend.xxx.xxx
VITE_SHORTCODE_BASE_URL=https://h-frontend.xxx.xxx
VITE_ADMIN_URL=https://h-admin.xxx.xxx

# Backend URLs
VITE_BACKEND_GQL_URL=https://h-backend.xxx.xxx/graphql
VITE_BACKEND_WS_URL=ws://h-backend.xxx.xxx/graphql
VITE_BACKEND_API_URL=https://h-backend.xxx.xxx/v1

# Terms Of Service And Privacy Policy Links (Optional)
VITE_APP_TOS_LINK=https://docs.hoppscotch.io/support/terms
VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy

# Set to `true` for subpath based access
ENABLE_SUBPATH_BASED_ACCESS=false

3. 安装

安装就很简单了，复杂的是前期的准备工作，把前面任意版本的docker-compose文件和.env文件，在服务器上新建个文件夹hoppscotch放好，结构如图：
直接命令：docker-compose up -d ，使用docker ps 观察是否成功启动容器（PS：如果无法拉取镜像，可看我另一文章）
启动成功后，会多一个文件夹，是postgresql的存储目录，如图：
细心观察会发现，其实容器一直在重启报错，这是因为没有数据库迁移，看下一步

4. 解决数据库迁移报错

4.1 3合1版本

运行命令：docker compose run --entrypoint sh hoppscotch-aio，这时候会进入容器内部
在容器内运行命令：npm config set registry https://registry.npmmirror.com，配置一下镜像地址
在容器内运行命令：pnpx prisma migrate deploy，这是在做数据库迁移，PS，这里偶尔会卡住，直接ctrl+c，强行停止，重新运行一次命令就ok。
在容器内运行命令：exit，退出容器
运行命令：docker-compose down，关闭容器
运行命令：docker-compose up -d，启动容器，这时候理论上就不重启了
浏览器尝试打开地址：
- ip版本
  - 前端地址是：http://localhost:3000，第一次打开要加载资源，有点慢，等全部打开后，就是眼熟的类似postman的界面了
  - 后台管理地址是：http://localhost:3100
- 二级域名版本
  - 前端地址是：https://h-frontend.xxx.xxx，第一次打开要加载资源，有点慢，等全部打开后，就是眼熟的类似postman的界面了
  - 后台管理地址是：https://h-admin.xxx.xxx

4.2 独立版本

运行命令：docker compose run --entrypoint sh hoppscotch-backend，这时候会进入容器内部
在容器内运行命令：npm config set registry https://registry.npmmirror.com，配置一下镜像地址
在容器内运行命令：pnpx prisma migrate deploy，这是在做数据库迁移，PS，这里偶尔会卡住，直接ctrl+c，强行停止，重新运行一次命令就ok。
在容器内运行命令：exit，退出容器
运行命令：docker-compose down，关闭容器
运行命令：docker-compose up -d，启动容器，这时候理论上就不重启了
浏览器尝试打开地址：
- ip版本
  - 前端地址是：http://localhost:3000，第一次打开要加载资源，有点慢，等全部打开后，就是眼熟的类似postman的界面了
  - 后台管理地址是：http://localhost:3100
- 二级域名版本
  - 前端地址是：https://h-frontend.xxx.xxx，第一次打开要加载资源，有点慢，等全部打开后，就是眼熟的类似postman的界面了
  - 后台管理地址是：https://h-admin.xxx.xxx

5. 安装浏览器插件

其实理论上，到上面的一步，能打开前端界面，能测试api，就可以愉快的使用了，但是，多用几个api就会发现，有些接口明明是通的，但是无法使用，这是浏览器的锅，为了安全，浏览器自作主张加了很多安全策略，在平时的时候保护了我们，但在开发的时候就是拦路虎，比如不同源不能调用接口啦，比如有证书的域名不能调用无证书的接口啦等等等。
解决的办法hoppscotch也提供了，安装hoppscotch提供的浏览器插件
先点击前端界面的设置按钮
往下拖动，最底下有浏览器插件的字眼，点击使用的对应的浏览器图标，会跳转到相应的地址
安装完成后，还得设置启用
哦对了，如果有人不习惯侧边栏在右侧，可以选择在左侧
至此，就可以愉快的使用了！

6. 配置github登录选项(可选)

如果想配置github登录，先打开github设置页，打开后，点击右上角，新建一个新的支持oauth的app
如下图所示，按照图里提示的填写，最重要的是回调地址，这个地址其实配置在.env文件里
注册成功后，获得GITHUB_CLIENT_ID和GITHUB_CLIENT_SECRET，填写到.env文件对应的地方
最后，需要重启一下服务，这里用个坑，修改了.env文件后，不会生效，需要清空配置表
先用docker ps，获得postgresql的容器id
获得容器id后，组装命令：docker exec -it <db_container_id> psql -d hoppscotch -c "TRUNCATE \"InfraConfig\";"，把<db_container_id>一整个替换成容器id，不要留<>，运行完毕后
使用命令：docker-compose down，停止服务
使用命令：docker-compose up -d ，启动服务
重启成功后，点击登录，使用github登录，能够成功跳转github并登录就ok了

7. 官方相关文档

附上github项目地址
附上官方文档地址

over, enjoy!!!
如对您有帮助，感谢投喂！
微信感谢投喂版

Scoful

关注

18
点赞
踩
17

收藏

觉得还不错? 一键收藏
1
评论
教程：postman的平替hoppscotch，又叫postwoman，hoppscotch的docker-compose安装过程

教程：postman的平替hoppscotch，又叫postwoman，hoppscotch的docker-compose安装过程
复制链接

扫一扫

专栏目录