Docker ENTRYPOINT 完全指南：容器启动的"门神"

1. 什么是 ENTRYPOINT？

1.1 本质定义

ENTRYPOINT 是容器启动时的"入口点"，它定义了容器启动时必须执行的命令。可以把它理解为：

• 容器的"门神"：所有进入容器的命令都要经过它

• 容器的"初始化程序"：负责容器的启动和初始化

• 容器的"守护者"：确保关键进程的正确运行

1.2 为什么需要 ENTRYPOINT？

1. 初始化工作
    

# 例如：容器启动前的准备工作
   ENTRYPOINT ["docker-entrypoint.sh"]
   CMD ["main-program"]

• 检查必要目录

• 初始化配置文件

• 设置权限

• 启动主程序

2. 环境准备

    # 例如：确保运行环境正确
      ENTRYPOINT ["/docker-entrypoint.sh"]

• 设置环境变量

• 创建必要目录

• 检查依赖服务

• 等待其他服务就绪

3. 进程管理
    

      # 使用 tini 作为 init 进程
      ENTRYPOINT ["/sbin/tini", "--", "./docker-entrypoint.sh"]

    

• 处理僵尸进程

• 转发信号

• 确保正确退出

2. ENTRYPOINT 的两种形式

2.1 Shell 形式

ENTRYPOINT ./docker-entrypoint.sh

 

特点：

• 通过 shell 执行

• 可以使用环境变量

• 不能正确处理 Unix 信号

• PID 1 是 shell，不是应用程序

2.2 Exec 形式（推荐）

ENTRYPOINT ["./docker-entrypoint.sh"]
# 或更常见的
ENTRYPOINT ["/sbin/tini", "--", "./docker-entrypoint.sh"]

 

特点：

• 直接执行，不通过 shell

• 可以正确处理 Unix 信号

• 应用程序是 PID 1

• 参数传递更灵活

3. 如何覆盖 ENTRYPOINT？

3.1 命令格式（最重要！）

# 正确格式：

docker run --entrypoint 新命令 镜像名 参数

一定要注意新的entrypoint命令是放在镜像名的前面!

 

# ✅ 正确示例

docker run --rm --entrypoint bash myapp:latest

docker run --rm \

    --entrypoint geth \

    myapp:latest \

    init --datadir "/data"

 

# ❌ 错误示例

docker run myapp:latest --entrypoint bash  # 位置错误

docker run --entrypoint myapp:latest bash  # 镜像名位置错误

3.2 常见错误及解决

1. 找不到镜像错误
    

      Unable to find image 'command:latest' locally
      # 原因：--entrypoint 位置错误，命令被当作镜像名

2. 命令不存在
    

      command not found
      # 原因：新命令在容器中不存在

4. ENTRYPOINT 的工作机制

4.1 启动流程

4.2 参数传递

graph TD

    A[Docker 启动容器] --> B[执行 ENTRYPOINT]

    B --> C[ENTRYPOINT 执行初始化]

    C --> D[处理 CMD 或命令行参数]

    D --> E[启动主程序]

 

5. 最佳实践

5.1 使用初始化系统

 

# Dockerfile
ENTRYPOINT ["echo", "Hello"]
CMD ["World"]

# 运行效果
docker run image        # 输出: Hello World
docker run image John   # 输出: Hello John

 

5.2 编写健壮的入口脚本

 

# 使用 tini 处理信号和僵尸进程
ENTRYPOINT ["/sbin/tini", "--", "./docker-entrypoint.sh"]

 

5.3 运行时注意事项

• 使用绝对路径避免命令找不到

• 保留必要的环境变量

• 使用多行格式提高可读性

• 确保新命令在容器中存在

• 检查用户权限

记住：ENTRYPOINT 不仅是一个启动命令，而是容器生命周期中的重要管理者，确保容器能够正确初始化并稳定运行。正确理解和使用 ENTRYPOINT，是容器化应用成功的关键。