Pangolin项目部署中Cookie域配置问题的解决方案

问题背景

在部署Pangolin项目时，许多用户会遇到一个常见但容易被忽视的问题：完成初始安装后，使用默认管理员账户([e-mail]/Password123!)登录时，虽然系统显示登录成功，但用户却始终停留在登录界面无法进入系统。

问题现象分析

通过开发者工具检查网络请求，可以发现登录API调用确实返回了成功状态(200 OK)，但仔细观察响应头中的Set-Cookie字段会发现问题所在。Cookie被设置为仅限HTTP使用(httpOnly)，而系统配置强制使用HTTPS协议，这种不匹配导致浏览器无法正确处理会话Cookie。

根本原因

问题的核心在于Pangolin配置文件中的base_domain设置。默认情况下，这个值可能被设置为"localhost"，导致系统生成的Cookie域与实际访问域不匹配。当用户通过自定义域名(如proxy.yourdomain.com)访问时，浏览器会拒绝存储这些Cookie，因为它们属于不同的域。

解决方案

要解决这个问题，需要按照以下步骤操作：

1. 找到Pangolin的配置文件(通常是config.yml或.env文件)
2. 定位base_domain配置项
3. 将其修改为你的实际域名(如yourdomain.com)
4. 重启Pangolin服务使配置生效

最佳实践建议

为了避免类似问题，建议在部署Pangolin项目时：

1. 仔细阅读配置文件中的每个选项说明
2. 在正式部署前，先进行本地测试
3. 使用开发者工具监控网络请求和Cookie设置情况
4. 保持配置文件与实际部署环境的一致性

总结

这个案例展示了配置管理在系统部署中的重要性。即使是看似简单的域名配置，也可能导致整个认证流程失效。通过理解Cookie的工作机制和域匹配规则，我们可以更好地诊断和解决这类认证问题。Pangolin团队已经注意到这个问题，并在文档中添加了相关说明，帮助用户避免类似的配置错误。