Docker 基础

适用范围：Dreamlog 生产环境日常运维、发布、排障
默认约定：已在 root 用户 shell 中封装 dc（见文末 Shell Alias），因此文档中 所有 Compose 命令只使用 dc。

---

0. 快速开始

dc ps
          

查看 Compose 服务运行状态（判断是否有服务 down / restarting）。

dc logs -f --tail 200 nginx
          

实时跟踪 Nginx 日志（排查 502/504、TLS、路由、上游连接问题）。

参数说明： - -f：持续跟随输出（实时滚动看日志） - --tail：只输出最近 N 行，避免一次性刷屏

dc logs -f --tail 200 backend
          

实时跟踪后端日志（排查 500、鉴权失败、数据库错误、第三方依赖错误）。

dc exec backend alembic current && dc exec backend alembic upgrade head
          

查看并升级数据库迁移到最新（发布后最常见的“表/字段不存在”问题）。

---

1. 容器（Containers）

启动 / 停止 / 重启

docker start <container>
          

• dc ps 的 NAME 列即容器名 启动指定容器（绕过 Compose，通常不推荐；除非临时救火）。

docker stop -t 30 <container>
          

优雅停止指定容器（给进程最多 30s 退出）。

参数说明： - -t：等待优雅退出的超时时间（超时后会强制杀进程）

docker restart <container>
          

重启指定容器（容器级操作，适合单点重启）。

查看运行状态

docker ps
          

查看运行中的容器（全局视角）。

docker ps -a
          

查看所有容器（包括已退出的，排查残留/冲突）。

参数说明： - -a：显示所有容器（包含已停止/退出的）

进入容器

docker exec -it <container> bash
          

进入容器 Shell（Debian/Ubuntu 用 bash）。

参数说明： - -it：交互式终端（可输入命令、可看到实时输出；排障/手工操作必备）

docker exec -it <container> env | sort
          

查看容器内环境变量。

删除容器

docker rm -f <container>
          

强制删除容器 - 利用底层系统的 SIGKILL 信号直接杀死进程，然后立即删除容器。 - 由于是“强杀”，容器里的应用可能来不及保存数据、关闭数据库连接或清理临时文件，有极小概率导致数据损坏。

docker rm <container>
          

删除已停止即非运行状态的容器。

---

2. 镜像（Images）

拉取 / 删除

docker pull <image:tag>
          

拉取镜像（发布前预热、回滚前预取）。

docker images
          

查看本机镜像列表（检查是否已拉取到目标 tag）。

构建

dc build backend frontend
          

使用 Compose 构建指定服务镜像（适用于本机 build 场景；CI/CD 通常在构建机完成）。

清理无用镜像

1. 先列出当前正在被容器使用的镜像

docker ps -a --format '{{.Image}}' | sort -u
          

这些 REPOSITORY:TAG 都是现在有容器在用的镜像，不要删。

2. 只保留当前线上版本 + 最近一两个可回滚版本

列出每个docker服务的所有tag

docker images 'crpi-nwtbgdcxek2l5bfv.cn-hangzhou.personal.cr.aliyuncs.com/dream-log-repo/dream-log-backend'
          docker images 'crpi-nwtbgdcxek2l5bfv.cn-hangzhou.personal.cr.aliyuncs.com/dream-log-repo/dream-log-frontend'
          

• 选 1–2 个最近的 Tag 作为回滚候选，其它旧tag镜像就可以删除

docker rmi <image:tag>
          

docker rmi \
            crpi-.../dream-log-repo/dream-log-backend:13ed46f \
            crpi-.../dream-log-repo/dream-log-backend:2dc498f \
            crpi-.../dream-log-repo/dream-log-backend:3bc2212
          

删除指定镜像（释放空间；如被容器占用会失败）。

3. 清理悬空镜像（完全没 Tag 或没在用）

docker image prune -f
          

参数说明： - -f：不提示确认直接执行

4. 查看镜像/容器/卷占用（决定是否需要清理，是否有可回收的空间）

docker system df
          

---

3. 服务（Docker Compose）

启动服务

dc up
          

前台启动（用于观察启动日志；Ctrl+C 会停止前台 attach）。

dc up -d
          

后台启动（生产环境最常用）。

参数说明： - -d：后台运行（不占用当前终端，适合生产常态运行）

停止 / 删除（不删数据卷）

dc stop
          

停止服务（容器仍保留，可快速 start）。

dc down
          

停止并移除服务容器与网络（不会删除 volume 数据）。

dc down --remove-orphans
          

停止并移除未在当前 compose 文件中的孤儿容器。

参数说明： - --remove-orphans：删除未在当前 compose 中定义的同项目容器（注意：可能会删掉你手动起的“临时容器”）

重建服务

dc pull
          

拉取 compose 定义的所有镜像（使用远端镜像时优先执行）。

dc up -d --pull always
          

先拉取（对 compose 里需要的镜像逐个执行 pull，能拉到就更新到最新 tag 对应的 digest），拉取完成后再创建/重建并启动容器

参数说明： - -d：后台运行 - --pull：启动前拉取镜像（always 表示每次都拉，避免用到旧镜像）

dc up -d --force-recreate
          

不改镜像的情况下强制重建容器（环境变量/挂载/网络变化后使用）。

参数说明： - -d：后台运行 - --force-recreate：强制重建容器（即使无变更也会重建；注意短暂中断/连接重置）

dc up -d --build
          

本机构建并启动（生产一般不推荐在同机 build；但紧急情况下可用）。

参数说明： - -d：后台运行 - --build：启动前先构建镜像（会消耗 CPU/IO，生产机器谨慎使用）

单服务操作

dc restart nginx
          

仅重启 Nginx（改了 nginx.conf、证书续期、上游变更后最常用）。

dc up -d backend worker
          

只启动/更新 backend 与 worker（前端/网关不动，减少影响面）。

dc exec backend alembic upgrade head
          

只对 backend 执行迁移命令（DB schema 同步）。

---

4. 日志（Logs）

实时日志

dc logs -f --tail 200
          

跟踪全量服务日志（排查跨服务链路问题，如 nginx→backend→db）。

指定服务日志

dc logs -f --tail 200 backend
          

后端实时日志（请求报错、数据库异常、第三方 API 调用失败）。

dc logs -f --tail 200 nginx
          

网关实时日志（502/504、TLS、rewrite、upstream connect refused）。

dc logs -f --tail 200 postgres
          

数据库日志（连接数、慢查询线索、崩溃恢复）。

限制输出 / 快速定位

dc logs --tail 300 backend | sed -n '1,120p'
          

取 backend 服务最近 300 行日志，然后只显示其中第 1 到 120 行。。

dc logs --tail 500 backend | grep -E "ERROR|Traceback|Exception" -n
          

快速从日志中定位异常关键词。

---

5. 状态与监控（Status & Debug）

查看资源占用

docker stats
          

实时查看容器 CPU/Mem/Net/IO（判断是否 OOM、CPU 打满、网络异常）。

docker stats --no-stream
          

容器 CPU/Mem/Net/IO状态的一次性快照（适合写入故障记录）。

查看容器状态 / 重启原因

docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}\t{{.Ports}}'
          

表格查看容器状态（快速扫一眼）。

参数说明： - --format：定制字段输出（快速定位状态/镜像/端口，不用翻全量 JSON）

docker inspect <container> --format '{{.State.Status}} {{.State.ExitCode}} {{.State.Error}}'
          

看退出码/错误原因（容器反复重启必查）。

查看端口占用

ss -lntp
          

查看监听端口与进程（生产排障端口冲突、服务是否监听）。

参数说明： - ss 一般解释为 Socket Statistics（套接字统计/查看 socket 状态的工具，iproute2 套件里）。

• -l: listening（只显示监听中的 socket）

• -n: numeric（用数字显示地址/端口，不做 DNS 解析、不把端口转成服务名）

• -t: TCP（只看 TCP 连接/端口）

• -p: process（显示占用该端口/连接的进程信息，如 PID/程序名；通常需要 root 才能看全）

---

6. 网络（Network）

查看网络

docker network ls
          

查看所有 Docker 网络（确认 compose 网络是否存在）。

docker network inspect <network>
          

查看网络内连接的容器与 IP（排查 DNS/连通性问题）。

排查容器通信

dc exec nginx sh -c 'getent hosts backend && nc -vz backend 8000'
          

从 nginx 容器内解析并连通 backend（排查 502/connection refused 的首选）。

参数说明： - -c：让 shell 执行一段字符串命令（便于一次性串联多个排查命令）

dc exec nginx sh -c 'apk add --no-cache curl >/dev/null 2>&1 || true; curl -sS -D- http://backend:8000/ | head'
          

从 nginx 容器直接请求后端（验证 upstream 是否通）。

注意：若你启用了 Nginx “运行时解析 upstream”，需要配置 resolver 127.0.0.11 + upstream zone，避免容器重启换 IP 后 502。

---

7. 数据卷（Volumes）

查看 / 删除

docker volume ls
          

列出所有数据卷。

docker ps --format '{{.Names}} {{.Mounts}}'
          

找出当前正在使用的卷（一定不要删）

docker volume inspect <volume>
          

查看卷的挂载信息）。

docker volume prune -f
          

一键回收所有悬空卷 - 会删除所有 未被任何容器使用的卷 - 不会删当前正在被挂载的卷

docker ps -a --filter volume=<卷名>
          

逐个对“看起来像旧卷”的名字做上述命令，如果没有输出则说明该卷无用

docker volume rm <volume>
          

删除数据卷（高危，会删除持久化数据；生产仅在确认无数据或已备份时使用）。

数据持久化注意事项（生产必读）:

• dc down 默认不会删 volume，但 dc down -v 会删卷（高危）。
• 项目名（COMPOSE_PROJECT_NAME）变化会导致卷名前缀变化，容易出现“看似丢数据”（实际挂了新卷）。
• 迁移/导入数据前先确认连的是预期数据库（检查 DATABASE_URL、psql \dt）。

---

8. 清理（Cleanup）

一键清理命令（慎用）

docker system prune -af
          

清理未使用的镜像/容器/网络。

参数说明： - -a：清理所有未使用镜像（不止 dangling；回滚依赖的镜像可能被清掉） - -f：不提示确认直接执行

docker volume prune -f
          

清理未使用数据卷。

参数说明： - -f：不提示确认直接执行（生产慎用，建议先备份/确认）

安全清理策略（推荐）

docker image prune -f
          

只清理 dangling 镜像（安全、常用）。

docker system df
          

先查看占用，再决定清理范围（运维基本功）。

---

9. 高级排障（Troubleshooting）

9.1 容器反复重启（Restarting）

docker ps --filter "status=restarting"
          

快速定位反复重启容器名。

docker logs --tail 300 <container>
          

看启动失败原因（配置缺失、连接不上 DB、迁移未执行等）。

docker inspect <container> --format '{{.State.OOMKilled}} {{.State.ExitCode}}'
          

判断是否 OOM killed / 退出码（资源类问题 vs 逻辑错误）。

9.2 服务无法访问（浏览器打不开 / 502 / 504）

dc logs --tail 200 nginx
          

先看 Nginx 是否报 upstream 错误（connect refused / timeout）。

dc exec nginx sh -c 'getent hosts backend && nc -vz backend 8000'
          

验证 nginx→backend 是否连通（DNS + TCP）。

dc logs --tail 200 backend
          

看后端是否在处理请求、是否 500。

经验判断： - 502 connect refused：后端未监听/重启中/网络解析旧 IP - 504 timeout：后端处理慢/卡死/数据库慢/上游慢 - 前端提示“加载用户信息失败”：多半是 /api/... 请求 401/403/500，优先看 backend 日志

9.3 网络异常（容器间不可达）

docker network ls
          

确认 compose 网络存在。

docker network inspect <network> | head -n 60
          

看网络里是否有 nginx/backend 容器。

dc up -d --force-recreate
          

强制重建容器（网络/DNS 状态异常时很有效）。

---

10. Dreamlog 常用运维任务（项目相关）

10.1 数据库迁移（生产发布必做）

dc exec backend alembic current
          

查看当前数据库迁移版本（确认是否落后）。

dc exec backend alembic upgrade head
          

升级到最新迁移。

注意：迁移失败常见于历史库结构差异，必要时将迁移写成幂等（如 DROP COLUMN IF EXISTS）。

10.2 导入初始数据（探索文章 / 梦境符号）

dc exec backend python scripts/articles/import_articles.py
          

导入探索文章到 exploration_articles（重复运行安全：存在则更新）。

dc exec backend python scripts/symbols/import_symbols.py
          

导入梦境符号到 exploration_symbols（重复运行安全：存在则更新）。

若需要先生成 symbols_output.json（依赖 Dify 配置）：

dc exec backend python scripts/symbols/batch_generate.py
          dc exec backend python scripts/symbols/import_symbols.py
          

先生成再导入。

---

11. Shell Alias（root 用户）

将以下内容加入 ~/.bashrc ，然后 source ~/.bashrc 生效。

# Compose 简写（本手册所有 compose 命令默认使用 dc）
          alias dc='docker compose'
          
          # 高频日志/状态
          alias dcp='dc ps'
          alias dcl='dc logs -f --tail 200'
          alias dclf='dc logs -f --tail 200'
          
          # 高频启停
          alias dcu='dc up -d'
          alias dcd='dc down'
          alias dcrs='dc restart'
          
          # 常用进入容器
          alias dce='dc exec'
          
          # 资源与容器视图
          alias dstats='docker stats'
          alias dps='docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}\t{{.Ports}}"'
          

使用场景： - dcl backend：快速跟踪后端日志 - dce backend alembic upgrade head：快速迁移 - dcu / dcrs nginx：发布后快速拉起/重启

---

12. 常用函数（可选但推荐）

将以下函数加入 ~/.bashrc 。

# 重新部署（不删除卷）：停止、清理孤儿、后台启动
          dcr() {
            set -e
            dc down --remove-orphans
            dc up -d
          }
          

用途：发布/配置变更后快速重建一套干净的服务（不动数据卷）。

# 快速检查 nginx->backend 连通性
          dcnet() {
            dc exec nginx sh -c 'getent hosts backend && nc -vz backend 8000'
          }
          

用途：出现 502/connection refused 时秒级判断是否上游连通。

# 数据库迁移快捷命令
          dcmig() {
            set -e
            dc exec backend alembic current
            dc exec backend alembic upgrade head
            dc exec backend alembic current
          }
          

用途：发布后快速确保 DB schema 最新（避免缺表/缺字段）。

---

13. 实战技巧（生产工程师常用）

• 快速定位异常容器

docker ps --format '{{.Names}} {{.Status}}' | grep -E 'Restarting|Exited|unhealthy' || true
          

用途：一眼找到异常容器（重启/退出/不健康）。

• 只重启单服务（最小影响面）

dc restart nginx
          

用途：只刷新网关（证书/配置/上游策略变更）。

• 安全更新服务（最小停机思路）

dc pull backend worker && dc up -d backend worker
          

用途：先拉镜像，再只更新后端相关服务；前端/DB/网关不动，减少波动。

• 发布后必做三连

dc ps
          dc exec backend alembic upgrade head
          dc logs --tail 200 nginx
          

用途：确认服务活着、迁移完成、入口无 5xx。