企业官网建设流程全解析

Hoppscotch自托管部署完全指南：Docker Compose一键搭建、Caddy配置与数据库迁移详解

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch

Hoppscotch 是一款开源 API 开发生态工具（支持 Web、桌面与 CLI），是 Postman 与 Insomnia 的开源替代方案。本文带你完成 Hoppscotch 自托管部署：通过 Docker Compose 一键搭建整套服务，理解 Caddy 反向代理的两种配置模式，并掌握 Prisma 数据库迁移的自动化原理，让你的 API 调试平台安全运行在自己的服务器上。🚀

一、为什么选择 Hoppscotch 自托管

自托管（Self-Host）意味着把整套服务部署到你自己的服务器上，适合团队共享与数据敏感场景：

• 🔒数据主权：请求、环境变量、团队集合全部存储在你可控的 PostgreSQL 中
• 🌐离线可用：内网环境也能完整使用，无需依赖公有云
• 👥团队协作：自带管理后台（SH Admin Dashboard），可邀请成员、管理团队
• 🖥️多端接入：Web、桌面端、CLI 均可连接同一套自托管实例

核心组件一览（全部通过 docker-compose.yml 编排）：

二、Docker Compose 一键搭建步骤

1. 克隆仓库并准备环境变量

git clone https://gitcode.com/GitHub_Trending/ho/hoppscotch cd hoppscotch cp .env.example .env

环境变量模板见 .env.example，部署前务必修改这三项：

DATABASE_URL=postgresql://postgres:你的密码@hoppscotch-db:5432/hoppscotch DATA_ENCRYPTION_KEY=一个32位的加密密钥 # 敏感数据加密，不可泄露 VITE_BACKEND_GQL_URL=http://localhost:3170/graphql # 改成你的访问域名

2. 使用 default 配置一键启动（推荐）

docker compose --profile default up

这条命令会同时拉起三个服务（详见 docker-compose.yml）：

• AIO 容器：由 prod.Dockerfile 的aio目标构建，内含 Caddy、后端与 Web 应用
• PostgreSQL 15：带健康检查，确保数据库就绪后才启动业务容器
• 自动迁移服务：执行pnpm exec prisma migrate deploy，首次部署自动建表

💡 其他常用 profile：backend（仅后端）、app（仅前端）、admin（仅管理后台）、database（仅数据库）、default-no-db（使用外部数据库时）

3. 记住这些核心端口

容器启动后可通过 healthcheck.sh 的健康检查逻辑自检：它会依次请求:3000、:3100、:3170/ping确认各服务存活。

三、Caddy 配置详解：多端口与子路径两种模式

AIO 容器内置 Caddy 作为反向代理，由启动脚本 aio_run.mjs 根据环境变量选择加载哪份配置文件。

模式 A：多端口模式（默认，推荐）

配置文件：aio-multiport-setup.Caddyfile

:3000 { root * /site/selfhost-web; file_server } # 主应用 :3100 { root * /site/sh-admin-multiport-setup; ... } # 管理后台 :3170 { handle { reverse_proxy localhost:8080 } } # 后端 API

各服务占用独立端口，结构清晰，适合搭配外层的 Nginx / Caddy / 云厂商负载均衡做 TLS 终结。

模式 B：子路径模式（单端口）

配置文件：aio-subpath-access.Caddyfile

:{$HOPP_AIO_ALTERNATE_PORT:80} { handle_path /admin* { ... } # 管理后台挂到 /admin 路径 handle_path /backend* { ... } # 后端 API 挂到 /backend 路径 handle_path /desktop-app-server* { ... } }

整个服务只暴露一个端口（默认 80，可用HOPP_AIO_ALTERNATE_PORT修改），主应用、/admin、/backend全部挂在同一域名下——非常适合反向代理已占用 80/443 端口的服务器。

如何切换模式

只需在.env中增加一行，然后重建容器：

ENABLE_SUBPATH_BASED_ACCESS=true

启动时 aio_run.mjs 会自动判断该变量并加载对应的 Caddyfile，无需手动改任何代理规则。

四、数据库迁移详解：Prisma 自动化原理

Hoppscotch 后端基于Prisma + PostgreSQL，数据库结构定义在 packages/hoppscotch-backend/prisma/schema.prisma，每次结构变更都会生成一份带时间戳的迁移脚本，存放在 packages/hoppscotch-backend/prisma/migrations/ 目录（如20251016080714_mock_server、20251110141554_api_doc等）。

迁移流程在 Docker 场景中全自动：

1. hoppscotch-db容器启动并通过pg_isready健康检查
2. hoppscotch-migrate容器依依赖顺序启动，执行prisma migrate deploy
3. Prisma 按时间戳顺序将未应用的迁移逐一写入数据库
4. 业务容器（AIO）确认数据库健康后才启动

这意味着：升级版本时只需重新构建镜像并启动，数据库结构会自动跟进，无需手工执行任何 SQL。手动补迁移也可进入容器执行：

docker compose run hoppscotch-migrate

⚠️ 注意：生产环境请务必修改docker-compose.yml中的POSTGRES_PASSWORD（默认testpass），切勿使用默认密码暴露公网。

五、进阶：桌面应用连接自托管实例

部署完成后，桌面客户端可直接指向你的自托管服务器，实现团队配置与请求数据统一同步，相关实现位于 packages/hoppscotch-desktop/。

连接自托管实例时，填写3200端口的 Bundle 服务器地址（http://<服务器IP>:3200），桌面端即可加载由 Web 应用服务器（Go 编写，源码见 packages/hoppscotch-selfhost-web/webapp-server/）分发的应用包：

六、常见部署问题速查

管理后台（3100 端口）可在此配置代理地址、默认环境等，源码位于 packages/hoppscotch-sh-admin/。

七、关键文件导航

• 部署编排：docker-compose.yml、docker-compose.deploy.yml
• 镜像构建：prod.Dockerfile（AIO / Backend / App 多目标）
• 反向代理：aio-multiport-setup.Caddyfile、aio-subpath-access.Caddyfile
• 启动脚本与健康检查：aio_run.mjs、healthcheck.sh
• 环境变量模板：.env.example
• 数据库模型与迁移：packages/hoppscotch-backend/prisma/
• 项目说明：README.md

🎯总结：一条docker compose --profile default up即可获得完整的 Hoppscotch 自托管环境——AIO 容器承载应用、Caddy 处理路由、Prisma 自动迁移数据库。理解ENABLE_SUBPATH_BASED_ACCESS开关与端口规划后，你就能灵活地把这套开源 API 开发平台部署到任何内网或公网服务器上，享受数据完全自主的 API 调试体验。

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch