docs: [guides] 운영 전환 시 .env 동기화 절차 문서 작성
- MNG/API 간 설정 관리 아키텍처 정리 - 바로빌 DB 우선, .env 폴백 구조 문서화 - 7단계 운영 전환 절차 및 롤백 방법 - MNG .env 누락 항목 목록 정리
This commit is contained in:
김보곤
1
INDEX.md
1
INDEX.md
@@ -93,6 +93,7 @@ docs/
|
||||
| [file-storage-guide.md](guides/file-storage-guide.md) | 파일 업로드/다운로드 구현 | 파일 기능 구현 전 |
|
||||
| [item-management-migration.md](guides/item-management-migration.md) | Item 시스템 전환 가이드 | 마이그레이션 작업 전 |
|
||||
| [project-launch-roadmap.md](guides/project-launch-roadmap.md) | 런칭 준비 현황 | 런칭 관련 작업 시 |
|
||||
| [production-env-sync.md](guides/production-env-sync.md) | 운영 전환 시 .env 동기화 절차 | 테스트→운영 전환 시 |
|
||||
|
||||
### quickstart/ - 빠른 시작
|
||||
> 핵심 규칙 요약, 자주 쓰는 명령어
|
||||
|
||||
317
guides/production-env-sync.md
Normal file
317
guides/production-env-sync.md
Normal file
@@ -0,0 +1,317 @@
|
||||
# 운영 전환 시 .env 동기화 절차
|
||||
|
||||
> **작성일**: 2026-02-21
|
||||
> **상태**: 설계 확정
|
||||
|
||||
---
|
||||
|
||||
## 1. 개요
|
||||
|
||||
### 1.1 목적
|
||||
|
||||
SAM 프로젝트는 MNG과 API가 **독립적인 `.env` 파일**을 사용하되, **공유 DB**를 통해 일부 설정을 공유한다.
|
||||
테스트 → 운영 전환 시 양쪽 환경 변수를 정확히 동기화해야 서비스 장애를 방지할 수 있다.
|
||||
|
||||
### 1.2 핵심 원칙
|
||||
|
||||
- MNG과 API는 **각각 독립된 `.env`** 파일을 보유
|
||||
- 바로빌 설정은 **DB 우선, `.env` 폴백** 구조
|
||||
- 동기화 필수 항목과 프로젝트 전용 항목을 명확히 구분
|
||||
|
||||
---
|
||||
|
||||
## 2. 설정 관리 아키텍처
|
||||
|
||||
### 2.1 전체 구조
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ 공유 DB (samdb) │
|
||||
│ barobill_configs → 바로빌 CERTKEY │
|
||||
│ barobill_members → 테넌트별 서버 모드 │
|
||||
│ barobill_settings → 테넌트별 연동 설정 │
|
||||
└──────────────┬───────────────────────────┘
|
||||
│ (양쪽 모두 직접 읽음)
|
||||
┌──────────┴──────────┐
|
||||
│ │
|
||||
┌───┴──────┐ ┌──────┴───┐
|
||||
│ MNG .env │ │ API .env │
|
||||
│ (독립) │ │ (독립) │
|
||||
└──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
### 2.2 설정 로드 우선순위 (바로빌)
|
||||
|
||||
```
|
||||
1순위: DB barobill_members.server_mode (테넌트별 모드)
|
||||
↓
|
||||
2순위: DB barobill_configs 테이블 (is_active 환경 설정)
|
||||
↓
|
||||
3순위: .env BAROBILL_TEST_MODE (폴백)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 동기화 필수 항목
|
||||
|
||||
> **경고: 아래 항목은 MNG과 API 양쪽에서 동일한 값이어야 한다.**
|
||||
|
||||
### 3.1 바로빌 SOAP API
|
||||
|
||||
| 환경 변수 | MNG `.env` | API `.env` | 설명 |
|
||||
|-----------|-----------|-----------|------|
|
||||
| `BAROBILL_CERT_KEY_TEST` | ⚠️ 현재 미설정 | ✅ 설정됨 | 테스트 CERTKEY |
|
||||
| `BAROBILL_CERT_KEY_PROD` | ⚠️ 현재 미설정 | ✅ 설정됨 | 운영 CERTKEY |
|
||||
| `BAROBILL_CORP_NUM` | ⚠️ 현재 미설정 | ✅ 설정됨 | 파트너 사업자번호 |
|
||||
| `BAROBILL_TEST_MODE` | ⚠️ 현재 미설정 | `true` | 테스트/운영 전환 플래그 |
|
||||
|
||||
> **참고**: MNG의 `.env`에 바로빌 항목이 누락되어 있지만, MNG는 **DB(`barobill_configs`)를 우선 참조**하므로 현재 정상 동작한다. 단, DB에 설정이 없는 경우 `.env` 폴백이 작동하지 않는다.
|
||||
|
||||
### 3.2 내부 통신 키
|
||||
|
||||
| 환경 변수 | MNG `.env` | API `.env` | 설명 |
|
||||
|-----------|-----------|-----------|------|
|
||||
| `INTERNAL_EXCHANGE_SECRET` | ⚠️ 현재 미설정 | ✅ 설정됨 | HMAC 서버 간 검증 |
|
||||
|
||||
> **경고: 불일치 시 MNG → API HTTP 호출이 인증 실패한다.**
|
||||
|
||||
### 3.3 공유 DB 접속 정보
|
||||
|
||||
| 환경 변수 | 동기화 필수 | 설명 |
|
||||
|-----------|-----------|------|
|
||||
| `DB_HOST` | ✅ | 동일 DB 서버 |
|
||||
| `DB_PORT` | ✅ | 동일 포트 |
|
||||
| `DB_DATABASE` | ✅ | 동일 데이터베이스 |
|
||||
| `DB_USERNAME` / `DB_PASSWORD` | ✅ | 접속 계정 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 프로젝트 전용 항목 (독립 관리)
|
||||
|
||||
### 4.1 MNG 전용
|
||||
|
||||
| 환경 변수 | 설명 | 비고 |
|
||||
|-----------|------|------|
|
||||
| `API_BASE_URL` | API 서버 URL | 운영: `https://api.sam.kr` |
|
||||
| `FLOW_TESTER_API_KEY` | API 테스터 키 | API의 `api_keys` 테이블과 일치 필요 |
|
||||
| `MENU_SYNC_API_KEY` | 메뉴 동기화 키 | MNG 전용 |
|
||||
| `CHANDJ_DB_*` | 레거시 DB 접속 | MNG에서만 사용 |
|
||||
|
||||
### 4.2 API 전용
|
||||
|
||||
| 환경 변수 | 설명 | 비고 |
|
||||
|-----------|------|------|
|
||||
| `CLAUDE_API_KEY` | Claude AI API 키 | API에서만 사용 |
|
||||
| `SANCTUM_*` | 토큰 만료 설정 | API 인증 전용 |
|
||||
| `LOG_SLACK_WEBHOOK_URL` | Slack 로그 알림 | API 전용 |
|
||||
|
||||
### 4.3 양쪽 독립 설정 (동일 서비스, 각자 관리)
|
||||
|
||||
| 환경 변수 | MNG 용도 | API 용도 |
|
||||
|-----------|---------|---------|
|
||||
| `GEMINI_API_KEY` | 음성 어시스턴트, OCR | AI 리포트 생성 |
|
||||
| `VERTEX_AI_*` | 영상 생성 | 영상 생성 |
|
||||
| `GOOGLE_APPLICATION_CREDENTIALS` | STT, GCS | STT, GCS |
|
||||
| `FCM_*` | 푸시 알림 | 푸시 알림 |
|
||||
|
||||
> **참고**: 같은 키를 사용해도 무방하지만, 서비스 어카운트 **파일 경로**가 다르므로 주의
|
||||
|
||||
---
|
||||
|
||||
## 5. 운영 전환 절차
|
||||
|
||||
### 5.1 사전 준비 체크리스트
|
||||
|
||||
```
|
||||
□ 바로빌 운영 CERTKEY 발급 완료
|
||||
□ 바로빌 운영 서버 사업자번호 등록 완료
|
||||
□ Google 서비스 어카운트 운영 경로 확인
|
||||
□ Firebase 서비스 어카운트 운영 경로 확인
|
||||
□ DB 백업 완료
|
||||
```
|
||||
|
||||
### 5.2 Step 1: DB 설정 전환 (바로빌)
|
||||
|
||||
> **가장 중요한 단계.** MNG과 API 모두 DB를 우선 참조하므로 DB 설정 변경이 핵심이다.
|
||||
|
||||
**방법 A: phpMyAdmin에서 직접 수정**
|
||||
|
||||
```sql
|
||||
-- 1. 현재 설정 확인
|
||||
SELECT id, name, environment, cert_key, corp_num, base_url, is_active
|
||||
FROM barobill_configs;
|
||||
|
||||
-- 2. 테스트 서버 비활성화
|
||||
UPDATE barobill_configs
|
||||
SET is_active = 0
|
||||
WHERE environment = 'test';
|
||||
|
||||
-- 3. 운영 서버 활성화 (없으면 INSERT)
|
||||
UPDATE barobill_configs
|
||||
SET is_active = 1,
|
||||
cert_key = '운영_CERTKEY_값',
|
||||
corp_num = '운영_사업자번호',
|
||||
base_url = 'https://ws.baroservice.com'
|
||||
WHERE environment = 'production';
|
||||
```
|
||||
|
||||
**방법 B: tinker로 수정**
|
||||
|
||||
```bash
|
||||
docker exec sam-api-1 php artisan tinker --execute="
|
||||
use App\Models\Tenants\BarobillConfig;
|
||||
|
||||
// 테스트 비활성화
|
||||
BarobillConfig::where('environment', 'test')->update(['is_active' => false]);
|
||||
|
||||
// 운영 활성화
|
||||
BarobillConfig::updateOrCreate(
|
||||
['environment' => 'production'],
|
||||
[
|
||||
'name' => '운영서버',
|
||||
'cert_key' => '운영_CERTKEY_값',
|
||||
'corp_num' => '운영_사업자번호',
|
||||
'base_url' => 'https://ws.baroservice.com',
|
||||
'is_active' => true,
|
||||
]
|
||||
);
|
||||
"
|
||||
```
|
||||
|
||||
### 5.3 Step 2: 테넌트별 서버 모드 전환
|
||||
|
||||
```sql
|
||||
-- 모든 테넌트를 운영 모드로 전환
|
||||
UPDATE barobill_members
|
||||
SET server_mode = 'production'
|
||||
WHERE server_mode = 'test';
|
||||
```
|
||||
|
||||
### 5.4 Step 3: API `.env` 수정
|
||||
|
||||
```bash
|
||||
# /home/aweso/sam/api/.env
|
||||
|
||||
# 변경 전
|
||||
BAROBILL_TEST_MODE=true
|
||||
|
||||
# 변경 후
|
||||
BAROBILL_TEST_MODE=false
|
||||
```
|
||||
|
||||
### 5.5 Step 4: MNG `.env` 수정 및 누락 항목 추가
|
||||
|
||||
```bash
|
||||
# /home/aweso/sam/mng/.env 에 추가/수정
|
||||
|
||||
# ─── 바로빌 SOAP API (누락 항목 추가) ───
|
||||
BAROBILL_CERT_KEY_TEST=<테스트_CERTKEY>
|
||||
BAROBILL_CERT_KEY_PROD=<운영_CERTKEY>
|
||||
BAROBILL_CORP_NUM=<사업자번호>
|
||||
BAROBILL_TEST_MODE=false
|
||||
|
||||
# ─── 내부 통신 키 (누락 항목 추가) ───
|
||||
INTERNAL_EXCHANGE_SECRET=k8sJ2mN4pQ7rT9wX3yB6cF1hL5vZ0aE8
|
||||
```
|
||||
|
||||
### 5.6 Step 5: Google 서비스 어카운트 경로 통일
|
||||
|
||||
| 프로젝트 | 현재 경로 (레거시) | 권장 경로 |
|
||||
|---------|-----------------|----------|
|
||||
| MNG | `/var/www/sales/apikey/` | `/var/www/mng/apikey/` |
|
||||
| API | `/var/www/mng/apikey/` | `/var/www/mng/apikey/` (유지) |
|
||||
|
||||
```bash
|
||||
# MNG .env 수정 (레거시 경로 → 통일 경로)
|
||||
# 변경 전
|
||||
GOOGLE_APPLICATION_CREDENTIALS=/var/www/sales/apikey/google_service_account.json
|
||||
|
||||
# 변경 후
|
||||
GOOGLE_APPLICATION_CREDENTIALS=/var/www/mng/apikey/google_service_account.json
|
||||
```
|
||||
|
||||
### 5.7 Step 6: 캐시 클리어 및 재시작
|
||||
|
||||
```bash
|
||||
# API 캐시 클리어
|
||||
docker exec sam-api-1 php artisan config:clear
|
||||
docker exec sam-api-1 php artisan cache:clear
|
||||
|
||||
# MNG 캐시 클리어
|
||||
docker exec sam-mng-1 php artisan config:clear
|
||||
docker exec sam-mng-1 php artisan cache:clear
|
||||
|
||||
# 서버 환경에서는
|
||||
ssh sam-server "cd /home/webservice/api && php artisan config:clear && php artisan cache:clear"
|
||||
ssh sam-server "cd /home/webservice/mng && php artisan config:clear && php artisan cache:clear"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 전환 후 검증 체크리스트
|
||||
|
||||
### 6.1 바로빌 API 검증
|
||||
|
||||
```
|
||||
□ MNG 세금계산서 발행 페이지 → 서버 모드 "운영" 표시 확인
|
||||
□ 바로빌 잔액 조회 정상 응답 확인
|
||||
□ 홈택스 매출/매입 조회 정상 확인
|
||||
□ 세금계산서 테스트 발행 → 국세청 전송 확인
|
||||
□ API 바로빌 엔드포인트 정상 응답 확인
|
||||
```
|
||||
|
||||
### 6.2 외부 서비스 검증
|
||||
|
||||
```
|
||||
□ Gemini AI 음성 어시스턴트 동작 확인 (MNG)
|
||||
□ FCM 푸시 알림 전송 확인 (MNG/API)
|
||||
□ Google STT/GCS 파일 업로드 확인
|
||||
□ MNG → API HTTP 호출 인증 성공 확인
|
||||
```
|
||||
|
||||
### 6.3 롤백 절차
|
||||
|
||||
문제 발생 시 즉시 테스트 모드로 복귀:
|
||||
|
||||
```bash
|
||||
# 1. DB 복구
|
||||
UPDATE barobill_configs SET is_active = 1 WHERE environment = 'test';
|
||||
UPDATE barobill_configs SET is_active = 0 WHERE environment = 'production';
|
||||
UPDATE barobill_members SET server_mode = 'test';
|
||||
|
||||
# 2. .env 복구
|
||||
# API: BAROBILL_TEST_MODE=true
|
||||
# MNG: BAROBILL_TEST_MODE=true
|
||||
|
||||
# 3. 캐시 클리어
|
||||
docker exec sam-api-1 php artisan config:clear
|
||||
docker exec sam-mng-1 php artisan config:clear
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. MNG `.env` 현재 누락 항목 요약
|
||||
|
||||
> **경고: 현재 MNG `.env`에 아래 항목이 누락되어 있다. DB 폴백으로 동작하지만, 안정성을 위해 추가를 권장한다.**
|
||||
|
||||
| 환경 변수 | 상태 | 위험도 | 설명 |
|
||||
|-----------|------|--------|------|
|
||||
| `BAROBILL_CERT_KEY_TEST` | ❌ 누락 | 🟡 중요 | DB 폴백 시 빈값 |
|
||||
| `BAROBILL_CERT_KEY_PROD` | ❌ 누락 | 🟡 중요 | DB 폴백 시 빈값 |
|
||||
| `BAROBILL_CORP_NUM` | ❌ 누락 | 🟡 중요 | DB 폴백 시 빈값 |
|
||||
| `BAROBILL_TEST_MODE` | ❌ 누락 | 🟡 중요 | 기본값 `true` 사용 중 |
|
||||
| `INTERNAL_EXCHANGE_SECRET` | ❌ 누락 | 🔴 필수 | 서버 간 HMAC 검증 실패 가능 |
|
||||
| `GEMINI_API_KEY` | 빈값 | 🟡 중요 | 음성 어시스턴트 미작동 |
|
||||
| `FCM_PROJECT_ID` | 빈값 | 🟡 중요 | 푸시 알림 미작동 |
|
||||
|
||||
---
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- [Docker 환경 구성](../specs/docker-setup.md)
|
||||
- [시스템 아키텍처](../architecture/system-overview.md)
|
||||
- [바로빌 카카오톡 연동](../features/barobill-kakaotalk/README.md)
|
||||
|
||||
---
|
||||
|
||||
**최종 업데이트**: 2026-02-21
|
||||
Reference in New Issue
Block a user