# Deployment ## 기본 배포 흐름 ```text [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 비밀번호 등) --- ## 최초 배포 ```bash # 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 ``` --- ## 업데이트 배포 ```bash 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` 열을 추가하며, 다시 실행할 수 있다. 미적용 시 다른 셀 편집은 가능하지만 병합은 사용할 수 없다. ```bash 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 뒤에 된다. ```bash 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 권한을 한 번에 받는다) — 공유 드라이브에 쓸 수 있는 계정으로 로그인·동의 ```bash python scripts/google_sheets_authorize.py --client-id --client-secret ``` 3. 서버 `/opt/www/main/.env` 의 `GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN` 을 새 토큰으로 바꾸고(쿠팡 시트도 같은 토큰으로 계속 동작) `docker compose up -d` 로 다시 띄운다. 토큰은 비밀값 — Git·메신저에 남기지 않는다. 설정이 없거나 권한이 모자라면 버튼을 눌렀을 때 사유가 안내되고(503), 회의록 다른 기능은 그대로 동작한다. ## PC 알림 프로그램 마이그레이션 (023) 023은 `notifier_links`·`notifier_tokens` 테이블만 추가한다(기존 값 그대로, 다시 실행 가능). 미적용이면 `/project/notifier` 화면은 "마이그레이션 필요" 안내만, PC 알림 API 는 503. ```bash 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` 를 서버로 옮긴 뒤 컨테이너 데이터 볼륨에 둔다. 없으면 화면에 "관리자에게 받으세요"만 나온다(공유 드라이브로 나눠 줘도 된다). ```bash 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` 열만 추가한다(기존 값 그대로, 다시 실행 가능). 미적용이면 [회의 완료] 버튼이 나오지 않고 회의록은 누구나 계속 고칠 수 있다. ```bash 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` 열만 추가한다(기존 값 그대로, 다시 실행 가능). 미적용이면 정량 목표·결과는 예전처럼 숫자만 받는다. ```bash 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:@postgres-db:5432/asset_db`를 설정한다. 원본 XML까지 DB 백업에 포함되며 별도 업로드 볼륨은 필요 없다. 자산 사진·모니터 연결·수퍼 관리자 삭제 기능을 기존 설치에 추가할 때는 `asset_db` 백업 후 `scripts/sql/asset_db_002_photos_monitors.sql`을 먼저 적용하고 web을 재빌드한다. 사진도 DB 백업에 포함된다. 실행 명령은 [자산관리 설치 문서](ASSET_MODULE.md#기존-설치에-사진모니터삭제-기능-적용)를 참조한다. DB 미설정 시에도 기존 모듈은 동작하고 자산관리에서 설정 안내/보고서 분석을 제공한다. 상태·백업 확인과 초기화 순서는 [ASSET_MODULE.md](ASSET_MODULE.md#저장소와-설치) 참조. ```bash 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:@postgres-db:5432/expense_db`). 미설정 시 JSON 폴백 | | `CUPANG_DB_URL` | 쿠팡 밀크런 DB DSN (예: `postgresql://cupang_app:@postgres-db:5432/cupang_db`). **필수** — 미설정 시 모듈 비활성(설정 필요 안내) | | `VACATION_DB_URL` | 휴가 관리 DB DSN (예: `postgresql://vacation_app:@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:@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 테스트 ```powershell # 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` 추가 필요. --- ## 복구 절차 ### 컨테이너만 깨진 경우 ```bash 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`로 확인)