Headway地图服务部署中的URL配置问题解析

问题背景

在使用Headway地图服务进行自托管部署时，一个常见但容易被忽视的问题是前端请求始终指向127.0.0.1地址，即使已经正确配置了公共URL参数。这种情况通常发生在通过Nginx等反向代理部署Headway服务时。

问题表现

部署完成后，前端控制台会出现类似以下的错误信息：

GET http://127.0.0.1:8080/tileserver/data/default.json net::ERR_CONNECTION_REFUSED

这表明前端应用正在尝试从本地地址获取资源，而非配置的公共域名。

根本原因

问题的核心在于HEADWAY_PUBLIC_URL环境变量的配置理解有误。这个变量应该设置为终端用户访问服务时使用的完整公共URL，而不是容器内部的通信地址。

正确配置方法

1. 在.env配置文件中，HEADWAY_PUBLIC_URL应设置为用户访问的完整URL，例如：

HEADWAY_PUBLIC_URL=https://yourdomain.com

2. 反向代理配置(Nginx示例)应保持指向容器内部地址：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

技术原理

Headway前端应用会根据HEADWAY_PUBLIC_URL变量构造API请求地址。当这个值设置为本地地址时，所有前端发起的资源请求都会尝试从本地获取，导致在反向代理环境下连接失败。

扩展配置建议

对于只部署特定区域地图的情况，还可以通过以下配置优化用户体验：

1. 设置默认地图显示区域：

HEADWAY_BBOX=经度1,纬度1,经度2,纬度2

2. 这个边界框参数会决定地图初始加载时显示的区域范围，对于只关注特定地区的部署非常有用。

部署验证

配置完成后，可以通过以下步骤验证：

1. 清除浏览器缓存
2. 访问配置的公共URL
3. 检查网络请求是否指向正确的域名
4. 确认地图初始视图是否符合预期

总结

正确理解HEADWAY_PUBLIC_URL的用途是Headway部署成功的关键。这个参数代表的是面向用户的访问入口，而非服务内部通信地址。配合反向代理和区域限制参数，可以构建出符合特定需求的地图服务部署方案。