Bind mounts: синтаксис, права, macOS-специфика

Bind mount — рабочая лошадка локальной разработки. На нём держится почти весь dev-workflow в контейнерах: редактируешь файл на хосте, контейнер видит изменение мгновенно. Но именно с bind mount связаны самые частые проблемы Junior’ов: «почему у файла owner = root», «почему npm install внутри контейнера пишет в host-папку с правами root», «почему bind на маке такой медленный». Разберём механику.

Два синтаксиса: -v и —mount

Исторически Docker предлагал короткий синтаксис через -v:

docker run -v $(pwd):/app python:3.13-slim
docker run -v /host/path:/container/path:ro alpine

Формат — host:container:options, через двоеточие. Удобно, но неоднозначно: если первая часть не начинается с /, Docker трактует её как имя named volume, а не как host path. Опечатался — получил пустой volume вместо bind.

Современный явный синтаксис — --mount:

docker run \
  --mount type=bind,source=$(pwd),target=/app \
  python:3.13-slim

Параметры через запятую, обязательно type=bind. Длиннее, но никаких сюрпризов. В compose-файлах для bind mount обычно используют именно длинную форму:

services:
  app:
    image: python:3.13-slim
    volumes:
      - type: bind
        source: ./src
        target: /app/src

Опции bind mount

Самый частый случай — read-only:

docker run --rm \
  -v $(pwd)/dags:/opt/airflow/dags:ro \
  apache/airflow:2.10.0 airflow dags list

Airflow видит DAG-папку, но не может туда писать. Это разумный default для production: ETL-код приложение не должно само себя переписывать.

Владелец и права файлов

Здесь начинается самое больное. На Linux при bind mount Docker не меняет UID/GID файлов — что было на хосте, то и видно в контейнере.

Пример:

# На хосте я — UID 1000.
ls -ln /tmp/data
# -rw-r--r-- 1 1000 1000 ... file.txt

docker run --rm -v /tmp/data:/data alpine ls -ln /data
# -rw-r--r-- 1 1000 1000 ... file.txt

Внутри alpine процесс запущен от root (UID 0). Root всё равно может читать и писать. Но если образ запускает процесс от своего пользователя (что правильно для security), могут быть проблемы:

docker run --rm \
  -u 999:999 \
  -v /tmp/data:/data \
  alpine sh -c 'echo hi > /data/new.txt'
# Файл создан, owner = 999:999. Я (UID 1000) на хосте могу его прочитать, но не могу удалить, потому что я не владелец.

Решения:

1. Запустить контейнер с UID хоста: -u $(id -u):$(id -g). Подходит для dev, не подходит для prod-образов с подготовленным user’ом.
2. Chown через entrypoint.sh: скрипт при старте делает chown -R user:user /data и потом переходит на exec gosu user "$@". Стандартный паттерн в Postgres и Airflow.
3. Совпадающий UID в образе и хосте. Build-arg UID=1000, в Dockerfile useradd -u $UID. На Linux совпадает в 90% случаев.

На macOS и Windows bind mount проходит через VM, и Docker Desktop / OrbStack обычно сглаживает UID-конфликты на лету (внутренняя реализация различается). Поэтому Junior, который разрабатывает на маке, не видит проблемы. На Linux-сервере она проявляется сразу.

macOS: почему bind медленный

Docker на macOS — это Linux VM под капотом. Контейнеры работают внутри этой VM. Host path /Users/me/project физически живёт на macOS, контейнерный путь — внутри VM. Чтобы файл с хоста стал виден в VM, нужен механизм проброса:

• Docker Desktop: исторически osxfs (медленный), потом gRPC FUSE (быстрее), сейчас VirtioFS (самый быстрый из этой ветки). Включается в Settings, не везде по умолчанию.
• OrbStack: свой механизм поверх VirtFS, заметно быстрее Docker Desktop.
• Rancher Desktop / Lima: sshfs или 9p, медленнее обоих.
• Mutagen: двунаправленная файловая синхронизация в файловую систему VM (не bind mount). Скорость нативная, но усложняет setup.

Эффект: npm install или pip install в bind-папку на маке может занять 2-5 минут вместо 30 секунд на Linux. Решения:

1. OrbStack. На M-серии маков это первый выбор. VirtFS-mount в OrbStack — самое близкое к нативной скорости, что есть на macOS.

2. Держать node_modules / .venv в named volume. В compose делаем bind для кода и named volume для tяжёлых директорий:

   volumes:
     - ./src:/app/src
     - ./pyproject.toml:/app/pyproject.toml
     - venv:/app/.venv

3. Mutagen / docker-sync. Двунаправленная синхронизация в named volume — даёт скорость VM-FS.

4. :cached-хинт. Исторически Docker Desktop поддерживал :cached (контейнер может видеть устаревшую host-версию короткое время) и :delegated (хост может видеть устаревшую container-версию). После перехода на VirtioFS флаги стали no-op, но всё ещё валидны в синтаксисе.

Когда bind mount — плохая идея

Сценарии, где bind — правильный выбор:

Попробуй сам

# 1. Bind read-only — контейнер не пишет.
mkdir -p /tmp/ro-demo && echo "config" > /tmp/ro-demo/app.conf
docker run --rm \
  --mount type=bind,source=/tmp/ro-demo,target=/etc/app,readonly \
  alpine sh -c 'echo trying >> /etc/app/app.conf'
# -> sh: can't create /etc/app/app.conf: Read-only file system

# 2. UID mismatch (на Linux чувствуется явно).
mkdir -p /tmp/uid-demo
docker run --rm \
  -u 1500:1500 \
  -v /tmp/uid-demo:/data \
  alpine sh -c 'echo "from 1500" > /data/note.txt; ls -ln /data'
# На хосте:
ls -ln /tmp/uid-demo
# Видишь owner = 1500. На macOS Docker сглаживает, на Linux буквально.

# 3. Performance-тест на маке (если ты на маке).
docker run --rm -v $(pwd):/work alpine \
  sh -c 'time find /work -type f | wc -l'
# Сравни время с такой же командой на native-папке.

В следующем уроке — named volumes: lifecycle, backup-стратегия, volume drivers.