sam-docs/guides/production-env-sync.md

운영 전환 시 .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에서 직접 수정

-- 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로 수정

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: 테넌트별 서버 모드 전환

-- 모든 테넌트를 운영 모드로 전환
UPDATE barobill_members
SET server_mode = 'production'
WHERE server_mode = 'test';

5.4 Step 3: API .env 수정

# /home/aweso/sam/api/.env

# 변경 전
BAROBILL_TEST_MODE=true

# 변경 후
BAROBILL_TEST_MODE=false

5.5 Step 4: MNG .env 수정 및 누락 항목 추가

# /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/ (유지)

# 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: 캐시 클리어 및 재시작

# 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 롤백 절차

문제 발생 시 즉시 테스트 모드로 복귀:

# 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 환경 구성
• 시스템 아키텍처
• 바로빌 카카오톡 연동

---

최종 업데이트: 2026-02-21