目录
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
- ip版本
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
- ip版本
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!!!
如对您有帮助,感谢投喂!