king
9e707be5ac
- app/modules/cupang: router/db/store/itemcode + 템플릿 5종 - cupang_db 전용(JSON 폴백 없음). CUPANG_DB_URL 미설정 시 안내 페이지 - 월간 달력 + 출고 묶음(헤더+라인), 박스 입수량 자동계산(서버 재계산) - 입고센터 관리(사용중 soft delete), 박스규칙 upsert, 엑셀 내보내기 - 상품 검색은 itemcode_db 읽기 전용(미설정 시 수동 입력) - MODULE_KEYS/메뉴/아이콘/라벨 동기화, scripts/sql/cupang_db_init.sql(멱등) - app/data/ gitignore 추가(PII) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
193 lines
6.0 KiB
Markdown
193 lines
6.0 KiB
Markdown
# 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
|
|
```
|
|
|
|
---
|
|
|
|
## 컨테이너 관리
|
|
|
|
```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:<pwd>@postgres-db:5432/expense_db`). 미설정 시 JSON 폴백 |
|
|
| `CUPANG_DB_URL` | 쿠팡 밀크런 DB DSN (예: `postgresql://cupang_app:<pwd>@postgres-db:5432/cupang_db`). **필수** — 미설정 시 모듈 비활성(설정 필요 안내) |
|
|
| `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}/` 에 저장 |
|
|
|
|
---
|
|
|
|
## 로컬 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`로 확인)
|