chatroom/README.md

# 🌟 飘落流星聊天室（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 配置

在宝塔面板的 Nginx 配置中，需要添加 WebSocket 反向代理。

**第一步：** 在 `server {}` 块的**外面上方**添加：

```nginx
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}
```

**第二步：** 在 `server {}` 块**内部**（`#REWRITE-END` 之后）添加：

```nginx
location /app {
    proxy_pass             http://127.0.0.1:8080;
    proxy_http_version     1.1;
    proxy_set_header       Upgrade $http_upgrade;
    proxy_set_header       Connection $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;
}

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 $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;
}
```

**第三步：** 在宝塔面板 → 网站 → 伪静态中选择 `laravel5`。

**第四步：** 测试并重载 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` |
| 进程数量 | `1`                        |

#### 进程二：Laravel Horizon（队列处理器）

| 配置项   | 值                        |
| -------- | ------------------------- |
| 名称     | `chatroom-horizon`        |
| 运行目录 | `/www/wwwroot/chat.ay.lc` |
| 启动命令 | `php artisan horizon`     |
| 进程数量 | `1`                       |

> ⚠️ **如果不配置 Supervisor：**
>
> - 关闭 SSH 终端后，Reverb 和 Horizon 会立刻停止
> - 聊天室将无法发送/接收消息，在线列表为空

---

## 🔧 常用运维命令

```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) 开源。