Docker 네트워크 충돌 대응

.env.example

@@ -31,3 +31,4 @@ NUXT_PUBLIC_SITE_TITLE=sori.studio
 
 # Server
 APP_PORT=43118
+DOCKER_SUBNET=10.250.50.0/24

docker-compose.yml

@@ -12,6 +12,8 @@ services:
       - ./public/uploads:/app/public/uploads
     depends_on:
       - sori-studio-db
+    networks:
+      - sori-studio-network
     restart: unless-stopped
 
   sori-studio-db:
@@ -28,7 +30,16 @@ services:
     volumes:
       - sori-studio-postgres:/var/lib/postgresql/data
       - ./db/migrations:/docker-entrypoint-initdb.d:ro
+    networks:
+      - sori-studio-network
     restart: unless-stopped
 
 volumes:
   sori-studio-postgres:
+
+networks:
+  sori-studio-network:
+    driver: bridge
+    ipam:
+      config:
+        - subnet: ${DOCKER_SUBNET:-10.250.50.0/24}

docs/changelog.md

@@ -1,5 +1,9 @@
 # 업데이트 요약
 
+## v1.0.1
+
+- Docker Compose 네트워크 충돌 대응을 위해 전용 브리지 네트워크와 `DOCKER_SUBNET` 설정 추가.
+
 ## v1.0.0
 
 - 운영 시작 기준 버전.

docs/deploy.md

@@ -117,7 +117,7 @@ ssh [NAS_IP]
 
 ```bash
 # 프로젝트 디렉토리로 이동
-cd /volume1/docker/sori.studio
+cd /volume1/docker/projects/apps/
 
 # 프로젝트 클론
 git clone https://git.sori.studio/zenn/sori.studio.git
@@ -127,24 +127,23 @@ cd sori.studio
 
 # 운영 환경 변수 설정
 # .env.production은 Git에 올리지 않는 운영 전용 파일
-cp .env.example .env.production
+cp .env.production
 # .env.production 파일에 운영 DB 연결 정보, 운영 전용 랜덤 비밀번호, APP_PORT=43118 입력
 # MEMBER_SESSION_SECRET은 ADMIN_PASSWORD와 다른 긴 난수 문자열로 반드시 입력
+# Docker 네트워크 대역이 NAS 기존 컨테이너와 겹치면 DOCKER_SUBNET을 다른 사설 대역으로 변경
 # Docker 내부 앱에서 PostgreSQL에 접근할 때는 sori-studio-db:5432 사용
 
 # Docker 빌드 및 실행
-docker compose --env-file .env.production up -d
+docker compose --env-file .env.production up -d --build
 ```
 
-### 프로덕션 빌드 (NAS에서)
+### Docker 네트워크 충돌 대응
+
+NAS에 Docker 컨테이너가 많이 실행 중이면 `could not find an available, non-overlapping IPv4 address pool` 오류가 날 수 있다. 이 프로젝트는 기본 `DOCKER_SUBNET=10.250.50.0/24`를 사용한다. 해당 대역도 NAS 내부망 또는 다른 Docker 네트워크와 겹치면 `.env.production`에서 예를 들어 아래처럼 바꾼 뒤 다시 실행한다.
 
 ```bash
-# 프로덕션 빌드
-npm run build
-
-# 또는 Docker로 빌드
-docker build -t sori.studio:latest .
-docker run -d -p 3000:3000 sori.studio:latest
+DOCKER_SUBNET=10.250.51.0/24
+docker compose --env-file .env.production up -d --build
 ```
 
 ### 포트
@@ -153,6 +152,7 @@ docker run -d -p 3000:3000 sori.studio:latest
 - NAS Docker 외부: 43118
 - 컨테이너 내부: 3000
 - PostgreSQL 외부: 43119
+- Docker 내부 네트워크 기본값: `10.250.50.0/24`
 - HTTPS: 3001 (SSL 설정 시)
 
 ---

docs/history.md

@@ -1,5 +1,11 @@
 # 의사결정 이력
 
+## 2026-05-14 v1.0.1
+
+### Docker Compose 전용 네트워크 대역 명시
+
+NAS에서 이미 실행 중인 Docker 서비스가 많으면 Docker가 자동으로 고르는 기본 브리지 네트워크 주소 풀이 기존 네트워크와 겹쳐 Compose 실행이 실패할 수 있다. 기존 네트워크를 정리할 수 없는 운영 환경을 고려해 이 프로젝트 전용 브리지 네트워크와 기본 subnet을 명시하고, 필요 시 `.env.production`의 `DOCKER_SUBNET`으로 다른 사설 대역을 지정할 수 있게 했다.
+
 ## 2026-05-14 v1.0.0
 
 ### 운영 환경의 샘플 콘텐츠 fallback 차단

docs/spec.md

@@ -199,6 +199,7 @@ components/content/
 - 로컬 개발 서버는 개발 DB만 연결
 - NAS 배포 환경은 운영 DB만 연결
 - 운영 환경(`NODE_ENV=production`)에서는 `DATABASE_URL` 누락 시 샘플 콘텐츠로 대체하지 않고 서버 오류로 즉시 실패
+- Docker Compose는 전용 브리지 네트워크를 사용하며 기본 subnet은 `DOCKER_SUBNET`(`10.250.50.0/24`)으로 관리
 - 운영 DB 접속 정보는 로컬 기본 `.env`에 기록하지 않음
 - DB 관리 도구는 CloudBeaver 등을 사용할 수 있도록 접속 정보를 환경별로 분리
 

docs/update.md

@@ -1,5 +1,11 @@
 # 업데이트 이력
 
+## v1.0.1
+
+- Docker Compose 기본 네트워크 주소 풀 충돌을 피하기 위해 전용 브리지 네트워크와 `DOCKER_SUBNET` 설정 추가.
+- 배포 문서에 NAS Docker 네트워크 충돌 시 `DOCKER_SUBNET` 변경 기준 추가.
+- 패키지 버전 `1.0.1`로 갱신.
+
 ## v1.0.0
 
 - 운영 환경에서 `DATABASE_URL` 누락 시 샘플 콘텐츠 fallback 대신 즉시 실패하도록 수정.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "sori.studio",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sori.studio",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "hasInstallScript": true,
       "dependencies": {
         "@nuxtjs/tailwindcss": "^6.14.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sori.studio",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": true,
   "type": "module",
   "imports": {