┌────────────────────────────────────────────────────────────┐
│  컨테이너 레이어 (읽기/쓰기)                                  │
│  — 컨테이너 실행 중 생성/변경된 파일 저장                      │
│  — 컨테이너 삭제(docker rm) 시 이 레이어도 삭제됨 ← 휘발성!   │
├────────────────────────────────────────────────────────────┤
│  이미지 레이어 4 (읽기 전용)                                  │
├────────────────────────────────────────────────────────────┤
│  이미지 레이어 3 (읽기 전용)                                  │
├────────────────────────────────────────────────────────────┤
│  이미지 레이어 2 (읽기 전용)                                  │
├────────────────────────────────────────────────────────────┤
│  이미지 레이어 1 (읽기 전용)                                  │
└────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│                    컨테이너                               │
│                                                          │
│  /app/data ──────────────────┐                          │
│  /var/lib/mysql ─────────────┤                          │
│  /workspace ─────────────────┘                          │
└──────────────────────┬───────────────────────────────────┘
                       │
         ┌─────────────┼─────────────┐
         ▼             ▼             ▼
    Named Volume   Bind Mount    tmpfs Mount
    (Docker 관리)  (호스트 경로)  (메모리, 임시)
    영속적 저장     개발 환경       민감 정보

  이러면 컨테이너가 삭제되어도 `/home/user/data` 내에 보존된 소스 및 데이터는 영구히 유지됩니다. 만약 좌측에 `/`로 시작하는 절대경로 대신 `my-vol` 같은 단순 명칭을 적으면 Docker는 이를 **Named Volume**으로 인식하여 Docker 전용 격리 공간(`/var/lib/docker/volumes/`)에 할당합니다.


| 항목 | Named Volume | Bind Mount |
|------|-------------|-----------|
| 데이터 위치 | Docker가 관리 | 호스트 임의 경로 |
| 이식성 | 높음 | 낮음 (호스트 의존) |
| 초기 데이터 | 이미지 기본값 채움 | 호스트 파일 그대로 |
| 백업 | docker volume + tar | 일반 파일 백업 |
| 주용도 | DB, 영구 데이터 | 개발 소스코드 |
| 성능 | 좋음 | 좋음 (Linux) / 느림 (macOS/Windows) |

</ConceptBlock>

---

<ConceptBlock title="Named Volume 상세 — 생성, 마운트, 관리">

`docker-compose down`을 실행했더니 MySQL 데이터가 모두 사라졌습니다. compose 파일에서 볼륨을 Named Volume이 아닌 익명 볼륨으로 설정했기 때문입니다. Named Volume은 이름으로 관리되기 때문에 컨테이너가 삭제되어도 데이터가 남고, 동일한 이름으로 새 컨테이너를 연결하면 그대로 이어집니다. 프로덕션에서 DB 컨테이너를 업그레이드하거나 재시작할 때 데이터를 유지하는 표준 방법입니다. 또한 Named Volume은 Docker가 내부에서 권한과 경로를 관리하기 때문에 Bind Mount처럼 UID/GID 문제가 자주 발생하지 않습니다. 이 ConceptBlock에서는 Named Volume 생성부터 마운트, 백업, 삭제까지 전체 생명주기를 다룹니다.

![Named Volume 상세 — 생성, 마운트, 컨테이너 교체 시 데이터 유지](/images/docker/volumes/named-volume-detail.png)

## Named Volume 전체 워크플로우

### 볼륨 생성

```bash
# 명시적 볼륨 생성
docker volume create mysql-data
docker volume create --driver local --name app-uploads

# 볼륨 목록 확인
docker volume ls
# DRIVER    VOLUME NAME
# local     mysql-data
# local     app-uploads

# 볼륨 상세 정보
docker volume inspect mysql-data

[
  {
    "CreatedAt": "2024-01-15T10:30:00Z",
    "Driver": "local",
    "Labels": {},
    "Mountpoint": "/var/lib/docker/volumes/mysql-data/_data",
    "Name": "mysql-data",
    "Options": {},
    "Scope": "local"
  }
]

# 형식 1: -v 플래그
docker run -d \
  -v mysql-data:/var/lib/mysql \
  -e MYSQL_ROOT_PASSWORD=secret \
  --name mysql-server \
  mysql:8.0

# 형식 2: --mount 플래그 (더 명시적, 권장)
docker run -d \
  --mount type=volume,source=mysql-data,target=/var/lib/mysql \
  -e MYSQL_ROOT_PASSWORD=secret \
  --name mysql-server \
  mysql:8.0

# 읽기 전용 마운트
docker run -d \
  --mount type=volume,source=config-data,target=/app/config,readonly \
  myapp

# 볼륨 마운트 확인
docker inspect mysql-server --format '{{json .Mounts}}'

# MySQL 이미지의 경우
# /var/lib/mysql 디렉토리에 초기 MySQL 파일들이 있음
# Named Volume 첫 마운트 시 이 파일들이 볼륨에 복사됨

# Bind Mount라면 빈 호스트 디렉토리가 그대로 마운트되어
# MySQL 초기화 파일들이 없어 문제 발생

# 사용하지 않는 볼륨 삭제 (컨테이너와 연결 안 된 것)

# 특정 볼륨 삭제
docker volume rm mysql-data

# 여러 볼륨 삭제
docker volume rm vol1 vol2 vol3

# 컨테이너 삭제 시 연결된 볼륨도 함께 삭제
docker rm -v mysql-server

# 볼륨 내용 확인 (임시 컨테이너 활용)
docker run --rm \
  -v mysql-data:/data \
  alpine:3.18 \
  ls -la /data/

# 볼륨 백업 (tar 아카이브)
docker run --rm \
  -v mysql-data:/source \
  -v $(pwd):/backup \
  alpine:3.18 \
  tar czf /backup/mysql-data-backup.tar.gz -C /source .

# 볼륨 복원
docker volume create mysql-data-restored
docker run --rm \
  -v mysql-data-restored:/target \
  -v $(pwd):/backup \
  alpine:3.18 \
  tar xzf /backup/mysql-data-backup.tar.gz -C /target

# 다른 서버로 볼륨 이전
scp mysql-data-backup.tar.gz user@newserver:/tmp/
# 새 서버에서
docker volume create mysql-data
docker run --rm \
  -v mysql-data:/target \
  -v /tmp:/backup \
  alpine:3.18 \
  tar xzf /backup/mysql-data-backup.tar.gz -C /target

# uploads 볼륨을 앱 서버와 nginx가 공유
docker run -d --name app \
  -v uploads:/app/uploads \
  myapp:latest

docker run -d --name nginx \
  -v uploads:/usr/share/nginx/html/uploads:ro \  # ro = 읽기 전용
  -p 80:80 \
  nginx:alpine

# 1. 초기 데이터 볼륨에 주입 (busybox 임시 컨테이너 사용)
docker run --rm \
  -v myapp-config:/config \
  busybox sh -c "
    echo 'LOG_LEVEL=info' > /config/app.conf
    echo 'MAX_CONN=100'  >> /config/app.conf
    echo 'TIMEOUT=30'    >> /config/app.conf
  "

# 2. 앱 컨테이너가 해당 볼륨 사용
docker run -d \
  --name myapp \
  -v myapp-config:/etc/myapp:ro \
  myapp:latest

# postgres:16 예시
# /var/lib/postgresql/data 에 빈 Named Volume 마운트 시
# → Docker가 자동으로 PostgreSQL 초기화 파일을 볼륨으로 복사

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

# 로그에서 초기화 확인
docker logs postgres
# PostgreSQL init process complete; ready for start up.

# 이미 데이터가 있는 볼륨은 재사용 (초기화 안 함)
docker stop postgres && docker rm postgres
docker run -d \
  --name postgres-new \
  -v postgres-data:/var/lib/postgresql/data \   # 기존 볼륨 재사용
  -e POSTGRES_PASSWORD=newsecret \
  postgres:16-alpine
# 기존 데이터 그대로 유지됨 (패스워드 변경도 안 됨)

# 볼륨 백업: 볼륨 + 현재 디렉토리 동시에 마운트
docker run --rm \
  -v mysql-data:/data \
  -v $(pwd):/backup \
  busybox \
  tar czf /backup/mysql-data-$(date +%Y%m%d-%H%M%S).tar.gz -C /data .

# 결과: 현재 디렉토리에 mysql-data-20260405-103045.tar.gz 생성
ls -lh mysql-data-*.tar.gz
# -rw-r--r-- 1 root root 45M Apr 5 10:30 mysql-data-20260405-103045.tar.gz

# 새 볼륨 생성 후 복구
docker volume create mysql-data-restored

docker run --rm \
  -v mysql-data-restored:/data \
  -v $(pwd):/backup \
  busybox \
  tar xzf /backup/mysql-data-20260405-103045.tar.gz -C /data

# 복구된 볼륨으로 컨테이너 실행
docker run -d \
  --name mysql-restored \
  -v mysql-data-restored:/var/lib/mysql \
  mysql:8

# 1. 원본 서버에서 백업
docker run --rm \
  -v app-data:/data \
  -v $(pwd):/backup \
  busybox tar czf /backup/app-data.tar.gz -C /data .

# 2. 백업 파일을 새 서버로 전송
scp app-data.tar.gz user@new-server:/tmp/

# 3. 새 서버에서 볼륨 생성 + 복구
ssh user@new-server "
  docker volume create app-data
  docker run --rm \
    -v app-data:/data \
    -v /tmp:/backup \
    busybox tar xzf /backup/app-data.tar.gz -C /data
"

# ❌ 주의: 데이터베이스 컨테이너 실행 중 파일 직접 백업은 일관성 보장 안 됨
# 쓰기 중인 파일을 tar로 복사하면 손상된 백업이 될 수 있음

# ✅ 올바른 방법: DB 덤프 명령어 사용
# PostgreSQL
docker exec postgres pg_dumpall -U postgres > backup.sql

# MySQL
docker exec mysql mysqldump -uroot -psecret --all-databases > backup.sql

# 덤프 파일을 볼륨에 저장하거나 외부로 전송