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

Scoful

91263人浏览 · 2024-08-21 16:34:06

Scoful · 2024-08-21 16:34:06 发布

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!!!
如对您有帮助，感谢投喂！
微信感谢投喂版

向您推荐>>Eolink开发者社区

权威｜前沿｜技术｜干货｜国内首个API全生命周期开发者社区

更多推荐

深入理解 Mocha 测试框架：从零实现一个 Mocha

前言什么是自动化测试自动化测试在很多团队中都是Devops环节中很难执行起来的一个环节，主要原因在于测试代码的编写工作很难抽象，99%的场景都需要和业务强绑定，而且写测试代码的编写工作量往往比编写实际业务代码的工作量更多。在一些很多业务场景中投入产出比很低，适合写自动化测试的应该是那些中长期业务以及一些诸如组件一样的基础库。自动化测试是个比较大的概念，其中分类也比较多，比如单元测试，端对端测试，集

云原生

ELK实现containerd的容器日志采集展示【基于logging的全栈监测】

企业级ELK Stack构建介绍

云原生

(20200916 Solved)docker-compose up创建容器自动退出

问题描述如题，创建容器后自动退出了。并且docker start container无效解决方案原因是缺失了控制终端的配置，需要在docker-compose.yml中增加tty:true ，有时候这样也不行，需要再增加一个command:/bin/bash，命令不一定是这个，需要是一个不会退出的命令，然后用-d后台启动容器。Referencesdocker-compose启动容器后自动退出...