Dokku 进入容器指南：深入掌握 `dokku enter` 命令的用法与底层原理

本文基于当前仓库 docs/processes/entering-containers.md 编写。dokku enter 是 Dokku 平台中用于进入运行中应用容器（enter a running container）的核心命令，支持按进程类型、容器序号或容器 ID 精确定位容器，并以交互式 Shell 或一次性自定义命令两种方式工作。读完本文，你将掌握 dokku enter 的全部命令变体、参数语义、默认行为与执行细节，并能结合源码理解它在 docker-local 与 k3s 两种调度器下的落地实现。

命令总览与适用场景

dokku enter 自 Dokku 0.4.0 起提供（见文档开头的 [!IMPORTANT] 提示），用于进入某个正在运行的应用容器，常见的排查与运维场景包括：

• 进入容器查看应用运行状态、环境变量与文件系统；
• 在容器内执行一次性诊断命令（如查看进程、检查日志文件）；
• 模拟 cron 类长时任务，直接在前台运行脚本；
• 在容器内快速验证代码或配置变更的实际效果。

其命令语法如下：

enter <app>  [<container-type> || --container-id <container-id>]  # Connect to a specific app container

其中 <app> 为应用名，<container-type> 与 --container-id 二选一（或都不指定），用来定位目标容器。对应地，在 Dokku 的插件注册表 plugins/enter/plugin.toml 中，该插件被描述为 dokku core enter plugin，帮助文本则概括为 "Enter running app containers"（见 plugins/enter/help-functions）。

用法详解：五种定位容器的命令变体

文档给出了 dokku enter 的全部使用变体，均以示例应用 node-js-app 演示：

# 进入第一个容器
dokku enter node-js-app

# 进入 web 进程
dokku enter node-js-app web

# 进入第一个 web 进程
dokku enter node-js-app web.1

# 按容器 ID 进入应用的某个容器
dokku enter node-js-app --container-id ID

各变体的语义与注意事项如下：

命令变体	定位方式	说明
dokku enter <app>	自动探测	仅当应用只有一种正在运行的进程类型时可用，直接进入唯一容器
dokku enter <app> <type>	进程类型 + 默认序号	进入该进程类型的第 1 个容器
dokku enter <app> <type>.<N>	进程类型 + 序号	进入该进程类型的第 N 个容器，序号从 1 开始
dokku enter <app> --container-id <id>	容器 ID	按 Docker 容器 ID（支持前缀匹配）精确进入容器

其中 <container-type> 的取值规则为：

• 若应用定义了 Procfile，则取 Procfile 中的某个进程类型名（如 web、worker）；
• 若应用没有 Procfile，则该参数固定为 web。

当指定进程类型被扩容（scale up）到多个容器时，默认自动选择第一个容器；可通过追加整数序号覆盖该行为，第一个容器的序号为 1。

不指定进程类型时的自动探测行为

文档特别说明：当应用 Procfile 中只定义了一种进程类型时，直接执行 dokku enter <app> 会进入唯一运行中的容器；但该自动探测行为不适用于同时传入自定义命令的场景（详见下文"运行自定义命令"一节）。

这一行为在调度器实现中有严格的守卫逻辑。在 plugins/scheduler-docker-local/scheduler-enter 中，当既没有 --container-id 也没有进程类型时，会调用 get_app_running_container_types 枚举正在运行的进程类型（该函数位于 plugins/common/functions 的 587 行附近，通过扫描 $DOKKU_ROOT/$APP/CONTAINER.* 文件推断类型）；若存在多于一种类型，则直接告警并列出可用类型后失败退出：

No container type specified.
Available types for app ($APP): web worker

也就是说，多进程应用必须显式指定进程类型，否则无法自动进入。

默认 Shell 与自定义命令

默认情况下，dokku enter 会在容器内启动一个 /bin/bash 交互式 Shell。同时它也支持附加任意自定义命令，命令将直接在容器内执行：

# 仅执行一条 echo
dokku enter node-js-app web echo hi

# 运行长时任务（如 cron 类后台任务）
dokku enter node-js-app web python script/background-worker.py

从底层实现看，命令后的所有参数会作为 exec 参数透传给容器：

• 在 plugins/enter/subcommands/default 中，cmd-enter-default 解析出 APP、CONTAINER_TYPE、CONTAINER_ID 后，将剩余参数原样附加到 plugn trigger scheduler-enter ... -- "$@"；
• 在 plugins/scheduler-docker-local/scheduler-enter 中，最终执行 "$DOCKER_BIN" container exec $DOKKU_RUN_OPTS "$CONTAINER_ID" $EXEC_CMD "${@:-$DOKKU_APP_SHELL}"，即：若提供了自定义命令则执行自定义命令，否则回退到默认 Shell。这也解释了为什么"无参数自动探测"仅在未附带自定义命令时有效——附加命令时调用方必须显式给定目标容器。

调度器属性：自定义默认 Shell（scheduler:shell）

除了默认的 /bin/bash，还可以通过调度器属性自定义进入容器时使用的 Shell：

• 应用级：dokku scheduler:set <app> shell /bin/sh
• 全局级：dokku scheduler:set --global shell /bin/sh

属性优先级为：应用级配置 > 全局配置 > 内置默认值 /bin/bash。在 plugins/scheduler/scheduler.go 中，shell 属性默认值为空字符串、被标记为全局属性；在 plugins/scheduler-docker-local/scheduler-enter 中通过 fn-plugin-property-get-default 依次读取应用级、全局级属性，最终回退到 /bin/bash。scheduler:report 也会输出 Scheduler computed shell、Scheduler global shell、Scheduler shell 等字段（见 plugins/scheduler/report.go），便于核对当前生效的 Shell 配置。

底层原理：enter 插件如何委派给调度器

dokku enter 本身是一个薄壳插件，真正的容器定位与 exec 逻辑由"调度器（scheduler）"完成。调用链如下：

1. plugins/enter/subcommands/default 中 cmd-enter-default 校验应用名（verify_app_name）、解析参数，并取得该应用的调度器 DOKKU_SCHEDULER=$(get_app_scheduler "$APP")；
2. 随后触发插件钩子 plugn trigger scheduler-enter，并把进程类型、容器 ID 及自定义命令透传下去；
3. 各调度器插件实现自己的 scheduler-enter 钩子。

--container-id 参数支持 --container-id=ID 与 --container-id ID 两种写法，且可与其他定位参数混用；当同时提供进程类型与容器 ID 时，从源码看容器 ID 分支优先命中（if [[ -n "$CONTAINER_TYPE" ]] ... elif [[ -n "$CONTAINER_ID" ]]）。

docker-local 调度器（默认）

在 plugins/scheduler-docker-local/scheduler-enter 中，docker-local 调度器按以下顺序完成容器解析：

1. 类型/ID 解析：与 enter 插件相同地解析 --container-id 与进程类型；
2. 自动探测：无 ID 且无类型时，用 get_app_running_container_types 探测唯一类型，多于一种则报错；无类型时进一步用 get_app_container_ids 取该类型第 1 个容器；
3. ID 校验：按 ID 进入时，用 get_app_container_ids 拉取该应用全部容器 ID，做前缀匹配校验（grep -e "^$CONTAINER_ID"），不匹配则列出可用 ID 并失败；
4. 运行状态检查：通过 is_container_status "$CONTAINER_ID" "Running" 确认容器处于 Running 状态，否则报错 Container is not running；
5. 镜像感知：通过 docker container inspect 读取镜像名，若镜像基于 herokuish（is_image_herokuish_based）则附加 /exec 入口；若基于 CNB（Cloud Native Buildpacks，is_image_cnb_based）则清除 exec 入口并附加 -w /workspace 工作目录；
6. TTY 支持：has_tty 检测到终端时附加 -i -t 参数，保证交互式 Shell 的体验；
7. 执行：调用 docker container exec 运行自定义命令或默认 Shell。

由此可见，dokku enter 对 herokuish 与 CNB 两类镜像的进入方式做了差异化处理，确保在 Buildpacks 类应用容器中也能以正确的工作目录与入口进入。

k3s 调度器

对于 k3s 调度器，scheduler-enter 钩子在 plugins/scheduler-k3s/src/triggers/triggers.go 中被分发到 scheduler_k3s.TriggerSchedulerEnter，参数为调度器名、应用名、进程类型、Pod 标识符与附加命令。即同一套 dokku enter 命令在 k3s 场景下进入的是应用对应的 Pod/容器，命令行交互方式保持一致。

常见问题与使用提示

• 报错 "No container type specified"：应用存在多种运行中的进程类型，但未指定 web、worker 等类型；命令会列出当前可用类型供选择。
• 报错 "No containers found for type '$CONTAINER_TYPE'"：指定类型当前没有运行中的容器（如进程未被启动或已退出），可先用 dokku ps 查看进程状态。
• 报错 "Invalid container id for app"：--container-id 未匹配到该应用的任何容器（容器 ID 属于其他应用或拼写错误）；命令会列出该应用全部可用容器 ID。
• 报错 "Container is not running"：目标容器处于非 Running 状态，需先启动应用。
• 默认 Shell 不是 bash：可通过 dokku scheduler:set 调整 shell 属性（应用级或全局级）。
• 多进程应用必须显式指定类型：不要依赖无参自动探测，除非确定应用只有一种进程类型。

小结

dokku enter 提供了从"整应用首个容器"到"指定进程类型 + 序号 / 容器 ID"的多级定位能力，支持交互式 Shell 与一次性命令两种运行方式，并允许通过 scheduler:set 自定义默认 Shell。其命令层（plugins/enter）负责参数解析与调度器委派，容器定位、状态校验与 exec 细节则由各调度器插件（docker-local、k3s）实现，架构清晰、可扩展。结合 dokku ps、dokku logs 等命令，dokku enter 是日常排查与维护运行中应用时最直接的容器入口。