Hoppscotch 自部署登录模块问题分析与解决方案

问题现象

在自部署 Hoppscotch 项目时，用户遇到了登录模块无法显示邮箱选项的问题，同时系统会弹出"Unable to load auth providers"的错误提示。通过调试发现，platform变量未定义，导致认证提供程序加载失败。

环境配置分析

典型的自部署环境配置包括以下关键组件：

1. Docker 编排文件：使用 hoppscotch/hoppscotch 镜像和 PostgreSQL 数据库容器
2. 环境变量文件：包含数据库连接、认证令牌、邮件服务器等配置
3. 反向代理：通过 Nginx 或类似工具提供 SSL 支持

根本原因

经过深入分析，发现问题主要源于环境变量在运行时的不一致性：

1. 环境变量丢失：页面刷新后，部分关键环境变量（如后端API地址）会丢失
2. SSL 要求：邮箱认证功能强制要求 HTTPS 连接
3. 缓存问题：浏览器缓存可能导致环境变量加载不一致

解决方案

1. 确保环境变量持久化

在部署配置中，必须确保所有 VITE_ 前缀的环境变量都能正确传递到前端：

VITE_BASE_URL=https://your-domain.com
VITE_SHORTCODE_BASE_URL=https://your-domain.com
VITE_ADMIN_URL=https://your-domain.com/admin
VITE_BACKEND_GQL_URL=https://your-domain.com/backend/graphql
VITE_BACKEND_WS_URL=wss://your-domain.com/backend/graphql
VITE_BACKEND_API_URL=https://your-domain.com/backend/v1
VITE_ALLOWED_AUTH_PROVIDERS=EMAIL

2. 配置反向代理

使用 Nginx 作为反向代理时，需要正确配置各个路由：

location / {
    proxy_pass http://localhost:3000;
    # 其他代理头设置...
}

location /admin {
    proxy_pass http://localhost:3100;
    # 其他代理头设置...
}

location /graphql {
    proxy_pass http://localhost:3170;
    # WebSocket 相关设置...
}

location /v1 {
    proxy_pass http://localhost:3170;
    # API 相关设置...
}

3. 强制 HTTPS 连接

邮箱认证功能必须运行在 HTTPS 环境下，确保：

1. 获取有效的 SSL 证书
2. 配置 HTTP 到 HTTPS 的重定向
3. 检查所有内部链接都使用 HTTPS 协议

4. 缓存控制策略

在部署配置中添加缓存控制头，防止环境变量被错误缓存：

add_header Cache-Control "no-cache, no-store, must-revalidate";
add_header Pragma "no-cache";
add_header Expires 0;

验证步骤

部署完成后，可通过以下步骤验证功能是否正常：

1. 清除浏览器缓存后访问页面
2. 检查开发者工具中的网络请求是否都使用 HTTPS
3. 确认登录模态框中显示邮箱选项
4. 测试完整的邮箱注册/登录流程

最佳实践建议

1. 使用容器编排工具管理服务依赖关系
2. 实现自动化部署流程确保配置一致性
3. 定期检查环境变量与预期是否一致
4. 建立监控机制及时发现认证服务异常

通过以上措施，可以确保 Hoppscotch 自部署环境中的认证模块正常工作，特别是邮箱登录功能的可用性。对于生产环境部署，建议进行全面的功能测试和安全审计。