普通安装 | 泡泡 IM 开发文档

适用于直接管理 Linux、Nginx 和 MySQL 的部署。以下软件包与 Nginx / MySQL 配置路径以 Ubuntu 24.04 / 26.04 为例，源码目录为 /srv/popoim，域名为 example.com。CentOS 等发行版需按实际环境安装依赖并调整配置路径；PHP 服务使用相同的启动命令。
这里使用系统仓库配套的 PHP 及扩展：Ubuntu 24.04 默认 PHP 8.3，26.04 默认 PHP 8.5，不要在 26.04 上照抄 php8.3-* 包名。已有多套 PHP 时，确保命令行、Composer 和启动服务使用同一套 PHP。确认命令行实际使用的 PHP：
pcntl、posix、sockets 在这里的 Ubuntu CLI 软件包中可用。若使用自定义 PHP，需自行启用这些扩展。泡泡 IM 由常驻 PHP CLI 进程运行，不通过 PHP-FPM 执行业务请求。
把收到的 Web 服务端 ZIP popoim-web.zip 上传到当前用户的家目录。文件名不带客户标识，解压后的顶层目录为 im-web/。
/srv/popoim 下应直接包含 start.php、composer.json、deploy/、public/，不要多套一层 im-web。本步骤用于空目录首次安装；已有站点按版本更新保留配置和数据。
把源码中的 deploy/mysql-search.cnf 放入 MySQL 配置目录：
在 MySQL 控制台创建专用数据库和用户，将示例密码换成随机强密码：
检查输出中的 ngram_token_size 为 1。配置修改后必须重启 MySQL，单独执行 SQL 不能改变这个启动参数。
源码由第 2 步的部署账号持有。用同一账号安装依赖并启动 PHP 服务，确保它能写入 runtime/、public/uploads/、config/ 和 plugin/sdk/config/；不要照抄其他服务器的运行用户名。Nginx 需要能读取 public/ 下的公开资源。
在源码目录，用上述部署账号启动后台服务：
-d 表示后台运行，关闭终端后服务继续运行，不会自动设置开机启动。若启动失败，先执行 php start.php start 查看终端错误；修复后按 Ctrl+C 停止前台进程，再以 -d 启动。状态、reload、重启和停止命令也使用同一账号与 PHP，见进程与版本更新。
修改 deploy/nginx.conf 的域名和根目录，再安装配置：
配置同时代理 HTTP 到 127.0.0.1:8787、/ws 到 127.0.0.1:6060，保留公开资源访问，并阻止 PHP、隐藏文件与私有媒体原文件被直接读取。完整配置说明见 Nginx 与 HTTPS。
将域名解析到服务器，访问 http://example.com/install，按照完成安装填写数据库与管理员。正式上线前为站点配置 HTTPS，并确认后台 WebSocket 公网地址使用 wss://example.com/ws。