【Docker】StarRocks 容器优雅停机与 PID 文件管理解决方案-优快云博客

文章目录

核心观点

解决 StarRocks 容器启动失败的关键在于：理解 Docker 的信号传递机制，并在启动前主动清理残留的 PID 文件。这不是一个简单的文件删除问题，而是涉及进程生命周期管理、信号处理和容器编排的综合性问题。

这个问题的核心在于：Docker 的 stop 命令不是立即断电，而是一次"限时谈判"。如果应用程序没有正确接收和处理信号，PID 文件可能残留，导致下次启动时被误判为进程仍在运行。因此，我们需要在启动脚本中实现"优雅停止优先、强制停止兜底、确保清理"的三重保障机制。

一、问题的本质：PID 文件残留如何导致启动失败

当你执行 docker restart 或容器异常退出后重启时，可能会遇到这样的错误：

Frontend running as process 23. Stop it first.
Backend running as process 30. Stop it first.

这个错误提示看起来进程正在运行，但实际上进程已经不存在了。问题的根源在于 StarRocks 的启动脚本在启动前会检查 PID 文件，如果发现 PID 文件存在且对应的进程"看起来"在运行，就会拒绝启动。

StarRocks 的启动脚本（start_fe.sh / start_be.sh）使用 kill -0 命令来检查进程是否存在。这个命令的作用是向进程发送信号 0，如果进程存在就返回成功，不存在就返回失败。然而，这里存在一个关键问题：PID 文件由 Java 进程在启动后写入，但如果进程异常退出或被强制杀死，PID 文件可能没有被正确清理。

这意味着即使进程已经不存在，PID 文件仍然存在，启动脚本会误判为进程仍在运行。更重要的是，即使 kill -0 检查失败（进程不存在），启动脚本也不会主动清理无效的 PID 文件，而是直接退出，导致容器无法启动。

二、Docker Stop 的信号传递机制：为什么 PID 文件会残留

理解 Docker 的停机机制是解决这个问题的关键。docker stop 本质上不是一个"关机"指令，而是一次"限时谈判"：它先向容器主进程发送 SIGTERM 信号请求优雅退出，若超时未响应，才会发送 SIGKILL 强制抹杀。

当你执行 docker stop 时，Docker 会向容器内的 PID 1 进程（也就是容器的主进程）发送一个 SIGTERM 信号。这个信号的含义是"请停止工作"，类似于餐厅打烊前礼貌地告诉顾客：“我们要关门了，请您吃完尽快离开。” 此时，一个设计良好的应用程序会捕获这个信号，开始执行清理工作：保存内存中的数据、关闭数据库连接、完成正在处理的请求。

Docker 默认会给容器 10 秒钟的"宽限期"（Grace Period）。如果 10 秒过后容器还在运行，Docker 就会失去耐心，发出第二个信号：SIGKILL。这个信号是内核级别的"强制终止"，应用程序无法捕获也无法忽略它。这就像是保安直接把赖着不走的顾客架出了大门。

然而，在我们的场景中，entrypoint 脚本使用了 exec tail -f 来持续输出日志。这意味着容器内的 PID 1 进程是 tail 进程，而不是 StarRocks 的 Java 进程。当 docker stop 发送 SIGTERM 时，tail 进程被终止，但 StarRocks 的 Java 进程（使用 --daemon 模式后台运行）变成了孤儿进程。10 秒后，所有进程被 SIGKILL 强制杀死，PID 文件可能没有被正确清理。

这里还有一个更深层的问题：

如果使用 Shell 格式启动（如 CMD command param1），Docker 会以 /bin/sh -c command param1 的方式运行你的程序。这意味着容器内的 PID 1 进程变成了 Shell，而你的应用程序只是 Shell 的一个子进程。问题在于，Unix 的 Shell 通常不会将收到的信号转发给它的子进程。当 Docker 发送 SIGTERM 给 PID 1（Shell）时，Shell 收到信号但什么也不做，也不会告诉你的应用该停了。你的应用还在快乐地运行，完全不知道外面发生了什么。直到 10 秒超时，SIGKILL 袭来，Shell 和你的应用一起被强制杀死。

因此，PID 文件残留的根本原因有两个：一是进程被强制杀死时没有机会清理 PID 文件，二是信号传递机制导致应用程序没有收到停止信号，无法执行清理逻辑。

三、解决方案：三重保障机制

基于对问题本质的理解，我们的解决方案采用了"优雅停止优先、强制停止兜底、确保清理"的三重保障机制。这个机制的核心思想是：无论进程是否真的在运行，无论停止命令是否成功，都要确保 PID 文件被删除，避免阻塞启动。

首先，我们在启动前检查 PID 文件是否存在。如果不存在，说明这是首次启动或之前的进程已经正常退出并清理了 PID 文件，直接继续启动流程即可。如果 PID 文件存在，我们读取其中的 PID，并验证 PID 是否有效（不为空且不是 PID 1，因为 PID 1 是容器入口点，不是真正的应用进程）。
接下来，我们优先尝试使用官方的 stop_fe.sh 或 stop_be.sh 脚本进行优雅停止。这些脚本会读取 PID 文件，验证进程是否为 Java 进程（安全验证），然后发送 SIGTERM 信号，并循环等待进程退出（每 2 秒检查一次）。如果进程正常退出，脚本会自动删除 PID 文件。这个过程最多等待 10 秒，给进程足够的时间完成清理工作。
然而，优雅停止可能失败。可能的原因包括：进程已经异常退出但 PID 文件残留、进程卡死无法响应信号、或者停止脚本本身执行失败。因此，我们需要检查进程是否仍在运行。如果进程仍在运行，我们使用 kill -9 强制停止。这个信号无法被捕获，会立即终止进程，但这是必要的兜底措施。
最关键的一步是：无论 stop 命令是否成功，无论进程是否仍在运行，我们都要删除 PID 文件。 这是为了避免阻塞启动。即使进程已经不存在，即使停止命令失败，我们也要确保 PID 文件被删除，这样启动脚本就不会误判为进程仍在运行。

这个三重保障机制确保了在各种异常情况下，容器都能正常启动。无论是正常停止、强制停止、异常退出，还是进程卡死，启动脚本都能自动处理，无需手动干预。

四、技术实现：深入理解每个步骤的原理

4.1 PID 文件的位置和写入时机

根据 StarRocks 官方脚本分析，FE 的 PID 文件位置是 $STARROCKS_HOME/bin/fe.pid（即 /opt/starrocks/fe/bin/fe.pid），BE 的 PID 文件位置是 $STARROCKS_HOME/bin/be.pid（即 /opt/starrocks/be/bin/be.pid）。这个位置由启动脚本中的 PID_DIR 变量决定，它被设置为脚本所在目录（$STARROCKS_HOME/bin）。

重要的是，PID 文件不是由启动脚本写入的，而是由 Java 进程在启动后写入的。这意味着如果 Java 进程异常退出或被强制杀死，PID 文件可能没有被正确清理。这就是为什么我们需要在启动前检查并清理残留的 PID 文件。

4.2 官方停止脚本的工作原理

官方的 stop_fe.sh 和 stop_be.sh 脚本的工作流程是：

首先读取 PID 文件，然后验证进程是否为 Java 进程（通过 ps -p $pid -o comm= 获取进程命令名，确保是 “java”）。这个安全验证很重要，因为如果 PID 被其他进程复用，可能会导致误杀。
接下来，脚本发送 kill $pid（即 SIGTERM 信号），这是优雅停止的标准方式。然后脚本会循环等待进程退出，每 2 秒检查一次，直到进程退出或超时。进程退出后，脚本会自动删除 PID 文件。

然而，这个机制有一个前提：

进程必须能够响应 SIGTERM 信号。如果进程卡死、信号被阻塞、或者进程已经异常退出，停止脚本可能无法正常工作。这就是为什么我们需要双重保障：先尝试优雅停止，失败则强制停止，最后确保删除 PID 文件。

4.3 为什么需要双重保障？

即使 stop_fe.sh 会删除 PID 文件，我们仍然需要在启动前检查并清理，原因有三个：

首先，异常情况下停止脚本可能执行失败。如果进程已经异常退出，停止脚本可能无法找到进程，或者执行过程中出错，导致 PID 文件没有被删除。
其次，容器重启时，之前的进程可能已经被强制杀死。当容器重启时，Docker 会先停止旧容器，如果旧容器中的进程没有正常退出，会被 SIGKILL 强制杀死。此时 PID 文件可能还在，但进程已经不存在了。
最后，如果 PID 文件存储在数据卷中，容器删除重建后 PID 文件仍然存在。这是因为数据卷是持久化的，即使容器被删除，数据卷中的数据（包括 PID 文件）仍然保留。当新容器启动时，如果 PID 文件存在，启动脚本会误判为进程仍在运行。

因此，我们需要在启动前主动检查并清理 PID 文件，无论进程是否真的在运行，都要确保 PID 文件被删除，避免阻塞启动。

五、最佳实践：如何设计可靠的容器启动脚本

5.1. Docker Compose 配置的关键参数

在 Docker Compose 配置中，有几个关键参数可以帮助实现优雅停机。

stop_grace_period 参数可以延长优雅停机时间，默认是 10 秒，但对于 StarRocks 这样需要保存大量数据的应用，可能需要更长时间。我们建议设置为 30 秒，给 StarRocks 足够的时间完成数据落盘和元数据保存。
stop_signal 参数可以明确指定停止信号，虽然默认就是 SIGTERM，但显式声明可以让配置更清晰，也便于后续维护。
更重要的是，不要持久化 PID 文件目录。PID 文件应该存储在容器的临时文件系统中，而不是数据卷中。这样可以避免容器删除重建后 PID 文件残留的问题。

5.2 Entrypoint 脚本的设计原则

Entrypoint 脚本的设计需要遵循几个原则。

首先，使用 Exec 格式或 exec 命令，确保应用程序能直接接收信号。如果使用 Shell 格式，Shell 可能不会将信号转发给子进程，导致应用程序无法收到停止信号。
其次，使用 trap 捕获 SIGTERM 和 SIGINT 信号，在收到信号时执行清理工作。这包括停止应用程序进程、清理临时文件、关闭连接等。然而，需要注意的是，如果使用 exec tail -f，当前 shell 进程会被替换，trap 会失效。应该使用后台运行 + wait 的方式，让 shell 进程保持运行，这样 trap 才能正常工作。
第三，启动前必须检查并清理残留的 PID 文件。这是解决启动失败问题的关键。无论之前的进程是否正常退出，都要确保 PID 文件被删除。
最后，优先使用官方停止脚本进行优雅停止，失败则强制停止。这样可以最大程度保护数据完整性，同时确保容器能够正常启动。