---
type: knowledge
domain: infra
status: active
last-reviewed: 2026-07-27
---

# 폐쇄망·온프레미스 실전

> 한 줄 정의
> 폐쇄망은 "인터넷이 느린 환경"이 아니라 **인터넷이 없다는 전제로 아키텍처를 다시 세워야 하는 환경**이다. 외부 API 호출 가능 여부는 착수 시점에 확인한다는 원칙은 [[인프라 원리]] — 여기는 발주사 폐쇄망(외주 단골 제약)에서의 실전 절차다.

## 패키지·이미지 공급 — 인터넷 없는 빌드

| 대상 | 폐쇄망 공급 방식 |
|------|----------------|
| 언어 패키지 (pip·npm 등) | 내부 미러 저장소, 또는 의존성 전체를 오프라인 번들로 반입 |
| 컨테이너 이미지 | 내부 레지스트리 — 외부 레지스트리 pull은 처음부터 불가로 가정 |
| OS 패키지·패치 | 내부 미러 + 정기 반입 주기 |
| 베이스 이미지·런타임 | 승인된 버전 목록을 내부에 보관 — "최신으로 올리면 되죠"가 안 되는 환경 |

- 의존성 하나 추가가 폐쇄망에선 **반입 절차 하나**다 — 의존성 최소화가 폐쇄망에선 생존 규율이 된다.
- 빌드는 내부 미러만으로 완결돼야 한다. 빌드 스크립트 어딘가의 외부 URL 하나가 폐쇄망 빌드 전체를 깨뜨린다 — 개발망에서 미리 "외부 차단 상태로 빌드" 리허설을 한다.

## 반입 절차 — 리드타임은 일정이다

- 전형적 절차: 반입 신청 → 발주사 보안 검토(백신·라이선스·취약점) → 승인 → 매체(승인된 USB·중계 서버) 반입 → 반입 대장 기록.
- **리드타임(수일~수주)을 일정에 명시적으로 반영한다.** "패키지 하나 받는 데 2주"는 폐쇄망에선 정상 범주다 — 반입 필요 목록을 초기에 최대한 모아 한 번에 신청하는 것이 반복 신청보다 압도적으로 싸다.
- 반출도 같은 절차의 역방향이며 더 엄격하다 — **소스·데이터·로그의 무단 반출은 계약 사고다** (개인 메일·USB·외부 저장소 업로드 전부). 반출이 필요하면 발주사 승인 절차를 탄다.

## 외부 SaaS 대안 표

| 외부 SaaS | 폐쇄망 대안 |
|-----------|------------|
| APM·에러 수집 (Sentry류) | 자가 수집 엔드포인트 + 내부 저장 → [[프론트엔드 에러 처리와 관측]], 지표 설계는 [[관측성 실전]] |
| 매니지드 큐·메시징 | 내부 브로커 설치, 또는 규모가 작으면 DB 테이블 큐 → [[백그라운드 작업과 스케줄링]] |
| 외부 LLM API | 발주사 승인 내부 게이트웨이만 — 게이트웨이의 모델·한도가 아키텍처 제약이 된다 |
| 외부 인증 (소셜 로그인 등) | 발주사 SSO·내부 IdP 연동 |
| CDN·외부 폰트·외부 스크립트 | 전부 내부 서빙 — HTML의 외부 URL 한 줄이 폐쇄망에서 무한 로딩을 만든다 |
| 알림 (메일·메신저 SaaS) | 발주사 내부 메일·메신저 중계 |

대안 선택 원칙: **발주사가 이미 운영 중인 것을 먼저 쓴다.** 수행사가 새 인프라를 반입해 세우면 그 운영 부담이 하자보수 기간 내내 수행사에 남는다.

## 시간 동기·인증서 — 폐쇄망의 조용한 시한폭탄

- **NTP**: 외부 시간 서버가 안 보이므로 내부 NTP를 확인하고 전 서버가 바라보게 한다 — 시계가 어긋나면 토큰 검증 실패·로그 순서 붕괴 같은 "귀신 같은" 장애가 난다.
- **인증서**: 공인 CA 발급·자동 갱신(ACME)이 안 되는 환경이 많다 — 내부 CA 체인을 전 서버·클라이언트에 배포하고, **만료일 대장 + 만료 전 알림**을 만든다. 폐쇄망 장애 단골 1위가 조용히 만료된 내부 인증서다.
- OS·브라우저의 인증서 검증 실패를 코드에서 검증 비활성화로 덮는 것은 금지 — 내부 CA 신뢰 배포가 정답이다.

## 개발망 ↔ 운영망 분리와 소스 이동

- 개발망과 운영망이 분리된 경우, 소스·아티팩트의 이동도 반입 절차를 탄다 — **이동 단위·주기·승인자를 착수 시점에 합의**하지 않으면 "하루 한 번 반입"이 배포 주기의 상한이 된다.
- 운영망에서의 직접 수정(핫픽스) 유혹이 크다 — 수정본이 개발망 소스에 반영되지 않으면 다음 반입이 핫픽스를 되돌린다. 운영망 수정은 반드시 개발망 역반영 절차와 세트다.
- 파이프라인이 망 경계에서 끊기는 지점(개발망 CI까지 자동, 반입 후 운영망 배포)을 명시적으로 설계한다 → [[CI-CD 파이프라인 실전]].

## "로컬에선 됐는데" — 원인 1순위는 망 차이

- 폐쇄망 이슈의 첫 용의자는 코드가 아니라 **망**이다: 외부 URL 접근, DNS, 프록시, 방화벽 포트, 내부 CA 미신뢰.
- 대응: 착수 초기에 **접근 가능 목록**(허용 도메인·포트·프록시 설정)을 발주사에서 받아 문서화하고, 헬스체크에 핵심 연동 대상 접근성을 포함한다 → [[관측성 실전]].
- 외부 접근이 필요한 새 기능은 개발 전에 방화벽 오픈 신청부터 — 개발 완료 후 "안 열려요"는 일정 사고다.

## 안티패턴

- **개발은 인터넷 되는 데서 하고 폐쇄망은 배포 때 처음 만난다** — 반입·망·인증서 이슈가 오픈 직전에 한꺼번에 터진다. 폐쇄망 리허설은 중간 산출물이다.
- **의존성 자동 업데이트 설정 방치** — 폐쇄망에서 업데이트 체크가 타임아웃으로 기동을 지연시키거나 실패시킨다. 오프라인 모드를 명시한다.
- **"임시로 제 핫스팟 연결해서"** — 망 분리 우회는 편의가 아니라 보안 사고이자 계약 위반이다.
- **반입 리드타임 없는 일정표** — 폐쇄망 프로젝트 일정 지연의 구조적 원인.

## 관련 문서

- [[00_인프라 허브]] — 08_인프라 진입점
- [[인프라 원리]] — 외부 API 가능 여부는 착수 시점 확인
- [[환경 구성과 시크릿 관리]] — 발주사 계정·키 관리, 환경 동등성
- [[CI-CD 파이프라인 실전]] — 망 경계에서의 파이프라인 설계
- [[관측성 실전]] — 폐쇄망 자가 관측 구성
- [[프론트엔드 에러 처리와 관측]] — 자가 수집 엔드포인트
- [[보안 원리]] — 최소 권한·반출입 통제의 원천