결론부터 말씀드리면: SmartSlim Server의 Docker 배포는 네 단계로 나뉩니다. 이미지 빌드, docker-compose.yml 작성, 서비스 시작, 헬스 체크 검증입니다. 이미지 크기는 약 450MB이며, 최소 구성 2코어 4GB로 실행 가능하고, 시작 후 5초 이내에 헬스 체크를 통과합니다. 운영 환경에서는 데이터 볼륨 영구 저장, Nginx 리버스 프록시, 로그 수집, 정기 백업을 구성해야 합니다. 본문에서는 완전한 docker-compose.yml 구성, 환경 변수 표, 배포 단계 상세 설명을 제공합니다. 아래에서 배포 아키텍처부터 시작하여 단계별로 운영 등급 배포를 완성해 보겠습니다.
Docker 배포 후 압축 API를 어떻게 호출하는지 알고 싶으시다면, 먼저 압축 API 호출 실전: RESTful 인터페이스 문서 상세 설명을 읽어보시기를 권장합니다.
1. Docker 배포 아키텍처
SmartSlim Server의 Docker 배포는 단일 컨테이너 아키텍처를 채택하며, 내부에서 FastAPI 애플리케이션을 실행하고, 데이터 볼륨을 통해 파일과 구성을 영구 저장하며, 포트 매핑을 통해 외부에 서비스를 제공합니다. 운영 환경에서는 TLS 종료 및 로드 밸런싱을 처리하기 위해 Nginx 리버스 프록시 계층을 추가합니다.
| 구성 요소 | 기술 | 역할 | 포트 |
|---|---|---|---|
| SmartSlim 컨테이너 | Python 3.9 + FastAPI | 압축 서비스 코어 | 8000(내부) |
| Nginx 컨테이너 | Nginx 1.25 | 리버스 프록시/TLS | 80/443(외부) |
| 볼륨-data | Docker Volume | 압축 파일 저장 | - |
| 볼륨-logs | Docker Volume | 로그 파일 | - |
| 볼륨-config | Docker Volume | 구성 및 라이선스 | - |
배포 전에 서버가 최소 구성 요구 사항을 충족하는지 확인해야 합니다. 아래 표는 다양한 부하에 대한 구성 권장 사항을 제시합니다.
| 배포 규모 | CPU | 메모리 | 디스크 | 동시성 | 적용 시나리오 |
|---|---|---|---|---|---|
| 최소 구성 | 2코어 | 4GB | 20GB | 4 | 테스트/소규모 팀 |
| 권장 구성 | 4코어 | 8GB | 50GB | 8 | 중소기업 |
| 고부하 구성 | 8코어 | 16GB | 100GB | 16 | 대기업 |
| 클러스터 구성 | 4코어 x3 노드 | 8GB x3 | 공유 저장소 | 24+ | 고가용성 운영 |
2. docker-compose.yml 구성 상세 설명
아래는 운영 환경의 docker-compose.yml 핵심 구성으로, SmartSlim 서비스, Nginx 리버스 프록시, 데이터 볼륨 및 네트워크 구성을 포함합니다.
| 구성 항목 | 설명 | 예시 값 |
|---|---|---|
| image | 이미지 이름 | uglypear/smartslim-server:latest |
| restart | 재시작 정책 | always(운영 환경) |
| ports | 포트 매핑 | 8000:8000 |
| volumes | 볼륨 마운트 | ./data:/app/data |
| environment | 환경 변수 | SMARTSLIM_LICENSE=xxx |
| healthcheck | 헬스 체크 | curl -f http://localhost:8000/health |
| depends_on | 의존 서비스 | nginx |
| deploy.resources | 리소스 제한 | cpus:4, memory:8G |
3. 환경 변수 구성 표
SmartSlim Server는 환경 변수를 통해 실행 매개변수를 구성하며, 아래 표에 구성 가능한 모든 항목을 정리합니다.
| 환경 변수 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|
| SMARTSLIM_LICENSE | 예 | - | 라이선스 키 |
| SMARTSLIM_HOST | 아니오 | 0.0.0.0 | 수신 주소 |
| SMARTSLIM_PORT | 아니오 | 8000 | 수신 포트 |
| SMARTSLIM_WORKERS | 아니오 | 4 | 워커 프로세스 수 |
| SMARTSLIM_MAX_FILE_SIZE | 아니오 | 1073741824 | 단일 파일 한도(1GB) |
| SMARTSLIM_SECURITY_LEVEL | 아니오 | MEDIUM | 보안 레벨 |
| SMARTSLIM_RATE_LIMIT | 아니오 | 60 | 분당 요청 제한 |
| SMARTSLIM_LOG_LEVEL | 아니오 | INFO | 로그 레벨 |
| SMARTSLIM_TEMP_DIR | 아니오 | /app/data/tmp | 임시 파일 디렉터리 |
4. 배포 단계 상세 설명
Docker 배포는 빌드, 시작, 검증, 모니터링 네 단계로 나뉩니다. 아래 표에 각 단계의 작업 및 검증 방법을 제시합니다.
| 단계 | 작업 | 명령 | 검증 방법 |
|---|---|---|---|
| 1. 이미지 빌드 | SmartSlim 이미지 빌드 | docker build -t smartslim-server . | docker images로 이미지 확인 |
| 2. 구성 작성 | docker-compose.yml 작성 | yml 파일 편집 | docker-compose config로 검증 |
| 3. 서비스 시작 | 모든 컨테이너 시작 | docker-compose up -d | docker-compose ps로 상태 확인 |
| 4. 헬스 검증 | 서비스 가용성 확인 | curl http://localhost:8000/health | {"status":"ok"} 반환 |
| 5. Nginx 구성 | 리버스 프록시 구성 | nginx.conf 편집 | curl https://도메인/health |
| 6. 모니터링 배포 | 로그 및 모니터링 구성 | 로그 수집 구성 | docker logs로 로그 확인 |
5. 운영 환경 모범 사례
운영 환경 배포에서는 헬스 체크, 로그 수집, 데이터 백업, 보안 강화 네 가지 측면에 주의를 기울여야 합니다. 아래 표에 모범 사례 권장 사항을 제시합니다.
| 실천 항목 | 구성 권장 | 확인 빈도 | 도구 |
|---|---|---|---|
| 헬스 체크 | interval:30s, timeout:10s, retries:3 | 실시간 | Docker healthcheck |
| 로그 수집 | json-file 드라이버, max-size:100m, max-file:5 | 실시간 | Docker logging |
| 데이터 백업 | 매일 data 볼륨을 독립 저장소에 백업 | 매일 | cron + docker run |
| 보안 강화 | 비root 사용자로 실행, 읽기 전용 파일 시스템 | 배포 시 | Docker security |
| 리소스 제한 | cpus:4, memory:8G, 알림 임계값 80% | 실시간 | Docker stats |
| 이미지 업데이트 | 정기적으로 최신 이미지 풀, 롤링 업데이트 | 매월 | docker-compose pull |
완전한 헬스 체크 구성 예시: healthcheck에서 interval을 30초로 설정(30초마다 한 번씩 확인), timeout을 10초로 설정(타임아웃 시 실패로 판정), retries를 3회로 설정(연속 3회 실패 시 unhealthy로 표시), start_period를 10초로 설정(시작 후 10초 후부터 확인 시작)합니다. 이렇게 하면 컨테이너 이상이 90초 이내에 발견되어 자동으로 재시작됩니다.
| 모니터링 지표 | 정상 범위 | 알림 임계값 | 확인 명령 |
|---|---|---|---|
| CPU 사용률 | 0%–60% | >80% | docker stats |
| 메모리 사용률 | 0%–70% | >85% | docker stats |
| 디스크 사용률 | 0%–70% | >85% | df -h |
| API 응답 시간 | 0–2초 | >5초 | curl -w 매개변수 |
| 압축 큐 길이 | 0–20 | >50 | API status 인터페이스 |
| 오류율 | 0%–0.1% | >1% | 로그 통계 |
압축 작업 큐의 하위 설계를 알고 싶으시다면, 압축 작업 큐 설계를 참조하시기 바랍니다. 서버 배포가 아닌 SDK 로컬 통합을 선호하신다면, 압축 SDK 통합 가이드를 참조하시기 바랍니다.
6. 자주 묻는 질문 FAQ
Q1: Docker로 압축 서비스를 배포하려면 어떤 구성이 필요한가요?
SmartSlim Server의 Docker 배포 최소 구성: 2코어 CPU, 4GB 메모리, 20GB 디스크 공간이며, 권장 구성은 4코어 CPU, 8GB 메모리, 50GB 디스크입니다. 운영 체제에는 Docker 20.10+ 및 Docker Compose 2.0+가 설치되어 있어야 합니다. x86_64 및 ARM64 아키텍처를 지원하며, 이미지 크기는 약 450MB입니다. 운영 환경에서는 임시 압축 파일을 위한 추가 디스크 공간을 확보할 것을 권장합니다.
Q2: Docker로 배포한 압축 서비스는 어떻게 업데이트 및 업그레이드하나요?
업데이트 절차는 세 단계로 나뉩니다. 1. docker-compose pull로 최신 이미지 가져오기. 2. docker-compose up -d로 컨테이너 재시작(볼륨 데이터는 손실되지 않음). 3. 헬스 체크 엔드포인트를 확인하여 서비스가 정상인지 확인합니다. 업데이트 전에 데이터 볼륨을 백업할 것을 권장하며(docker run --volumes-from 백업), 롤링 업데이트는 Kubernetes 환경에서 무중단으로 구현할 수 있습니다. 버전 간 호환성이 양호하므로, 메이저 버전 업그레이드 전에 변경 로그를 확인하시기 바랍니다.
Q3: Docker 압축 서비스의 데이터 영구 저장은 어떻게 구현하나요?
Docker 볼륨을 통해 영구 저장을 구현합니다. 마운트해야 할 세 개의 디렉터리는 /app/data(압축 파일 저장), /app/logs(로그 파일), /app/config(구성 파일 및 라이선스 키)입니다. docker-compose.yml의 volumes 필드에서 호스트에서 컨테이너로의 매핑을 선언합니다. 컨테이너를 삭제해도 볼륨은 삭제되지 않으므로 데이터가 안전합니다. 운영 환경에서는 백업 및 확장이 용이하도록 볼륨을 독립 디스크 또는 NAS에 마운트할 것을 권장합니다.
Q4: Docker 압축 서비스는 고가용성 배포를 지원하나요?
SmartSlim 서버판은 단일 머신 Docker 배포를 지원하며, 네트워크판은 Docker Compose 다중 서비스 및 Kubernetes 고가용성 배포를 지원합니다. Kubernetes 환경에서 HPA(수평 Pod 자동 확장)를 통해 3-10 복제본의 탄력적 확장이 가능하며, 공유 저장소(MinIO) 및 공유 데이터베이스(MySQL)와 결합하여 무상태화를 구현합니다. 단일 머신 버전은 Nginx 로드 밸런싱 + 다중 인스턴스를 통해 간단한 HA를 구현할 수 있지만, 운영 환경에는 네트워크판 K8s 솔루션을 권장합니다.
요약
SmartSlim Server의 Docker 배포는 네 단계로 진행됩니다. 이미지 빌드, docker-compose.yml 작성, 서비스 시작, 헬스 체크 검증입니다. 이미지 크기는 450MB이며, 최소 2코어 4GB로 실행 가능하고, 시작 후 5초 이내에 헬스 체크를 통과합니다. 9개의 환경 변수 구성을 통해 라이선스, 동시성, 보안, 속도 제한 등 핵심 매개변수를 다룹니다. 운영 환경의 6가지 모범 사례: 30초 간격의 헬스 체크, 100MB 로그 회전, 매일 데이터 백업, 비root 보안 강화, 4코어 8G 리소스 제한, 매월 이미지 업데이트.
세 가지를 기억하십시오. 첫째, 데이터 볼륨은 세 개의 디렉터리(data/logs/config)를 반드시 마운트하여 컨테이너를 삭제해도 데이터가 손실되지 않도록 합니다. 둘째, 헬스 체크 구성 interval:30s + retries:3로 90초 이내에 이상을 발견하여 자동 재시작합니다. 셋째, 운영 환경에서는 Nginx 리버스 프록시를 추가하여 TLS 종료를 처리하고 8000 포트를 직접 노출하지 마십시오. 배포 완료 후 압축 API 및 작업 큐와 결합하여 완전한 압축 서비스를 구축할 수 있습니다.
관련 추천
파일을 압축해야 하시나요? SmartSlim을 사용해 보세요
자체 개발한 Rust 압축 엔진 기반으로 PDF/이미지/비디오/Office/OFD 등 10개 대분류 40+ 포맷을 지원하며, 로컬 압축으로 데이터가 외부로 유출되지 않습니다.