IP로 온프레미스 설치 제한하기
이 페이지는 온프레미스 MonoChat 설치를 운영하는 담당자를 위한 문서입니다. 인터넷에서 MonoChat을 호출해야 하는 서비스를 차단하지 않으면서, 네트워크 수준(nginx 또는 방화벽)에서 웹 앱을 자사 네트워크로 제한하는 방법을 설명합니다.
MonoChat에는 자체 IP 허용 목록 기능이 없습니다. 제한은 nginx, 로드밸런서 또는 방화벽에서 설정하며, 단일 워크스페이스가 아니라 설치 전체에 적용됩니다.
제한할 것과 열어 둘 것
| 자사 네트워크로 제한할 것 | 인터넷에서 접근 가능하게 둘 것 |
|---|---|
| 웹 앱과 오른쪽에 나열되지 않은 모든 것 | 아래 표에 나오는 웹훅 및 콜백 경로 |
웹 앱이 연결하는 DDP/WebSocket 엔드포인트(/websocket) |
웹 UI와 WebSocket 엔드포인트는 앱이 둘 다 사용하므로 함께 제한하세요. 그 외의 모든 사용자에게는 아래 경로만 허용하고 나머지는 차단합니다.
외부 서비스가 호출하는 경로
아래 경로는 모두 MonoChat 서버가 등록합니다. 설정에서 만들어지는 경로는 서버 설정(channelConnectors.<name> 또는 paymentSystemConnectors.<name>)에서 지정한 hookPath이며, 뒤에 붙는 부분은 코드가 추가합니다. 사용하는 커넥터의 경로만 열어 두세요.
채널
| 경로 | 호출하는 곳 | 정의된 위치 |
|---|---|---|
<hookPath>/webhooks (POST) | omni-message (WhatsApp Cloud, WhatsApp Gupshup, Instagram, Messenger, Telegram, TikTok, Twilio SMS, Varan OTP용) | packages/app-connectors-om2-*/src/webhooks/webhook.ts, hookPath의 출처는 channelConnectors.whatsappBusinessVegaCloud, whatsappBusinessVegaGupshup, instagramCastor, messengerRigel, telegramBotRegulus, tikTokTimir, twilioSms, varanOtp |
<hookPath>/webhooks, <hookPath>/sessions, <hookPath>/messages (POST) | Messages API 채널을 통한 자사 시스템 | channelConnectors.messagesApi.hookPath, packages/app-connectors-messages-api/src/webhooks/webhook.ts |
<hookPath>/message, <hookPath>/info (POST) | Chatwoot | channelConnectors.chatwoot.hookPath, packages/app-connectors-chatwoot/src/webhook.ts |
<hookPath>/inbound (POST) | SIP 제공업체(일반 SIP 및 Sonitel SIP 채널) | channelConnectors.genericSip.hookPath, channelConnectors.sonitelSip.hookPath |
/api/facebook/channels/:channelId/flows/:flowId (POST) | WhatsApp(WhatsApp Flows용) | server/api/whatsapp-flow.js |
채널 제공업체(Meta, Telegram, TikTok, Twilio)는 MonoChat을 직접 호출하지 않습니다. omni-message 웹훅 리스너를 호출하고, 리스너가 위의 /webhooks 경로로 전달합니다. omni-message를 직접 운영한다면 웹훅 리스너가 다음 경로에서 인터넷으로부터 접근 가능해야 합니다: /webhooks/meta-messenger, /webhooks/instagram-business, /webhooks/wab-cloud, /webhooks/wab-gupshup/:channelId, /webhooks/wab-360-dialog/:channelId, /webhooks/telegram-bot/:channelId, /webhooks/tiktok, /webhooks/twilio-sms/:channelId(omni-message의 apps/webhook-listener/src/modules/webhook-listeners/webhook-listeners.controller.ts). MonoChat 자체도 omni-message에서 위의 /webhooks 경로로 접근 가능해야 합니다.
결제 시스템
결제 제공업체는 고객이 결제하면 콜백을 보내고, 그 뒤 고객을 MonoChat으로 되돌려 보냅니다. 두 가지 모두 네트워크 외부에서 동작해야 합니다.
| 커넥터 | hookPath(paymentSystemConnectors.<name>.hookPath) 아래 경로 |
|---|---|
| Stripe | /webhook/:clientId (POST), /return/success/:paymentSystemId, /return/cancel/:paymentSystemId |
| HyperPay | /pay/:clientId/:paymentSystemOrderId, /result/:clientId/:paymentSystemOrderId |
| Mamo | /webhook/:clientId (POST), /return/:clientId/:paymentSystemOrderId |
| Midtrans | /webhook/:clientId (POST), /return/:paymentSystemOrderId |
| Paymob | /webhook/:clientId (POST), /return/:paymentSystemOrderId |
| PayTabs | /callback/:clientId/:paymentSystemOrderId (POST), /return/:paymentSystemOrderId |
| Tabby | /webhook/:clientId (POST), /return/:paymentSystemOrderId/:status |
| Tamara | /webhook/:clientId (POST), /return/:paymentSystemOrderId/:status |
| Tap | /webhook/:clientId (POST), /return/:clientId/:paymentSystemOrderId |
| Telr | /webhook/:clientId/:paymentSystemOrderId (POST), /return/:paymentSystemOrderId/:status |
| Ziina | /return/:clientId/:paymentSystemOrderId/:status |
| iyzico | /:transactionId (POST) |
| JCC | /:status |
| MyFatoorah | hookPath 자체 (POST), /:paymentSystemOrderId/:status (POST) |
| N-Genius | hookPath 자체 (POST), /:paymentSystemOrderId/:status |
| Paywall | /:paymentSystemOrderId/:status |
| UniqoPay | hookPath 자체 (POST), /:paymentSystemOrderId/:status (POST) |
| VakıfBank Sanal POS | /:status (GET 및 POST) |
| İş Yerim POS | hookPath 자체 (GET 및 POST) |
가장 간단한 규칙은 사용하는 결제 커넥터마다 <hookPath>와 그 아래 모든 경로를 여는 것입니다. 각 정의 위치는 packages/app-connectors-<name>/src/webhook.ts입니다.
기타 서버 엔드포인트
| 경로 | 용도 | 정의된 위치 |
|---|---|---|
/api/:slug/custom-functions/… (POST) | 액세스 토큰으로 HTTP를 통해 커스텀 함수 호출 | lib/managers/custom-function-sdk/_/server/endpoint.js |
/api/ai-agent/mcp, /api/ai-agent/events (POST) | AI 에이전트 실행 결과를 MonoChat에 보고 | server/api/ai-agent.ts |
/api/channels-manager/facebook/auth, /api/channels-manager/tiktok/auth (GET) | Facebook 또는 TikTok 계정을 연결한 뒤 돌아오는 팝업 | packages/app-managers-channel/src/webhook.ts |
/l/:_id (GET) | 고객에게 보내는 단축 링크 | server/api/short-link.js |
/api/status (GET) | 모바일 앱이 서버와 로그인 옵션을 확인 | server/api/status.js |
/.well-known/assetlinks.json, /.well-known/apple-app-site-association (GET) | Android 및 iOS 앱 링크 | server/api/assetlinks.js, server/api/apple-app-site-association.js |
네트워크 외부에서 이러한 기능을 사용한다면 /api/:slug/custom-functions, /api/ai-agent, /l/과 두 개의 채널 팝업 경로를 열어 두세요. 채널 팝업 경로는 계정을 연결하는 사람의 브라우저에서 열리므로, 사내 네트워크의 사용자만 채널을 연결한다면 제한된 상태로 두어도 됩니다. /api/status와 두 개의 /.well-known 파일은 상담원이 네트워크 외부에서 MonoChat 모바일 앱을 사용하는 경우에만 여세요.
제공업체로 로그인(OAuth)
로그인 제공업체가 브라우저를 MonoChat으로 다시 리디렉션할 때, 이 리디렉션은 로그인하는 사람의 일반 브라우저 요청이므로 웹 앱과 같은 제한을 따릅니다. 이 방식으로 로그인하는 사람이 리디렉션 경로에 접근할 수 있도록 하세요. 경로는 서버 설정의 public.oauth.<provider>에 있는 redirectPath 값입니다(기본 예시는 /api/oauth/google/redirect, /api/oauth/microsoft/redirect, /api/oauth/facebook/redirect, /api/oauth/apple/redirect). Apple 로그인은 브라우저를 POST(responseMode: form_post)로 되돌려 보내며, 같은 경로가 이를 받습니다. 모바일 앱의 경우 서버는 /api/oauth/facebook/mobile, /api/oauth/microsoft/mobile, /auth/oauth-callback/<provider>에도 응답합니다(server/configs/oauth/mobile.ts).
Microsoft Marketplace 연동을 사용한다면 microsoftMarketplace.redirectWebhookPath의 경로가 Microsoft Marketplace 요청을 받으므로 인터넷에서 접근 가능해야 합니다(server/configs/microsoft-marketplace/webook.ts).
프록시를 통해 실제 클라이언트 IP 전달하기
MonoChat은 세션과 상태 로그를 위해 클라이언트 IP를 기록합니다. 리버스 프록시나 로드밸런서 뒤에서는 실제 주소를 전달하지 않으면 프록시의 주소만 보입니다.
- nginx(또는 로드밸런서)가 원래 주소를
X-Forwarded-For헤더로 보내도록 설정합니다. 예:proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;. - MonoChat 서버의 환경 변수
HTTP_FORWARDED_COUNT를 앱 앞에 있는 프록시의 수로 설정합니다. 이 값은 MonoChat 코드가 아니라 Meteor 프레임워크가 읽으므로, 설정 JSON이 아니라 배포 설정에 넣어야 합니다.
설정 확인하기
- 허용되지 않은 네트워크에서 웹 앱을 열어 보세요. 접속이 거부되어야 합니다.
- 허용된 네트워크에서 로그인하고 받은 편지함을 여세요. 메시지가 로드되어야 하며, 이는 WebSocket 엔드포인트가 열려 있다는 증거입니다.
- 네트워크 외부에서 연결된 채널로 테스트 메시지를 보내고 받은 편지함에 도착하는지 확인하세요.
- 소액의 테스트 주문에 대한 결제 링크를 만들어 결제하고, 주문이 결제 완료로 표시되는지 확인하세요.
프록시 규칙을 변경할 때마다 경로를 테스트하세요. 차단된 웹훅 경로는 MonoChat에 오류를 표시하지 않습니다. 메시지와 결제 확인이 도착하지 않을 뿐입니다.