Docker Storage

Docker Storage — 存储与数据持久化

Comprehensive guidance for managing persistent data in Docker.

When to Use

ALWAYS use this skill when the user mentions:

• "docker volume", "数据卷", "数据持久化"
• "bind mount", "tmpfs"
• "容器数据怎么保存", "数据不丢失"
• "数据库容器怎么持久化"
• "备份恢复", "存储驱动"

Storage Type Comparison

Visual Comparison

Volume:                       Bind Mount:               Tmpfs:
  Container                     Container                 Container
     │                              │                        │
  Docker-managed               /host/path                 Memory only
  /var/lib/docker/volumes/        ↕                     (no disk)
     ↕                         Container sees:              ↕
  Container sees:              /container/path           Container sees:
  /data                         = host files              /tmp (in RAM)

Volume Management

# Create & inspect
docker volume create mydata
docker volume ls
docker volume inspect mydata

# Use in container
docker run -v mydata:/var/lib/mysql mysql:8
docker run --mount source=mydata,target=/var/lib/mysql mysql:8  # explicit syntax (recommended)

# Cleanup
docker volume prune      # Remove unused volumes
docker volume rm mydata  # Remove specific volume

Named vs Anonymous Volumes

-v mydata:/data      → Named volume  (mydata) — survives container removal ✅
-v /data             → Anonymous volume — hard to identify later ❌

Bind Mount

# Read-write bind mount
docker run -v $(pwd)/app:/app nginx

# Read-only (protect host files)
docker run -v $(pwd)/config:/etc/nginx:ro nginx

# Explicit syntax
docker run --mount type=bind,source=$(pwd)/app,target=/app nginx

Tmpfs (Memory)

# Ephemeral data, never touches disk
docker run --tmpfs /tmp:rw,noexec,nosuid,size=64m nginx
docker run --mount type=tmpfs,destination=/tmp,tmpfs-size=64m nginx

Database Persistence Patterns

PostgreSQL

docker volume create pgdata
docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=secret \
  -v pgdata:/var/lib/postgresql/data \
  -p 5432:5432 \
  postgres:16-alpine

MySQL

docker volume create mysqldata
docker run -d \
  --name mysql \
  -e MYSQL_ROOT_PASSWORD=secret \
  -v mysqldata:/var/lib/mysql \
  -v $(pwd)/my.cnf:/etc/mysql/conf.d/my.cnf:ro \
  -p 3306:3306 \
  mysql:8.4

Redis (Persistence)

docker volume create redisdata
docker run -d \
  --name redis \
  -v redisdata:/data \
  -p 6379:6379 \
  redis:7-alpine redis-server --appendonly yes

Backup & Restore

# Backup (using a temporary container)
docker run --rm \
  -v mysqldata:/source \
  -v $(pwd):/backup \
  alpine tar czf /backup/mysqldata-backup.tar.gz -C /source .

# Restore
docker run --rm \
  -v mysqldata:/target \
  -v $(pwd):/backup \
  alpine tar xzf /backup/mysqldata-backup.tar.gz -C /target

Storage Drivers

docker info | grep "Storage Driver"  # Check current

Workflow — 推荐配置流程

Step 1: 确定存储类型: 持久化数据 → Volume；开发热加载 → Bind Mount；临时缓存 → tmpfs Step 2: 创建 Volume: docker volume create db_data Step 3: 挂载到容器: docker run -v db_data:/var/lib/mysql mysql Step 4: 验证: docker volume inspect db_data + docker exec mysql ls /var/lib/mysql Step 5: 备份: docker run --rm -v db_data:/source -v $(pwd):/backup alpine tar czf /backup/db.tar.gz -C /source .

Gotchas — Common Pitfalls

• Anonymous volumes accumulate: Every -v /data (no name) creates a new anonymous volume. → Recovery: docker volume prune cleans all unused; use named volumes: -v mydata:/data.
• Bind mount paths: Must be absolute. → Recovery: -v $(pwd)/app:/app for docker run; -v ./app:/app works in Compose only.
• Permission issues with bind mounts: Container UID != host UID → permission denied. → Recovery: --user $(id -u):$(id -g) or RUN chown 1000:1000 /data in Dockerfile entrypoint.
• Data loss on container removal: Without -v, data is lost when container is removed. --rm flag even worse. → Recovery: Always use named volumes: docker run -v db_data:/var/lib/mysql.
• macOS bind mount performance: Bind mounts on Docker Desktop Mac are slow. → Recovery: Use :cached or :delegated mount options, or named volumes for better I/O.

Boundary — 能力边界（适用与不适用场景）

When NOT to Use This Skill

Security & Stability

• Use :ro for config files that containers should not modify.
• Never bind mount Docker socket (/var/run/docker.sock) without understanding the security implications.
• Backup volumes regularly, especially database volumes.
• No executable scripts bundled. Guidance only.

📚 官方文档参考

🧭 Docker Skills Journey

📍 You are here: `docker-storage` — 数据持久化

← Previous: docker-run / docker-networking → Next: docker-compose / docker-security

FAQ

Q1: 如何快速上手此技能？ A: 参考上方的快速开始章节，按步骤操作即可。

Q2: 遇到版本不兼容问题怎么办？ A: 检查依赖版本，使用 lock 文件锁定，参考常见陷阱章节。

Q3: 如何在生产环境使用？ A: 参考最佳实践章节，确保配置正确，做好监控和日志。

Q4: 性能如何优化？ A: 参考性能优化相关文档，使用缓存、索引等手段。

Q5: 如何贡献或反馈问题？ A: 在 GitHub 仓库提交 Issue 或 Pull Request。

Q6: 是否支持中文？ A: 支持中文文档和中文注释，详见国内适配章节。

Using volumes to persist MySQL data

# 1. Create a named volume
docker volume create mysql-data

# 2. Run MySQL with the volume mounted
docker run -d --name mysql \
  -e MYSQL_ROOT_PASSWORD=secret123 \
  -v mysql-data:/var/lib/mysql \
  -p 3306:3306 \
  mysql:8.4

# 3. Verify data persists
docker exec mysql mysql -uroot -psecret123 -e "CREATE DATABASE testdb;"
docker stop mysql
docker rm mysql
docker run -d --name mysql-new -v mysql-data:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=secret123 -p 3306:3306 mysql:8.4
docker exec mysql-new mysql -uroot -psecret123 -e "SHOW DATABASES;"
# testdb still exists! ✅

Backup and restore a Docker volume

# === BACKUP ===
# Create a temporary alpine container that mounts:
# - the source volume at /source
# - the current directory at /backup
docker run --rm \
  -v mysql-data:/source:ro \
  -v $(pwd):/backup \
  alpine tar czf /backup/mysql-data-$(date +%Y%m%d).tar.gz -C /source .

# === RESTORE ===
# 1. Create a new (or ensure existing) volume
docker volume create mysql-data-restored

# 2. Restore from backup
docker run --rm \
  -v mysql-data-restored:/target \
  -v $(pwd):/backup \
  alpine tar xzf /backup/mysql-data-20250101.tar.gz -C /target

# 3. Verify: start a container using the restored volume
docker run --rm -v mysql-data-restored:/var/lib/mysql alpine ls /var/lib/mysql

Automate with a backup script

#!/bin/bash
# backup-volume.sh — Backup a Docker volume to a timestamped tar.gz
VOLUME=${1:?Usage: $0 <volume-name>}
BACKUP_DIR=${2:-./backups}
mkdir -p "$BACKUP_DIR"
docker run --rm \
  -v "$VOLUME":/source:ro \
  -v "$(cd "$BACKUP_DIR" && pwd)":/backup \
  alpine tar czf "/backup/${VOLUME}-$(date +%Y%m%d-%H%M%S).tar.gz" -C /source .
echo "Backed up $VOLUME to $BACKUP_DIR"

Volume types: when to use what

Decision Flow

Does the data need to outlive the container?
├── NO → Tmpfs (RAM only, never touches disk)
└── YES → Does Docker need to manage it?
    ├── YES → Named Volume (production data, managed lifecycle)
    └── NO → Bind Mount (your filesystem path)
        └── Is it mutable?
            ├── NO → Read-only bind mount (:ro)
            └── YES → Read-write bind mount

Volume 管理全命令

基本操作

docker volume create myvolume
docker volume ls
docker volume inspect myvolume
docker volume rm myvolume
docker volume prune     # 删除所有未使用的 volume

挂载到容器

# 命名卷
docker run -d -v myvolume:/data alpine

# bind mount（绝对路径）
docker run -d -v /host/path:/container/path:ro alpine

# bind mount（相对路径，需 --mount）
docker run -d --mount type=bind,src=./data,target=/data alpine

# tmpfs
docker run -d --tmpfs /tmp:rw,size=128M alpine

备份与恢复

# 备份
docker run --rm \
  -v db_data:/source \
  -v $(pwd):/backup \
  alpine tar czf /backup/db_data_backup.tar.gz -C /source .

# 恢复
docker run --rm \
  -v db_data:/target \
  -v $(pwd):/backup \
  alpine tar xzf /backup/db_data_backup.tar.gz -C /target

迁移 Volume

# 从旧主机导出
docker run --rm -v old_data:/data alpine tar czf - -C /data . > data.tar.gz

# 传输到新主机
scp data.tar.gz new-host:

# 在新主机导入
docker volume create new_data
docker run --rm -v new_data:/data -v $(pwd):/backup alpine \
  tar xzf /backup/data.tar.gz -C /data

查看 Volume 占用

docker system df -v      # 含 volume 详情
docker volume ls -q | xargs docker volume inspect --format '{{.Name}}: {{.Mountpoint}}'

NFS Volume 驱动

docker volume create \
  --driver local \
  --opt type=nfs \
  --opt o=addr=192.168.1.100,nolock,rw \
  --opt device=:/exports/data \
  nfs_data

存储驱动对比与选型

驱动总览

推荐：overlay2

# 检查当前驱动
docker info | grep "Storage Driver"
# Storage Driver: overlay2

# 检查 overlay 支持
lsmod | grep overlay
grep overlay /proc/filesystems

决策树

使用 Linux 4.x+？
├── 是 → overlay2（默认、推荐）
│
└── 否 → 升级内核。

使用 btrfs/zfs 作为宿主机文件系统？
├── btrfs → btrfs 驱动（快照优势）
└── zfs → zfs 驱动（快照+压缩优势）

Rootless 模式？
└── fuse-overlayfs（非特权 overlay）

性能对比（定性）

磁盘空间管理

docker system df         # 汇总
docker system df -v      # 详细
docker system prune -a   # 清理（慎用！删除所有未运行镜像和未使用卷）
docker image prune       # 清理 dangling 镜像
docker volume prune      # 清理未使用卷