hoppscotch自托管部署需五步：一、验证docker 20.10+/compose v2+及2gb内存；二、克隆官方仓库并确认配置文件存在；三、修改.env中database_url、data_encryption_key等关键变量；四、配置国内镜像加速与专用网络hoppscotch-net；五、调整端口映射后docker-compose up -d启动。
如果您希望在本地或私有服务器上快速搭建一个功能完整的Hoppscotch自托管API测试平台，但遇到Docker部署流程不清晰、环境配置失败或服务无法启动等问题，则可能是由于镜像拉取异常、端口冲突、网络隔离或环境变量缺失所致。以下是解决此问题的步骤：
一、基础环境准备与验证
确保宿主机已安装兼容版本的Docker和Docker Compose，这是容器化运行Hoppscotch的前提。未满足该条件将导致后续所有构建和启动操作失败。
1、执行命令检查Docker引擎是否就绪：docker --version
2、验证Docker Compose是否可用：docker compose version
3、确认系统内存不低于2GB，且磁盘剩余空间大于10GB。
4、若尚未安装，须依据官方文档安装Docker Engine 20.10+及Docker Compose v2+。
二、项目代码获取与目录初始化
Hoppscotch官方仓库提供标准化的Docker Compose编排文件，必须从可信源获取原始代码，避免使用过时或篡改的镜像或配置。
1、克隆最新稳定版仓库（注意非fork分支）：git clone https://github.com/hoppscotch/hoppscotch.git
2、进入项目根目录：cd hoppscotch
3、确认目录中存在docker-compose.yml和.env.example文件。
三、环境变量配置与安全加固
环境变量直接决定数据库连接、前端地址解析、CORS策略及认证密钥有效性，错误配置将导致服务启动后无法访问或登录失败。
1、复制示例配置文件：cp .env.example .env
2、编辑.env文件，重点修改以下项：DATABASE_URL=postgresql://root:123456@postgres:5432/public
3、设置32位长度加密密钥：DATA_ENCRYPTION_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
4、配置白名单Origin（含本地及内网IP）：WHITELISTED_ORIGINS=http://localhost:3000,http://192.168.1.100:3000
5、设定前端基础路径：VITE_BASE_URL=http://localhost:3000
四、Docker网络与镜像加速配置
默认Docker Hub拉取速度慢且易中断，尤其在国内网络环境下；同时多个服务需通过自定义网络通信，否则容器间DNS解析失败。
1、创建专用桥接网络：docker network create hoppscotch-net
2、配置国内镜像加速器：编辑/etc/docker/daemon.json，添加至少三个国内源，例如：https://docker.mirrors.ustc.edu.cn
3、重载并重启Docker守护进程：sudo systemctl daemon-reload && sudo systemctl restart docker
4、验证镜像加速生效：docker info | grep "Registry Mirrors"
五、服务启动与端口映射调整
Docker Compose默认绑定3000/3100/3170端口，若已被占用或需对外暴露，必须提前修改映射规则，否则服务将启动失败或不可达。
1、打开docker-compose.yml，定位hoppscotch-app服务下的ports字段。
2、如需更换前端端口，修改为：- "3001:3000"
3、同步更新.env中对应URL变量：VITE_BASE_URL=http://localhost:3001
4、后台启动全部服务：docker-compose up -d
5、查看容器运行状态：docker-compose ps
