A "회의록 보드" button next to attendees opens the week's Google Slides deck in its own window. The deck is found (Drive appProperties) or created in the shared drive MEETING_BOARD_FOLDER_ID as one BLANK slide, named like "10월 2주차 (10/5~10/11)". Needs a token with Drive and Slides scopes; the authorize script now requests them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
12 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 권한이 더 필요하다.
- Google Cloud Console(OAuth 클라이언트가 있는 프로젝트) → API 라이브러리에서 Google Drive API, Google Slides API 사용 설정
- 개발 PC에서 토큰 재발급(시트·Drive·Slides 권한을 한 번에 받는다) — 공유 드라이브에 쓸 수 있는 계정으로 로그인·동의
python scripts/google_sheets_authorize.py --client-id <ID> --client-secret <SECRET> - 서버
/opt/www/main/.env의GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN을 새 토큰으로 바꾸고(쿠팡 시트도 같은 토큰으로 계속 동작)docker compose up -d로 다시 띄운다. 토큰은 비밀값 — Git·메신저에 남기지 않는다.
설정이 없거나 권한이 모자라면 버튼을 눌렀을 때 사유가 안내되고(503), 회의록 다른 기능은 그대로 동작한다.
주간 회의록 정량 목표·결과 글 마이그레이션 (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) |
로컬 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 데이터가 깨진 경우 (사용자 승인 필수)
- 즉시 트래픽 차단 (NPM 비활성화 또는 점검 페이지)
- 가장 최근 백업 확인
- 새 DB 이름으로 먼저 복구해 검증
- 검증 완료 후 운영 DB 교체
- 복구 후 로그/주문 정합성 점검
운영 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 덮어쓰기 / 삭제 |
인증·세션 붕괴 |
원칙:
- 실행 전 현재 상태 확인 명령을 먼저 보여준다.
- 백업 위치를 명시한다.
- 사용자 명시 승인 후에만 실행한다.
점검 체크리스트
docker compose ps모든 서비스runningdocker compose logs --tail=200에러 없음https://dbx.no1king.freeddns.org200 응답- Google 로그인 정상 동작
- PostgreSQL 컨테이너 볼륨 마운트 정상
- 최근 DB 백업 존재 여부
.env미커밋 상태 (git status로 확인)