Docker部署静态网页+Express API+MongoDB的Nginx配置问题排查

问题1：/api/路径返回404，直接访问API端口正常 #

原因 #

Nginx容器内的localhost指向容器自身，而非宿主机。初始配置中proxy_pass http://localhost:5005/无法访问同Docker网络下的js-alist-api服务容器，因为Docker容器默认网络环境中，服务间需通过服务名而非localhost通信。

解决方案 #

将proxy_pass目标改为docker-compose中定义的服务名js-alist-api，利用Docker内置DNS解析容器：

location /api/ {
    proxy_pass http://js-alist-api:5005; # 注意去掉末尾斜杠，后续问题3会说明原因
}

问题2：修改根路径为不存在的/html2/仍能访问静态页，配置未加载 #

原因 #

1. 容器未同步配置：修改本地nginx-api.conf后，未重启Nginx容器或重载配置，容器仍使用旧配置运行。
2. 挂载有效性验证缺失：虽然docker-compose中配置了挂载，但未确认本地文件是否正确同步到容器内。
3. 浏览器缓存干扰：静态页面被浏览器缓存，导致看似配置未生效。

解决方案 #

1. 重启Nginx容器或重载配置：

   # 重启容器
   docker restart js-alist-client
   # 或在容器内重载配置
   docker exec js-alist-client nginx -s reload
   

2. 验证挂载是否生效：进入容器查看配置文件内容，确认与本地文件一致：

   docker exec js-alist-client cat /etc/nginx/conf.d/default.conf
   

3. 清除浏览器缓存或使用无痕模式测试静态页面访问。

问题3：使用服务名后仅/api根路径生效，子路径无法访问 #

原因 #

proxy_pass末尾的斜杠会触发Nginx路径截断逻辑：请求/api/images/something/else会被代理到http://js-alist-api:5005/images/something/else，而如果你的API路由是基于/api前缀定义的，就会因路径缺失前缀返回404。

解决方案 #

去掉proxy_pass末尾的斜杠，保留完整路径前缀传递；同时添加必要代理头，确保API能正确获取请求上下文：

location /api/ {
    proxy_pass http://js-alist-api:5005;
    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;
}

问题4：配置临时生效后突然失效，状态不稳定 #

原因 #

1. Docker网络DNS解析故障：默认Docker网络的DNS偶尔会出现解析延迟或失败，导致js-alist-api服务名无法映射到容器IP。
2. 挂载权限或文件变更：本地nginx-api.conf文件权限不足（容器无法读取），或文件被意外修改/替换，导致容器加载错误配置。
3. Nginx配置未持久生效：未通过正确方式重载配置，容器重启后恢复旧配置。

解决方案 #

1. 自定义稳定网络：在docker-compose中显式定义自定义网络，避免默认网络的DNS不稳定：

   version: "3.8"
   networks:
       alist-network:
           driver: bridge
   services:
       js-alist-api:
           # 保留原有配置
           networks:
               - alist-network
       js-alist-client:
           # 保留原有配置
           networks:
               - alist-network
       database:
           # 保留原有配置
           networks:
               - alist-network
   

2. 确保挂载稳定性：设置本地nginx-api.conf文件权限为644，避免容器读取失败；容器重启后再次验证配置内容。
3. 添加健康检查：在docker-compose中为Nginx容器添加健康检查，确保配置始终有效：

   js-alist-client:
       # 保留原有配置
       healthcheck:
           test: ["CMD", "nginx", "-t"]
           interval: 30s
           timeout: 10s
           retries: 3
   

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