# 伴行 Backend

**Repository Path**: gabr/cosing-backend

## Basic Information

- **Project Name**: 伴行 Backend
- **Description**: 伴行-远程自律监督系统-后端仓库
《伴行》是一款专为需要提升自制力、克服网络依赖的用户设计的远程监督软件。

- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-20
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 伴行 Backend

#### 介绍
伴行-远程自律监督系统-后端仓库
《伴行》是一款专为需要提升自制力、克服网络依赖的用户设计的远程监督软件。

## 主要功能

### 📹 视频流监督（最新功能）
- ✅ 客户端通过WebSocket实时发送2fps的视频流
- ✅ 后端定期从视频流中截取帧进行AI分析
- ✅ 实时监控网页，可查看被监督者的实时屏幕
- ✅ 所有ntfy通知都包含"实时监控"按钮
- ✅ **基于视频流的在线检测**：仅以视频流传输判断在线状态，5秒内无视频流即显示离线（NEW!）
- ✅ **即时响应**：启动监督立即在线，停止监督5秒内离线，关闭客户端5秒内离线（NEW!）
- ✅ **实时状态同步**：设备上线/离线状态实时推送到监控页面（使用Laravel Reverb）
- ✅ 显示在线状态和最后活动时间
- ✅ 低带宽占用（2fps帧率）

### � WebSocket长连接
- ✅ 使用WebSocket替代HTTP轮询，实现实时双向通信
- ✅ 自动重连机制，保证连接稳定性
- ✅ 支持设备注册、事件上报、视频流传输等所有操作
- ✅ 视频流帧通过base64编码在WebSocket中传输
- ✅ **旧的HTTP API接口已全部删除**，仅保留WebSocket通信
- ✅ WebSocket端点：`POST /api/v1/ws/message`
- ✅ **已移除心跳机制**：不再使用心跳判断在线状态，完全依赖视频流传输（NEW!）

### �📸 截图查看功能
所有截图相关的ntfy通知现在都包含"查看截图"action按钮：
- ✅ 点击按钮打开专门的网页展示截图
- ✅ 响应式设计，适合移动端观看
- ✅ 灯箱效果，点击截图可放大查看
- ✅ 美观的渐变背景和卡片设计
- ✅ 支持深色模式
- ✅ 显示AI分析结果（如果启用）

详细说明请查看 [SCREENSHOT_VIEWER_FEATURE.md](SCREENSHOT_VIEWER_FEATURE.md)

### 🔔 通知系统
- **监控者通知**：使用ntfy向监控者发送实时推送通知
- **被监控人通知**：当设备离线时，通知被监控人的其他设备
  - PC设备：通过WebSocket实时推送
  - HarmonyOS设备：通过华为Push Kit推送（可选，需配置）
- 支持多种通知类型（设备上线/下线、截图、系统事件等）
- 可配置的通知优先级和标签
- 推送功能默认关闭，可通过配置启用（详见 [HarmonyOS推送配置指南](docs/harmonyos-push-setup.md)）

### 🤖 AI截图分析
- 使用火山引擎AI分析截图内容
- 自动生成用户活动描述
- 批量截图智能总结

### 📊 管理后台
- 基于Filament 4.x构建
- 完整的用户、设备、监控关系管理
- 可配置的系统参数
- 数据统计和查看

## 🚀 部署指南

### 环境要求
- PHP 8.2+
- MySQL 5.7+
- Composer
- Nginx/Apache
- Linux服务器（推荐）

### 1. 基础部署

#### 1.1 克隆代码
```bash
cd /www/wwwroot
git clone git@gitee.com:gabr/focus-guard-backend.git jkb.szuxy.cn
cd jkb.szuxy.cn
```

#### 1.2 安装依赖
```bash
composer install --no-dev --optimize-autoloader
```

#### 1.3 配置环境变量
```bash
cp .env.example .env
nano .env
```

必需的环境变量配置：
```env
# 应用配置
APP_NAME=CoSing
APP_ENV=production
APP_DEBUG=false
APP_URL=https://jkb.szuxy.cn

# 数据库配置
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=jkb_szuxy_cn
DB_USERNAME=jkb_szuxy_cn
DB_PASSWORD=your_password

# 队列配置（重要！）
QUEUE_CONNECTION=database

# Ntfy通知配置
NTFY_SERVER=https://ntfy.sh
NTFY_DEFAULT_TOPIC=cosing-prod
NTFY_TIMEOUT=10

# 火山引擎AI配置（可选）
VOLCANO_API_KEY=your_api_key
VOLCANO_API_URL=https://ark.cn-beijing.volces.com/api/v3/chat/completions
VOLCANO_MODEL=doubao-seed-1-8-251215
VOLCANO_TIMEOUT=30
VOLCANO_ENABLED=true

# HarmonyOS推送配置（可选，默认关闭）
HARMONYOS_PUSH_ENABLED=false
# 如需启用推送功能，请参考 docs/harmonyos-push-setup.md
# HARMONYOS_PUSH_APP_ID=your_app_id
# HARMONYOS_PUSH_APP_SECRET=your_app_secret
```

#### 1.4 生成应用密钥
```bash
php artisan key:generate
```

#### 1.5 运行数据库迁移
```bash
php artisan migrate --force
```

#### 1.6 创建管理员账户
```bash
php artisan make:filament-user
```

#### 1.7 设置文件权限
```bash
chmod -R 755 storage bootstrap/cache
chown -R www:www storage bootstrap/cache
```

### 2. WebSocket服务器配置（必需）

系统使用Workerman提供WebSocket长连接服务，**必须配置WebSocket服务器进程**。

#### 2.1 使用Supervisor管理WebSocket服务器

创建Supervisor配置文件：
```bash
nano /etc/supervisor/conf.d/cosing-websocket.conf
```

添加以下内容：
```ini
[program:cosing-websocket]
process_name=%(program_name)s
command=php /www/wwwroot/jkb.szuxy.cn/websocket-server.php start
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=root
redirect_stderr=true
stdout_logfile=/www/wwwroot/jkb.szuxy.cn/storage/logs/websocket.log
stderr_logfile=/www/wwwroot/jkb.szuxy.cn/storage/logs/websocket-error.log
```

**注意事项**：
- ⚠️ **必须使用root用户运行**（`user=root`），因为Workerman需要管理多个worker进程
- ⚠️ **不要使用`-d`参数**，Supervisor会管理进程的守护化
- ⚠️ **确保日志目录存在**：`mkdir -p /www/wwwroot/jkb.szuxy.cn/storage/logs`

启动Supervisor：
```bash
supervisorctl reread
supervisorctl update
supervisorctl start cosing-websocket
```

检查WebSocket服务器状态：
```bash
supervisorctl status cosing-websocket
```

查看WebSocket日志：
```bash
tail -f /www/wwwroot/jkb.szuxy.cn/storage/logs/websocket.log
```

#### 2.2 宝塔面板配置Supervisor

如果使用宝塔面板：
1. 进入"软件商店" → 安装"Supervisor管理器"
2. 添加守护进程（WebSocket服务器）：
   - 名称：`cosing-websocket`
   - 启动命令：`php /www/wwwroot/jkb.szuxy.cn/websocket-server.php start`
   - 运行目录：`/www/wwwroot/jkb.szuxy.cn`
   - 运行用户：`root`（⚠️ 重要！必须是root）
   - 进程数量：`1`
3. 点击"启动"

#### 2.3 Nginx WebSocket代理配置

WebSocket需要通过Nginx反向代理才能支持SSL/TLS (wss://)。

创建WebSocket代理配置文件：
```bash
nano /www/server/panel/vhost/nginx/extension/jkb.szuxy.cn/websocket.conf
```

添加以下内容：
```nginx
# WebSocket代理配置
location /api/v1/ws {
    proxy_pass http://127.0.0.1:6001;
    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 86400;
}
```

测试并重新加载Nginx：
```bash
nginx -t
nginx -s reload
```

#### 2.4 验证WebSocket服务

检查WebSocket服务器是否运行：
```bash
ps aux | grep WorkerMan
```

应该看到类似输出：
```
root      12345  0.0  2.7 120632 44840 ?  S  16:49  0:00 WorkerMan: master process
root      12346  0.0  2.6 120628 43820 ?  S  16:49  0:00 WorkerMan: worker process
root      12347  0.0  2.6 120628 43820 ?  S  16:49  0:00 WorkerMan: worker process
root      12348  0.0  2.6 120628 43820 ?  S  16:49  0:00 WorkerMan: worker process
root      12349  0.0  2.6 120628 43820 ?  S  16:49  0:00 WorkerMan: worker process
```

测试WebSocket连接：
```bash
cd /www/wwwroot/jkb.szuxy.cn
python3 test_websocket_connection.py
```

### 3. 队列系统配置（必需）

系统使用Laravel队列处理异步任务（如发送通知、AI分析等），**必须配置队列工作进程**。

#### 3.1 使用Supervisor管理队列进程

创建Supervisor配置文件：
```bash
nano /etc/supervisor/conf.d/cosing-queue.conf
```

添加以下内容：
```ini
[program:cosing-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /www/wwwroot/jkb.szuxy.cn/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www
numprocs=1
redirect_stderr=true
stdout_logfile=/www/wwwroot/jkb.szuxy.cn/storage/logs/queue-worker.log
stopwaitsecs=3600
```

启动Supervisor：
```bash
supervisorctl reread
supervisorctl update
supervisorctl start cosing-queue:*
```

检查队列进程状态：
```bash
supervisorctl status cosing-queue:*
```

#### 3.2 宝塔面板配置Supervisor

如果使用宝塔面板：
1. 进入"软件商店" → 安装"Supervisor管理器"
2. 添加守护进程（队列工作进程）：
   - 名称：`cosing-queue`
   - 启动命令：`php /www/wwwroot/jkb.szuxy.cn/artisan queue:work --sleep=3 --tries=3 --max-time=3600`
   - 运行目录：`/www/wwwroot/jkb.szuxy.cn`
   - 运行用户：`www`
   - 进程数量：`1`
3. 点击"启动"

### 4. 定时任务配置（必需）

系统使用Laravel定时任务调度器执行以下任务：
- 每分钟检查设备离线状态
- 每5分钟检查并创建待处理的截图批次
- 每天凌晨3点清理旧截图

#### 4.1 配置Crontab

运行配置脚本：
```bash
cd /www/wwwroot/jkb.szuxy.cn
bash setup_crontab.sh
```

或手动添加：
```bash
crontab -e
```

添加以下行：
```cron
* * * * * cd /www/wwwroot/jkb.szuxy.cn && php artisan schedule:run >> /dev/null 2>&1
```

#### 4.2 验证定时任务

查看已配置的定时任务：
```bash
php artisan schedule:list
```

应该看到：
```
*   * * * *  php artisan device:check-offline ............. Next Due: X 秒后
*/5 * * * *  php artisan batches:check-pending .......... Next Due: X 分钟后
0   3 * * *  php artisan screenshots:cleanup --days=2 .. Next Due: X 小时后
```

### 5. Nginx配置

示例Nginx配置：
```nginx
server {
    listen 80;
    listen 443 ssl http2;
    server_name jkb.szuxy.cn;

    # SSL证书配置
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # 强制HTTPS
    if ($server_port !~ 443){
        rewrite ^(/.*)$ https://$host$1 permanent;
    }

    root /www/wwwroot/jkb.szuxy.cn/public;
    index index.php index.html;

    # 文件上传大小限制
    client_max_body_size 20M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/tmp/php-cgi.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
```

### 6. 部署检查清单

部署完成后，请检查以下项目：

- [ ] 数据库连接正常
- [ ] 文件权限正确（storage和bootstrap/cache可写）
- [ ] **WebSocket服务器运行中**（`supervisorctl status cosing-websocket`）
- [ ] **WebSocket连接测试成功**（`python3 test_websocket_connection.py`）
- [ ] 队列进程运行中（`supervisorctl status cosing-queue:*`）
- [ ] Crontab已配置（`crontab -l`）
- [ ] 定时任务正常（`php artisan schedule:list`）
- [ ] 可以访问管理后台（https://jkb.szuxy.cn/admin）
- [ ] Ntfy通知测试成功（`php test_ntfy.php`）
- [ ] 截图上传功能正常

### 7. 常用维护命令

#### 7.1 WebSocket服务器管理

```bash
# 查看WebSocket服务器状态
supervisorctl status cosing-websocket

# 重启WebSocket服务器
supervisorctl restart cosing-websocket

# 停止WebSocket服务器
supervisorctl stop cosing-websocket

# 启动WebSocket服务器
supervisorctl start cosing-websocket

# 查看WebSocket日志
tail -f /www/wwwroot/jkb.szuxy.cn/storage/logs/websocket.log

# 查看WebSocket错误日志
tail -f /www/wwwroot/jkb.szuxy.cn/storage/logs/websocket-error.log

# 查看WebSocket进程
ps aux | grep WorkerMan

# 测试WebSocket连接
cd /www/wwwroot/jkb.szuxy.cn
python3 test_websocket_connection.py
```

#### 7.2 队列系统管理

```bash
# 查看队列进程状态
supervisorctl status cosing-queue:*

# 重启队列进程
supervisorctl restart cosing-queue:*

# 查看队列日志
tail -f storage/logs/queue-worker.log
```

#### 7.3 应用维护

```bash
# 查看应用日志
tail -f storage/logs/laravel.log

# 手动执行定时任务
php artisan schedule:run

# 手动检查待处理批次
php artisan batches:check-pending

# 手动检查离线设备
php artisan device:check-offline

# 清理旧截图
php artisan screenshots:cleanup --days=2

# 清除缓存
php artisan config:clear
php artisan cache:clear
php artisan view:clear
```

#### 7.4 代码更新流程

```bash
# 更新代码
cd /www/wwwroot/jkb.szuxy.cn
git pull

# 安装依赖
composer install --no-dev --optimize-autoloader

# 运行数据库迁移
php artisan migrate --force

# 清除缓存
php artisan config:clear

# 重启所有服务
supervisorctl restart cosing-websocket
supervisorctl restart cosing-queue:*
```

### 8. 故障排查

#### WebSocket连接失败
1. 检查WebSocket服务器是否运行：`supervisorctl status cosing-websocket`
2. 查看WebSocket日志：`tail -f storage/logs/websocket.log`
3. 检查Nginx配置是否正确：`nginx -t`
4. 测试WebSocket连接：`python3 test_websocket_connection.py`
5. 检查防火墙是否开放6001端口（内部端口，不需要对外开放）
6. 重启WebSocket服务器：`supervisorctl restart cosing-websocket`

#### WebSocket认证失败
1. 检查客户端token是否有效
2. 查看WebSocket日志中的认证错误
3. 确认Laravel应用能正常访问数据库
4. 检查Sanctum配置是否正确

#### 队列任务不执行
1. 检查队列进程是否运行：`supervisorctl status cosing-queue:*`
2. 查看队列日志：`tail -f storage/logs/queue-worker.log`
3. 检查数据库jobs表是否有积压任务
4. 重启队列进程：`supervisorctl restart cosing-queue:*`

#### 定时任务不执行
1. 检查crontab配置：`crontab -l`
2. 查看定时任务列表：`php artisan schedule:list`
3. 手动执行测试：`php artisan schedule:run`
4. 检查系统日志：`tail -f /var/log/cron`

#### 通知不发送
1. 测试Ntfy连接：`php test_ntfy.php`
2. 检查队列是否正常运行
3. 查看应用日志：`tail -f storage/logs/laravel.log`
4. 检查监督者的ntfy_topic配置

#### 截图批次不创建
1. 检查定时任务是否运行
2. 手动执行：`php artisan batches:check-pending`
3. 查看未处理截图：`php check_unprocessed_screenshots.php`
4. 检查screenshot_batch_interval_minutes配置

#### AI截图分析失败（404错误）
**问题描述**: ntfy通知中显示"截图分析失败：Volcano AI API error: 400 - Error while downloading: https://jkb.szuxy.cn/storage/screenshots/xxx.jpg, status code: 404"

**根本原因**: WebSocket上传的截图存储位置和路径结构与HTTP上传不一致
- WebSocket上传使用默认的`local` disk（`storage/app/private`），无法通过web访问
- HTTP上传使用`public` disk（`storage/app/public`），可以通过`/storage/`路径访问

**解决方案**: 已修复（2026-01-03）
- 修改了`WebSocketMessageHandler.php`，使WebSocket上传与HTTP上传保持一致
- 现在所有截图都存储在`public` disk，路径结构为`screenshots/{supervisee_id}/{device_id}/{date}/{time}_{uniqid}.jpg`

**验证步骤**:
1. 重启WebSocket服务器：`supervisorctl restart cosing-websocket`
2. 使用客户端上传一张截图
3. 检查截图是否存储在正确位置：`ls -la storage/app/public/screenshots/`
4. 检查ntfy通知中的AI分析是否成功

## 📚 相关文档

- [部署状态报告](DEPLOYMENT_STATUS.md) - 当前部署状态和配置清单
- [README.md](README.md) - 完整部署指南（本文档）
- [基于视频流的在线检测](VIDEO_STREAM_ONLINE_DETECTION.md) - 新的在线检测机制说明和部署指南（NEW!）
- [视频流部署指南](VIDEO_STREAM_DEPLOYMENT.md) - 视频流功能部署和配置
- [实时监控修复指南](REALTIME_MONITOR_FIX.md) - 实时监控Reverb配置修复
- [Ntfy通知系统设置指南](NTFY_SETUP.md)
- [截图查看功能说明](SCREENSHOT_VIEWER_FEATURE.md)
- [批次通知问题分析](BATCH_NOTIFICATION_ANALYSIS.md)
- [快速参考手册](QUICK_REFERENCE.md)

## 🔧 技术栈

- **后端框架**: Laravel 11.x
- **管理面板**: Filament 4.x
- **数据库**: MySQL 5.7+
- **WebSocket服务器**: Workerman 5.1.7
- **实时通信**: WebSocket (wss://)
- **实时广播**: Laravel Reverb (WebSocket Broadcasting)
- **队列**: Laravel Queue (Database Driver)
- **通知**: Ntfy Push Notifications
- **AI分析**: 火山引擎豆包大模型
- **任务调度**: Laravel Task Scheduler + Crontab
- **进程管理**: Supervisor
- **Web服务器**: Nginx (反向代理 + SSL终止)

## 📝 开发说明

### 本地开发环境

本地使用SQLite数据库进行开发：

```env
DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/database.sqlite
```

### 服务器信息

- **服务器IP**: 120.79.129.18
- **系统**: Linux
- **部署路径**: /www/wwwroot/jkb.szuxy.cn
- **网站访问**: https://jkb.szuxy.cn
- **管理后台**: https://jkb.szuxy.cn/admin
- **本地开发**: http://127.0.0.1:8000

### Git仓库

- **后端仓库**: git@gitee.com:gabr/focus-guard-backend.git
- **PC客户端**: git@gitee.com:gabr/focus-guard-pc-client.git

### 管理员账户

- **用户名**: admin
- **邮箱**: gabrielshell@163.com
- **密码**: Nio159462（开发/生产环境相同）

## 🎯 项目初始需求

我想要做一个windows软件，这个软件是用来帮助监督电脑使用者，使电脑使用者戒除网瘾的的，它用于这种情景：某人请了别人来监督他使用电脑，他开了腾讯会议共享自己的屏幕，请人监督自己，不要玩电脑，但是他常常要带着电脑去不同的地方，带着走的时候必然要关闭电脑（或者让电脑休眠），所以监督者也不知道他什么时候开着电脑，造成监控空窗期，就容易让他玩电脑。

现在需要有个软件，随电脑启动，每次启动都要检查是否随电脑启动，如果这个随电脑启动的设置没有开启，需要提醒他开启，同时通知监督者。电脑一启动或者从休眠苏醒，都要通知监督者。电脑关闭或者休眠也要通知监督者。如果他手动关闭，或者通过进程管理器强制关闭，都要通知监督者。电脑开启的过程中，每分钟截图发送给服务器。服务器总结截图，每半个小时，总结30张截图，一起邮件发送给监督者。

这个程序需要有后端(laravel+filament 4.x)，和前端（python+pyside最后需要编译成exe，要有脚本能有一键编译为exe），通知方式用邮件通知。服务器端要有完整的管理后台，可以管理所有的监控者、被监控着以及他们的关系，可以做各种配置（尽量把各种参数做成可配置），还要有可查看的各类数据。

**设计原则**: 严密！确保不要给被监督者任何机会。但是注意不要做成了流氛软件，允许关闭、卸载软件，但是所有的操作都需要通知监督者。

#### 初始提示词
我想要做一个windows软件，这个软件是用来帮助监督电脑使用者，使电脑使用者戒除网瘾的的，它用于这种情景：某人请了别人来监督他使用电脑，他开了腾讯会议共享自己的屏幕，请人监督自己，不要玩电脑，但是他常常要带着电脑去不同的地方，带着走的时候必然要关闭电脑（或者让电脑休眠），所以监督者也不知道他什么时候开着电脑，造成监控空窗期，就容易让他玩电脑。现在需要有个软件，随电脑启动，每次启动都要检查是否随电脑启动，如果这个随电脑启动的设置没有开启，需要提醒他开启，同时通知监督者。电脑一启动或者从休眠苏醒，都要通知监督者。电脑关闭或者休眠也要通知监督者。如果他手动关闭，或者通过进程管理器强制关闭，都要通知监督者。电脑开启的过程中，每分钟截图发送f发送给服务器。服务器总结截图，每半个小时，总结30张截图，一起邮件发送给监督者。
这个程序需要有后端(laravel+filament 4.x)，和前端（python+pyside最后需要编译成exe，要有脚本能有一键编译为exe），通知方式用邮件通知。服务器端要有完整的管理后台，可以管理所有的监控者、被监控着以及他们的关系，可以做各种配置（尽量把各种参数做成可配置），还要有可查看的各类数据。
你是最强软件产品设计师，请你设计这款监督产品。确保不要给被监督者任何机会。严密，严密！
但是注意不要做成了流氓软件，允许关闭、卸载软件，但是所有的操作都需要通知监督者。
请直接帮我部署到服务器，服务器信息已经给出。
请使用git来进行服务器与本地的文件同步，本地和服务器都已经设置好了与gitee的密钥公钥连接。
本地为了方便开发，使用sqlite数据库，服务器部署使用mysql数据库。filament和laravel在本地和服务器都已经安装好，数据库连接都已经设置好，laravel初始化migration以及filament初始化、初始用户创建都已经完成。