如何为Titiler配置自定义root_path以适配现有Nginx配置？

现有一个GeoNode实例，其Nginx使用官方的geonode.conf.envsubst配置文件。我希望添加Titiler上游服务，已编写如下Docker Compose文件：

version: '2.2'

services:
  titiler:
    image: ghcr.io/developmentseed/titiler:latest
    container_name: titiler
    environment:
      - PORT=8081
      - WORKERS_PER_CORE=1
      - TITILER_API_ROOT_PATH=/api/v1/titiler

同时配置了新的Nginx规则：

(...)
location /api/v1/titiler {
    set $upstream titiler:8081;
    proxy_pass http://$upstream;
    proxy_set_header HOST $host;
    proxy_set_header Referer $http_referer;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

问题在于，在Nginx容器内执行curl titiler:8081/api/v1/titiler时，返回{"detail":"Not Found"}。尽管在Titiler容器内通过代码from titiler.application.main import api_settings; print(api_settings.root_path)已确认root_path为"/api/v1/titiler"，但Titiler似乎未正确使用该路径。由于该问题本质上与FastAPI相关，请问如何在现有服务器上正确配置Titiler？

问题核心是Nginx代理路径与FastAPI root_path的匹配逻辑冲突，调整以下配置即可解决：

1. 修正Nginx代理规则 #

当前Nginx会把/api/v1/titiler开头的请求完整转发到Titiler容器的对应路径，但FastAPI的root_path是作为路由前缀存在的，Titiler内部的实际路由是基于/的。需要修改proxy_pass，在末尾添加/，让Nginx去掉匹配的路径前缀后转发：

location /api/v1/titiler {
    set $upstream titiler:8081;
    # 关键：添加末尾的/，转发时去除location匹配的前缀
    proxy_pass http://$upstream/;
    proxy_set_header HOST $host;
    proxy_set_header Referer $http_referer;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    # 额外添加X-Forwarded-Prefix，帮助FastAPI正确识别外部访问前缀
    proxy_set_header X-Forwarded-Prefix /api/v1/titiler;
  }
}

2. 强制指定Titiler的root_path（可选但更可靠） #

Titiler的环境变量TITILER_API_ROOT_PATH有时可能未被正确加载，可通过启动命令直接指定--root-path参数，确保配置生效：

version: '2.2'

services:
  titiler:
    image: ghcr.io/developmentseed/titiler:latest
    container_name: titiler
    environment:
      - PORT=8081
      - WORKERS_PER_CORE=1
    # 直接通过uvicorn命令指定root_path
    command: uvicorn titiler.application.main:app --host 0.0.0.0 --port 8081 --root-path /api/v1/titiler

3. 验证配置 #

• 在Nginx容器内执行curl titiler:8081/，应返回Titiler的正常API响应（内部路由根路径）
• 外部访问http://你的域名/api/v1/titiler，即可正常使用Titiler服务

内容的提问来源于stack exchange，提问作者Louis