📚 Docker 워드프레스 파일 권한 문제 마스터 청사진

💡 상황 해독

현재 상태: 워드프레스에서 이미지를 업로드하려고 하는데 "파일을 content/uploads/2025/06으로 이동할 수 없습니다"라는 오류가 나타남. 웹 브라우저에서는 200 응답이 뜨지만 실제로는 파일이 저장되지 않는 상황

핵심 쟁점:

Docker 컨테이너 내부의 워드프레스는 www-data 사용자로 실행됨

호스트에서 마운트된 파일들은 일반 사용자(ds) 소유

권한 불일치로 인해 파일 쓰기 작업이 실패

예상 vs 현실: 파일 업로드가 성공적으로 완료될 것으로 기대했지만, 실제로는 권한 부족으로 파일이 저장되지 않음

영향 범위: 이미지 업로드뿐만 아니라 플러그인 설치, 테마 업데이트, 백업 파일 생성 등 모든 파일 쓰기 작업이 영향받음

🔍 원인 투시

근본 원인: Docker 컨테이너와 호스트 시스템 간의 사용자 권한 불일치. 컨테이너 내부의 워드프레스는 www-data(UID 33)로 실행되지만, 호스트의 파일들은 일반 사용자 소유로 되어 있어 쓰기 권한이 없음

연결 고리: 호스트 → 볼륨 마운트 → 컨테이너 내부로 파일이 연결되지만, 소유권은 호스트 사용자 그대로 유지 → 컨테이너 내부의 www-data 사용자가 파일에 접근할 수 없음 → 업로드 실패

일상 비유:

아파트 열쇠를 가진 사람(호스트 사용자)이 방을 빌려주었는데, 세입자(www-data)에게는 열쇠를 주지 않은 상황

도서관에서 책을 읽을 수는 있지만 메모를 쓸 수 없는 상황과 유사

숨겨진 요소: HTTP 200 응답은 서버가 요청을 받았다는 의미일 뿐, 실제 파일 처리 성공을 보장하지 않음

🛠️ 해결 설계도

즉시 해결: 컨테이너 내부에서 권한 수정

핵심 행동: Docker 컨테이너에 접속하여 파일 소유권을 www-data로 변경

실행 가이드:

bash

1단계: 실행 중인 컨테이너 확인

docker ps

2단계: 컨테이너에 접속

docker exec -it <컨테이너명> bash

3단계: 권한 수정

chown -R www-data:www-data /var/www/html/wp-content/uploads/

chmod -R 755 /var/www/html/wp-content/uploads/

4단계: 컨테이너에서 나가기

exit

성공 지표: 워드프레스에서 이미지 업로드가 정상적으로 작동함

주의사항: 컨테이너를 재시작하면 권한이 초기화될 수 있음

근본적 해결: docker-compose.yml 수정

핵심 행동: 컨테이너 실행 시 올바른 사용자 권한으로 시작하도록 설정

실행 가이드:

text

변경 전 (docker-compose.yml)

wordpress:

image: wordpress:latest

volumes:

- ./:/var/www/html

변경 후

wordpress:

image: wordpress:latest

user: "33:33" # www-data의 UID:GID

volumes:

- ./:/var/www/html

핵심 변화 설명

user: "33:33" 설정으로 컨테이너가 처음부터 www-data 권한으로 실행됨

성공 지표: 컨테이너 재시작 후에도 파일 업로드가 정상 작동

주의사항: 기존 파일들의 권한도 함께 수정해야 함

예방적 해결: 호스트에서 권한 사전 설정

핵심 행동: 컨테이너 시작 전에 호스트에서 올바른 권한 설정

실행 가이드:

bash

컨테이너 중지

docker-compose down

호스트에서 권한 변경 (33:33은 www-data의 UID:GID)

sudo chown -R 33:33 ~/docker-volumes/wp-duswn2/wp-content/

sudo chmod -R 755 ~/docker-volumes/wp-duswn2/wp-content/

컨테이너 재시작

docker-compose up -d

성공 지표: 처음부터 모든 파일 작업이 정상적으로 수행됨

주의사항: sudo 권한이 필요하며, 호스트에서 파일 편집 시 권한 문제가 발생할 수 있음

🧠 핵심 개념 해부

Docker 볼륨 마운트: 두 세계를 연결하는 다리

5살에게 설명한다면: 컴퓨터 안의 가상 컴퓨터(Docker)와 진짜 컴퓨터가 같은 폴더를 공유하는 것

실생활 예시: 집(호스트)과 사무실(컨테이너)에서 같은 USB 드라이브를 사용하는 것과 유사

숨겨진 중요성: 데이터 영속성과 개발 편의성을 동시에 제공하는 핵심 기능

오해와 진실: 단순히 폴더를 공유하는 것이 아니라, 권한과 소유권도 함께 고려해야 함

www-data 사용자: 웹서버의 실행 주체

5살에게 설명한다면: 웹사이트를 운영하는 전용 직원의 이름

실생활 예시: 은행에서 고객 업무를 처리하는 창구 직원과 유사

숨겨진 중요성: 보안을 위해 제한된 권한만 가지도록 설계된 시스템 사용자

오해와 진실: 일반 사용자가 아닌 시스템이 만든 특수 사용자로, UID 33번을 가짐

파일 권한 시스템: 디지털 세계의 출입 통제

5살에게 설명한다면: 파일마다 "누가 읽을 수 있고, 누가 쓸 수 있는지" 정하는 규칙

실생활 예시: 집 열쇠, 사무실 출입카드와 같은 접근 권한 시스템

숨겨진 중요성: 시스템 보안의 기초이자 멀티유저 환경에서 필수적인 요소

오해와 진실: 단순한 읽기/쓰기 구분이 아니라 소유자, 그룹, 기타 사용자별로 세밀하게 제어됨

🔮 미래 전략 및 지혜

예방 전략:

docker-compose.yml에 user 설정 포함: 새 프로젝트 시작 시 항상 적절한 사용자 권한 설정

권한 체크 스크립트 작성: 정기적으로 파일 권한을 확인하는 자동화 스크립트 구성

개발 환경 템플릿 구축: 권한 문제가 해결된 표준 Docker 구성을 템플릿으로 저장

장기적 고려사항: Docker를 사용한 개발 환경에서는 항상 호스트와 컨테이너 간의 권한 매핑을 고려해야 함. 이는 단순한 기술적 문제가 아니라 보안과 협업의 기초

전문가 사고방식: 문제 발생 시 증상(업로드 실패)보다는 원인(권한 불일치)에 집중하고, 임시 해결책과 근본적 해결책을 구분하여 접근

학습 로드맵:

Linux 파일 권한 시스템 이해

Docker 볼륨과 바인드 마운트 차이점 학습

컨테이너 보안 모범 사례 연구

개발 환경 자동화 도구 활용

🌟 실전 적용 청사진

즉시 적용:

현재 프로젝트에 docker exec -it <컨테이너명> chown -R www-data:www-data /var/www/html/wp-content/ 명령어 실행

docker-compose.yml에 user: "33:33" 설정 추가

권한 문제 해결 명령어를 개인 메모장에 저장

중기 프로젝트:

표준화된 WordPress Docker 개발 환경 구축

권한 문제 자동 진단 및 해결 스크립트 작성

팀 내 Docker 개발 환경 가이드라인 문서화

숙련도 점검:

새로운 Docker 프로젝트에서 권한 문제 없이 첫 번째 시도에 성공하는지 확인

다른 개발자에게 이 문제와 해결 방법을 명확하게 설명할 수 있는지 테스트

추가 리소스:

초급: Docker 공식 문서의 볼륨 섹션

중급: "Docker Deep Dive" 책의 권한 관련 챕터

고급: Kubernetes의 SecurityContext 개념 학습

📝 지식 압축 요약

Docker 워드프레스에서 파일 업로드 실패는 컨테이너 내부의 www-data 사용자와 호스트 파일 소유권 불일치가 원인이며, docker exec로 컨테이너 내부에서 권한을 수정하면 즉시 해결되고, docker-compose.yml에 user: "33:33" 설정을 추가하면 근본적으로 예방할 수 있다. 이는 Docker 개발 환경의 핵심 개념이므로 한 번 이해하면 모든 유사한 문제를 쉽게 해결할 수 있다.

여담으로 문제가 발생한 원인은 아마 도커 볼륨을 이동/변경을 해서 그럴거라 예상한다.

실수로 컴포즈에 ds사용자가아닌 de로 작성해서 볼륨초기화에 문제를 겪었고, 이후 오타를 찾아내어 올바른 경로에 옮겨주었기 때문에 발생한 것 같다.

이러한 상황이 아니라면 발생하지 않을 문제일것같다.