Chatwoot私有化部署实战：Docker搭建客服后台，cpolar公网访问与网页SDK集成

Chatwoot私有化部署实战：Docker搭建客服后台，cpolar公网访问与网页SDK集成

前言

如果要在已有网站中加入在线客服，前端那段 JavaScript 只负责加载聊天组件，真正的难点往往在后面：客服服务如何部署、数据库和邮件怎么配置、内网地址怎样被公网网页访问、消息能否从前台准确送达后台。只复制一段 SDK 并不能替代这些基础工作。对于有 NAS 的开发者而言，把 Chatwoot 放在自有设备上，是一条可以验证和维护的实现路径。

Chatwoot 是开源客服平台，网页聊天、会话管理和坐席协作可以围绕同一后台组织。本文不把“开源”理解为所有商业及 AI 功能都免费，也不把“私有化”当作免维护的安全承诺，而是按照实操顺序把各环节接起来。先在绿联 NAS 上开启 SSH，通过原文所用的第三方部署脚本安装服务，并完成 SMTP 与管理员初始化；然后借助 cpolar 将本地 4000 端口映射到 HTTPS 公网地址，按需设置固定域名。

接下来创建网站收件箱，获取包含 BASE_URL 和 websiteToken 的官方 JavaScript SDK，把它放进网页，完成发送、接收和回复测试，最后添加新客服。文中保留安装命令、界面截图、SDK 示例及关键配置位置，便于照着复现，也会把第三方脚本、固定域名条件和公网运行的注意事项交代清楚。

1 Chatwoot：把网站咨询接进自己的后台

Chatwoot 是基于 Ruby on Rails 与 Vue.js 构建的开源客服平台。它不只提供一个网页聊天气泡，更重要的是收件箱：访客从不同渠道发来的消息可以按照已接入的渠道归集，客服在统一界面中查看、分配和回复。

对于网站经营者而言，最容易先落地的是网页实时聊天；后续还可按照实际需要连接邮件、社交平台等渠道。客服也可以通过支持的移动端或网页端处理消息，不必始终守在一台电脑前。

结合原文的功能展示，可以重点关注以下几类能力：

• 网页和多渠道会话：网站聊天、邮件以及部分外部消息渠道，具体接入方式取决于对应平台的授权与配置。
• 多人协作：坐席分配、内部备注、提醒和会话管理，让问题能够交到合适的人手里。
• 访客与会话资料：保留联系人信息、历史对话及标签，便于持续跟进。
• 帮助中心与数据分析：根据所用版本和实际配置，建设常见问题入口并查看相关报表。
• 扩展与集成：可以结合业务需要对接其他系统；AI 助手 Captain 属于需要另行核对授权及费用的能力。

这里需要区分 免费自托管社区版 与付费功能：社区版可自行部署，但 AI、高级权限等功能是否可用，应以所选版本和当时的官方说明为准。自有设备的硬件、存储、网络和运维也仍有成本。

2 在绿联 NAS 上部署 Chatwoot

演示环境是一台支持 Docker 的绿联 NAS，并通过 SSH 在终端完成安装。群晖、极空间及 Linux 服务器可参考相同思路，但目录、权限、容器环境和系统界面可能不同，不能把截图中的路径直接视作所有设备的默认值。

本篇沿用原文提供的自动化部署脚本。它不是 Chatwoot 官方安装器，运行前应检查脚本来源和内容，确认镜像、数据目录、数据库、环境变量及权限设置符合自己的要求；尤其不应在不了解脚本行为时直接以 root 身份执行。

2.1 开启 SSH 并登录 NAS

先在绿联 NAS 首页打开 控制面板：

进入 终端机 设置页：

启用 SSH 并点击应用。SSH 使用的登录凭据应设置为强密码；只需要局域网管理时，不要额外把 SSH 管理端口直接开放到公网。

在 Windows 上按 Win + X，打开终端或 PowerShell，准备连接 NAS：

按 用户名@NAS局域网IP 的格式登录。示例中的用户名 susu 和地址 192.168.50.99 仅对应原文演示环境，实际使用时替换为自己的信息：

# ssh 你的绿联Nas用户名@你的绿联Nas访问IP地址
ssh [email protected]

登录后，如部署脚本需要管理员权限，可按原文切换至 root。切换前确认当前账户具备相应授权：

sudo -i

2.2 执行部署脚本

下面保留原文所用的下载并执行命令。命令会获取第三方 Gitee 仓库中的脚本并执行；正式部署前，建议先单独下载、阅读脚本内容并确认来源可信，同时核对其生成的 Compose 文件及持久化目录。

curl -fsSL https://gitee.com/jun-wan/script/raw/master/chatwoot_docker/deploy.sh -o /tmp/chatwoot-deploy.sh && chmod +x /tmp/chatwoot-deploy.sh && /tmp/chatwoot-deploy.sh

终端进入脚本的交互配置流程后，先按照提示选择安装目录：

可以输入自定义安装目录，也可以直接回车采用脚本建议的目录。接着配置应用的访问入口与端口：

原文示例选择访问方式 2，先使用 NAS 的 IP 地址完成内网部署。若已准备好长期使用的 HTTPS 域名，也可根据脚本提示选择域名方式；后面配置固定公网地址时，还要检查应用生成的外部访问地址是否与之相符。

填入这台 NAS 的局域网 IP，进入邮件服务配置。邮件用于账号邀请、通知等流程，建议使用专门的发送邮箱。

原文选择 163 邮箱，在相应服务商选项中输入发件人邮箱地址。不同服务商的 SMTP 主机、端口和授权要求可能不同，不要直接套用其他邮箱的设置。

登录 163 邮箱，在 设置 → POP3/SMTP/IMAP 页面启用 SMTP，并按页面说明获取授权码。原文使用的登录网址如下：

https://mail.163.com/

找到授权密码管理，点击 新增授权密码。此处申请的是邮箱应用授权码，不是把邮箱网页登录密码直接交给程序。

按页面提示取得授权码，妥善保存。授权码属于敏感凭据，不要放进教程截图、公开仓库或聊天记录。

回到脚本配置页面，输入刚取得的授权码。输入过程中留意终端是否会回显，避免被录屏或截图带出。

完成配置后，脚本开始拉取镜像和初始化服务。下载失败可以排查网络、镜像源和磁盘空间，再根据脚本自身的重试逻辑处理；不要在尚未确认原因时反复覆盖现有数据。

终端提示完成并输出访问地址时，说明脚本流程已经走完。接下来还需实际访问网页、注册管理员并验证容器服务，不能只凭“部署完成”四个字判断业务可用。

2.3 初始化管理员与中文界面

在同一局域网的浏览器中打开脚本给出的地址。原文示例为：

http://192.168.50.99:4000

首次打开后按页面填写管理员资料，设置强密码，并完成初始化。若需要通过邮箱验证，请先确认上一节的 SMTP 参数正确。

使用刚设置的邮箱与密码登录，进入 Chatwoot 控制台。

打开 Settings，找到语言设置，将界面语言切换为中文：

切换后可以看到中文后台。不同版本的菜单位置和翻译可能有差异，以实际安装界面为准。

到这里，客服后台已可以在内网管理。下一步要解决的是：已经上线的公网网站，怎样连接到这台只在局域网内的 NAS？

3 安装 cpolar，给客服后台建立公网入口

现在浏览器可以通过 192.168.50.99:4000 访问，但这个地址只在相应局域网中可用。若网页放在公网，访客的浏览器无法用 NAS 的私有 IP 加载 Chatwoot SDK，消息也就无法正常送入这套服务。

这里使用 cpolar 为本地 Web 服务建立公网隧道。它可以减少自行配置入站公网网络的步骤，但仍要保证 NAS 在线、容器持续运行，并妥善保护管理账户。尤其在公开客服场景，访客聊天入口与管理员后台要按业务需要分别考虑访问控制。

3.1 cpolar 的作用

cpolar 可以将局域网内的 HTTP 等服务映射为公网可访问的地址，用户通过公网地址访问时，请求再转发到本地对应端口。本文使用的是 Web 隧道，不需要直接在路由器上暴露 NAS 的 SSH 管理端口。

3.2 在 NAS 上安装 cpolar

返回终端。如果此前进入了容器交互终端，先退出容器，回到 NAS 宿主机：

确认当前位于 NAS 宿主机后，执行原文安装命令。该命令从远端获取安装脚本；对系统权限敏感的环境，应先检查脚本来源和内容。

sudo curl https://get.cpolar.sh | sh

安装完成后，通过下列命令查看 cpolar 服务状态：

sudo systemctl status cpolar

如果输出包含 active (running)，表示 cpolar 服务处于运行状态。然后在同一局域网浏览器中打开 NAS IP + 9200 的管理页面，原文访问示例如下：

http://192.168.50.99:9200/

登录 cpolar 管理页面；尚无账号时按页面指引注册。此处是配置隧道的管理入口，不是最终给网站访客展示的客服页面。

4 为 Chatwoot 配置公网地址

4.1 先用随机域名验证连通性

随机域名适合部署验证：可以先确认局域网内的 4000 端口能否通过 HTTPS 被外部访问，再决定是否使用固定域名。随机地址可能变化，不能直接当作长期不变的网站 SDK 地址。

在 cpolar 后台进入 隧道管理 → 隧道列表。原文界面显示两条初始隧道，实际数量以账号现状为准：

编辑示例中的 website 隧道，或新建专用隧道。将名称设为容易识别的 Chatwoot，协议选 http，本地地址填写 4000，地区按原文选择 China Top，随后更新。这里的 http 是隧道回源到本地服务的协议，给访客使用时应优先选择生成的 HTTPS 公网地址。

更新后进入 状态 → 在线隧道列表，查看对应的公网入口。原文界面同时展示 HTTP 与 HTTPS 地址：

复制 HTTPS 地址，用不在该局域网内的设备或网络访问，确认能否打开 Chatwoot 页面：

随机域名已经足以验证“公网入口 → 隧道 → NAS 端口 → Chatwoot”这条链路。但网站 SDK 会把服务地址写在 BASE_URL 中，地址一变，网页嵌入代码就得跟着更新，不适合正式上线后长期依赖。

因此，后续如果要把聊天组件放进公开网站，建议使用一个可持续维护的固定地址。地址能保持不变的前提是相应套餐、域名保留和隧道配置都持续有效，NAS 与 Chatwoot 服务也必须在线。

4.2 保留固定二级子域名

固定二级子域名通常需要具备相应套餐权限。先在账号中核对当前权益，再进入官网的预留页面：

https://dashboard.cpolar.com/reserved

在 预留 → 保留二级子域名 中填写地区、名称和可选备注，提交保留。

原文选择的地区为 China Top，示例子域名为 chatwoot01。名称需要由账号实际预留成功，不能照抄示例并假设它一定可用。

回到 cpolar Web UI 的 隧道管理 → 隧道列表，找到刚才的 Chatwoot 隧道，进入编辑。

将域名类型切换为 二级子域名，填写自己实际保留的名称，地区与预留时保持一致，点击更新。

在 状态 → 在线隧道列表 核对更新后的公网地址，确认已经变成保留的子域名。

使用 HTTPS 地址打开后台，再检查页面加载是否正常：

随后用管理员账号进行登录测试，确认固定域名不仅能显示登录页，也能完成后台登录。

重要检查： 如果部署脚本起初以 NAS IP 生成了 Chatwoot 的外部访问地址，改用固定 HTTPS 地址后，需检查其生成的应用环境配置，确保用于生成外部链接的 FRONTEND_URL 等相关项与实际公网入口一致；按部署方式重启或重新创建相关容器后再验证，不要只改隧道而忽略应用自身配置。

至此，客服后台已有公网入口，但网站访客仍然看不到聊天窗口。接下来才是标题所说的“几行 JavaScript”：用 Chatwoot 官方网页组件将网站与后台连接。

5 把 Chatwoot 聊天窗口嵌入网页

5.1 创建网站收件箱，获取 SDK

在 Chatwoot 后台打开 设置 → 收件箱 → 添加收件箱：

在渠道类型里选择 网站（Website），而不是邮件或社交平台收件箱。

填写收件箱名称和目标网站域名。原文用一个通过公网访问的 Nginx 默认页面演示嵌入效果，正式应用时填自己的真实网站地址。

按表单完成网站相关参数，检查目标域名及显示名称是否正确。

创建收件箱后，选择负责接待的客服代理。单人演示可以先选择当前管理员，后面再增加团队成员。

保存后会出现该网站收件箱的组件安装说明，里面包含一段 JavaScript SDK。

复制生成的代码，并将 BASE_URL 指向当前可用的 Chatwoot HTTPS 公网地址。下方代码保留原文示例，chatwoot01.cpolar.top 与 websiteToken 只用于展示结构；正式网站必须以自己收件箱生成的代码为准。

<script>
  (function(d,t) {
    var BASE_URL="https://chatwoot01.cpolar.top";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.chatwootSDK.run({
        websiteToken: '3EoaEfw7TkcDimTNEWi9T5t7',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>

这里有两个容易混淆的字段：BASE_URL 是 Chatwoot 服务入口；websiteToken 用于标识网站收件箱，应该由后台生成，不能把它当作管理员密码或服务器 API 密钥。实际部署时，若初始化阶段已经填了正确的公网域名，后续就能减少地址不一致造成的问题。

5.2 写入网页并验证前后台消息

打开目标站点的入口 HTML 文件，把生成的 SDK 代码放在关闭的 </body> 标签之前，再保存、部署网页。

重新打开目标网页，必要时按 Ctrl + F5 刷新缓存。正常加载时，页面右下角会出现客服聊天入口。

点击聊天图标，检查欢迎语及会话入口是否和收件箱设置相符。

先从访客侧发一条测试消息，确认页面没有脚本报错或加载失败。

回到 Chatwoot 后台，在相应收件箱的会话列表中查看新消息。能看到访客消息，说明前台到后台的方向已经打通。

由客服在后台回复，再回到网站聊天窗口核对回复是否到达；这样才算完成双向通信验证。

原文截图展示了前台收到后台回复的结果。若自己的页面只显示气泡却不能收发，可依次检查：公网 HTTPS 地址、SDK 的 BASE_URL、收件箱 websiteToken、NAS 端口、应用外部地址配置，以及浏览器控制台和服务日志。

6 添加客服坐席，让多人共同处理咨询

单人管理适合初期测试；随着咨询量增长，可以把接待工作分配给不同同事。进入后台底部 设置 → 客服代理 → 添加客服。

填写新成员的名称、邮箱与角色。普通客服和管理员的操作范围不同，应按照实际职责授予权限，不要为了省事把所有成员都设为管理员。原文操作界面展示了相关选项：

提交后系统会通过配置好的邮箱发送邀请。若收不到邮件，先检查垃圾邮件与前面配置的 SMTP 授权码、发件人地址等。

新成员打开邀请邮件中的确认链接，按页面提示设置自己的登录密码。

账户创建完毕后，还需要进入对应收件箱，把新成员添加为该收件箱的客服代理；仅创建账号不代表他已经接入全部网站会话。

完成分配后，可以在收件箱的代理列表中查看新增成员。

这样，网页访客消息就不再只能由一个人处理：需要时可以分配会话、留下内部备注，并由不同客服接续回复。协作效果仍取决于实际分工和工作流程，不是增加账号后就自动提升响应速度。

总结

本篇完成的是一套可复现的基础客服流程，而不是单独安装一个聊天图标：先在绿联 NAS 部署 Chatwoot 并完成邮件与管理员配置，再利用 cpolar 验证公网连接、设置适合长期嵌入的 HTTPS 地址，最后生成网站收件箱 SDK，完成网页消息发送、后台接收和客服回复，并添加新的客服坐席。

真正上线前还应做好三件事：确认外部访问地址与 Chatwoot 应用配置一致；备份数据库、附件与必要配置，保护 SMTP 授权码和管理员凭据；检查服务器在线状态与公网暴露范围。社区版与付费、AI 功能的边界也应按所使用的版本核对，不能把基础聊天窗口等同于已经开通 24 小时自动回复的 AI 客服。

网站客服的价值最终体现在访客能否顺利找到入口、消息能否送达、负责的人能否及时回应。先把这条链路跑通，再根据实际咨询量扩展渠道与自动化能力，往往比一开始追求功能堆叠更切合使用需求。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/m0_73879806/article/details/166794082