容器内进程管理与 Entrypoint 最佳实践

1. 成为所有"无父进程"子进程的收养者
   - 业务进程 fork 出的孙进程，父进程先死后，会被 PID 1 收养
2. 负责回收僵尸进程（wait() 子进程）
   - 子进程退出后未 wait，会残留为 <defunct> 状态
3. 接收并转发信号给子进程
   - 宿主机 docker stop 发出 SIGTERM，先到达 PID 1

# 查看容器内的 PID 1 是谁（镜像默认可能就是 bash 或 sh）
docker exec -it myapp ps -ef | head -5

# 看容器内是否存在僵尸进程（Z 状态）
docker exec -it myapp ps -ef | awk '$2=="Z" || $2=="Z+" || $3 ~ /defunct/'
docker exec -it myapp ps aux | grep -c defunct

bash 作为 PID 1 时：
  - 子进程退出 → 无人 wait → 僵尸堆积（尤其长期运行的容器）
  - docker stop → SIGTERM 发给 bash，bash 不转发给 Java/Node 进程
  - 应用没收到 SIGTERM → 不会优雅关闭连接、刷盘
  - 等到 SIGKILL → 数据丢失 / 连接中断

这就是"容器停了但服务端还在报错"的常见根源。

docker stop myapp
   │
   ▼
dockerd 向容器 PID 1 发送 SIGTERM
   │
   ▼（两种情况）
A. PID 1 = 应用本身（exec）    → 应用直接处理 SIGTERM，优雅退出
B. PID 1 = shell/init 包装器    → 需要把 SIGTERM 转发给真正的应用进程
   │
   ▼
超时后（默认 10s）dockerd 发送 SIGKILL 强制杀掉

# 给容器更长的优雅退出时间（单位秒）
docker run -d --stop-timeout 30 myapp

# docker-compose 中配置
# services:
#   myapp:
#     stop_grace_period: 30s

// Node.js 优雅退出
const server = require('http').createServer(...);
server.listen(8080);

process.on('SIGTERM', () => {
  console.log('收到 SIGTERM，停止接收新连接...');
  server.close(() => {
    console.log('存量连接处理完毕，退出');
    process.exit(0);
  });
  // 兜底：5 秒后强退
  setTimeout(() => process.exit(1), 5000).unref();
});

# Python 优雅退出
import signal, sys

def graceful(signum, frame):
    print("收到退出信号，正在清理...")
    # 关闭连接池、落盘缓存
    sys.exit(0)

signal.signal(signal.SIGTERM, graceful)
signal.signal(signal.SIGINT, graceful)
# 主循环
while True:
    time.sleep(1)

// Java 优雅退出（JVM 对 SIGTERM 默认会执行 shutdown hook）
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
    System.out.println("JVM 关闭钩子执行...");
    // 关闭线程池、释放资源
    executor.shutdownNow();
}));

# 让 Docker 自动注入 tini 作为 PID 1
docker run --init --rm alpine sleep 1000
# 验证：容器内 PID 1 是 /sbin/tini
docker exec -it <cid> ps -p 1 -o pid,comm,args

# 基于 Alpine（musl）的镜像
RUN apk add --no-cache tini
ENTRYPOINT ["tini", "--", "/entrypoint.sh"]

# 基于 Debian/Ubuntu 的镜像
RUN apt-get update && apt-get install -y tini && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["/usr/bin/tini", "--", "/entrypoint.sh"]

RUN wget -O /usr/local/bin/dumb-init \
      https://github.com/Yelp/dumb-init/releases/download/v1.2.5/dumb-init_1.2.5_x86_64 \
    && chmod +x /usr/local/bin/dumb-init
ENTRYPOINT ["dumb-init", "--"]
CMD ["/app/main"]

# exec-form：PID 1 = node
ENTRYPOINT ["node", "/app/server.js"]
# shell-form：PID 1 = sh，sh 再拉 node（信号被 sh 吞掉）
ENTRYPOINT node /app/server.js

# 推荐模板：ENTRYPOINT 固定、CMD 提供默认参数
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
EXPOSE 8080
ENTRYPOINT ["node", "/app/dist/server.js"]
CMD ["--port", "8080", "--env", "production"]

# 覆盖 CMD 传入新参数（ENTRYPOINT 不变）
docker run myapp --port 9090 --env staging
# 实际执行：node /app/dist/server.js --port 9090 --env staging

#!/bin/sh
set -e

echo "=== 初始化阶段 ==="
# 1. 等待依赖（数据库就绪）
until nc -z db 5432; do echo "等待 db..."; sleep 2; done

# 2. 执行一次性迁移
if [ "$RUN_MIGRATIONS" = "1" ]; then
  /app/bin/migrate --config /app/config.yml
fi

# 3. exec 真正的主进程（关键：必须 exec，让应用成为 PID 1）
exec "$@"

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
CMD ["/app/main"]

; /etc/supervisor/conf.d/app.conf
[supervisord]
nodaemon=true              ; 必须前台运行，否则容器立即退出
logfile=/dev/null

[program:web]
command=/usr/bin/python /app/wsgi.py
autostart=true
autorestart=true
stopsignal=TERM
stopwaitsecs=20

[program:worker]
command=/usr/bin/python /app/celery_worker.py
autostart=true
autorestart=true

RUN pip install supervisor
COPY supervisord.conf /etc/supervisor/conf.d/app.conf
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/supervisord.conf"]

FROM alpine:3.20
ADD https://github.com/just-containers/s6-overlay/releases/download/v3.1.6.2/s6-overlay-noarch.tar.xz /tmp/
RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz \
 && rm -f /tmp/s6-overlay-noarch.tar.xz
# 服务定义写 /etc/s6-overlay/s6-rc.d/ 下的目录结构
ENTRYPOINT ["/init"]

FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
COPY target/app.jar .
# exec-form + 显式堆限制（避免 JVM 与 cgroup 误判）
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0", "-jar", "/app/app.jar"]

FROM node:20-alpine
WORKDIR /app
# --init 让 Docker 内置 tini 当 PID 1，弥补 node 对孤儿进程不回收的问题
ENTRYPOINT ["node", "/app/server.js"]

# 运行时加 --init（PID 1 = tini，node 是子进程但信号被正确转发）
docker run --init --stop-timeout 30 mynodeapp

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir gunicorn==23.0.0
COPY . .
# gunicorn master 进程可作 PID 1，能回收 worker 僵尸
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "app:app"]

FROM golang:1.23 AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/server

FROM scratch
COPY --from=builder /app /app
# scratch 镜像无 shell，PID 1 就是 Go 程序本体，天然正确
ENTRYPOINT ["/app"]

# Dockerfile 内定义健康检查
HEALTHCHECK --interval=5s --timeout=3s --retries=3 --start-period=10s \
  CMD curl -fs http://localhost:8080/health || exit 1

# compose 中的重启策略（与健康检查联动）
services:
  web:
    image: myapp:1.2
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-fs", "http://localhost:8080/health"]
      interval: 10s
      timeout: 3s
      retries: 3

□ 能用 exec-form 就不用 shell-form（PID 1 就是应用本体）
□ 需要初始化时，脚本末尾务必 exec "$@" 
□ 多进程场景优先 s6-overlay，其次 supervisor（nodaemon=true）
□ 默认给 docker run 加 --init，或镜像显式装 tini
□ docker stop 超时不够时调 --stop-timeout / stop_grace_period
□ 应用侧正确实现 SIGTERM 的优雅关闭（关连接、刷盘、退线程池）
□ JVM 镜像加 -XX:MaxRAMPercentage 与 cgroup 联动
□ 用 HEALTHCHECK + restart 策略兜住崩溃进程