使用docker部署内网hoppscotch

实现目标

由于https://hoppscotch.io依赖于互联网
hoppscotch自己的部署教程又更侧重于使用 github / google / microsoft / email等鉴权登录(这种强制靠邮件注册新增用户真的是对内网及其不友好)
于是希望在内网部署一个公共可用的hoppscotch的服务,用于开发人员调试环境用,同时具有管理后台等相关功能

经过一番查找,官方的docker部署坑还是比较多,所以沿用了https://github.com/webysther/hoppscotch-docker.git仓库中的东西自己搭建了一套

简单来说就是通过本地的一个假smtp服务器用于创建用户与登录,同时拥有线上服务的所有功能

之后用户可使用自己的邮箱进行登录(由于是虚假的smtp服务,原则上连邮箱都可以省略,以邮箱的形式创建账户即可)

环境

OS: Debian 12 (其实这个不重要,毕竟都是用docker了,只要能装docker你用Windows也成)
IP: 192.168.0.66
CPU : 4core
内存: 4GB
硬盘: 40GB

搭建步骤

docker服务安装

# 安装docker
curl -fsSL https://get.docker.com -o /tmp/get-docker.sh
## 大陆机器可指定中科大源进行下载
DOWNLOAD_URL=https://mirrors.ustc.edu.cn/docker-ce sh /tmp/get-docker.sh
## 大陆地区外的机器可直接运行部署
sh /tmp/get-docker.sh

请自行解决镜像拉取问题

由于hoppscotch强依赖于邮件服务,所有账号注册都需要用到,若公司有自建服务则可以提供连接信息,若没有现成的邮件服务则可以考虑自己动手撸一个假的服务出来,这里我使用官方推荐的mailcatcher

# 部署smtp服务
docker run -d --name smtp -p 1025:1025 -p 1080:1080 dockage/mailcatcher:latest

部署后可通过访问服务器上的1080端口(http://192.168.0.66:1080)获取hoppscotch发送的邮件

构建镜像

# 部署hoppscotch
## 本地构建hoppscotch镜像
### 基于github仓库 https://github.com/webysther/hoppscotch-docker.git 进行构建
git clone https://github.com/webysther/hoppscotch-docker.git
cd hoppscotch-docker
## 由于仓库最新更新时间为2023年,距离当前的latest(24.09.01)有较大差异,所以要做些修改
## 编辑dockerfile,修改nodejs版本
-ENV NODE_VERSION=18.16.0
+ENV NODE_VERSION=20.9.0
## 保存退出,执行构建
docker build -t local/hoppscotch:24.09.01 .
## 构建完成后,检查本地镜像
docker image ls

准备配置文件

创建文件docker-compose.yml(touch /root/docker-compose.yml),编写以下内容

---
version: "2.1"
services:
  hoppscotch:
    image: local/hoppscotch:24.09.01
    container_name: hoppscotch
    networks:
      hoppscotch:
      hoppscotch-db:
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - ENABLE_ADMIN=true  # 启用dashboard控制面板
      - SMTP_PROTOCOL=smtp  # 使用smtp协议发送邮件
      - SMTP_DOMAIN=192.168.0.66  # smtp服务地址
      - SMTP_PORT=1025  # smtp服务端口
      - DOMAIN=192.168.0.66  # 内网访问域名,可填写ip地址
      - POSTGRES_PASSWORD=password  # 连接postgres数据库,需与下方postgres的密码保持一致
      - REFRESH_TOKEN_VALIDITY=2592000000  # toke有效期,单位为ms
      - ACCESS_TOKEN_VALIDITY=2592000000  # toke有效期,单位为ms
      - VITE_BACKEND_WS_URL=ws://192.168.0.66/api/graphql  # 默认使用wss,这里改写为ws,否则在http访问下会有问题
      - VITE_ALLOWED_AUTH_PROVIDERS=EMAIL # 验证方式仅启用email,如果你有考虑接入其他的登录服务可参考官方配置
      - DATA_ENCRYPTION_KEY=******************************** # 加密密钥,可输入随机字符串替换,如不替换这么写也可以

    volumes:
      - /home/hoppscotch-aio/hoppscotch/config:/config # 从本地创建一个目录挂载到容器中以保留原有配置
    ports:
      - 80:80
    depends_on:
      hoppscotch-db:
        condition: service_healthy
    restart: unless-stopped

  hoppscotch-db:
    image: postgres:alpine
    container_name: hoppscotch-db
    networks:
      hoppscotch-db:
    environment:
      - POSTGRES_DB=hoppscotch
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password  # 需与上方的连接密码保持一致
    volumes:
      - /home/hoppscotch-aio/postgres/data:/var/lib/postgresql/data # 从本地创建一个目录挂载到容器中用于持久化postgres数据
    expose:
      - 5432
    healthcheck:
      test: [
        "CMD-SHELL", 
        "sh -c 'pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}'"
      ]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

networks:
  hoppscotch:
    name: hoppscotch
  hoppscotch-db:
    name: hoppscotch-db

启动服务

创建一个本地文件夹hoppscotch-aio,并把刚刚创建的docker-compose.yml丢进这个目录中即可

mkdir /home/hoppscotch-aio
cp /root/docker-compose.yml
docker compose up -d

开始使用

通过http://192.168.0.66/admin/ 验证管理后台是否能通过邮箱登录,方法如下

1. 使用邮箱登录,可以随意填写一个邮箱
2. 点击"Send magic link"发送邮箱验证码
3. 由于我们配置了mailcatcher,邮件会被mailcatcher挟持,登录http://192.168.0.66:1080即可查看到hoppscotch发送的邮件
4. 在后台界面中,找到属于你的那封邮件,点击邮件中的"Sign to Hoppscotch"登录至后台

登录管理后台只是为了方面查看管理工作区与用户,实际使用的过程中,hoppscotch会将第一个登录使用的用户设置为管理员,在http://192.168.0.66界面进行注册登录也是相同的操作

剩下的就是愉快的使用hoppscotch了~