pllx
356 lines
11 KiB
Markdown
356 lines
11 KiB
Markdown
# 🌟 飘落流星聊天室（Laravel 12 重构版）
|
||
|
||
> 一款基于 Laravel 12 + WebSocket（Reverb）+ Redis 构建的实时多人在线聊天室系统。
|
||
> 原版为 VBScript ASP + MS Access 聊天室，现已全面升级为现代化 PHP 架构。
|
||
|
||
---
|
||
|
||
## 📋 技术栈
|
||
|
||
| 组件 | 版本 | 用途 |
|
||
| --------------- | -------- | ----------------------------- |
|
||
| PHP | 8.4+ | 运行环境 |
|
||
| Laravel | 12.x | 后端框架 |
|
||
| Laravel Reverb | latest | WebSocket 实时通讯引擎 |
|
||
| Laravel Horizon | 5.x | Redis 队列可视化管理面板 |
|
||
| Redis | 7.x | 缓存 / 会话 / 队列 / 在线状态 |
|
||
| MySQL | 8.0+ | 数据持久化存储 |
|
||
| Node.js | 20.x LTS | 前端构建工具链（Vite） |
|
||
| Tailwind CSS | CDN | 前端样式框架 |
|
||
| Alpine.js | 3.x | 前端轻量交互 |
|
||
|
||
---
|
||
|
||
## 🚀 本地开发部署
|
||
|
||
### 1. 克隆项目 & 安装依赖
|
||
|
||
```bash
|
||
git clone <仓库地址> chatroom
|
||
cd chatroom
|
||
|
||
# 安装 PHP 依赖
|
||
composer install
|
||
|
||
# 安装前端依赖
|
||
npm install
|
||
```
|
||
|
||
### 2. 环境配置
|
||
|
||
```bash
|
||
# 复制环境文件
|
||
cp .env.example .env
|
||
|
||
# 生成应用密钥
|
||
php artisan key:generate
|
||
```
|
||
|
||
编辑 `.env` 文件，配置以下关键项：
|
||
|
||
```env
|
||
# 数据库
|
||
DB_CONNECTION=mysql
|
||
DB_HOST=127.0.0.1
|
||
DB_PORT=3306
|
||
DB_DATABASE=chatroom
|
||
DB_USERNAME=root
|
||
DB_PASSWORD=root
|
||
|
||
# Redis（缓存/队列/会话）
|
||
REDIS_CLIENT=predis
|
||
REDIS_HOST=127.0.0.1
|
||
|
||
# 广播驱动
|
||
BROADCAST_CONNECTION=reverb
|
||
|
||
# 队列驱动
|
||
QUEUE_CONNECTION=redis
|
||
|
||
# Reverb WebSocket 配置
|
||
REVERB_APP_ID=chatroom
|
||
REVERB_APP_KEY=chatroom-key-2026
|
||
REVERB_APP_SECRET=chatroom-secret-2026
|
||
REVERB_HOST=127.0.0.1
|
||
REVERB_PORT=8080
|
||
REVERB_SCHEME=http
|
||
|
||
# 前端 WebSocket 连接配置（本地开发）
|
||
VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
|
||
VITE_REVERB_HOST="127.0.0.1"
|
||
VITE_REVERB_PORT=8080
|
||
VITE_REVERB_SCHEME="http"
|
||
```
|
||
|
||
### 3. 数据库初始化
|
||
|
||
```bash
|
||
# 创建数据库（MySQL 中手动执行）
|
||
# CREATE DATABASE chatroom CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
|
||
# 运行迁移 + 种子数据（自动创建默认房间"公共大厅"）
|
||
php artisan migrate --seed
|
||
```
|
||
|
||
### 4. 构建前端资源
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
### 5. 启动所有服务 ⚡
|
||
|
||
本地开发需要同时运行 **3 个终端窗口**：
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ 终端 1：WebSocket 实时通讯引擎 │
|
||
│ php artisan reverb:start │
|
||
│ │
|
||
│ 终端 2：消息队列处理器（二选一） │
|
||
│ php artisan horizon ← 推荐（带 Web 监控面板） │
|
||
│ php artisan queue:work ← 简易版 │
|
||
│ │
|
||
│ 终端 3：前端热更新（开发时可选） │
|
||
│ npm run dev │
|
||
└──────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
> **说明：**
|
||
>
|
||
> - Reverb 不启动 → 在线用户列表无法加载，消息无法实时推送
|
||
> - Queue 不启动 → 消息无法广播，聊天记录无法存入数据库
|
||
> - 如果使用 Herd，Web 服务器已自动运行，无需 `php artisan serve`
|
||
|
||
### 6. 访问聊天室
|
||
|
||
打开浏览器访问 `http://chatroom.test`（Herd）或 `http://localhost:8000`
|
||
|
||
---
|
||
|
||
## 🖥️ 生产服务器部署（宝塔面板）
|
||
|
||
### 1. 服务器环境要求
|
||
|
||
- PHP 8.4+（启用 `redis`、`pcntl`、`sockets` 扩展）
|
||
- MySQL 8.0+
|
||
- Redis 7.x
|
||
- Nginx
|
||
- Node.js 20.x
|
||
- Supervisor（守护进程管理）
|
||
|
||
### 2. 上传代码 & 安装依赖
|
||
|
||
```bash
|
||
cd /www/wwwroot/chat.ay.lc
|
||
|
||
# 安装生产依赖（不含开发依赖）
|
||
composer install --optimize-autoloader --no-dev
|
||
|
||
# 安装前端依赖并构建
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
### 3. 环境配置
|
||
|
||
```env
|
||
APP_ENV=production
|
||
APP_DEBUG=false
|
||
APP_URL=https://chat.ay.lc
|
||
|
||
# Reverb（服务端监听本机，由 Nginx 反代）
|
||
REVERB_HOST=127.0.0.1
|
||
REVERB_PORT=8080
|
||
REVERB_SCHEME=http
|
||
|
||
# 前端通过 HTTPS 域名连接（Nginx 反向代理到 8080）
|
||
VITE_REVERB_HOST="chat.ay.lc"
|
||
VITE_REVERB_PORT=443
|
||
VITE_REVERB_SCHEME="https"
|
||
```
|
||
|
||
### 4. 数据库迁移
|
||
|
||
```bash
|
||
php artisan migrate --seed --force
|
||
```
|
||
|
||
### 5. 优化缓存
|
||
|
||
```bash
|
||
php artisan config:cache
|
||
php artisan route:cache
|
||
php artisan view:cache
|
||
```
|
||
|
||
### 6. Nginx 配置
|
||
|
||
为了让外界能够通过 HTTPS 正常访问常驻内存服务器（Roadrunner 8000端口）以及实时 WebSocket 广播（Reverb 8080端口），需要在宝塔面板的 Nginx 配置中进行反向代理。
|
||
|
||
在 `server {}` 块**内部**（`#REWRITE-END` 之后，禁止访问敏感文件之前）添加以下配置：
|
||
|
||
```nginx
|
||
# ── 1. 静态资源优先由 Nginx 直接响应，动态请求分流给 Octane ──
|
||
location / {
|
||
try_files $uri $uri/ @octane;
|
||
}
|
||
|
||
# ── 2. API、心跳等动态请求反向代理到本地 8000 端口 (Octane / Roadrunner) ──
|
||
location @octane {
|
||
proxy_set_header Host $http_host;
|
||
proxy_set_header Scheme $scheme;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
|
||
proxy_pass http://127.0.0.1:8000;
|
||
}
|
||
|
||
# ── 3. ⚡ WebSocket 实时广播反向代理 (Laravel Reverb 8080端口) ──
|
||
# 浏览器通过 /app 和 /apps 路径发起 WebSocket 连接
|
||
location /app {
|
||
proxy_pass http://127.0.0.1:8080;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
|
||
# 避坑提示：某些宝塔环境全局未配置 $connection_upgrade 变量，
|
||
# 直接写死 "Upgrade" 能 100% 避免 500 代理握手失败。
|
||
proxy_set_header Connection "Upgrade";
|
||
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
|
||
# WebSocket 长连接保活：120秒无数据才断开
|
||
proxy_read_timeout 120s;
|
||
proxy_send_timeout 120s;
|
||
proxy_buffering off;
|
||
}
|
||
|
||
location /apps {
|
||
proxy_pass http://127.0.0.1:8080;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "Upgrade";
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
|
||
proxy_read_timeout 120s;
|
||
proxy_send_timeout 120s;
|
||
proxy_buffering off;
|
||
}
|
||
```
|
||
|
||
**测试并重载 Nginx：**
|
||
|
||
```bash
|
||
nginx -t && systemctl reload nginx
|
||
```
|
||
|
||
> 📄 完整的 Nginx 配置示例见项目根目录 `nginx.conf.example`
|
||
|
||
### 7. Supervisor 守护进程（关键！）
|
||
|
||
在宝塔面板 → 软件商店 → 安装「Supervisor管理器」，然后添加三个守护进程，确保长连接和心跳在后台持续运行：
|
||
|
||
#### 进程一：Laravel Reverb（WebSocket 服务器）
|
||
|
||
| 配置项 | 值 |
|
||
| -------- | -------------------------- |
|
||
| 名称 | `chatroom-reverb` |
|
||
| 运行目录 | `/www/wwwroot/chat.ay.lc` |
|
||
| 启动命令 | `php artisan reverb:start` |
|
||
| 运行用户 | `www` |
|
||
| 进程数量 | `1` |
|
||
|
||
#### 进程二：Laravel Horizon（队列处理器）
|
||
|
||
| 配置项 | 值 |
|
||
| -------- | ------------------------- |
|
||
| 名称 | `chatroom-horizon` |
|
||
| 运行目录 | `/www/wwwroot/chat.ay.lc` |
|
||
| 启动命令 | `php artisan horizon` |
|
||
| 运行用户 | `www` |
|
||
| 进程数量 | `1` |
|
||
|
||
#### 进程三：Laravel Octane（Roadrunner 常驻内存服务）
|
||
|
||
| 配置项 | 值 |
|
||
| -------- | ---------------------------------------------------------- |
|
||
| 名称 | `chatroom-octane` |
|
||
| 运行目录 | `/www/wwwroot/chat.ay.lc` |
|
||
| 启动命令 | `php artisan octane:start --server=roadrunner --port=8000` |
|
||
| 运行用户 | `www` |
|
||
| 进程数量 | `1` |
|
||
|
||
> ⚠️ **如果不配置 Supervisor：**
|
||
>
|
||
> - 关闭 SSH 终端后，Reverb、Horizon 和 Octane 会立刻停止运行，导致聊天室无法打开或无法收发消息！
|
||
> - **更新代码后**：当您在服务器上完成 `git pull` 后，需要运行 `php artisan octane:reload` 重新载入内存，代码才会生效。
|
||
|
||
---
|
||
|
||
## 🔧 常用运维命令
|
||
|
||
```bash
|
||
# 清除所有缓存
|
||
php artisan cache:clear && php artisan view:clear && php artisan config:clear
|
||
|
||
# 查看队列状态（浏览器访问）
|
||
# https://chat.ay.lc/horizon （需要 15 级以上管理员权限）
|
||
|
||
# 查看 Reverb 连接调试信息
|
||
php artisan reverb:start --debug
|
||
|
||
# 重建前端资源（修改 JS/CSS 后）
|
||
npm run build
|
||
|
||
# 代码格式化
|
||
vendor/bin/pint
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 项目结构概览
|
||
|
||
```
|
||
chatroom/
|
||
├── app/
|
||
│ ├── Events/ # WebSocket 广播事件（MessageSent, UserJoined, UserLeft...）
|
||
│ ├── Http/
|
||
│ │ ├── Controllers/ # 控制器（ChatController, RoomController, AuthController...）
|
||
│ │ ├── Middleware/ # 中间件（ChatAuthenticate, LevelRequired）
|
||
│ │ └── Requests/ # 表单验证
|
||
│ ├── Jobs/ # 异步队列任务（SaveMessageJob）
|
||
│ ├── Models/ # Eloquent 模型
|
||
│ └── Services/ # 业务服务层（ChatStateService, MessageFilterService）
|
||
├── config/
|
||
│ └── reverb.php # Reverb WebSocket 配置
|
||
├── resources/
|
||
│ ├── js/
|
||
│ │ ├── bootstrap.js # Laravel Echo + Reverb 前端初始化
|
||
│ │ └── chat.js # 聊天室前端 WebSocket 事件监听
|
||
│ └── views/
|
||
│ ├── auth/ # 登录页面
|
||
│ ├── chat/ # 聊天室主界面（frame.blade.php）
|
||
│ ├── rooms/ # 房间大厅
|
||
│ ├── leaderboard/ # 排行榜
|
||
│ ├── guestbook/ # 留言板
|
||
│ └── admin/ # 后台管理
|
||
├── routes/
|
||
│ ├── web.php # Web 路由
|
||
│ └── channels.php # WebSocket 频道鉴权
|
||
├── nginx.conf.example # Nginx 配置示例
|
||
└── .env.example # 环境变量模板
|
||
```
|
||
|
||
---
|
||
|
||
## 📜 开源协议
|
||
|
||
本项目基于 [MIT License](https://opensource.org/licenses/MIT) 开源。
|