Perplexica项目Docker部署中的CORS与端口配置问题解析

概述

在开源问答系统Perplexica的v1.9.3版本部署过程中，开发者遇到了前端无法连接后端服务的典型问题。本文将深入分析该问题的成因，并详细介绍多种解决方案的验证过程，为开发者提供Docker环境下的Web应用部署最佳实践。

问题现象

部署完成后，前端界面持续显示"Failed to connect to the server"错误。通过日志分析发现：

1. 后端服务(3001端口)正常启动且能响应API请求
2. 前端服务(3000端口)成功运行但无法建立WebSocket连接
3. 直接curl测试API接口返回正常数据

根本原因分析

端口映射冲突

初始配置中，开发者将前端服务的内部端口从默认的3001改为3000，但未同步更新docker-compose.yml中的端口映射规则，导致容器间通信异常。

CORS策略限制

当使用不同源(origin)访问时，浏览器严格执行同源策略：

• 域名不同(如mydomain.com vs localhost)
• 协议不同(HTTP vs HTTPS)
• 端口不同(3000 vs 3001)

混合内容安全策略

当HTTPS页面尝试加载HTTP资源时，现代浏览器会主动拦截这类"混合内容"请求，导致API调用失败。

解决方案验证

方案一：本地开发配置

环境变量:
  NEXT_PUBLIC_API_URL: http://localhost:3001/api
  NEXT_PUBLIC_WS_URL: ws://localhost:3001

结果：触发CORS错误，因前端与后端不同端口被视为不同源。

方案二：反向代理统一域名

通过CDN服务配置：

• 主域名 → 前端服务(3000)
• /api路径 → 后端服务(3001)

结果：出现JSON解析错误，因路径重写未正确处理。

方案三：子域名隔离方案（最终有效方案）

环境变量:
  NEXT_PUBLIC_API_URL: https://api.mydomain.com
  NEXT_PUBLIC_WS_URL: wss://api.mydomain.com

实现要点：

1. 为前后端分配独立子域名
2. 统一使用HTTPS协议
3. 正确配置SSL证书
4. 后端服务添加CORS白名单

最佳实践建议

1. Docker网络配置：

   • 使用自定义bridge网络确保容器间通信
   • 保持内部端口与映射端口的对应关系

2. Next.js环境变量：

   // next.config.js
   module.exports = {
     serverRuntimeConfig: {
       apiUrl: process.env.INTERNAL_API_URL // 容器间通信使用内部地址
     },
     publicRuntimeConfig: {
       apiUrl: process.env.NEXT_PUBLIC_API_URL // 浏览器访问使用外部地址
     }
   }
   

3. CORS配置示例：

   // 后端服务中间件
   app.use(cors({
     origin: [
       'https://app.mydomain.com',
       'https://localhost:3000'
     ],
     methods: ['GET', 'POST'],
     credentials: true
   }))
   

4. WebSocket安全：

   • 生产环境必须使用wss协议
   • 配置合理的消息大小限制
   • 实现心跳机制保持连接

总结

Perplexica项目的部署问题揭示了现代Web应用在容器化环境中的典型挑战。通过子域名隔离、协议统一和正确的CORS配置，开发者可以构建出既安全又灵活的部署架构。对于类似项目，建议在开发初期就规划好网络拓扑结构，避免后期出现连接性问题。