前言容器里跑 Nginx最典型的一类「日志问题」是这样的docker logs 容器名只能看到访问日志access log错误日志error log一条都没有或者反过来进容器里cat /var/log/nginx/error.log明明有一大堆内容但这些内容从来没进过日志采集系统。还有一种更隐蔽的版本容器跑了几个月某天突然起不来docker logs干干净净而容器可写层已经被/var/log/nginx/error.log撑满了。根因并不复杂Nginx 默认把日志写成文件而容器世界的约定是进程把日志写到标准输出stdout和标准错误stderr由容器运行时统一接管、轮转、转发。写在容器文件系统里的日志采集器看不见容器一销毁就随之消失而且它占用的是可写层空间不受镜像大小约束。还要先纠正一个常见误解error_log并不是只能写文件。它有一个专门的官方取值stderr写了它 Nginx 根本不打开任何文件。很多人不知道这一点绕道去用/dev/stdout之类的设备符号链接反而引入了额外的依赖和失败模式。本文基于 RHEL 9 与 Debian 12 上自带的 nginx1.22 / 1.24 一系以及官方 Docker 镜像nginx:1.24、nginx:1.27讲解error_log到底支持哪些输出目标、哪种写法最稳、官方镜像和自建镜像分别怎么改、改完怎么验证以及几个「改完还是收不到日志」的真实坑。指令名与取值以官方ngx_core_module文档和nginx -h为准版本有出入时以你手上二进制的实际行为为准。一、先搞清楚 error_log 支持哪些输出目标error_log指令的取值一共有四类全部列在下表里写法输出目标说明error_log /var/log/nginx/error.log;文件默认行为。相对路径基于编译期 prefix建议写绝对路径error_log stderr;标准错误官方文档中的特殊取值容器场景首选error_log syslog:server127.0.0.1:514;syslog可加facility、tag、severity等参数error_log memory:32m debug;内存环形缓冲需--with-debug构建供gdb抓取不落盘两个容易记混的点第一stderr是官方文档里写明的特殊取值不是文件路径。写了它Nginx 直接把每条日志write()到自己的 fd 2 上不经过文件系统不依赖/dev下有stderr这个符号链接也不依赖任何目录存在和权限正确。这是所有方案里失败面最小的一个。第二access_log没有对应的stdout特殊取值。访问日志要输出到标准输出只能用/dev/stdout这个由内核和运行环境提供的设备符号链接或者改用access_log syslog:...。这两条规则不对称很多人把error_log stderr的写法类比过去写成error_log stdout那是错的。关于作用域和级别error_log可以出现在main、http、mail、stream、server、location上下文。同一配置层上允许多次出现error_log此时日志会同时写到多个目标。级别level由低到高依次是debug、info、notice、warn、error、crit、alert、emerg默认值是error。这里的方向容易搞反级别越高越靠右输出的日志越少。设成error就只看得到 error 及更严重的容器里想在启动阶段看到「配置加载完成」「worker 起来了」这类过程信息通常设成notice。二、三种可行写法的取舍方案具体写法优点代价内置 stderrerror_log stderr notice;官方支持不依赖文件系统和设备节点需要二进制认识这个取值用nginx -t可验证设备符号链接ln -sf /dev/stderr /var/log/nginx/error.log官方镜像自带的做法配置里仍写文件路径依赖/dev与/procfd 被关闭时会启动失败syslog 转发error_log syslog:server127.0.0.1:514;对接已有 syslog 体系多一跳UDP 传输在拥塞时会丢包如果是你自己控制 nginx.conf用方案一一行搞定且和发行版无关。如果是继承别人镜像包括官方镜像配置里已经写死了文件路径那就顺着它的符号链接方案走不要去改配置——改了反而可能把链接架空。方案三在容器里通常没必要运行时本身就会把 stdout/stderr 收敛成日志流再套一层 syslog 只是多一个可能丢包的环节。三、实战两种镜像分别怎么改3.1 官方镜像验证它开箱就是对的官方 Docker 镜像的 Dockerfile 里包含两条建立符号链接的指令大意如下具体行号与上下文随镜像版本变化请以你拉到的那个版本的 Dockerfile 为准RUN ... \ ln -sf /dev/stdout /var/log/nginx/access.log \ ln -sf /dev/stderr /var/log/nginx/error.log镜像内的/etc/nginx/nginx.conf里这两条指令仍按常规路径书写指向/var/log/nginx/下的对应文件两者一叠加日志就落到了 stdout/stderr。这一条不必凭记忆下面用nginx -T一验便知。所以用官方镜像时不需要改任何配置。验证一遍# 起一个临时容器 docker run -d --name nginx-demo -p 8080:80 nginx:1.24 # 确认主进程的 fd 1 / fd 2 就是容器日志管道 docker exec nginx-demo ls -l /proc/1/fd/ # 造一条 error 级别日志请求一个不存在的静态文件 curl -s -o /dev/null http://127.0.0.1:8080/definitely-not-here # 看它有没有出现在容器日志里 docker logs --tail 20 nginx-demo # 顺便看一眼实际生效的日志相关配置 docker exec nginx-demo nginx -T 2/dev/null | grep -nE error_log|access_log docker rm -f nginx-demo其中nginx -T会把完整配置 dump 出来该选项 1.9.2 起可用-T与-t的区别就是前者额外打印配置内容比翻文件可靠。对不存在的静态文件发请求Nginx 会以error级别记录一行形如[error] 29#29: *1 open() /usr/share/nginx/html/definitely-not-here failed (2: No such file or directory), client: 172.17.0.1, server: localhost, request: GET /definitely-not-here HTTP/1.1。用它能最省事地验证 error log 通道是否打通。3.2 自建镜像基于发行版包Debian 和 RHEL 系的 nginx 包都在/etc/nginx/nginx.conf里显式写了日志路径因此必须改。下面是 Debian 12 上一份可直接用的最小配置关键改动已加注释# /etc/nginx/nginx.conf user www-data; worker_processes auto; pid /run/nginx.pid; # 关键错误日志走标准错误交给容器运行时收集 error_log stderr notice; events { worker_connections 1024; } http { # 访问日志没有 stdout 特殊值只能用设备符号链接 access_log /dev/stdout; include /etc/nginx/mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; include /etc/nginx/conf.d/*.conf; }两个细节access_log /dev/stdout;只给了路径、没给格式此时使用内置的combined格式是合法的。如果你写access_log /dev/stdout main;那么main这个log_format必须在同层或外层定义过否则会报[emerg] unknown log format main。Debian 的包默认不定义mainRHEL 的包默认定义这就是同一份配置换个发行版就起不来的原因之一。只有写在main上下文的error_log才管得住启动早期报出的错原因见「常见坑点」第 3 条。RHEL 9 / Rocky 9 / AlmaLinux 上可以用sed就地改掉原有的那两行改完务必用nginx -T核对是否只留下你要的目标# 需 rootRHEL 9 系 sed -i s|^error_log .*|error_log stderr notice;| /etc/nginx/nginx.conf sed -i s|^\s*access_log .*| access_log /dev/stdout;| /etc/nginx/nginx.conf nginx -t对应的 DockerfileFROM debian:12-slim RUN apt-get update \ apt-get install -y --no-install-recommends nginx ca-certificates \ rm -rf /var/lib/apt/lists/* COPY nginx.conf /etc/nginx/nginx.conf EXPOSE 80 # 必须以非 daemon 模式启动否则主进程 fork 完就退出容器立刻结束 CMD [nginx, -g, daemon off;]构建与验证docker build -t my-nginx:1 . docker run -d --name my-nginx -p 8081:80 my-nginx:1 curl -s -o /dev/null http://127.0.0.1:8081/nope docker logs --tail 20 my-nginx docker rm -f my-nginx3.3 别漏了轮转日志进了 stdout容器的日志文件仍然在宿主机磁盘上只是位置从可写层换到了运行时管理的目录。所以「写 stdout 就不用管磁盘」是错的。Docker 的json-file驱动默认不做轮转需要在启动或编排里限制。Compose 写法# docker-compose.yml 片段 services: nginx: image: nginx:1.27 ports: - 8080:80 logging: driver: json-file options: max-size: 20m max-file: 5Kubernetes 侧由 kubelet 的containerLogMaxSize默认 10Mi与containerLogMaxFiles默认 5控制改在 kubelet 的配置文件里不是改 Pod。这些都是「上限/份数」参数实际取值按你的保留需求定不要照抄。四、写出去的那一下原子性、多行与采集端理解几个写入层面的细节能省掉很多「日志看着怪怪的」的排查时间。Nginx 不走 C 库的 stdio 缓冲。它写日志用的是直接的系统调用内部封装为ngx_write_fd每条日志一次write(2)。所以不存在「日志卡在用户态缓冲区里、进程没退出就看不到」的问题——这一点比很多语言写的应用省心。你在docker logs里看不到几乎一定是配置指到了文件而不是缓冲问题。但管道上的原子性有长度上限。当 fd 是管道时Linux 保证单次不超过PIPE_BUF该值为 4096 字节的写入是原子的。一条普通的访问日志只有几百字节安全但 error log 里带client:、server:、request:、upstream:后缀的长行或者debug级别的行可能超过这个长度多 worker 同时写就有互相穿插的可能。这是多 worker 容器里的真实现象表现为采集端偶尔出现半行拼接。采集端按换行切分。Docker 的日志驱动把写入内容按换行切成一条条记录。Nginx 的 error log 每条自带时间戳前缀且是单行天然适配但如果有后端应用的异常堆栈混进同一个流采集端就需要配多行multiline解析规则否则一条堆栈会被拆成十几条。常见坑点1. 以为error_log off;能关掉错误日志❌error_log off;✅ 不想要错误日志指向黑洞并抬高门槛error_log /dev/null crit;off是access_log的取值error_log只有文件路径、stderr、syslog:、memory:四类没有off写下去不会得到「关闭」的效果具体解释以官方文档为准。真心想关就用/dev/null加一个高到几乎不会触发的级别。2. 配置里写了daemon off;启动命令又带-g daemon off;❌ 配置文件末尾有daemon off;同时CMD [nginx, -g, daemon off;]✅ 二选一推荐只保留命令行那一份结果是启动直接失败报[emerg] daemon directive is duplicate in /etc/nginx/nginx.conf:NN。daemon、pid、worker_processes这类指令在同一配置层只能出现一次重复就是致命错误。官方镜像的做法是配置文件里不写只在 CMD 里带-g daemon off;。顺带一句-g是往main上下文追加指令不是覆盖。别指望用nginx -g error_log stderr;压掉配置文件里的error_log——同名指令在main层可以共存结果可能是两处都在写。3. 只在http {}里改了 error_log❌ 把error_log stderr;写进http块main层不做处理✅ 在main上下文文件最外层设置error_log stderr notice;容器启动早期、配置解析阶段产生的[emerg]用的是main层的日志目标main层没设就落到编译期 prefix 下的默认路径。症状是容器立刻退出docker logs里什么都没有只看到一个退出码 1——配置错了却看不到错在哪。4. 用了符号链接方案又把配置里的路径改到了别处❌ln -sf /dev/stderr /var/log/nginx/error.log但配置写的是error_log /var/log/nginx/app-error.log;✅ 配置路径与符号链接路径保持一致改完用nginx -T核对符号链接方案成立的唯一前提是「配置里写的路径正是被链接的那个路径」。换一个文件名链接就彻底白做了日志照样静静地躺在容器可写层里。5. error_log 指向的目录不存在❌error_log /var/log/nginx/apps/error.log;而apps目录没建✅ 先mkdir -p或干脆用error_log stderr;Nginx 不会帮你创建目录启动时报[emerg] open() /var/log/nginx/apps/error.log failed (2: No such file or directory)然后退出。这也正是stderr比文件路径省事的地方它不依赖目录存在也不依赖运行用户对目录有写权限。6. 镜像没关 daemon容器秒退❌CMD [nginx]✅CMD [nginx, -g, daemon off;]默认配置下 Nginx 以守护进程方式启动主进程 fork 出后台进程后自己退出容器认为主进程已结束立刻进入 Exited 状态。症状是「容器起来又马上没了」而不是报错。7. 以为日志进了 stdout 就不用管磁盘❌ 什么都不配让json-file驱动默认无限增长✅ 给日志驱动设max-size和max-fileCompose或调 kubelet 的containerLogMaxSize/containerLogMaxFiles写 stdout 只是换了落盘位置从容器可写层换到了运行时的日志目录。默认不轮转的话该撑满还是撑满只是撑满的换了地方。8. 把级别调到debug却发现毫无变化❌error_log stderr debug;然后期待看到详细的内部流程✅ 先nginx -V 21 | tr \n | grep with-debug确认二进制是否支持debug级别的日志只在以--with-debug编译的二进制上才有输出。发行版自带的包绝大多数没开这个选项此时设了debug不报错但一行 debug 也不会产生。总结场景error_log 写法access_log 写法官方 nginx 镜像镜像自带/dev/stderr符号链接无需改动同上无需改动自建镜像Debian / RHEL 包main层写error_log stderr notice;access_log /dev/stdout;已有集中式 syslog 体系error_log syslog:server...;同左Kubernetes与 Docker 一致写 stdout/stderr 交给 kubelet同左需要 debug 级别必须是--with-debug构建——一句话结论优先用官方的error_log stderr;它不依赖文件系统、目录和权限失败面最小access_log没有stdout取值只能走/dev/stdout。改完别靠肉眼确认用nginx -T看生效配置再请求一个不存在的文件造一条 error 日志确认它出现在docker logs里。最后给容器日志加上大小与份数上限——stdout 不等于不占磁盘。