대동에프앤디(Daedong FND) 웹 서비스 인프라

대동에프앤디 공식 홈페이지 및 온라인 쇼핑몰을 위한 Docker Compose 기반 통합 웹 서비스 인프라스트럭처 레포지토리입니다.
그누보드5 및 영카트5에 최적화된 PHP-FPM 8.2 환경과 독립된 Nginx 웹 서버, 공유 MariaDB 및 Redis 캐시 계층을 컨테이너 기반으로 제공합니다.

---

📌 목차

1. 프로젝트 개요
2. 시스템 아키텍처 및 서비스 구성
3. 디렉터리 구조
4. 사전 준비사항
5. 설치 및 실행 방법
6. 서비스 접속 정보
7. 주요 설정 및 가이드
8. 운영 및 유지보수

---

1. 프로젝트 개요

• 목적: 멀티 사이트(공식 홈페이지 및 쇼핑몰)의 독립성 보장 및 단일 인프라 환경 구축
• 기반 기술:
  • 웹 서버: Nginx (Alpine)
  • 애플리케이션 런타임: PHP-FPM 8.2 (Debian Bookworm 기반 최적화 빌드)
  • 데이터베이스: MariaDB 11.4 LTS
  • 인메모리 캐시: Redis (Alpine)
  • DB 관리 도구: phpMyAdmin
  • 소스코드 관리: Git Submodule 기반 멀티 레포지토리 연동

---

2. 시스템 아키텍처 및 서비스 구성

전체 인프라는 Docker 브리지 네트워크(bridge)를 통해 상호 연결되어 통신합니다.

                      [ Client Requests ]
                               │
            ┌──────────────────┴──────────────────┐
            ▼                                     ▼
┌───────────────────────┐             ┌───────────────────────┐
│  nginx-ddfnd (:8080)  │             │   nginx-shop (:8081)  │
│ (대동에프앤디 홈페이지) │             │     (대동 쇼핑몰)     │
└───────────┬───────────┘             └───────────┬───────────┘
            │ FastCGI                             │ FastCGI
            ▼                                     ▼
┌───────────────────────┐             ┌───────────────────────┐
│   php-ddfnd (:9000)   │             │    php-shop (:9000)   │
│     (PHP-FPM 8.2)     │             │     (PHP-FPM 8.2)     │
└───────────┬───────────┘             └───────────┬───────────┘
            │                                     │
            └──────────────────┬──────────────────┘
                               │
            ┌──────────────────┴──────────────────┐
            ▼                                     ▼
┌───────────────────────┐             ┌───────────────────────┐
│     mariadb:11.4      │             │     redis:alpine      │
│ (데이터베이스 - 공유) │             │   (세션/캐시 - 공유)  │
└───────────▲───────────┘             └───────────────────────┘
            │
┌───────────┴───────────┐
│      pma (:8082)      │
│     (phpMyAdmin)      │
└───────────────────────┘

컨테이너 목록

컨테이너명	이미지	외부 포트	내부 포트	역할 및 설명
mariadb	mariadb:11.4	-	3306	MariaDB 11.4 LTS 공유 데이터베이스
redis	redis:alpine	-	6379	인메모리 캐시 및 세션 저장소 (최대 256MB, LRU 정책)
pma	phpmyadmin:latest	8082	80	웹 기반 데이터베이스 관리 GUI
nginx-ddfnd	nginx:alpine	8080	80	대동에프앤디 홈페이지 리버스 프록시 및 정적 파일 서빙
php-ddfnd	git.siane.kr/daedong/php-fpm:8.2	-	9000	대동에프앤디 홈페이지 PHP-FPM 백엔드
nginx-shop	nginx:alpine	8081	80	대동 쇼핑몰 리버스 프록시 및 정적 파일 서빙
php-shop	git.siane.kr/daedong/php-fpm:8.2	-	9000	대동 쇼핑몰 PHP-FPM 백엔드

---

3. 디렉터리 구조

daedong/web/
├── .env.example             # 환경변수 템플릿 파일
├── .gitignore               # Git 추적 제외 설정
├── .gitmodules              # Git 서브모듈(홈페이지/쇼핑몰) 설정
├── docker-compose.yml       # 전체 컨테이너 오케스트레이션 구성
├── build/
│   └── Dockerfile           # 그누보드 필수 확장 및 Redis를 포함한 PHP-FPM 8.2 이미지 빌드 파일
├── config/
│   ├── ddfnd/               # 대동에프앤디 전용 설정
│   │   ├── nginx.conf       # Nginx 가상 호스트 및 그누보드 Rewrite 규칙
│   │   └── php.ini          # PHP 런타임 환경설정 (용량, 실행시간 등)
│   └── shop/                # 대동 쇼핑몰 전용 설정
│       ├── nginx.conf       # Nginx 가상 호스트 설정
│       └── php.ini          # 쇼핑몰 PHP 환경설정
├── mariadb/
│   ├── conf.d/
│   │   └── custom.cnf       # MariaDB 성능 및 인코딩 최적화 설정
│   ├── data/                # MariaDB 데이터 영구 볼륨 (Git 제외)
│   └── init/                # 컨테이너 최초 생성 시 자동 실행되는 SQL 디렉터리
├── logs/                    # Nginx 웹 서버 로그 디렉터리
│   ├── ddfnd/               # 대동에프앤디 로그
│   └── shop/                # 대동 쇼핑몰 로그
├── redis/                   # Redis 데이터 영구 볼륨 (AOF)
└── site/
    ├── ddfnd/               # [Submodule] 대동에프앤디 소스코드 (그누보드5)
    └── ddfnd.shop/          # [Submodule] 대동 쇼핑몰 소스코드 (영카트5)

---

4. 사전 준비사항

• Docker Engine: v24.0.0 이상
• Docker Compose: v2.20.0 이상
• Git: 최신 버전 권장

---

5. 설치 및 실행 방법

1) 저장소 클론 및 서브모듈 초기화

서브모듈 소스코드(site/ddfnd, site/ddfnd.shop)를 함께 다운로드해야 합니다.

# 서브모듈을 포함하여 재귀적으로 클론
git clone --recurse-submodules https://git.siane.kr/daedong/web-service.git
cd web-service

# 이미 일반 클론을 수행한 경우 서브모듈 초기화 및 갱신
git submodule update --init --recursive

2) 환경변수 설정

템플릿 파일(.env.example)을 복사하여 .env 파일을 생성하고 환경에 맞게 값을 변경합니다.

cp .env.example .env

.env 주요 설정 항목:

# 시간대 설정
TZ=Asia/Seoul

# Gitea 레포지토리 인증 정보 (필요 시)
GIT_USER=your_gitea_username
GIT_TOKEN=your_gitea_token_or_password

# MariaDB 데이터베이스 인증 정보
MARIADB_ROOT_PASSWORD=실제_루트_비밀번호_입력
MARIADB_DATABASE=ddweb
MARIADB_USER=ddweb
MARIADB_PASSWORD=실제_사용자_비밀번호_입력

# 파일 권한 (호스트 User/Group ID)
PUID=1001
PGID=1001

3) 초기 데이터베이스(DB) 덤프 배치 (선택사항)

기존 운영 데이터 또는 초기 테이블 구조 덤프 파일(.sql)이 있는 경우, 컨테이너 최초 실행 전에 mariadb/init/ 디렉터리에 복사합니다.

cp daedong_backup.sql mariadb/init/

참고: mariadb/data/ 디렉터리가 비어 있을 때 컨테이너가 최초 기동하면서 mariadb/init/*.sql 파일이 알파벳 순서로 자동 실행됩니다.

4) Docker 컨테이너 빌드 및 실행

# 이미지 빌드 및 백그라운드 실행
docker compose up -d --build

# 실행 상태 확인
docker compose ps

5) 파일 권한 및 실행 권한 설정

그누보드/영카트의 파일 업로드 디렉터리(data/) 및 결제/본인인증 바이너리 모듈의 권한을 확인합니다.

# 본인인증(KCP, OKNAME) 및 PG 결제 모듈 실행 권한 부여
docker compose exec php-ddfnd bash -c "cd /var/www/html && bash perms.sh"
docker compose exec php-shop bash -c "cd /var/www/html && bash perms.sh"

# data 디렉터리 권한 확인 (필요 시 웹 서버 쓰기 권한 부여)
docker compose exec php-ddfnd chown -R www-data:www-data /var/www/html/data
docker compose exec php-shop chown -R www-data:www-data /var/www/html/data

---

6. 서비스 접속 정보

컨테이너 정상 구동 후 아래의 포트로 접속할 수 있습니다.

서비스명	접속 URL	비고
대동에프앤디 홈페이지	http://localhost:8080	대동에프앤디 공식 사이트 (포트: 8080)
대동 쇼핑몰	http://localhost:8081	온라인 쇼핑몰 (포트: 8081)
phpMyAdmin	http://localhost:8082	DB 관리 도구 (호스트: db, 포트: 8082)

---

7. 주요 설정 및 가이드

1) PHP-FPM 환경 (build/Dockerfile)

그누보드5 및 영카트5 구동에 필요한 필수 PHP 확장이 사전 탑재되어 있습니다.

• 탑재 확장 모듈: gd, mysqli, pdo_mysql, opcache, bcmath, exif, intl, zip, sockets, redis
• 세부 런타임 값은 config/{ddfnd,shop}/php.ini에서 관리되며, 기본적으로 대용량 파일 업로드(최대 2GB) 및 긴 실행 시간(360초)이 설정되어 있습니다.

2) MariaDB 최적화 (mariadb/conf.d/custom.cnf)

• 기본 문자셋: utf8mb4 / 정렬 순서: utf8mb4_unicode_ci
• 대소문자 구분: lower_case_table_names = 1 (Windows/Linux 간 호환성 확보)
• 버퍼 풀: innodb_buffer_pool_size = 512M
• 최대 패킷: max_allowed_packet = 64M

3) Nginx SEO & Rewrite 규칙 (config/{ddfnd,shop}/nginx.conf)

• 그누보드 짧은 주소(SEO Friendly URL) 규칙이 Nginx 설정 내에 기본 반영되어 있습니다.
• 정적 자원(CSS, JS, 이미지, 웹폰트)에 대한 브라우저 캐싱 만료 헤더가 적용되어 있습니다.

---

8. 운영 및 유지보수

서브모듈 최신 코드 반영

각 사이트 레포지토리의 변경사항을 가져와 반영할 때 사용합니다.

# 모든 서브모듈 최신 커밋으로 갱신
git submodule update --remote --merge

로그 확인

실시간 로그를 확인하여 웹 요청 및 에러를 모니터링합니다.

# 전체 서비스 실시간 로그
docker compose logs -f

# 대동에프앤디 웹/PHP 로그만 확인
docker compose logs -f nginx-ddfnd php-ddfnd

# 쇼핑몰 웹/PHP 로그만 확인
docker compose logs -f nginx-shop php-shop

서비스 중지 및 재시작

# 서비스 일시 중지
docker compose stop

# 서비스 시작
docker compose start

# 컨테이너 완전 종료 (네트워크 및 컨테이너 삭제, 데이터 볼륨 유지)
docker compose down

# 컨테이너 완전 종료 및 데이터 볼륨까지 삭제 (주의: DB 데이터 삭제됨)
docker compose down -v

데이터베이스 백업 및 복구

• 백업 (덤프):

  docker compose exec db mariadb-dump -u ddweb -p ddweb > backup_$(date +%Y%m%d).sql
  

• 복구:

  docker compose exec -T db mariadb -u ddweb -p ddweb < backup_20261014.sql