# 企业IM客服系统 注意事项 ●以下每一步都必不可少，完成安装流程后，才能获得完整体验 ●IM基于Swoole扩展运行，不支持Windows系统，请确保服务器系统为Linux、MacOs等支持Swoole的系统 ●IM插件的安装比普通插件多了swoole服务的调通，稍微复杂一点，但并不难，若调不通请先耐心阅读文档。 一、 安装 FastAdmin，已安装请忽略，安装参考[快速后台开发框架安装](https://doc.fastadmin.net/docs/install.html) 二、 登录到FastAdmin后台->插件管理->安装IM插件->清理缓存->刷新后台； 三、 检查后台与用户中心的IM悬浮按钮是否自动部署。 ●若未能自动部署，请您按以下步骤检查，已经自动部署的请忽略此条。 1站点首页不会自动部署，若需在首页部署IM系统，建议在安装流程结束后，再点我查看如何配置 2您未开启调试模式：安装完插件后，请于后台->常规管理-》系统配置-》修改基础配置中的版本号->清理缓存并刷新后台。\*\*重点\*\* 3您的JS文件已配置为从CDN/对象存储中加载：请更新public/assets/js/addons.js文件，到您的CDN/对象存储中，再执行上面的第1点。 四、安装swoole扩展 ●可使用任何可能的方式安装\*\*Swoole 4\*\*扩展 ●宝塔面板可直接在软件商店找到对应的php版本->设置->安装扩展->找到Swoole 4安装成功后即可跳到第五步 ●非宝塔可参考：[swoole官方安装文档](https://wiki.swoole.com/#/environment)，该安装文档分为快速安装、进阶完整编译示例、PECL，使用三种方式的任意一种均可，在该页面底部，也有视频安装教程 五、启动swoole服务 ●打开终端，执行命令php think fastim start调试启动swoole服务 ●安装流程完成后，请在终端按下ctrl+c结束服务，再执行php think fastim start -d正式启动服务(守护进程模式) 六、对外开放\*\*2088\*\*端口 ●端口号2088可在后台运行配置中修改，此处假设您要开启的端口是默认的2088端口 ●若您使用了宝塔管理面板，请登录面板->安全->放行端口2088重点 ●若您的服务器购买于阿里云，首先登录到阿里云控制台->找到云服务器管理控制台->找到服务器实例对应的安全组->添加入方向规则放行2088号端口。 ●若您的服务器购买于腾讯云或其他任何主机服务商，均需先在服务商方面放行端口。\*\*重点\*\* ●若有使用cdn、负载均衡等产品服务，且该服务有防火墙功能，还需要前往对应服务的面板开放2088端口 ●检查端口是否已经开放成功，最简单可行的办法是端口扫描，请自行某度查找自己喜欢的:端口扫描工具，对2088端口进行扫描，扫描结果为开放，则端口已准备好！ 七、注意事项 ●https下，必须创建wss服务，才能正常连接网络，可先行通过http访问网站，安装流程完成后，再参考[创建wss服务](https://doc.fastadmin.net/fastim/1032.html)，若您的站点未创建wss服务，请确定：IM插件配置->运行配置->wss协议链接 是关闭状态。 ●Im的网络无法连接，90%是因为端口未开放，无法连接请务必进行端口扫描，不要只关注你刚设置的开放端口规则。\*\*重点\*\* ●安装插件清理缓存后，请刷新后台后，再执行启动服务命令，否则会报错runtime目录的某个文件不能访问，因为使用了root用户建立站点缓存 八、测试 ●刷新后台，检查Im网络连接状态 ●确定网络可以正常连接后，请回到终端按下ctrl+c结束服务，再执行php think fastim start -d正式启动服务 ●若网络任然无法连接，请检查终端是否有报错显示出来 IM配置项解释 配置入口：企业IM客服系统-》IM配置，插件管理中的插件配置，也已经整合至此处运行配置一栏。 cAd2YyiW8ahs+CFqIJrH3Q== 基本 ●插件默认不包含富文本编辑器插件，请在[插件市场](https://www.fastadmin.net/store.html?category=16&pay=all&order=default)按需要安装。 ●部分系统级设置项与用户的IM设置重合，实际以用户的个人设置为准，系统级的设置将作为默认值；比如：是否使用ESC键关闭会话窗口，系统级默认设置为关闭，用户个人设置为不关闭，则该用户不可使用ECS键关闭会话窗口。 客服配置 ●当开启客服功能之后，有新的用户访问到IM系统时，将自动为其添加智能客服小蜜的会话，这也是知识库的入口，智能客服小蜜通过用户发送的消息内容来为其推荐知识点或转接人工客服，有多种接人工客服的配置组合，建议管理员通过调整客服配置中的客服分配分组选择和客服分配方式自行了解分配方式。 ●添加人工客服请[参考这里](https://doc.fastadmin.net/fastim/1019.html) ●新用户欢迎消息(默认)，当客服本身代表没有设置欢迎消息时，则默认使用此欢迎消息，单个客服代表专有的欢迎消息设置位置在：企业IM客服系统管理->用户管理->找到客服代表->编辑新用户欢迎消息 消息推送配置 ●PC端消息通知:Notification API只能在https下使用，https下用户首次访问浏览器将在左上角弹出的是否允许通知提示，就算用户未在当前页面浏览，新消息到来时也可以收到消息通知 ●APP端消息推送通知：uniPush配置请[参考文档](https://doc.fastadmin.net/fastim/1021.html)，若需要实现离线消息通知，则需要申请的账户较多(各大手机厂商)，且配置稍显复杂，我们已经尽可能简化，但任建议开发者来进行配置 运行配置 ●开启WSS服务：请先配置好ssl证书的绝对路径，在https下是必需开启wss的，创建wss请参考文档 ●WebSocket 端口：通过Swoole在服务器上启动的WebSocket服务的连接端口，此端口需要对外开放 ●Worker 进程数：如 1 个请求耗时 100ms，要提供 100QPS 的处理能力，那必须配置 10 个进程或更多。 但开的进程越多，占用的内存就会大大增加，而且进程间切换的开销就会越来越大。所以这里适当即可。不要配置过大。 YX0mIgUElk331D+oXrhduQ== ●Reactor 线程数：调节主进程内事件处理线程的数量，以充分利用多核；每个线程能都会维持一个 EventLoop。 ●最大并行连接数：在Swoole启动时，我们申请了两个高性能内存Swoole\\Table，用于存储在线用户的fd和uid的对应关系等资料，以实现单用户可同时存在多个连接，此最大并行连接数代表申请的Swoole\\Table的最大行数，通常可以直接理解为WebSocket服务最大同时连接数，如：默认值2048代表同时可以有2048位用户在线沟通；在内存足够的情况下尽量将此值设置的大一些，报错：Unable to allocate memory，代表内存不足。 客服功能使用必看 如何添加客服代表？ ●管理员登录后台->企业Im客服系统->用户管理->选择任意一位用户->编辑资料->用户类型修改为客服即可，建议为其选择一个客服组，而客服组的配置则在：企业Im客服系统->客服分组管理 ●IM不限客服代表坐席数量 客服功能注意事项 1使用本功能前，请先于后台->企业IM客服系统->IM配置->客服配置中开启客服功能 2IM可以将任意前台/后台用户设置为客服代表 3被设置为客服代表的用户，需要允许临时会话：客服代表点开自己的IM会话窗口->左下角菜单->设置->隐私设置中。 4若客服代表未允许临时会话，不影响已接待客户沟通，但不会将他推荐给新的客户（不再接入新的咨询） 5客服代表可在：IM会话窗口->左小角菜单->设置->管理自己专有的快捷回复，若未显示请刷新窗口再查看。 6IM配置->客服配置中的项目，请自行做不同搭配体验其功能，此处不再做额外介绍。 7不是好友且对方未开启临时会话，客服代表依然可以发送消息对方，除非被对方屏蔽。 uniApp(启用H5、APP端) 准备工作 1安装HBuilderX开发工具，[下载地址](https://www.dcloud.io/hbuilderx.html)，请下载安装App开发版本 2使用HBuilderX打开站点根目录/addons/fastim/uniapp目录 3修改uniapp/common/config.js中的baseUrl、httpsSwitch、httPort，请参考注释进行修改 4编译到各个平台运行查看 5Im系统已测试IOS、安卓APP、微信小程序、H5平台，若您在编译到其他端时，遇到与预期不同表现，请不要气馁并[与我们联系](https://doc.fastadmin.net/fastim/1034.html) 对编译到H5举例 1完成准备工作的第1-3步 2如果您的站点使用了https，建议打开uniapp目录的manifest.json文件，找到h5配置，启用https协议 3在HBuilderX中打开任意一个uniapp目录的文件 4在HBuilderX的顶部菜单中找到发行->网站-PC Web或手机H5，在提示框中填写网站域名如:im.thankphp.com 5编译成功后，找到提示出来的h5目录，将整个h5目录上传到站点的根目录/public目录内 6浏览器访问：域名/h5/ 编译到其他平台 1与H5大同小异，首先都是完成准备工作的第1-3步 2打开uniapp目录的manifest.json文件，找到你要编译的平台的配置项，按需修改 3HBuilderX顶部菜单：运行或发行 uniPush推送(APP离线消息推送) 第一步、开通uniPush 1请查看 [uniPush官方开通指南](https://ask.dcloud.net.cn/article/35716) 2其中的iOS推送证书，若未配置，则IOS系统用户，无法收到离线推送消息，申请IOS推送证书的流程在上面的开通指南中有介绍，需要注册苹果开发者网站费用99美元（688人民币），该费全部由苹果官方收取 3其中的厂商推送参数设置，表示向魅族、OPPO、华为、小米、VIVO等厂商申请离线推送消息后配置到uniPush后台，不申请，则对应品牌用户无法收到离线推送消息 4配置过程中出现的应用包名/应用标识是随便取的，比如addon.fastim，需和厂商推送后台的包名保持同步 第二步、配置后台 1成功注册uniPush、建立应用后，打开应用，获取应用Uni Push的AppID、AppKey、MasterSecret、Android应用标识全部填入后台的Im配置->消息推送配置中，并开启消息推送功能->保存设置 第三步、编译自定义调试基座 1HBuilder X编辑器上，登录与uniPush相同的账户(编辑器左下角可切换账户) 2HBuilder X内打开Imuniapp项目后，运行->运行到手机或模拟器->制作自定义调试基座，在打开的窗口中Android包名和IOS的BundleID(AppID)请与后台推送配置设置的包名、uni Push配置、厂商的推送后台配置的包名保持一致 3完成基座打包后:运行->运行到手机或模拟器->运行基座选择->自定义调试基座 4接下来，运行到设备即可接收到推送消息，若收不到，请检查通知权限、厂商推送配置、包名是否统一、以及本文档下方的各厂商奇怪规定 第四部、问题排查 ●Im系统已测试IOS、华为、小米、OPPO、魅族的离线消息推送可以送达，若您仔细检查了自己的各项配置，并更换其他设备后任然无法接受到推送消息，请不要气馁并[与我们取得联系](https://doc.fastadmin.net/fastim/1034.html) ●[uniPush官方常见问题](https://ask.dcloud.net.cn/article/id-36611__page-4) ●[uniPush官方使用指南](https://ask.dcloud.net.cn/article/35622) 各厂商推送的一些奇怪规定 华为 1必须安装“华为移动服务HMS Core” 2通知太多会自动折叠 3可能被归类到静默通知(只推送到通知栏,不响铃,不震动,不提醒)，好像是根据APP历史推送的消息来分类的，建议打开APP的营销通知和关闭静默通知 VIVO 1vivo部分机型默认关闭APP的通知 2vivo[运营消息]，一个设备一天只能收到5条离线消息，非运营消息需要于VIVO官网申请 31个自然日内相同文案的运营消息给同个设备发，vivo会在客户端做去重处理 4通知文案中不能包含测试、test、纯数字、纯表情、符号或者\`符号+数 字、表情+数字、表情＋符号\` SrkDF6XRGVs3KIRVVHgFDQ== 小米 ●推送消息可能被归类到不重要通知，可通过修改APP权限规避 OPPO ●OPPO部分机型默认关闭APP通知权限 ●需要将通知权限下的Default通道权限也打开。 魅族 ●消息可能被归类到魅族手机右上角魅族消息盒子 ●收不到推送时，请尝试清除缓存：手机->系统设置->应用管理->所有应用->点击右上角->显示系统服务应用->找到推送服务和您自己的App，分别进行清除数据，然后重启手机。 各厂商推送申请地址 ●华为 [https://developer.huawei.com/consumer/cn/](https://developer.huawei.com/consumer/cn/) ●小米 [https://dev.mi.com/console/](https://dev.mi.com/console/) ●魅族 [http://open.flyme.cn/](http://open.flyme.cn/) ●oppo [https://open.oppomobile.com/](https://open.oppomobile.com/) ●vivo [https://id.vivo.com.cn/](https://id.vivo.com.cn/) ●安卓注册/申请推送账户中若有疑问，[请参考](https://docs.getui.com/getui/mobile/vendor/vendor_open/) ●IOS申请推送证书，[请参考](https://docs.getui.com/getui/mobile/ios/apns/) 常见问题 1. 什么是离线、在线消息推送 ●在线消息推送指用户的WebSocket已经断开，但手机APP任在前台或后台运行，任然可以向用户推送新的消息 ●离线消息推送指用户WebSocket已经断开且手机APP未在后台运行，任然可以向用户推送新的消息，用户手机必须开启APP的推送权限 2. 为什么又要申请uniPush还要申请各大厂商的推送账户 ●uniPush可以将各大厂商的推送Api聚合在一起，只需向对应厂商申请推送功能后，简单配置即可，而实际进行离线消息推送还是各大厂商实现的，uniPush实现了在线推送 云存储支持 云存储使用注意事项 ●请先参考您的云存储插件的介绍页，完成云存储插件的安装/配置 ●IM系统可自动识别您启用的云存储插件，无需额外设置 ●云存储插件需设置为：服务器中转模式 ●已启动Swoole服务时，若要启用/更换云存储插件，请重启Swoole服务 ●为方便使用，以及兼容多端，IM系统内上传的文件在直接使用的绝对路径，好处是无论何时启用/关闭云存储时无需整理以前上传的文件，更换云存储时，若之前的云存储不弃用则也无需整理以前上传的文件等，缺点若要弃用某种云存储，需要批量替换文件路径 需提前上传至云存储的文件列表 ●public/assets/img/avatar.png 默认头像 ●public/assets/addons/fastim/audio/ringing.mp3 来信提示音 ●public/assets/addons/fastim/img/emoji/ 表情图片文件夹 ●若不清楚如何上传，请参考您安装的云存储插件介绍页 快捷键支持 快捷提取新消息 ●未打开会话窗口时提取最新消息快捷键：Ctrl+/ ●在会话窗口打开时，切换到最新消息所在的会话快捷键：Ctrl+/ ●无最新消息时，关闭窗口快捷键：Ctrl+/ ESC键关闭窗口 ●若在配置中开启了ESC键关闭窗口，则随时可以通过ESC键关闭IM内的任意弹窗，若没有弹窗，则会关闭IM主会话窗口 ●IM的正确使用姿势：需要使用Im时通过ctrl+/打开窗口，不使用时直接按下ESC关闭，关闭了窗口不会影响新消息接收，在后台打开新的标签，不会重复加载Im，不会影响新消息接接收 修改新消息提取快捷键 ●找到addons/fastim/bootstrap.js文件，搜索event.keyCode === 191这段代码负责监听后台iframe内的按键事件 ●找到addons/fastim/assets/js/fastim.js文件，搜索case 191: // 消息提取快捷键 ●数字191代表/键的keyCode，请拿到要更换的新按键的keyCode替换191即可 ●插件管理内关闭后再打开插件，清理缓存，以上修改才会生效 WSS支持 准备工作 1已经申请了对应域名的证书，且证书在有效期内(pem/crt文件及key文件)放在磁盘某个目录(位置任意，能读即可) 2建议先行调通http+ws，服务正常后，再开启wss\*\*重点\*\* 创建WSS服务 1请于后台找到：企业IM客服系统->IM配置->运行配置 2运行配置内：开启WSS服务，然后配置好ssl证书和ssl证书KEY的绝对路径 3关闭Swoole服务，再重新启动Swoole服务，[命令参考](https://doc.fastadmin.net/fastim/1028.html)，平滑重启可能无效 4我们在启动Swoole服务时，注明了当前启动的服务协议，请参考下图  URfCmMJosYSPXPjFfB0tGg== 注意事项 1请确保证书路径可读、证书在有效期内、证书与域名对应 2Linux绝对路径一般以/www开头，列如：/www/wwwroot/im.thankphp.com/cert/im.pem 3如果站点已创建好https服务，将无法通过ws协议连接WebSocket，请参考以上方法配置wss 4如果已经创建好wss服务，则只能通过wss协议连接，无法通过ws协议连接 常见问题 启动与停止 使用IM-Swoole的命令文档 准备工作 1Windows不支持swoole，请在Linux、macOS等支持swoole的服务器上使用IM系统 2cd 到FastAdmin根目录，也就是think文件所在的目录 3请确保php已经加入到系统环境变量，否则会提示找不到该命令 4已安装好swoole扩展，[安装](https://doc.fastadmin.net/fastim/1017.html) 命令 ●以debug（调试）方式启动（关闭终端或ctrl+c,服务自动退出） GqJK9kLwkzK1Mj6r/JbYtQ== ●以daemon（守护进程）方式启动 9d/SzZcFO/7DOJpXj1tNzA== ●停止服务 jH2+795h+3XVmIuFYJEdUA== ●平滑重启 用户身份识别失败 已知此提示可能出现在后台 复现路径 1管理员A登录后台 2管理员A使用另外的浏览器再次登录后台 3管理员A主动注销其中一个后台的登录 4管理员A打开未注销的后台，此时问题复现 问题出现原因 ●管理员的主动注销操作，销毁了数据库中的token，未被注销的后台使用纯session数据鉴权，但Im的swoole服务中无法访问session，无法对身份进行有效验证 解决方案 ●重新登录 站外.其他模块调用 站外/其他模块调用 IM系统不能自动在cms、问答等插件的前台部署，需您根据本章内容进行引入，总的来说就是引入一个js和css文件然后添加一行js代码，看得懂\*\*html\*\*的开发者同学，请直接滑至页末。 其他模块调用 1、 找到需要调用IM系统的页面的视图文件，比如：FastAdmin站点首页是application/index/view/index/index.html文件2、 也可以找到整个模块的公共meta模板文件，比如FastAdmin的index模块的公共meta模板文件是：application/index/view/common/meta.html，在此文件完成调用流程后，整个index模块的页面都可以启用IM系统，除非某页面没有使用公共meta模板3、 在你选择的视图文件中引入：\_\_CDN\_\_/assets/addons/fastim/css/fastim\_default.css文件。\_\_CDN\_\_/assets/addons/fastim/js/fastim.js文件。\_\_CDN\_\_/assets/libs/jquery/dist/jquery.min.js，若没有引入过Jquery才需引入它 4、 标签内添加代码：FastIm.initialize(此处请改为您的站点域名，无需携带协议与端口);5、 可在页末查看示例代码 在外站调用 1、 找到您要调用IM的页面的文件2、 在该文件内引入您的域名/assets/addons/fastim/css/fastim\_default.css文件您的域名/assets/addons/fastim/js/fastim.js文件您的域名/assets/libs/jquery/dist/jquery.min.js，若没有引入过Jquery才需引入它 3、 标签内添加代码：FastIm.initialize(此处请改为您的站点域名，无需携带协议与端口);4、 可在页末查看示例代码 注意事项 ●站点首页也属于其他模块，只有后台和用户中心(含登录注册页面是可以自动部署的) ●其他模块调用时，不使用二级域名，可以实现前台用户自动登录 通用调用示例 铃声无法上传？ 错误：上传文件格式受限制(code:0) 1找到根目录/application/extra/upload.php文件。 2修改该文件内的mimetype数组项，追加所需上传文件的格式。 3假设新铃声格式为mp3，修改后如图所示。  二次开发 调试IM系统 调试模式 ●FastAdmin的调试模式 application/config.php中，找到Env::get('app.debug', false), 把 false 改成 true，如果使用了env，请在根目录/.env文件中，添加或修改debug = false TauEWr3GD0K+cWbY85XFyQ== ●Swoole调试模式 调试启动Swoole服务命令php think fastim start确定启动Swoole服务时，使用的是调试启动命令即可，如果不是，请先执行php think fastim stop再重新执行调试启动命令 SQn0W/e6p3B73t0G6ubarg== ●Swoole调试启动后，ws协议下的所有报错，都会直接显示到终端，排查Swoole服务中的错误最好的办法是前台做了一项操作后，检查终端上的输出 IM系统目录结构 FastIm **Nginx** 复制代码 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 FastIm **├─command** **│** Swoole.**php 命令行文件，此文件通常无需改动** **│** **├─controller** **│**│ Base.**php** **│**│ Index.**php 内含用户在连接ws前的初始化请求，识别身份、建立游客等** **│**│ **│**└─api **│** Base.**php** **│** User.**php uniapp端的用户登录注册等** **│** **├─data**插件数据包(内含菜单规则数组) **│** **├─lang**插件语言包 **│** **├─library** **│**│ Common.**php 公共函数库，可以静态调用方法** **│**│ CommonCode.**php 一些变量** **│**│ **│**├─controller **│**│ Base.**php** **│**│ ImBase.**php 二开核心文件，IM的一些基础事件(可以理解为http中的请求)处理** **│**│ Message.**php 二开核心文件**IM的一些和消息相关的事件处理 **│**│ User.**php 二开核心文件**IM的一些和用户相关的事件处理 **│**│ **│**├─pushapi**uniPush库**,**以改为命名空间方式调用** **│**│ **│**└─swoole **│** Common.**php 依赖Swoole环境的公共函数库(通过ws触发的事件内可用)，不可以静态调用方法** **│** WebSocket.**php ws服务创建，此文件通常无需改动** **│** **├─public**将自动覆盖到根目录/**public，内含后台功能的js文件** **│** **├─uniapp**uniApp代码 **│**│ **│**├─common **│**│**│** config.**js 配置文件，编译uniapp前请按注释修改此文件** **│**│**│**http.interceptor.**js** **│**│**│** websocket.**js WS相关(连接、重连、消息处理等等)，以全局引用** **│**│**└─css**一点公共css **│**│ **│**├─components **│**│**├─link-message**链接消息的组件 **│**│**│** **│**│**├─message**文本、图片、文件等消息的组件 **│**│**│** **│**│**└─session**\`消息页\`单个会话的组件，封装后性能更好 **│**│ **│**├─pages**uniapp端的所有页面代码** **│**│ **│**├─static **│**│**├─icon**一些uniapp使用到的图标 **│**│**│** **│**│**└─img**一些uniapp使用到的图片-登录背景图、默认头像等 **│**│ **│**├─unpackage **│**│**└─res** **│**│**└─icons**内含FastIm官方的LOGO **│**│ **│**└─uview-ui**uview组件库** **│** **│** bootstrap.**js 插件启动js文件** **│** config.**php 插件扩展配置文件，运行配置保存于此** **│** Fastim.**php 核心安装卸载控制器文件** **│** info.**ini 插件基础配置** **│** install.**sql 插件安装SQL** **│** **└─view**FastIm视图文件-PC端会话窗口HTML代码、全屏模式HTML代码 **└─default** **│** pc.**html** **│** **└─index** fullscreen.**html** **index**.**html** 若有收获，就点个赞吧