3.2 run 参数义项大全：按意图分组的常用选项

3.2 run 参数义项大全：按意图分组的常用选项

本节摘要：docker run 是全书义项最多的单条命令。本节不按字母序罗列，而按使用意图把高频选项分成命名、前后台、端口、环境、存储、重启策略几组，每组给语法、最小现场与删掉它的后果。读完能拼出符合生产要求的 run 命令，并读懂别人写的长命令。

「--rm」这类以双横线开头的义项，是命令词典里最像"词缀"的存在：同一条 run，配上不同词缀就是完全不同的容器。面对一条几十个选项的 run 命令，逐个背是背不动的，本节的任务是给你一张分组地图——遇到什么意图，去哪组里找选项。

参数地图：run 的选项分组

词条卡：docker run

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
​

唯一的位置参数是 IMAGE；它之后的字符串不再是 docker 的选项，而是交给容器入口的命令与参数——这条分界线是读懂长命令的第一把钥匙。

现场一：命名与前台后台

$ docker run -d --name web nginx:1.25
8f3a2b1c9d0e...
$ docker run --rm -it debian:12-slim bash
root@7c2e1a9b3d:/# exit
exit
$ docker ps -a --filter name=7c2e1a9b3d
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    NAMES
​

-d 把容器放后台，回一行 ID 就交还终端；不加 -d，容器输出直接糊在你脸上，Ctrl+C 还可能顺手停掉容器。-it 是交互场景的固定搭配：-i 保住标准输入，-t 分配伪终端，少了任何一个体验都不对。--rm 让容器退出即自动删除——上面那次一次性 bash 退出后，ps -a 里连遗体都找不到。注意它管的是"退出后删不删"，与管"挂了要不要拉起"的 --restart 是两回事，两者同时给会直接报错。

现场二：端口映射的读法

$ docker run -d --name web -p 8080:80 -p 127.0.0.1:5433:5432 postgres:16
$ docker port web
80/tcp -> 0.0.0.0:8080
$ docker ps --format '{{.Names}}\t{{.Ports}}'
web      0.0.0.0:8080->80/tcp, 127.0.0.1:5433->5432/tcp
​

-p 宿主:容器 是最常见形态；加宿主 IP 前缀（127.0.0.1:5433:5432）就把映射收紧到本机回环，数据库这类不该对外的服务务必这样写。忘了 -p，容器内的服务从宿主机彻底不可达——这是新手最常撞的墙，症状是 curl 拒绝连接而容器状态却是 running。

现场三：环境变量与配置注入

$ docker run --rm -e APP_ENV=prod -e TZ=Asia/Shanghai --env-file ./app.env \
    debian:12-slim env | grep -E 'APP_ENV|TZ'
APP_ENV=prod
TZ=Asia/Shanghai
​

-e 逐项注入，--env-file 整文件灌入，后者是配置项多时的正解——命令行里不再堆秘密。要警惕的是 -e 的值会进 inspect 输出与日志，数据库密码走它等于把密码写进了任何人 docker inspect 都能看到的明文里；敏感信息用编排层的 secret 机制，或挂载文件注入。

现场四：重启策略四选一

$ docker run -d --name cache --restart unless-stopped redis:7.2
$ docker inspect cache --format '{{.HostConfig.RestartPolicy.Name}}'
unless-stopped
​

策略可选 no（默认）、on-failure（仅异常退出时重启，可配次数）、always（总是）、unless-stopped（总是，但手动 stop 后不违背人的意志）。生产机推荐 unless-stopped：进程崩了自动拉起，而运维明确停掉的容器不会在维护窗口里诈尸。always 与它的差别就在这处"听话"上。

⚠️ 常见坑：--restart 与 --rm 互斥，同时给出会报 "--restart" and "--rm" 的冲突错误；另外 --restart 只管容器主进程的生死，进程假死（还活着但不再响应）它无能为力，那需要外部的健康检查配合，词条在捌部。

读懂一条长命令

把本节各组串起来演练一次拆解。看到这条命令：

docker run -d --name order-api --restart unless-stopped \
  -p 127.0.0.1:9000:9000 \
  -e DB_HOST=pg.internal -e DB_PORT=5432 \
  -v /etc/localtime:/etc/localtime:ro \
  --memory 512m --cpus 1.5 \
  registry.local:5000/order-api:1.8
​

逐组对号：后台起、命名 order-api、异常自动拉起；端口只绑本机回环；两个环境变量连数据库；挂载时区文件且只读；资源上双帽；镜像来自自建仓库。能这样按组读下来，任何长命令都不再是天书。

写长命令的两条纪律

一是顺序无谓、成组有序：选项与位置参数之间的先后 Docker 不在乎，但"同组选项写在一处"（端口组、环境组、存储组、资源组）能让半年后的自己一眼对号。二是先短后长：新服务第一次手敲完整命令验证通过后，立即把它固化进部署脚本或 compose 文件——长命令留在历史记录里反复手敲，就是事故的温床。

本节要点回顾

• IMAGE 之后是入口命令：位置参数分界线是读长命令的第一把钥匙。
• -d 与 -it 是两种存在方式；--rm 管身后事，--restart 管来世，互斥不可同给。
• -p 别裸奔：不应对外的端口绑 127.0.0.1；忘写 -p 的症状是"容器活着但连不上"。
• -e 会泄漏进 inspect：敏感配置走文件或 secret，别图省事。
• 重启策略选 unless-stopped：崩了自动拉、停了不诈尸。

容器跑起来之后，下一件事是盯着它：ps、stats、logs、top 四个观测词条，3.3 逐一开讲。