Cheshire Cat AI核心服务HTTPS重定向问题分析与解决方案

问题现象

在Kubernetes集群中部署Cheshire Cat AI核心服务时，当UI通过HTTPS访问时，插件管理页面出现网络错误。具体表现为：

1. 浏览器直接访问/plugins端点可正常响应
2. 前端XHR请求返回307临时重定向
3. 容器日志显示重定向来自后端服务而非反向代理

技术分析

该问题本质是反向代理场景下的协议转换问题。典型表现为：

• 前端使用HTTPS协议访问
• 后端服务接收到的却是HTTP请求
• 服务内部产生协议不匹配的重定向

根本原因

Cheshire Cat AI核心服务默认运行在HTTP协议下，当检测到X-Forwarded-Proto头时会触发协议转换。但需要完整配置以下环境变量才能正确处理HTTPS场景：

1. UVICORN_PROXY_HEADERS=1（启用代理头处理）
2. FORWARDED_ALLOW_IPS=10.0.0.0/8（允许的内部网络范围）
3. CORE_USE_SECURE_PROTOCOL=true（启用安全协议）
4. CCAT_HTTPS_PROXY_MODE=true（关键配置，启用HTTPS代理模式）

解决方案

完整的容器环境变量配置应包含：

UVICORN_PROXY_HEADERS=1
FORWARDED_ALLOW_IPS=10.0.0.0/8
CORE_USE_SECURE_PROTOCOL=true
CCAT_HTTPS_PROXY_MODE=true
CORE_HOST=your.domain.com

配置验证

成功配置后，服务启动日志应显示HTTPS协议已启用：

INFO:     Application startup complete.
INFO:     Uvicorn running on https://0.0.0.0:1865

最佳实践建议

1. 生产环境必须配置完整的HTTPS相关变量
2. FORWARDED_ALLOW_IPS应根据实际网络拓扑调整
3. 建议结合Kubernetes Ingress或Service Mesh管理TLS终止
4. 定期检查服务日志中的协议警告信息

技术原理

该解决方案基于ASGI服务器的代理协议处理机制：

• UVICORN通过代理头识别原始协议
• CCAT_HTTPS_PROXY_MODE强制内部链接生成使用HTTPS
• 双重验证机制确保前后端协议一致性