README

简体中文 | English

Giorgio IM 的 Laravel 后端，提供好友、群聊、消息和实时事件接口

相关包

• Giorgio IM：Vue 3 + TypeScript 即时通讯组件
• Giorgio IM React：React + TypeScript 即时通讯组件
• Giorgio IM Socket：Laravel 即时通讯后端
• Giorgio Socket：Laravel WebSocket 底层服务相关包

快速体验包

从 Releases 页面 下载适合系统的 im-test-* 独立程序（Windows 为 .exe），运行后按终端提示打开演示页面。无需安装 PHP、Node.js、Composer 或 Redis；运行 --help 可查看端口等参数。另有需要兼容 PHP 的 .phar 包。

一键安装本地演示

演示安装脚本最低要求 PHP 8.0.2+（pdo_sqlite、mbstring），新建项目使用 Laravel 9；已有 Laravel 9/10 项目需满足自身依赖要求；另需 Composer、Node.js/npm 和 Redis。脚本自动安装前后端、配置 SQLite 并构建演示页面，使用 PHP 原生 Socket 驱动。

curl -fsSL https://raw.githubusercontent.com/m-finder/giorgio-im-socket/main/tools/setup.sh -o /tmp/giorgio-im-setup.sh
bash /tmp/giorgio-im-setup.sh

按提示确认安装到当前 Laravel 项目，或选择空目录创建新项目。每次运行都需输入具有 read:packages 权限且能访问前端包的 GitHub classic PAT，输入不会显示。

安装完成后，在项目根目录打开四个终端，各运行一条命令：

redis-server --bind 127.0.0.1 --port 16380 --save '' --appendonly no
php artisan socket:start
php artisan socket:events
php artisan serve --host=127.0.0.1 --port=8001 --no-reload

打开 http://127.0.0.1:8001/im，注册两个账号即可测试私聊和群聊。自定义端口时，以脚本打印的启动命令和地址为准。

手动安装

用于接入已有 Laravel 项目。最低要求 PHP 8.0.2+、Laravel 9+，并满足项目依赖；需启用 mbstring，准备数据库和 Redis。

1. 安装并发布配置

composer require wu/giorgio-im-socket
php artisan vendor:publish --provider="GiorgioImSocket\Providers\ImServiceProvider" --tag=im-config
php artisan vendor:publish --provider="GiorgioSocket\Providers\SocketServiceProvider" --tag=socket-config

2. 配置用户与认证

在 config/im.php 中指定用户模型和项目已有的认证中间件：

'user_model' => App\Models\User::class,
'routes' => [
    'prefix' => 'api/im',
    'middleware' => ['api'],
    'auth_middleware' => ['auth:sanctum'],
],

auth:sanctum 仅为示例，使用前需自行接入 Sanctum；也可替换为项目的认证方式。认证后 $request->user() 须返回当前用户，用户主键须为正整数，用户表与 IM 表须使用同一数据库连接。

3. 配置并启动服务

在 .env 中配置 Socket，Redis 使用项目现有配置：

SOCKET_HOST=127.0.0.1
SOCKET_PORT=9501
SOCKET_DRIVER=auto
SOCKET_PREFIX=giorgio-im:9501:
SOCKET_PUSH_URL=http://127.0.0.1:9501/push
SOCKET_PUSH_TOKEN=replace-with-a-private-random-secret
IM_SOCKET_URL=ws://127.0.0.1:9501

确认用户表已创建，执行迁移：

php artisan migrate

在两个终端分别启动 Socket 和事件推送：

php artisan socket:start
php artisan socket:events

以上地址用于本地开发；公网使用 HTTPS/WSS，推送密钥仅保存在服务端。修改配置或代码后重启这两个服务。

4. 接入前端

按 Vue 或 React 文档安装组件，使用登录后取得的访问令牌连接：

import { createConnectedIM } from '@m-finder/giorgio-im'

const im = await createConnectedIM({
  token: () => accessToken,
  apiUrl: '/api/im',
  widget: { locale: 'zh-CN' },
})
im.open()
// 页面卸载时调用 im.destroy()

React 项目将导入路径替换为 @m-finder/giorgio-im-react。

连接认证

认证后的 POST /api/im/socket-ticket 为当前用户签发短期票据,默认票据有效期 60 秒，连接最长一小时，签发端和 Socket 服务须使用同一个 APP_KEY

默认身份适配器只确认用户存在，需要检查登录会话或令牌是否吊销时，实现 GiorgioImSocket\Contracts\SocketIdentity 并配置 im.socket_identity：

public function claims(Request $request): array;
public function resolve(array $claims): ?int;

HTTP 接口

除签名文件读取外，接口均需认证。JSON 接口使用 Accept: application/json，上传使用 multipart

私聊和群聊的 type 分别为 friend、group。发送消息需提供 UUID mid，用于幂等重试，附件须先上传 多图消息可使用 attachments 图片数组与 content 文字一起发送；单附件继续使用 attachment

群聊支持 mentions: { id, username, start, end }[]，索引按正文的 UTF-16 编码计算，结束位置不包含在内。服务端校验成员身份、文字范围及重叠。

群消息静音是个人设置，与群禁言独立。初始化及设置接口返回的群信息包含 notificationsMuted，设置后仅向当前用户同步 group.updated；消息仍完整投递，由前端保留未读计数并对 @ 自己的消息继续提醒。升级后运行 php artisan migrate，添加个人群通知设置字段。

私聊和群聊引用消息时，提交 replyTo: { mid, fromid }。服务端只允许引用当前会话内可见的消息，并返回含 username、content 的快照；图片消息同时保留 attachment 或 attachments，供前端展示缩略图及文字。mentions 和 replyTo 均随实时事件与历史消息返回，同一 mid 重试时必须保持一致。升级后运行 php artisan migrate，添加消息上下文字段。

其他配置

敏感词词库通过 IM_SENSITIVE_WORDS_PATH 指定

MIT，见 LICENSE