Files
dbx-main/docs/DEPLOYMENT.md
T
king 4c17158753 feat(inout): 옵션을 톱니 팝업으로, 겹치던 옵션 화면 정리, 공장 담당자·연락처 분리
- 옵션 탭 → 상단 오른쪽 톱니(관리자) → 팝업(탭: 담당자·공장). 내용은 /inout/settings?panel=1,
  저장은 팝업 안에서(X-Inout-Options: 1 → JSON, 같은 탭 그대로 다시 그림), 바뀌면 닫을 때 새로고침.
  예전 /inout/settings 주소는 목록으로 가서 팝업 열기(?options=1).
- 겹침 원인: 공용 .erp-input(min-width 240px + content-box)이 좁은 칸에서 옆 칸을 덮고,
  .erp-table-wrap(카드 그림자·둥근 모서리)이 카드 안에서 상자를 겹쳐 보이게 함 → .io/.io-dlg 안에서만 바로잡음.
  공장 표는 진짜 <table> + 입력칸 form 속성으로 열 맞춤(줄 선·배경 어긋남 없음).
- 공장 담당자·연락처 분리: inout_db 002(manager 열, 이름만 있던 연락처는 담당자로). 발주서 화면에 공장 담당자·연락처.
  002 미적용이어도 발주서 화면은 열리고 공장 저장만 안내.
- 테스트: 팝업·JSON 저장·예전 주소·권한, 담당자/연락처, 002 전후. 실제 브라우저로 겹침 0·줄 맞춤 확인.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 15:45:53 +09:00

26 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

주간 회의록 셀 병합 마이그레이션

주간 회의록 셀 병합을 배포할 때는 project_db의 최근 백업 위치를 확인한 뒤 마이그레이션 019를 적용한다. DB는 공용 postgres-db 컨테이너의 PostgreSQL(컨테이너 포트 5432)을 사용한다. 019는 기존 글을 바꾸지 않고 content_row_span 열을 추가하며, 다시 실행할 수 있다. 미적용 시 다른 셀 편집은 가능하지만 병합은 사용할 수 없다.

cd /opt/www/main
docker compose ps
docker exec postgres-db psql -U postgres -d project_db -c 'SELECT current_database();'
# project_db 최근 백업 위치를 확인한 후 적용
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_019_meeting_cell_editing.sql
docker exec postgres-db psql -U postgres -d project_db -c "SELECT column_name FROM information_schema.columns WHERE table_name = 'goal_meeting_items' AND column_name = 'content_row_span';"

주간 회의록 새 주차·결과 글·주차별 목표 마이그레이션 (020)

020은 goal_meeting_items.result_note 열·goal_week_targets 표를 추가하고, goal_meetings 의 "월요일만" CHECK 를 없애며, 새 주차 규칙에 흡수된 월요일 회의록을 새 주차 시작일로 옮긴다(옮길 자리에 회의록이 있으면 NOTICE 만). 다시 실행할 수 있다. 코드는 020 전에도 열리지만 결과 글·주차별 목표·월요일이 아닌 주차 회의록 만들기는 020 뒤에 된다.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_020_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_020_meeting_periods.sql
docker exec postgres-db psql -U postgres -d project_db -c "SELECT to_regclass('goal_week_targets') AS t, (SELECT count(*) FROM information_schema.columns WHERE table_name='goal_meeting_items' AND column_name='result_note') AS note;"

주간 회의록 "회의록 보드"(Google 슬라이드) 설정

회의록 화면의 [회의록 보드] 는 주차마다 빈 Google 슬라이드를 공유 드라이브(MEETING_BOARD_FOLDER_ID, 기본 0AGF3CIEboPQiUk9PVA)에 만들어 새 창으로 연다(app/integrations/google_slides.py). DB 변경 없음. 인증은 쿠팡 시트와 같은 Google 설정을 쓰되 Drive·Slides 권한이 더 필요하다.

  1. Google Cloud Console(OAuth 클라이언트가 있는 프로젝트) → API 라이브러리에서 Google Drive API, Google Slides API 사용 설정
  2. 개발 PC에서 토큰 재발급(시트·Drive·Slides 권한을 한 번에 받는다) — 공유 드라이브에 쓸 수 있는 계정으로 로그인·동의
    python scripts/google_sheets_authorize.py --client-id <ID> --client-secret <SECRET>
    
  3. 서버 /opt/www/main/.env 의 GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN 을 새 토큰으로 바꾸고(쿠팡 시트도 같은 토큰으로 계속 동작) docker compose up -d 로 다시 띄운다. 토큰은 비밀값 — Git·메신저에 남기지 않는다.

설정이 없거나 권한이 모자라면 버튼을 눌렀을 때 사유가 안내되고(503), 회의록 다른 기능은 그대로 동작한다.

주간 회의록 항목 칸 묶음 마이그레이션 (027)

027은 goal_meeting_items.label_cont 열만 추가한다(기본 false, 기존 값 그대로, 다시 실행 가능). 미적용이면 "주요 업무" 칸의 같은 항목 칸 줄 추가·항목 칸 나누기만 503 안내, 나머지는 그대로.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_027_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_027_meeting_label_groups.sql
docker exec postgres-db psql -U postgres -d project_db -c "SELECT column_name FROM information_schema.columns WHERE table_name='goal_meeting_items' AND column_name='label_cont';"

담당자·협업자 겹침 정리 마이그레이션 (028)

028은 스키마를 바꾸지 않고, 담당자와 같은 사람인 협업자 행(task_followers)만 지운다(담당자는 협업자가 아니다 — 2026-10-13). 다시 실행해도 같고, 지운 행 수를 NOTICE 로 보여 준다. 앱은 새 코드부터 담당자를 협업자로 넣지 않으므로, 028 을 늦게 적용해도 새로 겹치는 행은 생기지 않는다(예전 겹친 행만 남음). 되돌리기 = 아래 백업에서 task_followers 만 복원.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_028_$(date +%Y%m%d%H%M).sql
docker exec postgres-db psql -U postgres -d project_db -c "SELECT COUNT(*) FROM task_followers f JOIN tasks t ON t.id = f.task_id WHERE COALESCE(t.assignee_email,'') <> '' AND lower(f.user_email) = lower(t.assignee_email);"
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_028_followers_exclude_assignee.sql

Project 옵션(시스템 전체 설정) 마이그레이션 (029)

029는 project_options 테이블만 추가한다(키 하나 = 행 하나, 기존 값 변경 없음, 다시 실행 가능). 수퍼관리자·Admin 이 Project 옵션 창에서 바꾸는 "처음 여는 탭"·"보드 카드 표지"를 모든 사용자에게 적용하는 저장소다. 행이 없으면 기본값(보드·표지 켬). 미적용이면 화면은 기본값으로 열리고, 옵션 저장만 503 안내(폰트는 브라우저 저장이라 그대로 동작). 되돌리기 = DROP TABLE project_options;(사용자 확인 후 — 저장한 시스템 설정만 사라지고 기본값으로).

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_029_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_029_project_options.sql
docker exec postgres-db psql -U postgres -d project_db -c "SELECT key, value, updated_by, updated_at FROM project_options;"

실적 수동 입력·열 순서 마이그레이션 (performance_db 002)

002는 perf_marketplaces.manual_input 열(기본 꺼짐) + perf_manual_sales 표를 추가하고, 쇼핑몰 순서(sort_order)를 카페24·네이버·쿠팡·토스·GS샵·11번가·오늘의집·G마켓·카카오·롯데ON 으로 바꾼다(기존 매출·인증정보 그대로, 다시 실행 가능). 미적용이면 수동 입력 토글·저장만 503 안내, 나머지 실적 화면은 그대로 동작한다.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres performance_db > ~/performance_db_before_002_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d performance_db < scripts/sql/performance_db_002_manual_sales.sql
docker exec postgres-db psql -U postgres -d performance_db -c "SELECT code, sort_order, manual_input FROM perf_marketplaces ORDER BY sort_order;"

실적 쇼핑몰 순서·신규 수동 입력 쇼핑몰 마이그레이션 (performance_db 003)

003은 기존 쿠팡 이름을 쿠팡(윙) 으로 바꾸고, 수동 입력 전용 쇼핑몰 쿠팡(로켓)(coupang_rocket)·애터미아자몰(atomy)을 manual_input = TRUE 로 추가하며, 순서를 카페24·네이버·쿠팡(윙)·쿠팡(로켓)·오늘의집·G마켓·카카오·GS샵·11번가·롯데ON·토스·애터미아자몰 로 바꾼다(기존 매출·인증정보 그대로, 다시 실행 가능). 002 뒤에 적용한다. 미적용이면 새 쇼핑몰 2곳만 화면에 안 나온다.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres performance_db > ~/performance_db_before_003_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d performance_db < scripts/sql/performance_db_003_marketplace_order.sql

실적 네이버 이름 마이그레이션 (performance_db 004)

004는 perf_marketplaces 의 naver 이름만 네이버 스마트스토어 → 네이버 로 바꾼다(다시 실행 가능). 미적용이면 설정 화면에 예전 이름이 남는다.

cd /opt/www/main
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d performance_db < scripts/sql/performance_db_004_naver_name.sql

실적 광고비 마이그레이션 (performance_db 005)

005는 광고비 표 perf_ad_spend 하나만 만든다(기존 표·데이터 그대로, 다시 실행 가능). 미적용이면 광고비 탭에 안내가 나오고 입력·업로드가 503.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres performance_db > ~/performance_db_before_005_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d performance_db < scripts/sql/performance_db_005_ad_spend.sql
docker exec postgres-db psql -U postgres -d performance_db -c "\d perf_ad_spend"

되돌리기(광고비 데이터만 사라짐): docker exec postgres-db psql -U postgres -d performance_db -c "DROP TABLE perf_ad_spend;"

실적 광고비 ROAS·보고서 항목 마이그레이션 (performance_db 006)

006은 perf_ad_spend 에 roas·metrics 열 두 개만 더한다(기존 값 그대로, 다시 실행 가능). 005 다음에 적용한다. 미적용이면 네이버 보고서 업로드·네이버 일자별 상세만 503 안내, 나머지 광고비 화면은 그대로.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres performance_db > ~/performance_db_before_006_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d performance_db < scripts/sql/performance_db_006_ad_roas_metrics.sql
docker exec postgres-db psql -U postgres -d performance_db -c "\d perf_ad_spend"

되돌리기(보고서 ROAS·상세만 사라짐): docker exec postgres-db psql -U postgres -d performance_db -c "ALTER TABLE perf_ad_spend DROP COLUMN metrics, DROP COLUMN roas;"

실적 광고 API 연동 마이그레이션 (performance_db 007)

007은 광고 API(구글 광고) 인증정보 표 perf_ad_credentials·연결 상태 표 perf_ad_source_status 두 개만 만든다(기존 표·데이터 그대로, 다시 실행 가능). 005·006 다음에 적용한다. 미적용이면 실적 설정 → 광고 API 연동 카드에 안내가 나오고 저장이 503, 광고비 탭은 그대로. 새 환경변수 없음 — 인증정보는 설정 화면에서 입력하고 기존 APP_ENCRYPTION_KEY 로 암호화된다.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres performance_db > ~/performance_db_before_007_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d performance_db < scripts/sql/performance_db_007_ad_api.sql
docker exec postgres-db psql -U postgres -d performance_db -c "\dt perf_ad_*"

되돌리기(광고 API 인증정보·상태만 사라짐, 가져온 광고비는 perf_ad_spend 에 남음): docker exec postgres-db psql -U postgres -d performance_db -c "DROP TABLE perf_ad_source_status, perf_ad_credentials;"

회의록 작업 등록 표 — 작업 칸 마이그레이션 (026)

026은 goal_meeting_tasks.parent_task_id 열만 추가한다(기존 값 그대로, 다시 실행 가능). 025 뒤에 적용한다. 미적용이면 작업 칸을 고를 때만 503 안내.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_026_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_026_meeting_quick_parent_task.sql
docker exec postgres-db psql -U postgres -d project_db -c "SELECT column_name FROM information_schema.columns WHERE table_name='goal_meeting_tasks' AND column_name='parent_task_id';"

회의록 작업 등록 표 마이그레이션 (025)

025는 goal_meeting_tasks 테이블만 추가한다(기존 값 그대로, 다시 실행 가능). 작업 등록 표를 주차별로 서버에 두어 모두가 같이 본다. 미적용이면 표 자리에 "마이그레이션 025 필요" 안내만 나오고(브라우저에 남은 예전 표는 지우지 않고 기다린다), 회의록 다른 기능은 그대로.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_025_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_025_meeting_quick_tasks.sql
docker exec postgres-db psql -U postgres -d project_db -c "SELECT to_regclass('goal_meeting_tasks') AS t;"

입출고 관리 DB 생성 (inout_db, 2026-10-16)

새 DB 라 기존 DB·데이터는 건드리지 않는다(초기화 SQL 은 멱등, DROP·TRUNCATE 없음). 비밀번호를 DSN 에 그대로 넣지 않는다 — @·:·/·#·% 같은 문자가 있으면 주소가 깨져 앱이 DB 를 못 찾고 (failed to resolve host '…@postgres-db') 화면은 30초 뒤 500(PoolTimeout)이 된다(2026-10-16 실제 발생). 아래처럼 URL 인코딩해서 넣는다.

cd /opt/www/main && git pull
docker exec postgres-db psql -U postgres -lqt | cut -d| -f1 | grep -w inout_db || echo "inout_db 없음 — 새로 만든다"
read -s -p "inout_app password: " APP_PWD; echo
docker exec -i postgres-db psql -U postgres -v app_password="$APP_PWD" < scripts/sql/inout_db_init.sql
ENC=$(APP_PWD="$APP_PWD" python3 -c "import os,urllib.parse;print(urllib.parse.quote(os.environ['APP_PWD'],safe=''))")
# .env 끝에 줄바꿈이 없으면 앞 줄에 붙으므로 printf 로 새 줄부터, 이미 있으면 그 줄을 바꾼다
grep -q "^INOUT_DB_URL=" .env && sed -i "s|^INOUT_DB_URL=.*|INOUT_DB_URL=postgresql://inout_app:${ENC}@postgres-db:5432/inout_db|" .env \
  || printf '\nINOUT_DB_URL=postgresql://inout_app:%s@postgres-db:5432/inout_db\n' "$ENC" >> .env
docker compose up --build -d --force-recreate web
docker exec dbx-main python -c "import os,psycopg; psycopg.connect(os.environ['INOUT_DB_URL']).execute('select 1 from inout_roles limit 1'); print('DB OK')"
curl -s http://127.0.0.1:8080/inout/health          # {"status":"ok"} — DSN 이 있다는 뜻일 뿐, 실제 연결 확인은 위 DB OK

그다음 ERP 관리자 화면에서 쓸 사람에게 입출고 관리 권한 → 입출고 관리 → 옵션에서 공장·발주 담당·입고 담당 지정. 백업: 매일 docker exec postgres-db pg_dump -U postgres inout_db > /var/backups/postgres/inout_db_$(date +%F).sql.

입출고 관리 공장 담당자 마이그레이션 (inout_db 002)

002는 inout_factories.manager(담당자) 열만 추가한다(다시 실행 가능). 예전 "담당자·연락처" 한 칸에 숫자 없이 이름만 있던 값은 담당자로 옮긴다. 미적용이면 공장 저장만 안내(발주·입고는 그대로).

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres inout_db > ~/inout_db_before_002_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d inout_db < scripts/sql/inout_db_002_factory_manager.sql
docker exec postgres-db psql -U postgres -d inout_db -c "SELECT name, manager, contact FROM inout_factories ORDER BY id;"

긴급 공지 마이그레이션 (024)

024는 urgent_notices·urgent_notice_targets·urgent_notice_acks·urgent_notice_images 테이블만 추가한다(기존 값 그대로, 다시 실행 가능). 새 환경변수 없음(PROJECT_DB_URL 연결 풀을 같이 씀). 미적용이면 /notice/ 는 "준비 필요" 안내, 공지 API 는 503, 화면 스크립트는 조용히 멈춘다. 상세는 docs/NOTICE_MODULE.md.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_024_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_024_urgent_notices.sql
docker exec postgres-db psql -U postgres -d project_db -c "SELECT to_regclass('urgent_notices') AS t;"

PC 알림 프로그램 마이그레이션 (023)

023은 notifier_links·notifier_tokens 테이블만 추가한다(기존 값 그대로, 다시 실행 가능). 미적용이면 /project/notifier 화면은 "마이그레이션 필요" 안내만, PC 알림 API 는 503.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_023_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_023_notifier.sql

내려받기 파일(선택): 개발 PC 에서 desktop/notifier/build.ps1 로 만든 dist/DBXNotifier.exe 를 서버로 옮긴 뒤 컨테이너 데이터 볼륨에 둔다. 없으면 화면에 "관리자에게 받으세요"만 나온다(공유 드라이브로 나눠 줘도 된다).

cd /opt/www/main && docker compose exec web mkdir -p /data/notifier && docker compose cp ~/DBXNotifier.exe web:/data/notifier/DBXNotifier.exe

주간 회의록 회의 완료 마이그레이션 (022)

022는 goal_meetings 에 completed_at·completed_by 열만 추가한다(기존 값 그대로, 다시 실행 가능). 미적용이면 [회의 완료] 버튼이 나오지 않고 회의록은 누구나 계속 고칠 수 있다.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_022_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_022_meeting_complete.sql

주간 회의록 정량 목표·결과 글 마이그레이션 (021)

021은 goal_meeting_items 에 target_text·result_text 열만 추가한다(기존 값 그대로, 다시 실행 가능). 미적용이면 정량 목표·결과는 예전처럼 숫자만 받는다.

cd /opt/www/main
docker exec postgres-db pg_dump -U postgres project_db > ~/project_db_before_021_$(date +%Y%m%d%H%M).sql
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d project_db < scripts/sql/project_db_021_meeting_amount_text.sql

컨테이너 관리

자산관리의 asset_db 생성은 사용자가 서버 명령으로 직접 진행한다 (2026-10-06). 이미 생성한 DB에 프로그램을 적용할 때는 초기화 SQL을 다시 실행할 필요가 없다. ASSET_DB_URL=postgresql://asset_app:<URL-encoded-password>@postgres-db:5432/asset_db를 설정한다. 원본 XML까지 DB 백업에 포함되며 별도 업로드 볼륨은 필요 없다. 자산 사진·모니터 연결·수퍼 관리자 삭제 기능을 기존 설치에 추가할 때는 asset_db 백업 후 scripts/sql/asset_db_002_photos_monitors.sql을 먼저 적용하고 web을 재빌드한다. 사진도 DB 백업에 포함된다. 실행 명령은 자산관리 설치 문서를 참조한다. DB 미설정 시에도 기존 모듈은 동작하고 자산관리에서 설정 안내/보고서 분석을 제공한다. 상태·백업 확인과 초기화 순서는 ASSET_MODULE.md 참조.

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)
INOUT_DB_URL 입출고 관리 DB DSN (예: postgresql://inout_app:<pwd>@postgres-db:5432/inout_db). 미설정 시 입출고 모듈 비활성(설정 필요 안내). 권한키 inout. 제품은 ITEMCODE_DB_URL(단품) 재사용

로컬 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로 확인)