Laravel Horizon+Nginx Proxy Manager服务器静态文件502错误求助

一、静态文件502错误排查 #

1. 挂载路径与软链一致性检查 #

• 确认Laravel的storage:link命令已在线上API容器执行：本地环境可能已手动创建软链，但线上容器每次部署为全新镜像，需在容器启动脚本（如Dockerfile的CMD/ENTRYPOINT，或docker-compose的command字段）加入php artisan storage:link && php-fpm（假设用PHP-FPM）。
• 核对挂载映射：API容器将storage卷挂载到/var/www/html/storage/app/public，Nginx代理容器挂载到/var/www/html/public/storage，映射逻辑正确，但需确保API容器内public/storage软链确实指向../storage/app/public。可执行命令验证：

docker exec -it <api容器ID> ls -l /var/www/html/public/storage

2. Nginx代理配置校验 #

• 检查Nginx代理管理器的规则：确保静态文件请求（如/storage/*、/vendor/*）由Nginx直接读取挂载卷，而非转发到API上游。若误将静态请求转发给PHP-FPM或API服务，会因无对应路由返回502。
• 验证Nginx配置中是否存在类似Laravel官方的静态文件处理规则：

location /storage {
    alias /var/www/html/public/storage;
    try_files $uri $uri/ =404;
}
location /vendor {
    alias /var/www/html/public/vendor;
    try_files $uri $uri/ =404;
}

3. 文件权限与所有者检查 #

• 检查Nginx容器内挂载目录的权限：Nginx进程通常以www-data或nginx用户运行，需确保/var/www/html/public/storage和/var/www/html/public/vendor的所有者/组与Nginx运行用户匹配。执行命令：

docker exec -it <nginx容器ID> ls -ld /var/www/html/public/storage
docker exec -it <nginx容器ID> id nginx # 查看Nginx用户ID

• 若权限不符，可在API容器启动时添加权限修正命令，或构建镜像时设置正确权限：

chown -R www-data:www-data /var/www/html/storage /var/www/html/public/vendor

4. 容器网络连通性验证 #

• 确认Nginx代理容器能正常访问API容器：执行命令测试网络连通性（假设API容器暴露9000端口用于PHP-FPM）：

docker exec -it <nginx容器ID> ping api # 检查DNS解析
docker exec -it <nginx容器ID> curl api:9000 # 检查端口可达性

• 若网络不通，需检查容器是否在同一Docker网络，docker-compose是否默认创建了自定义网络，或手动指定网络。

二、Portainer无法浏览卷的排查 #

1. Portainer权限配置检查 #

• 确认Portainer容器已挂载Docker套接字：启动Portainer时需添加挂载参数/var/run/docker.sock:/var/run/docker.sock，否则Portainer无权限访问Docker资源（包括卷）。
• 检查Portainer运行用户权限：若以非root用户运行，需确保该用户加入docker组，拥有访问Docker套接字的权限。

2. 本地卷存储路径权限检查 #

• Docker本地卷默认存储在/var/lib/docker/volumes/，检查服务器上该目录的权限：

ls -ld /var/lib/docker/volumes/

• 确保Portainer容器的运行用户（如root）对该目录有读写权限。

3. Portainer栈与卷同步问题 #

• 若栈是通过docker-compose手动部署而非Portainer创建，需在Portainer中手动扫描“栈”或“卷”，触发资源同步。
• 查看Portainer日志排查错误：

docker logs <portainer容器ID>

三、CI/CD部署流程验证 #

1. Webhook触发有效性检查 #

• 手动执行Portainer Webhook的curl命令，观察服务器上容器是否重建、镜像是否拉取最新版本：

curl -X POST http://portainer.gitlab.domain.com/api/stacks/webhooks/token

• 验证容器是否使用最新镜像：

docker inspect <api容器ID> | grep Image

2. 镜像拉取权限验证 #

• 在部署服务器手动执行GitLab镜像拉取命令，确认无权限问题：

echo $CI_REGISTRY_PASSWORD | docker login -u $CI_REGISTRY_USER $CI_REGISTRY --password-stdin
docker pull $CI_REGISTRY_IMAGE

3. 环境变量配置校验 #

• 检查API容器的环境变量，确保APP_URL、FILESYSTEM_DISK=public等关键配置正确，这些会影响静态文件的生成与访问路径。

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