Docker Nextcloud 데이터 저장 경로 확인 방법
Docker 컨테이너 내 Nextcloud 데이터 디렉토리와 호스트 볼륨 매핑 경로를 찾는 방법을 설명합니다. 사용자 파일 외에 백업 시 반드시 포함해야 할 설정 파일과 데이터베이스 위치를 확인하여 데이터 유실을 방지하는 구체적인 가이드를 제공합니다.
Docker에서 Nextcloud가 파일을 저장하는 위치
Docker의 Nextcloud는 컨테이너 내부의 데이터 디렉터리에 파일을 저장하며, 서버에서 실제 위치는 연결한 volume 또는 bind mount에 따라 달라진다. linuxserver.io 이미지에서는 lscr.io/linuxserver/nextcloud, 사용자 파일이 /data에 저장되고, config.php, 앱과 테마는 /config 아래에 저장된다. 이 두 경로는 모두 컨테이너 경로다. 한 명령으로 이 경로에 해당하는 호스트 경로를 출력할 수 있으며, 이 가이드의 나머지 부분에서는 질문의 더 어려운 부분인 데이터 디렉터리에 저장되지 않는 모든 항목을 다룬다.
이미지 태그를 고정해야 한다. 경로는 Nextcloud가 아니라 이미지에 속하며, floating tag는 예고 없이 변경될 수 있다. 2026년 11월 20일 기준 현재 안정 이미지 릴리스는 35.0.3-ls3이며, Nextcloud 35.0.3을 포함한다. 이는 Nextcloud 35 메이저 버전의 네 번째 릴리스다. 이미지는 한 번에 하나의 메이저 버전만 업그레이드하므로, 여전히 34.x를 사용하는 스택은 한 단계로 35로 이동하며, 이 단계에서는 먼저 백업을 고려할 만하다.
services:
nextcloud:
image: lscr.io/linuxserver/nextcloud:35.0.3-ls3
container_name: nextcloud
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
volumes:
- nextcloud_config:/config
- nextcloud_data:/data
ports:
- 443:443
restart: unless-stopped
nextcloud-db:
image: mariadb:11.8
container_name: nextcloud-db
environment:
- MARIADB_ROOT_PASSWORD=${MARIADB_ROOT_PASSWORD}
- MARIADB_DATABASE=nextcloud
- MARIADB_USER=nextcloud
- MARIADB_PASSWORD=${NEXTCLOUD_DB_PASSWORD}
volumes:
- nextcloud_db:/var/lib/mysql
restart: unless-stopped
volumes:
nextcloud_config:
nextcloud_data:
nextcloud_db:두 비밀번호는 compose 파일 옆의 .env 파일에서 가져오므로 compose 파일 자체에는 저장되지 않는다. 따라서 답에 해당하는 volume은 3개이며, 그중 사용자 파일을 저장하는 것은 1개뿐이다.
이러한 컨테이너 경로는 해당 이미지 하나의 문서에서 가져온 것이다. 다른 Nextcloud 이미지는 파일 시스템을 다르게 구성하고 자체 웹 루트 아래에 설치를 보관하므로, 포럼 게시물에서 복사한 경로는 추측에 불과하다. 실행 중인 컨테이너에서 실제 경로를 확인해야 한다.
docker inspect nextcloud출력의 Mounts 섹션에는 모든 mount가 나열되며, Source은 호스트 측 경로이고 Destination은 컨테이너 측 경로다. 어떤 이미지를 선택했든 이 목록으로 해당 설정의 답을 확인할 수 있다.
볼륨 뒤의 실제 호스트 경로를 어떻게 확인합니까?
named volume은 Docker가 관리하므로 경로를 직접 지정하지 않습니다. Docker에 경로를 요청해야 합니다.
docker volume ls
docker volume inspect nextcloud_nextcloud_data이름이 중요합니다. Docker Compose는 volume 이름 앞에 프로젝트 이름을 붙입니다. 프로젝트 이름의 기본값은 compose 파일이 있는 디렉터리 이름입니다. 따라서 파일에 nextcloud_data로 작성한 volume은 일반적으로 디스크에서 nextcloud_nextcloud_data으로 존재합니다. docker volume ls은 실제 이름을 표시합니다. inspect 출력은 다음과 같습니다. 일부 내용은 생략했습니다.
[
{
"CreatedAt": "2026-08-18T09:12:44Z",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/nextcloud_nextcloud_data/_data",
"Name": "nextcloud_nextcloud_data",
"Scope": "local"
}
]Mountpoint이 답입니다. 경로가 변경될 수 있으므로 추측하지 말고 명령에서 확인해야 합니다. rootless Docker에서는 기본적으로 전체 Docker 데이터 루트가 daemon을 실행하는 사용자의 home directory 안에 있습니다. 따라서 해당 경로는 다른 위치에서 시작합니다.
bind mount를 사용하면 이 질문이 필요하지 않습니다. compose 파일에 - /srv/nextcloud/data:/data을 작성하면 호스트 경로는 입력한 경로가 됩니다. docker inspect은 이를 Source로 표시합니다. 선택에 따라 경로만 달라지는 것은 아닙니다. named volume과 bind mount는 ownership과 백업을 다르게 처리합니다.
데이터 디렉터리가 백업이 아닌 이유
Nextcloud 매뉴얼에는 백업에서 보존해야 하는 항목이 5가지로 나와 있습니다. config 폴더, custom apps 폴더, data 폴더, theme 폴더, 데이터베이스입니다. 이 이미지에서는 config, apps, theme 폴더가 모두 /config 아래에 있고, 데이터베이스는 자체 volume을 사용하는 별도 컨테이너에서 실행됩니다. /data만 복사하면 문제에서 가장 중요하지 않은 부분만 저장한 셈입니다.
데이터베이스가 중요한 이유는 웹 인터페이스가 디렉터리의 파일을 직접 나열하지 않기 때문입니다. 웹 인터페이스는 file cache의 행을 나열합니다. 따라서 매뉴얼에서는 data 디렉터리에 파일을 수동으로 복사한 뒤 scan을 실행하라고 안내합니다. 빈 데이터베이스 옆에 /data을 복원하면 인덱스가 없는 바이트만 남습니다. 사용자도, 공유도, 파일 목록도 없습니다. 반대로 빈 /data 옆에 데이터베이스를 복원하면 모든 행이 이미 사라진 파일을 가리킵니다.
config.php에는 데이터베이스 자격 증명과 trusted domains가 저장됩니다. instance id도 저장되며, 이 값 앞에 appdata_을 붙여 app data 폴더의 이름을 구성합니다. 어느 값을 기억에 의존하지 말고 실행 중인 인스턴스에서 직접 확인해야 합니다.
docker exec -it nextcloud occ config:system:get datadirectory
docker exec -it nextcloud occ config:system:get instanceid첫 번째 명령은 이 인스턴스가 실제로 사용하는 data 디렉터리를 출력합니다. 여기서는 /data입니다. 이 이미지는 PATH에 occ wrapper를 포함하므로 docker exec를 통해 바로 실행하면 됩니다. 컨테이너 외부 설치를 전제로 작성된 Nextcloud 매뉴얼의 더 긴 sudo 및 php occ 형식은 복사하지 마십시오.
데이터 볼륨을 조용히 채우는 것은 무엇인가?
미리 보기와 사용자별 기록은 파일과 동일한 볼륨에 저장되며, 웹 인터페이스에서 사용자가 보는 저장 공간 수치에는 둘 다 포함되지 않는다.
- 미리 보기는 생성된 축소 이미지다. 데이터 디렉터리 안의 앱 데이터 폴더에 저장되며,
appdata_뒤에 인스턴스 ID가 붙은 이름을 사용한다. - 삭제된 파일은 휴지통에 남는다.
trashbin_retention_obligation의 기본값은auto이다. 따라서 공간이 있으면 삭제된 파일이 30일을 초과해 남을 수 있고, 공간이 필요하면 30일이 되기 전에 삭제될 수도 있다. 삭제된 파일은 사용자의 일반 quota에는 포함되지 않지만, 휴지통에는 자체 제한이 있다. 기본적으로 사용자가 남겨 둔 quota 공간의 최대 50%까지 사용하며, quota가 없는 사용자의 경우에는 디스크 여유 공간을 사용한다. 휴지통이 이 제한을 초과하면 Nextcloud는 삭제 가능한 항목 중 오래된 것부터 제거한다. 여기에는auto에 따라 30일이 지나지 않은 항목도 포함된다. - 이전 버전도 남는다.
versions_retention_obligation의 기본값도auto이다. 이 설정은 시간이 지나면서 버전 수를 줄이고 각 시간 구간에서 최신 버전을 하나씩 유지한다. 최대 보존 기간을 설정하면 백그라운드 작업이 해당 기간을 지난 버전이나 파일이 더 이상 존재하지 않는 버전을 삭제한다. quota가 있는 계정에서는 Versions 앱이 사용자가 현재 남겨 둔 quota 공간의 50%를 목표로 한다. quota가 없으면 파일 시스템의 여유 공간을 직접 사용한다. 공간을 확보해야 할 때는 최신 버전 2개 이상을 유지하면서 가장 오래된 버전부터 삭제하므로, 이 목표는 엄격한 상한이 아니다. 사용자가 직접 이름을 지정한 버전은 자동 만료 대상에서 제외된다. 그러나 사용자는 해당 버전을 직접 삭제할 수 있으며,occ versions:cleanup은 이름이 지정된 버전도 다른 버전과 함께 제거한다.
삭제하기 전에 먼저 측정한다.
docker exec -it nextcloud sh -c 'du -sh /data/*'
docker exec -it nextcloud sh -c 'du -sh /data/appdata_*'첫 번째 줄에는 각 사용자 폴더와 앱 데이터 폴더의 수치가 하나씩 표시된다. 앱 데이터 수치가 크면 해당 폴더의 preview 하위 디렉터리를 확인한다. 앱 데이터에는 아바타와 캐시된 자산도 저장된다. 아래의 정리 명령은 문서화된 명령이며, 모든 명령은 의도적으로 데이터를 삭제한다.
docker exec -it nextcloud occ trashbin:cleanup --all-users
docker exec -it nextcloud occ versions:cleanup alice
docker exec -it nextcloud occ preview:cleanuppreview:cleanup은 생성된 미리 보기를 모두 삭제한다. 사용자가 해당 파일을 열면 Nextcloud가 미리 보기를 다시 생성하므로 공간은 점차 다시 사용되고 CPU도 추가로 사용된다. 볼륨 문제가 더 큰 디스크 문제의 일부라면 오래된 이미지와 남은 build cache가 대개 다른 원인이다.
호스트에 복사한 파일이 Nextcloud에 표시되지 않는 이유는 무엇인가?
Nextcloud는 디렉터리가 아니라 데이터베이스의 파일 캐시를 읽기 때문이다. 파일을 직접 복사하면 디스크에는 파일이 생성되지만 이에 대응하는 행은 생성되지 않는다. 따라서 웹 인터페이스에 표시할 항목이 없다. 매뉴얼에서도 이 경우를 정확히 설명한다. 데이터 디렉터리에 파일을 직접 복사한 뒤에는 스캔이 필요하다.
docker exec -it nextcloud occ files:scan --path="/alice/files/Photos"
docker exec -it nextcloud occ files:scan --all --unscanned -v
docker exec -it nextcloud occ files:scan --all--path 인수는 데이터 디렉터리 내부의 구조도 보여 준다. 각 사용자는 사용자 이름으로 된 폴더를 가지며, 그 안의 files에는 웹 인터페이스에 표시되는 파일이 저장된다. 파일이 저장된 위치를 알고 있다면 해당 경로 하나만 스캔한다. --all은 모든 사용자를 순회하므로 인스턴스가 크면 시간이 오래 걸린다. --unscanned는 아직 완전히 스캔되지 않은 것으로 표시된 파일만 처리한다. -v은 처리 중인 각 파일을 출력한다. 따라서 명령이 멈춘 것처럼 보이는 경우와 진행 상황을 확인할 수 있는 경우의 차이가 생긴다.
소유권에 따라 스캔만으로 충분한지가 결정된다. 컨테이너 사용자가 쓸 수 없는 파일은 인덱싱되더라도 이동할 수 없다. 따라서 목록은 올바르게 표시되지만 웹 인터페이스에서 이름 변경이나 삭제를 수행하면 실패한다.
PUID와 PGID를 설정한 뒤 쓰기 작업이 실패하는 이유는 무엇입니까?
커널은 이름이 아닌 숫자를 비교하기 때문입니다. PUID와 PGID는 컨테이너 프로세스가 실행될 때 사용할 숫자 형태의 사용자 ID(uid)와 그룹 ID(gid)를 결정합니다. 호스트의 모든 파일 역시 숫자 형태의 소유자를 가집니다. 두 숫자가 일치하지 않으면, 양쪽에서 이름이 어떻게 보이든 상관없이 쓰기 작업이 거부됩니다.
docker exec -it nextcloud id abc
sudo ls -ln /var/lib/docker/volumes/nextcloud_nextcloud_data/_dataid abc는 컨테이너가 실제로 사용 중인 uid와 gid를 출력하며, 이는 설정한 PUID 및 PGID와 같습니다. ls -ln은 숫자 형태의 소유자를 출력하며, 이때 -n 옵션이 중요합니다. 일반적인 ls -l는 해당 숫자들을 호스트의 사용자 목록을 통해 변환하여 보여주는데, 이는 컨테이너 내부에서는 아무런 의미가 없는 이름일 수 있습니다. 두 숫자를 비교하십시오.
그다음 추측하지 말고 쓰기 작업을 직접 테스트하십시오.
docker exec -u abc -it nextcloud touch /data/writetestPermission denied에 /data가 포함된 메시지가 출력되면 확인된 것입니다. 컨테이너 내부에서 소유권 문제를 해결한 뒤, 동일한 테스트를 다시 실행하십시오.
docker exec -u 0 -it nextcloud chown -R abc:abc /data
docker exec -u abc -it nextcloud touch /data/writetest
docker exec -u abc -it nextcloud rm /data/writetest컨테이너 내부에서 작업하는 데에는 이유가 있습니다. rootless Docker 환경에서는 컨테이너의 사용자 ID가 /etc/subuid에 정의된 하위 범위(subordinate range)를 통해 매핑되므로, 컨테이너 내부의 uid 1000은 호스트에서는 훨씬 더 큰 uid에 해당합니다. 따라서 호스트 측에서 chown 1000:1000을 실행하면 컨테이너가 사용할 수 없는 소유자가 설정되어 쓰기 작업이 여전히 실패하게 됩니다. 컨테이너 내부에서 chown을 실행하면 Nextcloud 프로세스가 사용하는 것과 동일한 매핑 과정을 거치므로, 숫자가 구조적으로 일치하게 됩니다. 이것이 바로 다른 문제를 디버깅하기 전에 PUID와 PGID가 디스크상의 소유자와 일치해야 하는 이유입니다.
실제로 복원할 수 있도록 백업하려면 어떻게 해야 합니까?
데이터베이스와 디렉터리를 같은 시점에 백업합니다. 유지 관리 모드를 활성화하면 로그인이 중지되므로, dump와 복사 사이에 업로드가 저장되지 않습니다.
docker exec -it nextcloud occ maintenance:mode --on
docker exec nextcloud-db mariadb-dump --single-transaction -u nextcloud -p"$NEXTCLOUD_DB_PASSWORD" nextcloud > nextcloud-sqlbkp.sql
docker run --rm -v nextcloud_nextcloud_data:/data:ro -v "$PWD":/backup alpine:3.22 tar czf /backup/nextcloud-data.tgz -C /data .
docker run --rm -v nextcloud_nextcloud_config:/config:ro -v "$PWD":/backup alpine:3.22 tar czf /backup/nextcloud-config.tgz -C /config .
docker exec -it nextcloud occ maintenance:mode --offdump 명령에 없는 항목을 확인합니다. -t flag가 없습니다. TTY는 줄바꿈을 다시 작성합니다. TTY를 거친 SQL dump는 복원할 때까지 발견하기 어려운 방식으로 손상됩니다. 명령줄에 password를 입력하면 명령이 실행되는 동안 ps 출력에 표시된다는 점도 확인해야 합니다. .env 파일에서 password를 읽어 shell에 전달하면 shell history에 직접 입력하지 않아도 되지만, 확장된 명령줄 인수가 숨겨지는 것은 아닙니다. 이전 database image는 mariadb-dump 대신 mysqldump를 제공하며, manual에는 두 항목이 모두 설명되어 있습니다.
복원하려면 빈 database에 dump를 불러오고, 두 archive를 새 volume에 각각 압축 해제한 다음, container를 시작하고 유지 관리 모드를 비활성화합니다. 디렉터리와 dump가 서로 다른 시점에 생성되었다면 file cache와 disk의 내용이 일치하지 않습니다. occ files:scan --all는 이 문제를 한 방향으로만 수정합니다. row 없이 존재하는 파일은 찾을 수 있습니다. row가 가리키는 파일이 삭제된 경우에는 복구할 수 없습니다.
결과물은 서버 외부에 보관합니다. 같은 VPS 내부에 있는 복사본은 VPS와 함께 손실됩니다. 따라서 서버 외부 repository로 restic 사용을 이 절차에 포함해야 합니다. provider snapshot은 backup과 다른 도구라는 점도 기억해야 합니다. 아직 stack을 구축하는 중이라면 VPS에 Nextcloud 전체 설치에서 이 안내서가 다루지 않는 reverse proxy와 TLS (transport layer security) certificate 설정을 설명합니다.
FAQ
Nextcloud 데이터 디렉터리는 Docker 컨테이너에서 어디에 있습니까?
linuxserver.io 이미지에서는 컨테이너 내부의 /data에 있으며, config.php, 앱과 테마는 /config 아래에 있습니다. 이는 컨테이너 경로입니다. 호스트 경로는 docker inspect nextcloud을 실행하고 Mounts 섹션에서 Source 값을 확인하거나, 볼륨에서 docker volume inspect을 실행한 뒤 Mountpoint를 확인합니다. 다른 Nextcloud 이미지는 컨테이너 경로가 다르므로 고정한 tag의 문서를 확인하고 docker exec -it nextcloud occ config:system:get datadirectory로 검증합니다.
볼륨에 복사한 파일이 Nextcloud에 표시되지 않는 이유는 무엇입니까?
Nextcloud는 디렉터리를 직접 읽지 않고 데이터베이스의 파일 캐시에서 항목을 표시합니다. 따라서 Nextcloud를 거치지 않고 추가된 파일에는 해당 항목이 없으므로 표시되지 않습니다. 한 폴더에 대해서는 docker exec -it nextcloud occ files:scan --path="/alice/files/Photos"을 실행하고, 모든 사용자에 대해서는 occ files:scan --all을 실행합니다. 파일이 표시되지만 이동하거나 삭제할 수 없다면 원인은 소유권입니다. 컨테이너 사용자가 해당 파일에 쓸 수 있어야 합니다.
데이터 볼륨 사본만으로 Nextcloud를 복원할 수 있습니까?
아니요. 데이터 볼륨에는 파일 내용이 저장됩니다. 데이터베이스에는 파일 인덱스와 사용자 및 공유 정보가 저장되며, config.php에는 데이터베이스 자격 증명과 인스턴스 ID가 저장됩니다. 정상적으로 복원하려면 데이터 폴더, config 폴더, 데이터베이스, 그리고 사용하는 경우 사용자 지정 앱 및 테마 폴더가 필요합니다. 모두 같은 시점에 가져와야 합니다. 데이터베이스가 파일보다 최신이면 존재하지 않는 파일을 가리키기 때문입니다.
데이터 볼륨이 사용자가 보는 파일보다 훨씬 큰 이유는 무엇입니까?
미리 보기, 삭제된 파일, 이전 버전은 같은 볼륨에 저장되지만 사용자가 보는 용량에는 포함되지 않습니다. docker exec -it nextcloud sh -c 'du -sh /data/*'로 용량을 측정합니다. 기본적으로 휴지통은 공간이 필요할 때 30일이 지난 파일을 삭제하고, 공간이 부족하지 않으면 더 오래 보관합니다. 버전 정리는 quota가 설정된 계정에서는 남은 quota 공간의 절반을 대상으로 하며, 그렇지 않으면 파일시스템의 여유 공간을 직접 사용합니다. 최근 버전이 보존되면 이 목표를 달성하지 못할 수 있습니다. occ trashbin:cleanup --all-users, occ versions:cleanup alice, occ preview:cleanup로 정리합니다. 사용자가 파일을 열면 미리 보기는 다시 증가할 수 있습니다.
Nextcloud 데이터 디렉터리를 다른 디스크로 옮길 수 있습니까?
Nextcloud가 인식하는 경로를 변경하지 말고 새 위치를 동일한 컨테이너 경로에 마운트합니다. 컨테이너를 중지하고, 소유권을 보존하면서 기존 내용을 새 디스크로 복사합니다(cp -a 또는 rsync -aAX). 그런 다음 compose 파일에서 볼륨 또는 bind mount가 새 위치를 가리키도록 수정하고 컨테이너를 다시 시작합니다. Nextcloud는 여전히 /data를 보므로 데이터베이스의 항목을 변경할 필요가 없습니다. docker exec -it nextcloud occ config:system:get datadirectory과 테스트 업로드 1건으로 확인합니다.