按 IP 限制本地部署的访问
本页面向本地部署 MonoChat 的运维人员。它说明如何在网络层（nginx 或防火墙）将网页应用限制在您自己的网络内，同时不阻止必须从互联网调用 MonoChat 的服务。
MonoChat 自身没有 IP 白名单。限制设置在您的 nginx、负载均衡器或防火墙中，作用于整个安装，而不是单个组织。
哪些要限制，哪些要保持开放
| 仅限您的网络访问 | 保持可从互联网访问 |
|---|---|
| 网页应用以及右侧未列出的所有内容 | 下表中的 Webhook 和回调路径 |
网页应用所连接的 DDP/WebSocket 端点（/websocket） |
请同时限制网页界面和 WebSocket 端点：应用会同时使用两者。对其他所有人只允许下列路径，并阻止其余路径。
外部服务调用的路径
下列每个路径都由 MonoChat 服务器注册。由设置构建的路径是您在服务器上配置的 hookPath（位于服务器设置的 channelConnectors.<name> 或 paymentSystemConnectors.<name> 中），后缀由代码添加。只需开放您使用的连接器。
渠道
| 路径 | 调用方 | 定义位置 |
|---|---|---|
<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 from 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 的 Webhook 监听器，再由监听器转发到上面的 /webhooks 路径。如果您自行运行 omni-message，其 Webhook 监听器必须能从互联网通过这些路径访问：/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/ 以及两个渠道弹窗路径。渠道弹窗路径在连接账号的人员的浏览器中打开，因此如果只有您网络内的人员连接渠道，它们可以保持受限。只有当您的客服人员在网络之外使用 MonoChat 移动应用时，才需要开放 /api/status 和两个 /.well-known 文件。
使用提供商登录（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设置为应用前面的代理数量。它由 Meteor 框架读取，而不是由 MonoChat 代码读取，因此应放在您的部署设置中，而不是设置 JSON 中。
检查您的配置
- 在不被允许的网络中打开网页应用，它必须被拒绝。
- 在允许的网络中登录并打开收件箱。消息必须能够加载，这证明 WebSocket 端点对您是开放的。
- 从您的网络之外向已连接的渠道发送一条测试消息，并确认它到达收件箱。
- 为一个小额测试订单创建支付链接，完成支付，并确认订单显示为已支付。
每次修改代理规则后都要测试这些路径。被阻止的 Webhook 路径不会在 MonoChat 中显示错误：消息和支付确认只是不再到达。