배포 직후 장애. "로컬·스테이징에선 됐는데 운영에서만 죽어요." 로그를 보니 운영에만 없는 환경변수, 운영 DB에만 안 적용된 스키마, 9시간 어긋난 시간 표시, 구버전 앱에서만 나는 에러가 뒤섞여 있습니다. 이 모든 건 '환경 차이'라는 한 범주입니다. PM·인프라가 이 용어들을 알면 "운영에서만"이라는 증상에서 원인을 빠르게 좁힙니다. 이 사전은 환경 차이·설정·운영 이슈 용어를 빠르게 해독합니다.
- 1환경(dev/stg/qa/uat/prod)과 프로파일·설정 외부화를 설명할 수 있다
- 2시크릿 관리(Vault/Secret)와 노출 시 대응을 설명할 수 있다
- 3버전/스키마/데이터 불일치 등 "환경 차이" 장애를 진단할 수 있다
- 4타임존(KST/UTC)·인코딩·하위호환 이슈를 식별할 수 있다
환경과 설정
dev에서 prod까지, 코드는 같고 설정만 다르게
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Dev / Stage / QA / UAT / Production Environment | 개발/스테이징/QA/사용자검수/운영 환경 | 단계별 검증 | ★★ |
| Environment Variable / Config File / Profile | 환경변수 / 설정파일 / 프로파일 | 환경별 분리 → [[twelve-factor-app]] | ★★★ |
| Externalized Config / Property Override | 설정 외부화 / 값 덮어쓰기 | 코드 동일, 설정만 | ★★ |
| Feature Toggle | 기능 토글 | → [[release-strategy]] | ★★ |
| Config Reload / Hot Reload / Cold Restart | 설정 재적용 / 무중단·재시작 | 적용 방식 | ★ |
핵심: 12-Factor대로 코드는 모든 환경에서 동일, 설정만 환경에 따라 주입합니다([[twelve-factor-app]]). 'dev/prod parity'(환경 간 차이 최소화)가 "운영에서만 죽는" 문제를 줄이는 근본 원칙입니다.
시크릿 관리
비밀을 코드에서 떼어 안전하게
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Secret Management / Vault | 비밀 중앙 관리 / 대표 도구 | 코드에 박지 말 것 | ★★★ |
| Keystore / Truststore | 내 키·인증서 / 신뢰 인증서 저장소 | TLS → [[glossary-network-security]] | ★★ |
핵심: 비밀(DB 비밀번호·API 키)을 코드/이미지에 박으면 git 이력·레이어에 영구 노출됩니다([[twelve-factor-app]]). Vault/Secret Manager로 중앙 관리하고, 노출되면 삭제가 아니라 즉시 교체(rotate) 합니다(이력엔 남으므로).
환경 차이 장애
'운영에서만'의 단골 원인들
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Version Mismatch / Dependency·Library Conflict | 버전 / 의존성·라이브러리 충돌 | 잠금파일 → [[semantic-versioning]] | ★★★ |
| Schema Mismatch / Data Mismatch | 스키마 / 데이터 불일치 | 마이그레이션 → [[migration-versioning]] | ★★ |
| Permission Issue | 권한 문제 | 파일·계정 권한 → [[file-permissions]] | ★★ |
| Encoding Issue | 인코딩 문제 | UTF-8 통일 → [[glossary-file-esign]] | ★★ |
| Timezone / Locale Issue / KST / UTC / Epoch Time/Millis / Timestamp / Date Format | 타임존·로케일·시각 표현 | UTC 저장+표시 변환 → [[data-types]] | ★★ |
핵심: "로컬은 되는데 운영은 안 됨"은 거의 항상 이 표의 항목 중 하나입니다. 버전(잠금파일 누락), 스키마(마이그레이션 미적용), 시크릿(환경변수 누락), 타임존, 인코딩을 순서대로 점검합니다.
호환성
신·구 버전이 공존할 때
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Backward / Forward Compatibility | 하위 / 상위 호환 | 구버전 클라이언트 공존 | ★★ |
| Legacy System / Deprecated API | 레거시 / 폐기예정 API | 단계적 폐기 → [[api-contract]] | ★★ |
| Breaking Change | 호환 깨는 변경 | 버전·공지 → [[semantic-versioning]] | ★★★ |
핵심: 모바일 앱(구버전 잔존)·롤링 배포(신구 공존)에선 하위호환이 필수입니다([[release-strategy]]). breaking change는 버전 분리·deprecated·공지로 다룹니다([[semantic-versioning]]·[[api-contract]]).
'운영에서만' 장애 진단 — 직접 확인
"로컬은 되는데 운영은 안 됨"은 환경 차이 5축(설정·버전·스키마·타임존·인코딩)으로 좁힙니다.
1) 설정/시크릿: 운영에만 없는 환경변수? → diff로 환경변수 비교
2) 버전: 런타임/라이브러리 버전 차이? → java -version, 잠금파일 적용?
3) 스키마: 운영 DB에 마이그레이션 미적용? → 버전 테이블 확인([[migration-versioning]])
4) 타임존: 서버 TZ가 UTC인데 변환 누락? → date, DB now()
5) 인코딩: 운영 DB charset이 UTF-8인가? → ([[mysql-features]])
diff 환경변수: prod에 PAYMENT_API_KEY 없음 → 결제 초기화 실패(운영만)
java -version: local 17 / prod 11 → UnsupportedClassVersion([[language-runtime-build]])
스키마: prod에 V12 마이그레이션 미적용 → 컬럼 없음 에러
→ '운영에서만'의 3대 원인 모두 환경 차이로 확인
diff <(env | sort) <(ssh prod 'env | sort')- 환경변수 diff에서 운영에만 빠진 키가 있으면 그게 원인 1순위 → 시크릿/설정 외부화가 환경별로 누락됐는지([[twelve-factor-app]])
- 런타임/라이브러리 버전이 환경마다 다르면 → 잠금파일·불변 이미지로 통일([[semantic-versioning]]·[[language-runtime-build]])
- "컬럼 없음/테이블 없음" 에러가 운영에서만이면 마이그레이션 미적용 → 스키마 버전 테이블 확인([[migration-versioning]])
- 시간이 9시간(또는 배수) 어긋나면 타임존 변환 누락/중복 → 저장 UTC + 표시 변환 원칙 확인([[data-types]])
상황: 새 결제 기능을 배포했는데 로컬·스테이징은 정상이고 운영에서만 결제 초기화가 실패합니다. 코드는 동일한데 운영에서만 죽습니다.
원인: 운영 환경에만 필요한 환경변수(PAYMENT_API_KEY)가 설정되지 않은 것입니다. dev/stg엔 있었지만 prod 시크릿에 추가하는 것을 빠뜨렸습니다 — 전형적 환경 차이 장애입니다([[twelve-factor-app]]).
진단:
# 환경별 설정 키 비교(값 아닌 키만)
diff <(grep -o '^[A-Z_]*' .env.stg | sort) <(ssh prod 'env' | grep -o '^[A-Z_]*' | sort)
# 운영에만 없는 키 = 범인 후보
해결: (1) 누락 시크릿을 운영 Secret Manager에 추가·재배포. (2) 근본 대응 — 설정 키 목록을 환경 간 검증하는 단계를 배포 파이프라인에 추가([[cicd-pipeline]])해, 필수 키 누락 시 배포 전에 실패하게. (3) .env.example([[twelve-factor-app]])로 필요한 키를 문서화. "운영에서만 죽는" 문제의 절반은 설정·시크릿 누락이므로, 환경 간 설정 정합성 검증을 자동화하는 것이 예방책입니다.
인프라/SRE에게 환경 차이 관리는 핵심 책임입니다 — 설정 외부화·시크릿 중앙관리(Vault)·환경 간 정합성 검증·dev/prod parity를 설계해 "운영에서만 죽는" 사고를 구조적으로 줄입니다([[twelve-factor-app]]). 마이그레이션 적용·런타임 버전 통일·타임존(UTC) 표준도 인프라가 지킵니다. PM은 이 용어로 "운영에서만 안 돼요"를 "설정/버전/스키마/타임존/인코딩 중 무엇"으로 좁혀, 정확한 담당과 빠른 복구로 연결합니다. 배포 전 환경 정합성 체크리스트는 가장 값싼 장애 예방책입니다.
다음(마지막) 용어사전에서는 프론트엔드와 UX/UI 용어를 정리합니다.