# LiveHelper

**Repository Path**: qobn/live-helper

## Basic Information

- **Project Name**: LiveHelper
- **Description**: 直播测算项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 趣玩 · 直播互动娱乐平台（liveHelper）

一个基于 **webman** 的高性能 PHP 直播互动娱乐平台：**企业官网 + 玩法中心 + SEO 博客 + 管理后台** 一体化。
主播把镜头对准直播间，观众发弹幕报「称呼 / 姓名 / 车牌号」等，系统即时给出**娱乐向**的趣玩结果（综合指数、维度评分、文字解读、关键词），全程**不依赖 AI、纯规则引擎**，结果稳定可复述。

> 合规声明：所有趣玩结果仅用于娱乐，不涉及疾病、死亡、投资、升学、医疗等确定性结论。

---

## 🌐 在线体验（测试验证地址）

| 地址 | 说明 |
| --- | --- |
| **http://live.zhengduimen.com** | 线上测试环境：注册任意账号即可登录，进入控制台体验全部玩法 |
| http://localhost:8790 | 本地启动后的访问地址 |

---

## ✨ 功能亮点

- **企业官网首页** `/`：Hero 首屏 + 核心能力 + 玩法预览（读库实时展示）+ 博客精选，浅色企业风设计
- **玩法中心** `/play`：玩法由后台维护（存 `play` 表），前端仅做展示；点击任意玩法需**注册登录**后使用
- **SEO 博客** `/blog`：WangEditor 可视化发布（图文混排 / 本地上传 / 粘贴截图），每页 10 条分页，自动生成 `sitemap.xml` / `robots.txt` / canonical / OpenGraph / `rel=prev|next`
- **双端权限分离**：
  - **普通用户**：控制台、趣玩玩法、博客浏览
  - **管理员**（`users.is_admin = 1`）：左侧菜单式管理后台 —— 玩法管理 / 文章管理 / 写文章
- **纯规则趣玩引擎**：6 种玩法，同日稳定、跨天变化，结果文案全部后台可维护

---

## 🖼 效果预览

### 公开页面（无需登录）

| 官网首页 | 玩法中心 |
| --- | --- |
| ![官网首页](docs/screenshots/home.png) | ![玩法中心](docs/screenshots/play.png) |

| 博客列表 | 博客详情 | 登录页 |
| --- | --- | --- |
| ![博客列表](docs/screenshots/blog.png) | ![博客详情](docs/screenshots/blog-detail.png) | ![登录页](docs/screenshots/login.png) |

### 主播控制台（登录用户）`/console`

![主播控制台](docs/screenshots/console.png)

### 管理后台（左侧菜单 · 需管理员 `is_admin=1` 登录）

| 玩法管理 `/admin/play` | 文章管理 `/admin/blog` |
| --- | --- |
| ![玩法管理](docs/screenshots/admin-play.png) | ![文章管理](docs/screenshots/admin-blog.png) |

| 写文章（新建）`/blog/admin` | 文章编辑（回填旧数据）`/blog/admin?edit=slug` |
| --- | --- |
| ![写文章-新建](docs/screenshots/blog-admin.png) | ![文章编辑-回填](docs/screenshots/blog-admin-edit.png) |

---

## 一、技术栈与环境要求

| 项目 | 要求 |
| --- | --- |
| PHP | **>= 8.1**（Docker 镜像用 8.3） |
| 数据库 | **MySQL 5.7+ / 8.0+**（utf8mb4） |
| 框架 | webman 2.1+（workerman）、Laravel 组件（database / pagination / events / blade） |
| 扩展 | `pdo`、`pdo_mysql`、`pcntl`（CLI 常驻必须）、`ext-event`（可选，性能更优） |
| 前端 | 原生 HTML + PHP 模板 + jQuery + WangEditor 5（自托管），无构建步骤 |
| WS 服务 | `live_server.py`（独立目录 `live-gui`，Python 3.12 + `websockets`，不在本仓库） |

---

## 二、目录结构

```
liveHelper/
├── app/
│   ├── controller/       # Index / Auth / Console / Fortune / Live / Profile / History / Play / Blog
│   ├── service/          # Auth、FortuneService（趣玩引擎）、WsRuleParser、Captcha、RateLimit、Theme、Markdown
│   ├── model/            # User / Play / FortuneHistory / FortuneRule / FortuneKeyword / Theme ...
│   ├── middleware/       # AuthCheck（登录守卫）、AdminCheck（管理员守卫）、Throttle、StaticFile
│   ├── process/          # Http（webman 主进程）、Monitor（热重载）
│   └── view/             # index / auth / console / fortune / live / profile / history / play / blog / layout
├── config/               # route.php、database.php、process.php、server.php、ws.php ...
├── database/             # schema.sql、install.sql、seed*.sql（含 play 玩法种子、funny 搞笑数据）
├── docs/screenshots/     # README 效果图
├── article/              # 博客文章存储（<slug>.json 优先，兼容 <slug>.md）
├── public/               # 静态资源（css/js/img/blog/uploads），webman 根目录
├── runtime/              # logs、sessions、views 缓存、install.lock（安装标记）
├── deploy/               # nginx-ws-proxy.conf、source_client_example.py
├── install.php           # 一键安装脚本（CLI + Web 双模式）
├── webman / start.php    # 启动入口
└── composer.json
```

---

## 三、快速开始

### 1. 配置并运行安装器

**CLI 模式（推荐服务器部署）：**
```bash
php install.php --host=127.0.0.1 --port=3306 --db=live_helper \
                --user=root --pass=你的密码 \
                --admin-email=admin@example.com --admin-pass=你的管理密码 -y
```

**Web 模式：** 浏览器访问 `http://域名/install.php`，按向导填写提交。装完**务必删除 install.php**。

安装流程：建库 → 建表（含 `users.is_admin`、`play` 玩法表）→ 导入基础/搞笑数据 + 9 个玩法种子 → 创建管理员（`is_admin=1`）→ 写回数据库配置与 `runtime/install.lock`。任意 SQL 失败都不会写入安装标记。

常用参数：`--force` 重装（清空业务表，危险）· `--unlock` 仅清安装标记 · `--use-pdo` 无 mysql CLI 时用 PDO 导入 · `--skip-seed` 只建表不灌数据。

### 2. 启动 webman
```bash
php start.php start -d     # 守护进程模式（调试模式去掉 -d）
php start.php stop
```
HTTP 服务监听 **`0.0.0.0:8790`**（见 `config/process.php`）。浏览器打开 `http://localhost:8790` 即看到官网首页。

### 3. 登录
用安装时创建的管理员邮箱登录 → 右上角下拉可进「控制台」和「玩法管理 / 文章管理」。普通注册用户只能进控制台与玩法。

---

## 四、页面与路由

路由定义见 `config/route.php`。按权限分三组：

### 公开（无需登录）
| 路由 | 说明 |
| --- | --- |
| `/` | 企业官网首页（登录后访问仍是官网，不再强跳控制台） |
| `/play` | 玩法中心，展示全部上线玩法 |
| `/blog` · `/blog?page=N` | 博客列表（每页 10 条，分页） |
| `/blog/{slug}` | 博客文章详情 |
| `/sitemap.xml` · `/robots.txt` | SEO 自动生成 |
| `/login` · `/register` · `/logout` · `/captcha` | 登录 / 注册 / 退出 / 验证码 |

### 登录用户（AuthCheck）
| 路由 | 说明 |
| --- | --- |
| `/console` | 主播控制台：玩法入口、资料快捷入口 |
| `/play/enter/{slug}` | 进入某个玩法（未登录会 302 到登录页并带 redirect） |
| `/fortune/{type}` · `POST /api/fortune/{type}` | 趣玩页（表单）与趣玩接口 |
| `/history` · `POST /history/delete` · `/history/clear` | 趣玩历史记录管理 |
| `/profile` · `POST /profile/save` · `/profile/avatar` · `/profile/password` | 个人资料 / 头像 / 密码 |

### 管理员（AdminCheck，非管理员 302 回 `/console`）
| 路由 | 说明 |
| --- | --- |
| `/admin/play`（+ `save` / `delete`） | 玩法管理：列表、新建、编辑、删除（`play` 表） |
| `/admin/blog` | 文章管理列表：编辑 / 查看 / 删除 |
| `/blog/admin?edit={slug}` | WangEditor 可视化编辑器（新建 / 编辑） |
| `POST /api/blog/publish` · `/api/blog/upload` · `/api/blog/delete` | 文章发布 / 图片上传 / 删除 |

---

## 五、趣玩引擎（FortuneService）

**设计原则：** 完全不依赖 AI，纯「规则表 + 稳定哈希 + 随机因子 + 模板匹配」。
同一输入同一天结果基本稳定（主播复述不打脸），跨天自动变化；综合指数带 ±2 随机微扰；所有文案来自 `fortune_rules` / `fortune_keywords` 表，后台改文案无需改代码（进程内缓存 60 秒）。

### 六种玩法（`FortuneService::TYPES`）

| type | 名称 | 输入字段 | 维度（权重） |
| --- | --- | --- | --- |
| `birthday` | 生日趣玩 | 称呼 / 性别 | 性格20 事业20 财运20 感情20 人缘20 |
| `love` | 情侣匹配 | A称呼 / B称呼 | 感情契合35 性格契合25 沟通20 默契20 |
| `number` | 数字趣玩 | 任意数字（≤20 位） | 数字能量30 幸运30 记忆20 数字颜值20 |
| `name` | 姓名趣玩 | 姓名（≤20 字） | 名字魅力25 性格20 社交20 幸运20 事业15 |
| `car` | 车牌趣玩 | 车牌号（≤12 位） | 号码颜值25 组合20 稀有度20 幸运20 记忆15 |
| `nickname` | 昵称趣玩 | 昵称（≤24 字）/ 来源 | 霸气25 社交20 记忆20 个性20 搞笑15 |

### 算法原语
- **命数 1-9**：数字串各位求和反复归约；文本按 UTF-8 码点求和。
- **稳定基**：`md5(输入 + 当天 Ymd)` —— 同日稳定、跨天变化。
- **结果类型**：`(md5(seed|t|category|life) % 9) + 1`，查 `fortune_rules` 取文案。
- **单项评分**：`60 + (hash % 40)` + `random_int(-2,2)` 微扰，钳制 60-99。
- **综合指数**：各维度按权重加权；情侣玩法另有命数环形距离加成；车牌有豹子/顺子/回文亮点加分。

---

## 六、直播大屏与 WebSocket（本地直连模式）

`/live/{type}` 是全屏直播画面（可直接被 OBS / 直播伴侣捕获窗口），自带 WebSocket 连接，接收 `live_server.py` 推送的观众弹幕输入并实时结算展示。主题优先级：URL `?theme=` > 用户默认主题。

```
观众弹幕 → live_server.py (本机 :8765，抓取直播间实时弹幕)
                ↓ (WebSocket)
浏览器 /live/{type}  ← ws://127.0.0.1:8765  实时结算并全屏展示
```

- **WS 服务 `live_server.py` 不在本仓库**，位于独立目录 `live-gui/`（配套 GUI 启停、`restart_ws.sh` 一键重启脚本）。Web 端需配合 live-gui 运行。
- **消息格式**（由 `WsRuleParser` 解析，类型取自页面 register 时上报的 type）：
  1. 结构化 JSON：`{"type":"birthday","name":"小明","gender":"male"}`
  2. 信封 JSON：`{"type":"birthday","raw":"小明-男"}`
  3. 裸字符串规则：`小明-男`（按当前页面注册的 type 解析）
  - 兼容旧格式：消息仍可带类型前缀（如 `生日-小明-男`），服务端优先按前缀识别。
- **混合内容注意**：大屏页面用 `http://` 打开；`https` 页面会被浏览器拦截明文 `ws://`。

---

## 七、数据库概览

> 字符集 `utf8mb4`、引擎 `InnoDB`，权威定义见 `database/schema.sql`。安装器会自动建齐并灌入种子数据。

| 表 | 作用 |
| --- | --- |
| `users` | 用户/主播。含 `is_admin TINYINT(1)`（管理员标识，安装器创建的管理员自动置 1）、`theme` 默认主题等 |
| `play` | 玩法表（官网/玩法中心数据源）。`category`(fortune/live)、`name`、`slug`(唯一)、`icon`、`summary`、`entry`、`enabled`、`sort`；安装时预置 9 个玩法 |
| `fortune_history` | 趣玩历史（每条记录输入/结果 JSON，供「我的趣玩」回顾） |
| `fortune_rules` | 趣玩结果文案库（type+category+result_type 定位，`content` 多条 `\|` 分隔随机取，`contentValue` 为搞笑释义） |
| `fortune_keywords` | 关键词库（关键词 + 搞笑释义） |
| `themes` | 直播视觉主题（预置 guofeng / cyber / dream / minimal） |
| `console_types` | 控制台玩法入口卡片（预置 3 条） |

---

## 八、部署

### Docker（自带 Dockerfile / docker-compose.yml）
```bash
docker compose up -d
# 或
docker build -t livehelper .
docker run -d -p 8790:8790 livehelper
```

### 传统部署
1. 上传代码到服务器，`composer install`
2. 跑 `php install.php ...`（CLI）或访问 `/install.php`（Web 向导），装完删掉 `install.php`
3. `php start.php start -d` 常驻（建议配合 supervisor）
4. Nginx 反代 8790，WebSocket 走本机 8765（live-gui 同机部署）；如需云端中转模式，见 `deploy/nginx-ws-proxy.conf` 与 `config/ws.php`

---

## 九、常见问题（高频）

1. **8765 端口被占 / WS 连不上**：旧 `live_server.py` 残留抢端口或被 Ctrl+Z 挂起（状态 T，端口 LISTEN 但不回握手）。用 `live-gui/restart_ws.sh` 一键重启（自动杀残留 + 脱离终端拉起）。
2. **必须用 live-gui 的 venv python**：`websockets` 库只装在 `live-gui/venv`，裸 python 会 `ModuleNotFoundError`。
3. **安装标记机制**：装完写 `runtime/install.lock`，再访问提示「已安装」；重装 `--force`，只解标记 `--unlock`。安装失败不会写标记，可安全重试。
4. **SQL 兼容**：种子文件已用 `FROM DUAL` 写法，兼容 MySQL 5.7/8.0。
5. **注册限制**：邮箱唯一、密码 6–32 位、图形验证码、同 IP 24h 最多 3 个、蜜罐防机器人；登录跳转仅允许站内相对路径；密码 bcrypt 存储。
6. **结果同日稳定**：由 `md5(输入+当天日期)` 决定，方便主播当天复述；纯娱乐合规，页面与接口均带免责声明。
7. **改了 Controller / route.php 不生效**：webman 生产模式缓存 PHP 类，需 `php start.php stop && php start.php start -d` 重启；视图 html 每次请求都重读，无需重启。

---

## 十、关键文件速查

| 文件 | 作用 |
| --- | --- |
| `install.php` | 一键安装脚本（CLI + Web），建表/种子/管理员/写回配置 |
| `config/route.php` | 全部路由（公开 / 登录 / 管理员三组） |
| `config/database.php` | 数据库连接（安装时由脚本回填） |
| `app/service/FortuneService.php` | 趣玩引擎（核心算法） |
| `app/service/WsRuleParser.php` | WS 消息解析（3 种格式） |
| `app/controller/PlayController.php` | 玩法中心 / 玩法管理后台 |
| `app/controller/BlogController.php` | 博客前台 / 编辑器 / 管理列表 / sitemap |
| `app/middleware/AdminCheck.php` | 管理员守卫（登录 + is_admin） |
| `app/view/live/stage.html` | 直播大屏前端（含 WS 连接 / 重连） |
| `database/schema.sql` · `seed*.sql` | 建表与种子（含 play 玩法、is_admin） |
| `article/` | 博客文章存储（json 优先，兼容 md） |
| `../live-gui/` | WS 数据源服务 + GUI 遥控器（**不在本仓库**） |