Files
dbx-main/docs/DEPLOYMENT.md
T
king aa669553db feat(performance): 실적(쇼핑몰 통합 매출) 모듈 1단계 — 대시보드·설정·보안·어댑터 구조
- 네 영역 분리: ① 수집(adapters/ 쇼핑몰 10곳 + sync.py) ② 보안(security/ + credentials.py)
  ③ 계산·저장(calc.py + db.py) ④ 화면(dashboard.py, router.py, templates, performance.css/js)
- 대시보드: 기간(오늘/이번주/이번달/올해/직접선택, 이전·다음), 쇼핑몰 필터, KPI 5개(진행 중 기간은
  직전 기간 같은 경과일 대비), 일자×쇼핑몰 표(주간합계, 총매출/수수료/차감매출 전환), 일별 추이·
  쇼핑몰 비중(SVG), 월 누적(비중)·연간 누적, 금액 클릭 → 주문 상세
- 설정(관리자): 사용/매출 집계, 수수료율 이력(적용 시작일), 쇼핑몰별 API 인증정보 입력·연결 테스트·
  연결 상태, 마스터 키 상태·재암호화, 테스트(모의) 데이터 생성/삭제
- 인증정보: 설정 화면 입력 → AES-256-GCM(키 버전, AAD=쇼핑몰+항목) 암호화 저장, secret 원문은
  화면으로 다시 보내지 않음, 오류·로그·raw 는 비밀값 가린 뒤 저장. 마스터 키는 APP_ENCRYPTION_KEY(.env)
- 매출 기준일: 결제=결제일, 취소·반품=발생일. 금액 원 단위 정수, 수수료 반올림은 calc.commission 한 곳
- 동기화: 같은 쇼핑몰 동시 실행 차단(running 부분 유니크), 쇼핑몰별 실패 격리, 중복 방지 UNIQUE+UPSERT
- 카페24 어댑터는 기존 app/integrations/cafe24 OAuth 토큰 재사용, 나머지는 입력칸만(수집은 다음 단계)
- performance_db 초기화 스크립트, 권한키 performance(설정은 is_admin), 문서·.env.example

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:07:46 +09:00

7.1 KiB

Deployment

기본 배포 흐름

[Windows 개발 PC]
   │  git push (Gitea)
   ▼
[Gitea Repository]
   │  git pull (서버에서)
   ▼
[Ubuntu Server]
   │  .env 확인 → docker compose up --build -d
   ▼
[Docker]
   │  main-app, postgres 컨테이너 실행
   ▼
[NPM (Nginx Proxy Manager)]
   │  외부 HTTPS 종단 → 내부 :80
   ▼
[서비스 정상 동작]

운영 서버 배포 경로

운영 서버는 Ubuntu Server. 동일 호스트에 여러 서비스가 있으므로 경로를 분리한다.

경로 용도
/opt/www/main main-app (본 프로젝트) 배포 경로 — 기본
/opt/dbx-corm CORM (CS/발주/반품/코드관리) 서비스 경로
/opt/dbx-orderlist 주문관리/orderlist 서비스 경로

main-app 관련 모든 명령/문서 작성 시 /opt/www/main 사용. 새로운 경로가 필요하면 사용자 지시를 받은 뒤 결정한다.


사전 준비

  • 서버에 Docker, Docker Compose 설치 완료
  • Gitea 접근 권한 있는 SSH/HTTPS 인증 설정 완료
  • NPM에 호스트 매핑 등록: dbx.no1king.freeddns.org → http://192.168.0.194:80
  • .env 값 확보 (Google OAuth, 세션 키, DB 비밀번호 등)

최초 배포

# 1) main-app 배포 경로
sudo mkdir -p /opt/www/main
sudo chown $USER:$USER /opt/www/main
cd /opt/www/main

# 2) 저장소 클론
git clone https://gitea.no1king.freeddns.org/king/dbx-main.git .

# 3) 환경 변수 파일 준비
cp .env.example .env
nano .env   # 실제 값으로 수정 (절대 Git에 커밋 금지)

# 4) 빌드 및 백그라운드 실행
docker compose up --build -d

# 5) 로그 확인
docker compose logs -f

업데이트 배포

cd /opt/www/main
git pull
docker compose up --build -d
docker compose logs -f --tail=200

컨테이너 관리

docker compose ps               # 상태 확인
docker compose restart web      # 단일 서비스 재시작
docker compose stop             # 중지 (볼륨 유지)
docker compose down             # 컨테이너 제거 (볼륨 유지)
# docker compose down -v        # ⚠ 볼륨까지 삭제. 운영에서 금지

docker compose down -v, docker volume rm, docker system prune -a --volumes 는 사용자 승인 없이 실행 금지.


.env / 비밀값 관리

  • .env, .env.local, .env.production 은 절대 Git에 올리지 않는다.
  • 예시 파일(.env.example)만 커밋한다.
  • 신규 변수 추가 시 .env.example과 본 문서를 함께 갱신한다.
  • 비밀값 유출 의심 시 즉시 회전(rotate)한다 (특히 GOOGLE_CLIENT_SECRET, SESSION_SECRET_KEY, DB 비밀번호).

주요 환경 변수

변수 설명
GOOGLE_CLIENT_ID Google OAuth 클라이언트 ID
GOOGLE_CLIENT_SECRET Google OAuth 클라이언트 보안 비밀
SESSION_SECRET_KEY 세션 쿠키 서명용 랜덤 문자열
SESSION_COOKIE_SECURE HTTPS 환경 true / 로컬 HTTP false
PUBLIC_BASE_URL 외부 접속 주소 (예: https://dbx.no1king.freeddns.org)
CS_ORDER_URL CS 발주 업무 버튼 이동 주소
CUSTOMER_ORDER_LIST_URL 고객 주문리스트 프로그램 버튼 이동 주소
*_DB_HOST, *_DB_USER, *_DB_PASSWORD, *_DB_NAME 각 PostgreSQL DB 접속 정보
EXPENSE_DB_URL 개인경비 DB DSN (예: postgresql://expense_app:<pwd>@postgres-db:5432/expense_db). 미설정 시 JSON 폴백
CUPANG_DB_URL 쿠팡 밀크런 DB DSN (예: postgresql://cupang_app:<pwd>@postgres-db:5432/cupang_db). 필수 — 미설정 시 모듈 비활성(설정 필요 안내)
VACATION_DB_URL 휴가 관리 DB DSN (예: postgresql://vacation_app:<pwd>@postgres-db:5432/vacation_db). 필수 — 미설정 시 모듈 비활성(설정 필요 안내). 권한키 vacation/vacation_approver
ITEMCODE_DB_URL 상품 검색용 itemcode_db 읽기 전용 DSN. 미설정 시 검색 비활성(수동 입력). 테이블/컬럼은 ITEMCODE_TABLE/ITEMCODE_CODE_COL/ITEMCODE_NAME_COL/ITEMCODE_TYPE_COL 또는 ITEMCODE_SEARCH_SQL 로 지정
DATA_DIR 영구 데이터 경로 (Docker 볼륨 마운트). 첨부파일은 $DATA_DIR/uploads/expense/{item_id}/ 에 저장
PERFORMANCE_DB_URL 실적 DB DSN (예: postgresql://performance_app:<pwd>@postgres-db:5432/performance_db). 필수 — 미설정 시 실적 모듈 비활성(설정 필요 안내). 권한키 performance
APP_ENCRYPTION_KEY 쇼핑몰 API 인증정보 암호화 마스터 키(32바이트, openssl rand -hex 32). DB 에 저장하지 않음. 분실 시 저장된 인증정보 복구 불가 — 별도 안전 보관. 쇼핑몰별 ID/Key/Secret 은 .env 에 넣지 않고 실적 → 설정 화면에서 입력
APP_ENCRYPTION_KEY_VERSION 현재 마스터 키 버전(기본 1). 교체 시 올리고 예전 키는 APP_ENCRYPTION_KEY_V{n} 로 남긴 뒤 설정 화면에서 재암호화(docs/PERFORMANCE_MODULE.md)
PERFORMANCE_SYNC_DAYS [매출 업데이트] 수집 기간(오늘 포함 최근 N일, 기본 7, 최대 90)

로컬 Docker 테스트

# 1) 로컬 env 파일 준비
copy .env.local.example .env.local
# .env.local 을 열어 실제 값으로 수정

# 2) 이미지 빌드 및 실행
docker compose -f docker-compose.local.yml up --build

# 3) 브라우저 확인
# http://localhost:8080

로컬 OAuth: Google Cloud Console 리디렉션 URI에 http://localhost:8080/auth/google 추가 필요.


복구 절차

컨테이너만 깨진 경우

docker compose up --build -d
docker compose logs -f

DB 데이터가 깨진 경우 (사용자 승인 필수)

  1. 즉시 트래픽 차단 (NPM 비활성화 또는 점검 페이지)
  2. 가장 최근 백업 확인
  3. 새 DB 이름으로 먼저 복구해 검증
  4. 검증 완료 후 운영 DB 교체
  5. 복구 후 로그/주문 정합성 점검

운영 DB에 직접 pg_restore --clean을 실행하지 않는다. DATABASES.md 참고.


위험 명령 (사용자 승인 없이 실행 금지)

명령 위험
rm -rf 파일/디렉터리 영구 삭제
docker compose down -v 볼륨 포함 삭제 → DB 손실
docker volume rm, docker volume prune 볼륨 영구 삭제
docker system prune -a --volumes 이미지·네트워크·볼륨 일괄 삭제
DROP DATABASE, DROP TABLE, TRUNCATE DB 파괴 (DATABASES.md 참고)
git reset --hard, git push --force, git clean -fd 작업 내역 손실
운영 .env 덮어쓰기 / 삭제 인증·세션 붕괴

원칙:

  1. 실행 전 현재 상태 확인 명령을 먼저 보여준다.
  2. 백업 위치를 명시한다.
  3. 사용자 명시 승인 후에만 실행한다.

점검 체크리스트

  • docker compose ps 모든 서비스 running
  • docker compose logs --tail=200 에러 없음
  • https://dbx.no1king.freeddns.org 200 응답
  • Google 로그인 정상 동작
  • PostgreSQL 컨테이너 볼륨 마운트 정상
  • 최근 DB 백업 존재 여부
  • .env 미커밋 상태 (git status로 확인)