2.3 挂载、端口与数据卷策略：让权重、数据与日志容器一关还在

2.3 挂载、端口与数据卷策略：让权重、数据与日志"容器一关还在"

读者读完这一节，应该能一句话说出他学到了什么：镜像是临时的，容器也是临时的，只有挂载卷里的东西能活过容器生命周期——所以模型权重、数据集、训练日志必须挂出去，而端口映射决定你能不能从浏览器摸到 Jupyter。

我见过最痛的一次事故：一位同事训练了三天的大模型，容器被误删，权重全在容器可写层里，没挂卷，三个月工作归零。这件事的教训只有一句：凡是你舍不得丢的东西，都不要留在容器内部。 镜像层是只读的、构建时确定；容器可写层是临时的、删容器即消失。能跨越容器生命周期的，只有挂载进来的宿主目录或命名卷。

这一节把"数据怎么活"这件大事讲透。

一、先分清三种"存储"

理解挂载策略前，要分清容器内数据的三种归宿：

1. 镜像层：构建时写死，只读，删容器不影响（因为它不在容器里）。适合放代码和依赖。
2. 容器可写层：运行时产生，随容器删除而消失。默认所有没挂载的写入都在这。危险区。
3. 挂载卷（bind mount / volume）：把宿主机的目录或 Docker 管理的卷挂进容器，容器删了数据还在。安全区，权重/数据/日志的归宿。

关键认知：可写层不是备份，是消耗品。 把训练权重 save 到 /app/outputs 而不挂载，等同于把成果放在一张随时被撕掉的便签上。很多人直到容器被 docker system prune 清掉才明白这一点，但代价已经付过。

二、bind mount：把宿主目录直接挂进去

最常用的挂载是 bind mount，把宿主机一个绝对路径挂到容器内路径。运行训练容器时：

docker run --gpus all -it --rm \
  -v /data/llm-models:/models \
  -v /data/datasets:/data \
  -v $(pwd)/outputs:/app/outputs \
  my-sandbox:latest \
  python train.py --model-dir /models --data-dir /data
​

三个挂载含义：

• /models：放 HuggingFace 权重缓存，避免每次启动重新下载几十 GB。
• /data：放训练数据集，只读为主。
• /app/outputs：训练日志与 checkpoint 落盘到宿主 $(pwd)/outputs，容器删了还在。

-v 左边是宿主路径（必须绝对路径），右边是容器路径。推荐把"会变大、会变、舍不得丢"的都挂出来，把"代码"留在镜像里。注意 $(pwd)/outputs 必须在运行前于宿主机创建好，否则 Docker 会自动建一个属于 root 的目录，引发下一节的权限坑。

三、命名卷 vs bind mount：什么时候用 volume

bind mount 直观，但宿主路径管理混乱时容易丢三落四。Docker 的命名卷（named volume）由 Docker 统一管理，适合"不想关心宿主具体在哪"的场景，比如数据库或缓存：

docker volume create llm_cache
docker run --gpus all -v llm_cache:/root/.cache/huggingface \
  my-sandbox python -c "from transformers import AutoModel; AutoModel.from_pretrained('bert-base')"
​

命名卷的好处是 docker volume inspect 能查位置、备份方便、不依赖宿主目录结构，且初始内容会自动从镜像对应层复制（首次挂载时）。我的实践：模型权重/数据集用 bind mount（我要精确知道在哪、要能直接 rsync 到别的机器），框架缓存用命名卷（我不在乎在哪，只要持久）。

四、端口映射：把容器里的服务暴露出来

训练沙箱常需要交互：Jupyter Notebook（8888）、TensorBoard（6006）、SSH（22）。容器默认网络隔离，必须 -p 映射端口：

docker run --gpus all -d \
  -p 8888:8888 \
  -p 6006:6006 \
  -v $(pwd)/notebooks:/app/notebooks \
  my-sandbox:latest \
  jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root
​

-p 8888:8888 表示宿主 8888 转发到容器 8888。浏览器开 http://宿主机IP:8888 即可进 Jupyter。注意 Jupyter 必须监听 0.0.0.0（不是默认的 127.0.0.1），否则只接受容器内连接，宿主访问不到——这是新手最常见的"开了端口却连不上"。另外 Jupyter 首次启动会打印一个带 token 的 URL，把它复制到浏览器才能完成认证，别把 token 当报错忽略了。

端口安全提醒：不要图省事把 SSH 22 直接 -p 22:22 暴露到公网，训练机被扫端口爆破的案例极多。需要远程建议走跳板机或 SSH 隧道（ssh -L 8888:localhost:8888 user@host），而非裸暴露。在云上更该用安全组限制来源 IP。

五、用 docker-compose 把挂载和端口固化为"沙箱契约"

单条 docker run 参数一多就记不住、易写错。把挂载、端口、GPU、环境变量写进 compose.yaml，沙箱就变成一份可读、可版本化、可交接的契约：

services:
  sandbox:
    image: my-sandbox:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    volumes:
      - /data/llm-models:/models:ro
      - /data/datasets:/data:ro
      - ./outputs:/app/outputs
      - llm_cache:/root/.cache/huggingface
    ports:
      - "8888:8888"
      - "6006:6006"
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - PYTHONUNBUFFERED=1
      - WANDB_MODE=offline
    command: jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root

volumes:
  llm_cache:
​

这份文件就是沙箱的"使用说明书"：新人 docker compose up 即得到一模一样的环境与挂载约定。注意我把模型/数据集标 :ro（只读），防止训练脚本误删原始数据——这是工程上的防御性习惯。PYTHONUNBUFFERED=1 让 Python 日志实时刷到终端，否则训练日志会因为缓冲而延迟出现，排错时很误事。

六、权限与用户映射：别让挂载目录变成 root 专属

bind mount 有个隐蔽坑：容器内默认以 root 写宿主目录，导致宿主机上 outputs/ 里文件全是 root 权限，普通用户无法清理，甚至 docker compose down 后留下一堆 root 文件没人能删。两个对策：

• 在 Dockerfile 建非 root 用户并 USER 切换（推荐，更安全，也符合最小权限原则）。
• 或在 docker run 加 --user $(id -u):$(id -g)，让容器内以当前宿主用户身份写挂载目录。

训练沙箱建议走非 root 用户 + --user 双保险，既安全又避免"训练完文件删不掉"的尴尬。但要注意：某些 CUDA 相关操作对权限敏感，非 root 用户在容器内通常仍能用 GPU（因为设备节点权限由 NVIDIA Container Toolkit 处理），所以切非 root 一般不会影响 GPU 使用，可以放心做。

七、tmpfs：让敏感/临时数据不落盘

有些中间数据（如解密后的密钥、超大临时张量缓存）不该落盘，也不该进可写层。可以用 --tmpfs /tmp 把内存当临时文件系统挂进去，容器退出即消失，既不占镜像也不占卷，还更安全。对涉及密钥的场景，这是比挂卷更合适的选择。

八、挂载策略的 Checklist

落地时按这张清单核对，能避开 90% 的数据丢失与连不上问题：

• 权重/数据集/日志是否都挂到卷，而非写在容器可写层？
• 只读数据是否标 :ro 防误删？
• Jupyter/TensorBoard 端口是否映射，且服务监听 0.0.0.0？
• 是否用 compose 固化挂载与端口，而不是靠记忆敲 docker run？
• 挂载目录权限是否会导致宿主机无法访问（root 专属）？
• 是否对敏感临时数据用了 tmpfs 而非落盘？

九、常见故障排查速查

• 训练完容器一删，权重没了：检查 checkpoint 是否写到未挂载的路径。用 docker diff <容器> 能看到容器相对镜像改了哪些文件，快速定位"漏挂"的目录。
• Jupyter 开了端口连不上：确认服务监听 0.0.0.0；确认访问的是宿主机 IP 而非容器 IP；确认云安全组/防火墙放行端口。
• 挂载目录是 root 权限删不掉：用 --user $(id -u):$(id -g) 重建容器，或 sudo chown 修权限。

十、多卡与多容器共享：挂载的边界

当用到多张 GPU 时，挂载策略不变，但要注意：每个容器都该挂自己的 outputs 子目录，避免多个训练任务写同一个 checkpoint 路径互相覆盖。在 compose 里用 deploy.resources 指定每张卡给哪个服务，配合独立的卷目录，就能让多任务并行而不打架。

另外，若多个容器要共享同一份只读数据集，bind mount 同一个 /data 目录（标 :ro）即可，无需复制多份——这是挂载相比打包进镜像的另一个优势：一份数据，多处挂载。

十一、卷的备份与清理：别让宿主机被撑爆

挂载把数据从容器可写层转移到了宿主机磁盘，但宿主机不是无限大。训练产生的 checkpoint 往往几十上百 GB，必须建立清理纪律：

• 用 docker volume ls 与 docker system df 定期盘点卷占用。
• 对命名卷，用一次性容器把卷内容拷到备份卷做卷级备份。
• 对 bind mount，直接 rsync 宿主目录到对象存储或 NAS。
• 明确哪些 checkpoint 值得保留（如最优验证指标那一个），其余定时清理，避免磁盘写满导致训练崩溃。

我见过训练半夜因磁盘 100% 而中断、且最后几个 epoch 未保存的惨剧。挂载解决了容器删了数据还在，但数据还在不等于数据被妥善管理，后者要靠纪律。

十二、Windows 与 macOS 上的挂载差异

如果你在 Windows（WSL2）或 macOS 上开发，挂载性能和路径有个坑：把宿主目录 bind mount 进 Linux 容器时，WSL2 与 macOS 的虚拟化文件系统（如 macOS 的 VirtioFS）在大量小文件读写上比原生 Linux 慢很多。训练时若把数据集放在宿主再挂进去，数据加载可能成为瓶颈。

对策：在开发机上把数据集放进 WSL2 的 Linux 文件系统（而非 Windows 的 /mnt/c），或 macOS 上用容器内命名卷做缓存，避免跨虚拟化边界的小文件 IO。生产训练机通常是原生 Linux，不存在这个问题，但开发联调时要注意。

十三、bind mount 与 volume 的 IO 性能取舍

训练是重 IO 负载（随机读数据集、频繁写 checkpoint）。经验上：bind mount 直接映射宿主目录，性能接近宿主原生；命名卷在 Linux 上由 Docker 的 overlay 管理，小文件场景可能有少许开销，但大块顺序 IO 差异不大。结论：数据集用 bind mount 到高速盘（NVMe）最稳；框架缓存用命名卷无碍。若训练中出现数据加载跟不上 GPU，优先怀疑挂载所在的磁盘是否够快，而不是先怪模型。

小结：第二章收束

2.1 讲分层让镜像高效，2.2 讲锁定让环境可信，本节 2.3 讲挂载让数据存活。三者合起来，你拥有的不再是一行 docker run 命令，而是一份可复用、可复现、数据安全的沙箱骨架：

• 改代码秒级重建（分层）
• 任何机器行为一致（锁定）
• 权重日志永不着火（挂载）

这正是"隔离式沙箱"作为团队基础设施的雏形。下一章（第三章）会往深里走，解释 GPU 透传与隔离的底层原理——为什么 --gpus all 是安全的、CUDA 到底在容器里怎么找到那张卡。理解了原理，你才能在出问题时快速定位，而不是只会重装。

十四、实战对照：一次权重归零事故的全过程复盘

回到开篇那次权重归零。复盘细节是：同事用 docker run --rm -v $(pwd):/app my-sandbox python train.py 训练，权重 save 到 /app/ckpt。看似挂了卷，但他挂的是 $(pwd)（当前工作目录）到 /app，而训练脚本实际把 checkpoint 写到了镜像里 /app 之外的临时路径（因为代码里写死的是相对路径，且当前目录不是他以为的那个）。容器 --rm 退出即清理，三个月训练成果随可写层一起消失。

正确的做法：明确训练脚本的落盘绝对路径（如 /outputs），compose 里把 ./outputs:/outputs 挂好，并在训练入口断言 os.path.exists 该路径可写。事故后他们加了一条 CI 检查：训练结束自动 ls /outputs 确认有 checkpoint 文件，否则构建失败。挂载策略的落地，靠的是"路径对齐 + 落盘校验"，而不是"我以为挂了"。

小结：第二章收束

十五、落地清单：给你的挂载与端口做一次体检

对照下面八条，任一条不满足就可能数据丢失或连不上：

1. 权重/数据集/日志是否都挂到卷，而非写在容器可写层？
2. 只读数据是否标了 :ro 防止训练脚本误删原始数据？
3. Jupyter/TensorBoard 端口是否映射，且服务监听 0.0.0.0？
4. 是否用 compose 固化挂载与端口，而非靠记忆敲 docker run？
5. 挂载目录权限是否会导致宿主机无法访问（避免 root 专属）？
6. 敏感临时数据是否用了 tmpfs 而非落盘？
7. 是否建立了 checkpoint 的保留/清理纪律，防止磁盘写满？
8. 训练结束是否自动校验落盘路径确有产出，而非"我以为存了"？

八条全过，你的数据才算"活着且安全"。挂载策略的本质，是把"容器是临时的"这个事实，用卷隔离掉它对数据的威胁。