如何配置 Nginx 错误日志实现对 proxy_store 镜像存储失败原因的追踪-Nginx-PHP中文网

要精准定位 proxy_store 镜像存储失败原因，需增强日志上下文并分层诊断：提升 error_log 级别至 info/debug、自定义 access_log 记录关键变量、结合系统权限/磁盘/上游连通性验证，并用 if + error_page 捕获特定失败场景。

如何配置 nginx 错误日志实现对 proxy_store 镜像存储失败原因的追踪

要追踪 proxy_store 镜像存储失败的具体原因，仅靠默认的 Nginx 错误日志往往不够——它通常只记录“open() failed”这类泛化信息，不说明是上游不可达、磁盘满、权限拒绝，还是文件已存在但无法覆盖。关键在于**增强日志上下文**和**分层定位问题**。

Nginx 默认的 error_log 级别为 error，会过滤掉大量调试线索。需显式提升至 info 或 debug（后者需编译时启用 --with-debug）：

在 http 或 server 块中添加：
error_log /var/log/nginx/proxy_store_error.log info;
避免全局设为 debug，可针对特定 location 使用 error_log ... debug;，减少日志噪音
重启后，日志中会出现类似 open() "/data/mirror/path/to/file.jpg" failed (13: Permission denied) 或 (2: No such file or directory) 的明确系统错误码

标准日志无法体现 proxy_store 的决策路径。可通过 log_format 记录关键变量，区分是“本地已有”还是“回源失败”：

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

定义带上下文的日志格式：
log_format store_debug '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_addr" "$upstream_status" "$request_filename" "$sent_http_x_cached_by" $upstream_http_content_length';
在 location 块中应用：
access_log /var/log/nginx/store_access.log store_debug;
这样能清晰看到：
– $upstream_addr 是否为空（表示未触发回源）
– $upstream_status 是 200 还是 502/504（上游是否响应）
– $request_filename 对应的本地路径是否存在或可写

日志给出线索后，需快速验证对应系统状态：

权限检查：运行 ls -ld /data/mirror 和 ls -l /data/mirror/first/level/，确认 Nginx 工作用户（如 www-data）有 rwx 权限；proxy_store_access 指令设置的权限必须与实际目录权限匹配
磁盘空间：执行 df -h /data，proxy_store 在写入失败时不会自动降级，磁盘满直接报 No space left on device
上游连通性：从 Nginx 所在服务器手动测试 curl -I http://origin.example.com/path/to/file.jpg，确认 DNS、防火墙、TLS 证书（若用 HTTPS）均正常

对常见失败类型做显式拦截，便于集中分析：

在 location 内添加：
if (!-d $request_filename) { set $store_dir "missing"; }
if (!-w $request_filename) { set $store_dir "unwritable"; }
if ($store_dir) { return 499; # 自定义状态码，配合 log_format 区分}
再配置：
error_page 499 /499.html;
location = /499.html { internal; add_header X-Store-Failure $store_dir; }
这样所有 499 请求都会带明确原因头，方便在 access_log 或监控中聚合统计