ENTRYPOINT 入口点

什么是 ENTRYPOINT

ENTRYPOINT 指定容器启动时运行的入口程序。与 CMD 不同，ENTRYPOINT 定义的命令不会被 docker run 的参数覆盖，而是接收这些参数。

核心作用：让镜像像一个可执行程序一样使用，docker run 的参数作为这个程序的参数。

---

语法格式

格式	语法	推荐程度
exec 格式	ENTRYPOINT ["可执行文件", "参数1"]	✅ 推荐
shell 格式	ENTRYPOINT 命令 参数	⚠️ 不推荐

# exec 格式（推荐）
ENTRYPOINT ["nginx", "-g", "daemon off;"]

# shell 格式（不推荐）
ENTRYPOINT nginx -g "daemon off;"

---

ENTRYPOINT vs CMD

核心区别

特性	ENTRYPOINT	CMD
定位	固定的入口程序	默认参数
docker run 参数	追加为参数	完全覆盖
覆盖方式	--entrypoint	直接指定命令
适用场景	把镜像当命令用	提供默认行为

行为对比

# 只用 CMD
CMD ["curl", "-s", "http://example.com"]

$ docker run myimage              # curl -s http://example.com
$ docker run myimage -v           # 执行 -v（错误！）
$ docker run myimage curl -v ...  # curl -v ...（完全替换）

# 只用 ENTRYPOINT
ENTRYPOINT ["curl", "-s"]

$ docker run myimage                      # curl -s（缺参数）
$ docker run myimage http://example.com   # curl -s http://example.com ✓

# ENTRYPOINT + CMD 组合（推荐）
ENTRYPOINT ["curl", "-s"]
CMD ["http://example.com"]

$ docker run myimage                      # curl -s http://example.com（默认）
$ docker run myimage http://other.com     # curl -s http://other.com ✓
$ docker run myimage -v http://other.com  # curl -s -v http://other.com ✓

---

场景一：让镜像像命令一样使用

需求

创建一个查询公网 IP 的"命令"镜像。

使用 CMD 的问题

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
CMD ["curl", "-s", "http://myip.ipip.net"]

$ docker run myip           # ✓ 正常工作
当前 IP：61.148.226.66

$ docker run myip -i        # ✗ 错误！
exec: "-i": executable file not found
# -i 替换了整个 CMD，被当作可执行文件

使用 ENTRYPOINT 解决

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["curl", "-s", "http://myip.ipip.net"]

$ docker run myip           # ✓ 正常工作
当前 IP：61.148.226.66

$ docker run myip -i        # ✓ 添加 -i 参数
HTTP/1.1 200 OK
...
当前 IP：61.148.226.66

交互图示

ENTRYPOINT ["curl", "-s", "http://myip.ipip.net"]
            │
docker run myip -i
            │
            ▼
curl -s http://myip.ipip.net -i
└─────────────────────────────┘
     ENTRYPOINT + docker run 参数

---

场景二：启动前的准备工作

需求

在启动主服务前执行初始化脚本（如数据库迁移、权限设置）。

实现方式

FROM redis:7-alpine
COPY docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["redis-server"]

docker-entrypoint.sh：

#!/bin/sh
set -e

# 准备工作
echo "Initializing..."

# 如果第一个参数是 redis-server，以 redis 用户运行
if [ "$1" = 'redis-server' ]; then
    chown -R redis:redis /data
    exec gosu redis "$@"
fi

# 其他命令直接执行
exec "$@"

工作流程

docker run redis                    docker run redis bash
        │                                    │
        ▼                                    ▼
docker-entrypoint.sh redis-server   docker-entrypoint.sh bash
        │                                    │
        ├─ 初始化                            ├─ 初始化
        ├─ chown -R redis:redis /data        │
        └─ exec gosu redis redis-server      └─ exec bash
           (以 redis 用户运行)                  (以 root 用户运行)

关键点

1. exec "$@"：用传入的参数替换当前进程，确保信号正确传递

2. 条件判断：根据 CMD 不同执行不同逻辑

3. 用户切换：使用 gosu 切换用户（比 su 更适合容器）

---

场景三：带参数的应用

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt

ENTRYPOINT ["python", "app.py"]
CMD ["--host", "0.0.0.0", "--port", "8080"]

# 使用默认参数
$ docker run myapp
# 执行: python app.py --host 0.0.0.0 --port 8080

# 覆盖参数
$ docker run myapp --host 0.0.0.0 --port 9000
# 执行: python app.py --host 0.0.0.0 --port 9000

# 完全不同的参数
$ docker run myapp --help
# 执行: python app.py --help

---

覆盖 ENTRYPOINT

使用 --entrypoint 参数覆盖：

# 正常运行
$ docker run myimage

# 覆盖 ENTRYPOINT 进入 shell 调试
$ docker run --entrypoint /bin/sh myimage

# 覆盖 ENTRYPOINT 并传入参数
$ docker run --entrypoint /bin/cat myimage /etc/os-release

---

ENTRYPOINT 与 CMD 组合表

ENTRYPOINT	CMD	最终执行命令
无	无	无（容器无法启动）
无	["cmd", "p1"]	cmd p1
["ep", "p1"]	无	ep p1
["ep", "p1"]	["cmd", "p2"]	ep p1 cmd p2
ep p1（shell）	["cmd", "p2"]	/bin/sh -c "ep p1"（CMD 被忽略）

⚠️ 注意：shell 格式的 ENTRYPOINT 会忽略 CMD！

---

最佳实践

1. 使用 exec 格式

# ✅ 推荐
ENTRYPOINT ["python", "app.py"]

# ❌ 避免 shell 格式
ENTRYPOINT python app.py

2. 提供有意义的默认参数

ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]

3. 入口脚本使用 exec

#!/bin/sh
# 准备工作...

# 使用 exec 替换当前进程
exec "$@"

4. 处理信号

确保 ENTRYPOINT 脚本能正确传递信号：

#!/bin/bash
trap 'kill -TERM $PID' TERM INT

# 启动应用
app "$@" &
PID=$!

# 等待应用退出
wait $PID

---

本章小结

ENTRYPOINT	CMD	适用场景
✓	✗	镜像作为固定命令使用
✗	✓	简单的默认命令
✓	✓	推荐：固定命令 + 可配置参数

延伸阅读

• CMD 容器启动命令：默认命令

• 最佳实践：启动命令设计

• 后台运行：前台/后台概念