다크 모드
사설 네트워크 / 내부 호스팅
공개 CDN(sdk.turacocloud.com) 없이 SDK를 사내 nginx로 자체 호스팅하고, 위젯 iframe이 내부 chat 호스트를 가리키도록 구성하는 방법을 설명합니다. 인터넷이 차단된 폐쇄망(air-gapped) 환경을 포함합니다.
구성 요소
위젯이 동작하려면 두 가지가 내부망에서 서비스되어야 합니다.
| 구성 | 역할 | 내부 호스팅 |
|---|---|---|
SDK 번들 (msap-ai-chat.min.js) | iframe을 주입하는 초경량 로더 | nginx 정적 서빙 |
chat 위젯 앱 (/widget/:applicationKey) | 실제 채팅 UI (iframe 내부) | chat 앱 + /api 백엔드 |
SDK는 로더일 뿐이며 실제 UI는 chat 위젯 앱이 담당합니다. 따라서 SDK만 내부에 올린다고 끝이 아니라, chat 위젯 앱과 그 API도 같은 내부망에서 서비스되어야 합니다.
1. SDK 자체 호스팅
빌드 산출물(msap-ai-chat.min.js, .esm.js, .js)을 사내 nginx로 서빙하고, 임베드 페이지에서 그 내부 주소로 스크립트를 로드합니다.
html
<script src="https://sdk.내부도메인/msap-ai-chat.min.js"></script>정적 파일이므로 별도 백엔드가 필요 없습니다. CORS(Access-Control-Allow-Origin: *)와 적절한 캐시 헤더만 설정하면 됩니다.
2. iframe 위젯 호스트 지정 (iframeSrc)
SDK는 iframeSrc(위젯 origin)를 런타임에 해석합니다. 임베드 페이지(호스트 페이지)가 내부 chat 호스트를 지정하는 것이 기본 방식입니다.
해석 우선순위
SDK는 다음 순서로 위젯 origin을 결정합니다.
init({ iframeSrc })— 명시적으로 전달한 값 (최우선)window.MSAP_CHAT_IFRAME_SRC— 스크립트 로드 전에 설정한 전역 값- SDK 스크립트 origin 자동 유추 — SDK와 위젯이 같은 호스트일 때 zero-config로 동작
- 레거시 기본값 (
https://ai-chat.turacocloud.com)
방법 A — init 옵션 (권장)
호스트 페이지에서 내부 chat 주소를 직접 전달합니다.
html
<script src="https://sdk.내부도메인/msap-ai-chat.min.js"></script>
<script>
MSAPChat.init({
applicationKey: 'your-application-key',
iframeSrc: 'https://chat.내부도메인',
});
</script>방법 B — 전역 변수
여러 페이지에서 공통 주소를 쓰거나, 초기화 코드를 건드리기 어려운 경우 SDK 로드 전에 전역 변수를 설정합니다.
html
<script>
window.MSAP_CHAT_IFRAME_SRC = 'https://chat.내부도메인';
</script>
<script src="https://sdk.내부도메인/msap-ai-chat.min.js"></script>
<script>
MSAPChat.init({ applicationKey: 'your-application-key' });
</script>같은 호스트에 함께 올린 경우
SDK와 chat 위젯을 동일 origin에서 서비스한다면 위 설정 없이도 SDK가 자신의 스크립트 origin을 자동으로 사용합니다(우선순위 3). 단, 서로 다른 서브도메인(예: sdk.* 와 chat.*)이라면 방법 A 또는 B로 명시해야 합니다.
3. 폐쇄망(air-gapped) 체크리스트
인터넷이 완전히 차단된 환경에서는 런타임에 외부로 나가는 요청이 하나도 없어야 합니다.
- SDK 번들을 사내 nginx에서 서빙 (공개 CDN 미사용)
- chat 위젯 앱(
/widget)과/api백엔드를 내부망에 배포 iframeSrc를 내부 chat 호스트로 지정 (방법 A/B)- chat 위젯 앱이 외부 폰트/CDN/텔레메트리를 호출하지 않도록 점검 (폰트·에셋 self-host)
- 임베드 페이지 CSP에 내부 호스트만 허용 (아래 참고)
SDK 번들은 자급자족
SDK 번들 자체는 외부 의존성을 모두 인라인하도록 빌드되어 런타임에 추가 네트워크 요청을 하지 않습니다. 외부 호출 여부는 chat 위젯 앱 쪽을 별도로 점검해야 합니다.
4. CSP 설정
임베드 페이지에서 Content-Security-Policy를 사용하는 경우 내부 호스트를 허용합니다.
html
<meta
http-equiv="Content-Security-Policy"
content="
script-src 'self' https://sdk.내부도메인;
frame-src https://chat.내부도메인;
connect-src https://api.내부도메인;
"
/>보안 메커니즘 전반은 보안 문서를 참고하세요.