[手把手系列]Hoppscotch Self-Host

引言

Postman 的功能非常出色，它基本上将 API 调试这个场景挖掘得淋漓尽致了。我印象深刻的是它强大的脚本能力; 不仅可以对单个请求设置前后脚本，对于整个 Collection 甚至都可以设置前后脚本，这在环境初始化、Token 签发上、测试上非常有用; 还有 Flows 功能，我可以通过集成API、Agen的形式，快速地构建 API 测试用例，而无需繁杂的手动调试。简单地说: "Life is short, you should use Postman"。

这么好的应用，收费当然是无可厚非的。但是 Postman 的 API 是托管在云端，信息隐私和安全是当前第一位重要的，尤其是我可不希望我的 AppKey 或者其他什么密钥在未来的某一谈被 Claude 或者什么 Copilot 自动补全出来;

这也是我迫切希望使用一个开源的、本地的 API 调用工具的原因;

Hoppscotch

Hoppscotch 并没有哪个功能让我拍腿叫绝, 我所有的使用场景就是 API 调试, 相比较 Postman , 它甚至不能给 API 编写文档, 你敢信? 我过一段时间, 甚至都会忘记某个 API 应该如何传递参数, Hoppscotch 甚至没有发送请求的Console, 我都不能确定我发送给服务端的请求中的参数正不正确(在使用的环境变量占位符的情况下); Hoppscotch 的脚本功能也只能提供少的可怜的 API , 他的 Collection RUN 功能也简陋的像个玩具,但是没关系, 对于我们程序员而言, 如果一个东西, 长得像鸭子, 叫起来像鸭子, 飞起来像鸭子, 那他就是鸭子;

至于 Hoppscotch 的多协议支持对我而言只是佐酒的小添头, 我其实并不在意 GraphQL 和 WebSocket 协议, 我编写他们的数量只占用我所有代码的 1%?

自建 Self-Host 版本

选择自搭建的初衷一直是数据安全, 随着数据落入 postgreSQL 数据, 心里终于有了一种落地的感觉

前置环境搭建, 你可以看看这个链接, 总的来说, 我们需要预先安装好:

node.js / npm / pnpm; 作为一个Java 程序员 , 我的本地环境中有这些很正常;
docker, (smtp可以跳过, 自己给自己发邮件没什么意思);
PostgreSQL, 数据库;
GITHUB OAuth, 用于登录验证, 看 Creating an OAuth app 这里就不会错了;

对我而言准备阶段的耗时, 和你读完到这里的时间耗时差不多;

我选择在本机(MacOS M1)中构建 Hoppscotch AIO(All In One)镜像;

为什么是 All In One? ⇒ 懒得折腾, All In One 镜像打包了 FrontEnd, Admin Dashboard, Backend 三个镜像; 看看下面, 相比All In One 容器, 后三者莫名有种多此一举的美;

拉取镜像:

bash 复制代码

docker pull hoppscotch/hoppscotch

接下来, 我们就需要配置 Hoppscotch AIO 容器的 .env 文件了, 这绝对是旅程中最困难的一部分了, 相信我;

整个配置文件 .env 大概长这个样子:

为了你的生活质量着想, 我就不贴出完整的配置条目了, 你只需要注意以下这几个点就行:

DATABASE_URL: 数据库链接, Hoppscotch 使用了 Prisma 这个开源项目; 如果你想连接到本机的PostgreSQL数据库时, 记得将host替换成 host.docker.internal , 就像下面这样:

json 复制代码

postgresql://<user_name>:<password>@host.docker.internal:5432/<db_name>

如果你已经是一个老 Docker, 一眼就看出了 URL不应该是localhost/127.0.0.1, 而是 host.docker.internal 这个神秘代码;

HOPP_AIO_ALTERNATE_PORT=8998 , 设置All In One ; 以及开启 subpatch access mode 必配的参数, 选择你的幸运数字;

Auth Tokens Config 不用去动它, 如果你没有特殊要求的话

VITE_ALLOWED_AUTH_PROVIDERS → 选择 GITHUB, 和下面这些配制是配套的;

json 复制代码

# Github Auth Config
GITHUB_CLIENT_ID=Ov23l***9EyZQd6Kn
GITHUB_CLIENT_SECRET=76b****039050a67578fe
GITHUB_CALLBACK_URL=http://localhost:8998/backend/v1/auth/github/callback
GITHUB_SCOPE=user:email

python 复制代码

#-----------------------Frontend Config------------------------------#
# 前端配置
# Base URLs
VITE_BASE_URL=http://localhost:8998
VITE_SHORTCODE_BASE_URL=http://localhost:8998
VITE_ADMIN_URL=http://localhost:8998

# Backend URLs
VITE_BACKEND_GQL_URL=http://localhost:8998/backend/graphql
VITE_BACKEND_WS_URL=wss://localhost:8998/backend/graphql
VITE_BACKEND_API_URL=http://localhost:8998/backend/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

# 非常重要!! 必须设置成 true
ENABLE_SUBPATH_BASED_ACCESS=true

Self Host! 启动

如果选择了 AIO 以及开启 subpatch access mode , 并且配置了一个 PostgreSQL 作为存放API 数据, 然后像官网教程一样

运行下面的代码, 并启动了容器:

bash 复制代码

docker run -p 8998:8998 --env-file .env --restart unless-stopped hoppscotch/hoppscotch

那你大概率会在控制台遇到这个问题: 数据表还没初始化呢!

bash 复制代码

Database migration not found. Please check the documentation 
or assistance: https://docs.hoppscotch.io/documentation/self-host/community-edition/install-and-build#running-migrations

并且你需要先执行下面这个:

bash 复制代码

 # 登录容器; 
 docker run -it --entrypoint sh --env-file .env hoppscotch/hoppscotch
 # 执行神秘的数据库初始化脚本, 这会在你的PostgreSQL的 DB中, 创建 hoppscotch 需要的数据表格; 
 pnpm dlx prisma migrate deploy

访问 localhost:8998/admin/ , 你将看到 GITHUB 登录界面, 登录你的 GITHUB 账号后, 你就可以开始创建 Workspace 了, 具体可以查看链接;

访问 localhost:8998 你将有用一个私有的 API 调试工具啦; 在 Postgres 中的 TeamRequest 表中可以看到哦;

总结

Hoppscotch 作为一个轻量级的 API 调试工具，虽然功能没有 Postman 那么丰富，但它的开源特性和自托管能力让我们能够更好地保护 API 数据的安全性。通过 Docker 和 PostgreSQL 的配合，我们可以快速搭建一个私有的 API 调试环境。

整个搭建过程中最关键的环节是:

正确配置 .env 文件，特别是数据库连接和 GitHub OAuth 设置
注意使用 host.docker.internal 来连接宿主机的 PostgreSQL
记得执行数据库迁移脚本初始化表结构

[手把手系列]Hoppscotch Self-Host

引言

Hoppscotch

自建 Self-Host 版本

Self Host! 启动

总结

参考资料