故障排除

如果您遇到技术问题并且在其他部分找不到解决方案，请在 社区论坛 或 Telegram 频道 上提问。

客户技术支持：

• https://support.angie.software

调试日志

在执行自我诊断或按照技术支持建议进行操作之前，应启用调试日志。

为此，请使用支持调试的可执行文件运行 Angie：

LinuxFreeBSDDocker从源构建

在 Linux 的 预构建包 中，angie-debug 文件是启用调试支持构建的：

$ ls -l /usr/sbin/ | grep angie

   lrwxrwxrwx 1 root root      13 Sep 21 18:58 angie -> angie-nodebug
   -rwxr-xr-x 1 root root 1561224 Sep 21 18:58 angie-debug
   -rwxr-xr-x 1 root root 1426056 Sep 21 18:58 angie-nodebug

配置运行 angie-debug：

$ sudo ln -fs angie-debug /usr/sbin/angie
$ sudo angie -t && sudo service angie upgrade

这将启动 实时可执行文件升级。

调试后要恢复到常规可执行文件：

$ sudo ln -fs angie-nodebug /usr/sbin/angie
$ sudo angie -t && sudo service angie upgrade

备注

使用支持调试的可执行文件可能会略微降低性能；启用调试日志可能会显著降低性能并增加磁盘空间使用。

要启用调试日志，请在配置中使用 error_log 指令设置 debug 级别（模板化 Docker 镜像改用环境变量，如下方的 Docker 选项卡所示）：

error_log /path/to/log debug;

然后使更改生效：

LinuxFreeBSDDocker从源构建

$ sudo angie -t && sudo service angie reload

如果切换到不支持调试的可执行文件但在 error_log 指令中保留 debug 级别，Angie 将以 info 级别记录条目。

指令位置

error_log 指令的位置会影响收集的调试信息的完整性。

在较低配置级别（例如，在 server 或 location 块内）指定的指令会覆盖在较高级别（例如，在主配置级别或 http 块内）指定的日志设置。

为特定服务器禁用调试日志

如果全局启用了调试日志，但为单个服务器指定了不带 debug 级别的 error_log，则不会为该服务器收集调试信息。

error_log /var/log/angie/error.log debug; # 全局调试日志

http {

    server {

        listen 80;
        server_name example.com;

        error_log /var/log/angie/example.com.error.log;
        # example.com 的调试日志被禁用，文件包含 error 级别

        # ...
    }

    server {

        listen 80;
        server_name another.com;

        # 此服务器将使用全局调试日志
        # ...
    }
}

在服务器级别保留调试日志

要继续为特定服务器收集调试信息，请删除该服务器中的 error_log 覆盖设置；若要将这些信息写入另一个文件，请在覆盖设置中同时指定 debug 级别：

error_log /var/log/angie/error.log debug; # 全局调试日志

http {

    server {

        listen 80;
        server_name example.com;

        error_log /var/log/angie/example.com.error.log debug;
        # example.com 的调试日志已启用但写入单独的文件

        # ...
    }
}

记录特定地址

您可以仅为 指定的客户端地址 启用调试日志：

error_log /path/to/log;

events {
  debug_connection 192.168.1.1;
  debug_connection 192.168.10.0/24;
}

循环内存缓冲区

调试日志可以写入循环内存缓冲区：

error_log memory:32m debug;

在 debug 级别写入内存缓冲区即使在高负载下也不会显著影响性能。在这种情况下，可以使用 GDB 脚本提取日志，例如：

set $log = ngx_cycle->log

while $log->writer != ngx_log_memory_writer
  set $log = $log->next
end

set $buf = (ngx_log_memory_buf_t *) $log->wdata
dump binary memory debug_log.txt $buf->start $buf->end

核心转储

核心转储有助于调查崩溃。在 联系支持 时请包含它们。对于从 我们的仓库 构建的版本，我们在特殊包中提供调试符号。它们与原始包同名，但添加了 -dbg 后缀，例如 angie-dbg。

备注

本节假设您以 root 用户身份运行 Angie（推荐）。

Linux: systemd

要在将 Angie 作为 systemd 服务运行时启用核心转储保存（例如，当 从包安装 时），请修改 /lib/systemd/system/angie.service 文件中的 服务设置：

[Service]
...
LimitCORE=infinity
LimitNOFILE=65535

或更新 /etc/systemd/system.conf 文件中的 全局设置：

[Manager]
...
DefaultLimitCORE=infinity
DefaultLimitNOFILE=65535

然后重新加载服务配置并重启 Angie 以重现崩溃条件：

$ sudo systemctl daemon-reload
$ sudo systemctl restart angie.service

崩溃后，查找核心转储文件：

$ sudo coredumpctl -1 # 可选

   TIME                           PID   UID   GID SIG COREFILE  EXE
   --- 2026-10-13 11:05:40 GMT   1157     0     0  11 present   /usr/sbin/angie

$ sudo ls -al /var/lib/systemd/coredump/  # 默认位置，另见 /etc/systemd/coredump.conf 和 /etc/systemd/coredump.conf.d/*.conf

  ...
  -rw-r----- 1 root root 177662 Jul 27 11:05 core.angie.0.6135489c850b4fb4a74795ebbc1e382a.1157.1590577472000000.lz4

Linux: 手动配置

本节适用于不通过 systemd 启动的 Angie，例如 从源代码构建 的 Angie，并假定以这种方式安装的 Angie 正在运行；命令中使用的是此类构建在 /usr/local/angie 下的默认路径。

内核把核心转储文件放在哪里，取决于 /proc/sys/kernel/core_pattern。如果该模式以 | 开头，内核会把转储交给 | 之后指定的程序（例如 systemd-coredump），即使对不通过 systemd 启动的 Angie 也是如此；此时请按 Linux: systemd 中的说明查找核心转储文件，并跳过下面与工作目录相关的步骤。如果该模式是 core 这样的普通名称，内核会把核心转储文件写入崩溃进程的工作目录；对工作进程来说，默认就是启动 Angie 时所在的目录。

工作进程以 user 指令设置的账户运行（采用默认选项从源代码构建时为 nobody）；如果该账户无法写入工作目录，崩溃时就不会留下核心转储文件，因此请创建一个用于存放核心转储文件的目录：

$ sudo mkdir -p /var/tmp/angie-cores
$ sudo chown nobody /var/tmp/angie-cores

请在 /usr/local/angie/conf/angie.conf 的 main 上下文中，使用 working_directory 指令把刚创建的目录设为工作目录：

working_directory /var/tmp/angie-cores;

然后提高核心转储大小限制。若只想为工作进程提高该限制并避免重启，请再添加 worker_rlimit_core 指令（该指令的参数是大小，而不是 unlimited），并重新加载配置：

worker_rlimit_core 1g;

$ sudo /usr/local/angie/sbin/angie -s reload

若还要为主进程提高核心转储大小限制，请改为重启 Angie。默认情况下，sudo 启动命令时会把核心转储大小限制设为 0，而 ulimit 只会更改运行它的 shell 以及该 shell 所启动命令的限制。请停止正在运行的 Angie，等待 Angie 主进程退出，然后在同一个 root shell 中提高限制并启动 Angie：

$ sudo /usr/local/angie/sbin/angie -s quit
$ while [ -e /usr/local/angie/logs/angie.pid ]; do sleep 1; done
$ sudo sh -c 'ulimit -c unlimited && exec /usr/local/angie/sbin/angie'

若从源代码构建时使用 --with-debug 进行配置，则 /usr/local/angie/sbin/angie 本身就支持调试，没有单独的 angie-debug 可执行文件。

检查工作进程的限制；重启后，两个值都是 unlimited，而使用 worker_rlimit_core 时，它们显示的是所设置的大小（以字节为单位）：

$ grep 'core file' /proc/$(pgrep -n -f 'angie: worker process')/limits
Max core file size        unlimited            unlimited            bytes

然后重现崩溃。如果崩溃留下了核心转储文件，错误日志（默认为 /usr/local/angie/logs/error.log）会显示 worker process pid exited on signal number (core dumped)；如果同一条消息中没有 (core dumped)，则说明是核心转储大小限制或工作目录导致没有生成核心转储文件。请查找核心转储文件：

$ sudo ls -al /var/tmp/angie-cores
  ...
  -rw------- 1 nobody nogroup 177662 Jul 27 11:05 core.1157

FreeBSD

检查 /etc/sysctl.conf 文件中的 核心转储设置，必要时修改它们：

kern.coredump=1                             # 应为 1
kern.corefile=/path/to/core/files/%N.core   # 需要正确路径

或在运行时更新设置：

$ sudo sysctl kern.coredump=1
$ sudo sysctl kern.corefile=/path/to/core/files/%N.core

无论采用上述哪种方式，user 指令设置的账户都必须对 kern.corefile 中的目录有写权限：工作进程以该账户运行，并将各自的核心转储文件写入该目录。

然后重启 Angie 以重现崩溃条件。 如果 Angie 作为服务安装：

$ sudo service angie restart

如果 Angie 是手动安装的，请停止它，等待 Angie 主进程退出，然后在同一个 root shell 中提高核心转储大小限制并启动 Angie，与 Linux 上的做法相同：

$ sudo <Angie 安装目录路径>/sbin/angie -s quit
$ while [ -e <Angie 安装目录路径>/logs/angie.pid ]; do sleep 1; done
$ sudo sh -c 'ulimit -c unlimited && exec <Angie 安装目录路径>/sbin/angie'

崩溃后，查找核心转储文件：

$ sudo ls -al <核心转储文件路径>

  ...
  -rw------- 1 nobody nobody 9912320 Jul 27 11:05 angie.core