Hoppscotch私有化部署需四步：一、安装Docker 20.10+、Compose v2、Git并预留2GB内存；二、克隆官方仓库并检出稳定标签；三、配置.env文件，替换IP、生成32位密钥、添加桌面端Origin白名单；四、按需选择All-in-One或docker-compose.deploy.yml启动，并逐项验证服务状态与接口连通性。
如果您希望在本地或私有服务器上运行Hoppscotch，以实现数据隔离、团队协作与安全可控的API测试环境，则需完成自部署私有实例。以下是针对生产级需求的高级部署配置流程：
一、准备基础运行环境
Hoppscotch自托管依赖标准化容器运行时与数据库服务，确保系统满足最低兼容性要求是启动部署的前提。缺失任一组件将导致服务初始化失败或功能受限。
1、安装Docker Engine 20.10.x或更高版本，并验证运行状态：docker info | grep "Server Version"
2、安装Docker Compose v2，并确认其为默认CLI插件：docker compose version
3、分配至少2GB内存与20GB可用磁盘空间，避免构建阶段因资源不足中断
4、安装Git工具用于拉取源码，执行：git --version 验证可用性
二、获取并校验项目源码
使用官方镜像仓库可保障组件完整性与版本一致性，避免第三方分叉引入未审计变更。必须核对提交哈希以确认代码来源可信。
1、克隆主干仓库至本地指定路径：git clone https://gitcode.com/GitHub_Trending/ho/hoppscotch.git && cd hoppscotch
2、检出经验证的稳定发布标签（如v4.25.0）：git checkout tags/v4.25.0 -b stable-v4.25.0
3、校验Git签名或SHA256摘要（参考RELEASES.md中公布的checksum值）
三、配置多层级环境变量
环境变量需按作用域分层设置：全局基础参数控制服务拓扑，敏感密钥必须脱离版本控制，域名相关字段须严格匹配客户端访问路径，否则触发CORS拦截或认证失败。
1、复制模板文件：cp .env.example .env
2、编辑.env，替换所有{{SERVER_IP}}为服务器实际内网IP（例如192.168.1.100），不可使用localhost或127.0.0.1
3、生成并填入32字符DATA_ENCRYPTION_KEY：openssl rand -hex 16
4、在WHITELISTED_ORIGINS中添加桌面客户端专用Origin：app://hoppscotch_mydomain_com（将mydomain_com替换为实际域名下划线格式）
5、若启用SMTP，配置MailCatcher镜像地址为http://{{SERVER_IP}}:1080，端口不可更改
四、选择部署架构模式
根据使用规模与运维能力选择对应架构：All-in-One适用于快速验证与小团队试用；多容器分离部署支持水平扩展与故障隔离，适合企业级长期运行。
1、All-in-One模式（推荐入门）：直接运行默认编排文件：docker-compose up -d
2、生产级分离部署：使用专用部署配置：docker-compose -f docker-compose.deploy.yml up -d
3、Kubernetes部署：应用Service定义中必须暴露targetPort: 3200供桌面客户端通信，Ingress规则需单独指向webapp-server端口
4、手动构建镜像（定制化需求）：执行docker build -f prod.Dockerfile -t my-hoppscotch .，跳过远程镜像拉取
五、验证服务连通性与权限控制
服务启动后需逐层验证网络可达性、接口响应有效性及安全策略生效情况。任何环节异常均需回溯对应配置项，不可跳过中间验证步骤。
1、检查容器运行状态：docker-compose ps，确认hoppscotch-app、hoppscotch-backend、hoppscotch-db全部为"Up"
2、测试前端服务响应：curl -I http://192.168.1.100:3000，应返回HTTP 200且Header含X-Frame-Options: DENY
3、验证GraphQL端点可用性：curl -X POST http://192.168.1.100:3170/graphql -H "Content-Type: application/json" -d '{"query":"{ __typename }"}'
4、登录管理后台http://192.168.1.100:3100，检查JWT_SECRET是否已加载为非默认值
