# JiuduoCloud **Repository Path**: dyw0908/jiuduo-cloud ## Basic Information - **Project Name**: JiuduoCloud - **Description**: 九多肉多云眸直播平台 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-01 - **Last Updated**: 2026-11-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # JiuduoCloud · 九多肉多云眸直播共享平台 > 模式 B(自建直播单):云眸只做**设备源 + 标准流取流**(HLS 带有效期防盗链 + 云眸 UIKit 播放),直播单 / 分享 / 播放全自建。 > 视频流不经过本服务器——观众浏览器经云眸 UIKit / HLS 直连云眸流媒体 CDN 播放(控制面架构)。 ## 一、核心需求 | 编号 | 需求 | 实现 | |------|------|------| | 1 | 从云眸获取设备列表 | `A1/A2/A3` + `CloudEyeClient.GetDevicesAsync/GetChannelsAsync` | | 2 | 管理平台建直播单、设备多选 | `A4` 创建接口,前端多选设备通道 | | 3 | 二维码/URL 免登录观看 | `A10` 分享链接+二维码,`P1/P2/P3` 免登录观看页 | | 4 | 手机端(标签栏切画面)/ PC 端(网格同屏) | `wwwroot/watch.html` 响应式 H5 | ## 一·补 业务流程(直播间语义,重要) **一个直播间 = 一个二维码 = 该直播间内全部摄像头画面。** 不是「一个摄像头一个二维码」。 ``` ① 创建直播间(管理后台,需登录) 勾选多个摄像头 → POST /api/live-sheets → 生成 live_sheet + live_sheet_device(N 路) ↓ ② 实时观看(创建后立即可看) 点「实时观看」→ /live/{token} → PC 网格同屏 / 手机顶部标签切画面 ↓ ③ 分享直播间二维码 GET /api/live-sheets/{id}/share → 一个二维码 + 一条 /live/{token} 链接 ↓ ④ 扫码进入直播间(免登录) 播放该直播间内「全部」选中摄像头画面(meta 返回 devices 数组,前端全部渲染) ``` **取流时机(关键修正)**:E5 开通 + E6 取流**不再只在建单时做一次**。 改为 **「扫码即取流」的惰性模式** —— `PublicWatchController.Meta` 在返回前调用 `LiveSheetService.EnsureStreamsAsync(sheetId)`,仅对「已过期或 5 分钟内将过期」的路数重新取流, 同一直播间 60 秒内不重复取(防刷)。好处: - 分享链接 7 天有效,但流地址只有 1 小时 —— 观众任何时候扫码都能拿到新鲜地址,不会看到"无信号"; - 没人看的直播间不再后台空转续期,省云眸流量与接口调用; - 单路取流失败(如流量超额 60061)不影响直播间其他摄像头。 后台 `StreamRenewalWorker` 仍保留,作为长看场景的兜底(且已跳过过期/已结束的直播间)。 ## 二、技术栈 - **后端**:.NET 9(分层:Core / Integration / Data / Api) - **数据**:SQLite(仅业务数据,不含视频),EF Core + `Microsoft.EntityFrameworkCore.Sqlite`(文件库,零依赖、启动自动建表) - **前端**:`wwwroot/watch.html`(H5 观看页,hls.js + 云眸 UIKit 兼容) - **管理后台前端**:规划于 `web/`(Vue3 / Uni-app,TODO) ## 三、分层结构 ``` src/ ├── CloudEye.Core # 配置(CloudEyeOptions)、常量(CloudEyeApi/Errors)、模型、DTO、ITokenCache ├── CloudEye.Integration # 云眸 REST 客户端 CloudEyeClient(E1–E6) + TokenProvider(缓存/续期) ├── CloudEye.Data # EF Core 上下文、实体(对应 DDL)、仓储、DbTokenCache └── CloudEye.Api # ASP.NET Core:控制器、业务服务、流地址续期后台作业、H5 ├── AuthController / AuthService # Cookie 登录鉴权 + 默认管理员播种 ├── AdminController + AdminPages/ # 管理后台页面(登录页 + 控制台) ├── CloudEyeController / LiveSheetsController # 受保护的管理 API └── PublicWatchController # 免登录公开观看端 sql/schema.sql # 建表 DDL(7 张表:含 sys_user) docs/ # 方案与接口清单(来自仓库既有 md) ``` ## 四、接口清单(已实现) > 管理端按需求迭代:除「创建直播间 + 分享二维码」外,已补回**编辑设备 / 延长有效期 / 删除**,并新增**云眸分组同步(只读)**与**账号管理**。所有管理接口均启用 Cookie 登录鉴权。 **鉴权 / 账号管理** - `POST /api/auth/login` — 登录(免鉴权) - `POST /api/auth/logout` — 退出(需登录) - `GET /api/auth/me` — 当前用户(需登录,返回 id/username) - `GET /api/auth/users` — 账号列表 - `POST /api/auth/users` — 新增账号(密码 ≥ 8 位,用户名唯一) - `PUT /api/auth/password` — 修改**自己**的密码(校验原密码) - `PUT /api/auth/users/{id}/password` — 重置他人密码(不允许重置自己) - `DELETE /api/auth/users/{id}` — 删除账号(不允许删自己,至少保留一个) **管理端(需登录 `[Authorize]`)** - `POST /api/cloud-eye/sync` — 同步设备/通道 **+ 云眸分组**(建单前先同步) - `POST /api/cloud-eye/sync-groups` — 仅同步分组(云眸后台改了分组后刷新) - `GET /api/cloud-eye/devices` — 设备列表(建单多选,带 `groupName`) - `GET /api/cloud-eye/groups` — 分组概览(各组设备数 + 未分组数量 + 同步时间) - `POST /api/live-sheets` — 创建直播单(多选设备 + 取流落库) - `GET /api/live-sheets` — 直播单列表 - `GET /api/live-sheets/{id}/devices` — 直播单当前设备(编辑回显) - `PUT /api/live-sheets/{id}/devices` — **编辑设备**(整体替换,新增设备重新取流,保存后立即生效) - `POST /api/live-sheets/{id}/extend` — **延长有效期**(`hours<=0` = 改为永久;二维码内容不变) - `DELETE /api/live-sheets/{id}` — **删除直播单**(链接与二维码立即失效) - `GET /api/live-sheets/{id}/share` — 分享链接 + 二维码(含 `baseUrlSourceText`,可见地址来源) - `GET /api/settings/share-domain` — 查看当前分享域名 / 实际生效地址 / 来源 / 本机局域网 IP - `PUT /api/settings/share-domain` — 保存分享域名(**立即生效,无需重启**;留空 = 自动探测) - `POST /api/settings/share-domain/use-lan` — 一键设为「本机局域网地址」(手机同 WiFi 扫码) - `GET /api/settings/general` — 全局参数只读(appsettings.json 中的有效期/上限等) **公开观看端(免登录,校验 share_token + 有效期)** - `GET /live/{token}` — H5 观看页(链接过期 → 友好提示页) - `GET /api/live/{token}/meta` — 观看元数据(含 `expireAt`/`remainSeconds`;过期 → 410) - `GET /api/live/{token}/qrcode` — 二维码 PNG ## 五、管理后台(登录) - 入口:`/admin/login`(登录页)→ 登录后进入 `/admin`(控制台)。 - 默认管理员:`admin / Admin@123456`(在 `appsettings.json` 的 `Auth:DefaultAdminUser/DefaultAdminPassword` 配置;库无用户时自动播种,生产请务必修改)。 - 控制台菜单(左侧二级): - **直播间管理**:创建直播单(按分组勾选设备)/ 直播单列表(实时观看、二维码、编辑设备、延长有效期、删除) - **设备管理**:摄像头列表(**按云眸分组分段展示**,分组只读) - **系统设置**:基础设置(分享域名 + 全局参数只读 + 模拟数据)/ 账号管理(账号列表、新增、改密、删除) - 鉴权方式:ASP.NET Core Cookie 认证;未登录访问 `/api/*` 返回 401,访问 `/admin` 跳转登录页。 - **分组来源**:云眸「设备分组」(`GET /api/v1/open/basic/groups/actions/listAll`),本平台只读;新建/改名/删除/设备转组请到云眸后台,再点「同步设备与分组」。账号未开通分组能力时自动降级为「未分组」,不影响设备同步。 ## 六、关键约定与坑(见 docs 接口清单) - ⚠️ **H.264 强制**:H.265 设备需先在设备网页端改编码,否则标准流取不到。 - ⚠️ **先关加密**:`is_encrypt=1` 的设备必须先在云眸后台关闭加密才能建单,否则报 `50150001`/`60019`(建单已拦截提示)。 - ⚠️ **token 频率**:`/oauth/token` 调用过频会作废现有 token;服务端单例缓存,过期前 30 分钟静默续期(`TokenProvider`)。 - ⚠️ **流地址过期**:分享用 E6 带 `expireTime` 防盗链;后台作业 `StreamRenewalWorker` 在 `stream_expire_at` 前 30 分钟自动续期,避免观看中途断流。 - ⚠️ **流量配额**:E5 返回 `ret=60061` 表示账号流量超额/未购买标准流套餐。 - ⚠️ **字段命名**:巡检描述中的 `url_expires_at` 即本库 `live_sheet_device.stream_expire_at`。 ## 六·补 分享链接(/live/{token})有效期 三层"有效期"要分清,别混: | 层级 | 字段 / 配置 | 默认 | 过期后果 | 谁来续 | |---|---|---|---|---| | ① **分享链接**(本文主题) | `live_sheet.expire_at`,配置 `CloudEye:DefaultSheetExpireHours` | 168h(7 天) | 观众打开提示「分享链接已过期」 | 不自动续,需重新建单 | | ② **流地址防盗链** | `live_sheet_device.stream_expire_at`,配置 `CloudEye:DefaultStreamExpireSec` | 3600s(1 小时) | 画面中断 | 后台 `StreamRenewalWorker` 自动续期 | | ③ **云眸 access_token** | `cloud_eye_token.expires_at` | 7 天 | 取流接口 401 | `TokenProvider` 到期前 30 分钟静默续期 | **怎么设置 ①(三种方式,优先级从高到低)** 1. **管理后台 UI(推荐)**:创建直播间时选「分享有效期」下拉(1 小时 / 6 小时 / 12 小时 / 1 天 / 3 天 / **7 天(默认)** / 30 天 / 永久有效)。 2. **建单接口传参**: ```jsonc POST /api/live-sheets { "name": "车间A监控", "deviceChannels": [{"deviceId": 12, "channelNo": 1}], "expireHours": 24, // 24 小时后失效;0 = 永久 "expireAt": "2026-11-09T10:00:00+08:00" // 或直接指定时刻(优先级高于 expireHours) } ``` 3. **全局默认配置** `src/CloudEye.Api/appsettings.json`: ```jsonc "CloudEye": { "DefaultSheetExpireHours": 168, // 建单未指定时用这个;0 = 永久 "MaxSheetExpireHours": 8760 // 上限(0 = 不限制),防止链接长期外泄 } ``` **过期后的行为** - `GET /live/{token}` → 直接返回友好提示页(⛔ 分享链接已过期),不再返回播放器页面。 - `GET /api/live/{token}/meta` → **HTTP 410 Gone**,`{"error":"分享链接已过期"}`。 - 后台续期作业会**跳过**已过期/已结束直播单,不再白耗云眸流量与接口调用。 - 分享接口 `GET /api/live-sheets/{id}/share` 会返回 `expireAt` / `expired` / `remainSeconds`,管理后台据此显示倒计时并在已过期时红色告警。 - 观看页右上角实时显示剩余有效期(如「⏱ 6天23小时后失效」)。 > 时间统一以 **UTC 落库**,前端展示时按浏览器本地时区换算;直接改库时请写 UTC,否则会差 8 小时。 > 已支持:直播单列表「⏱ 延长」调用 `POST /api/live-sheets/{id}/extend`,已过期的链接从当前时间起重新计算;`hours<=0` 改为永久有效。二维码内容不变,扫码时按新 `expireAt` 判断是否放行。 ## 六·补二 分享域名(对外访问地址)配置 二维码里写的地址由 `ShareUrlResolver` 按**三级优先级**决定,**域名配了就优先用域名**: | 优先级 | 条件 | 结果 | 典型场景 | |---|---|---|---| | ① | `CloudEye:PublicDomain` 已配置且非占位域名 | 直接用 | 公网部署(`https://live.your.com`) | | ② | 未配置,但后台是用局域网 IP / 内网域名打开的 | 用该请求 Host | 内网直接访问 | | ③ | 未配置,且后台用 `localhost` 打开 | **自动探测本机局域网 IPv4** → `http://192.168.x.x:5041` | 本机开发,手机扫码 | - 占位域名(`example.com` / `localhost` / `your-domain` 等)会被识别为**未配置**,不会误用。 - 第 ③ 条很重要:`localhost` 在手机上指向手机自身,二维码写 localhost 必然打不开。 **两种配置方式** 1. **管理后台在线配(推荐,立即生效、无需重启)** `⚙️ 分享域名` 面板:填域名 → 保存;或点「用局域网地址」一键填充;「清除」恢复自动探测。 面板实时显示:当前配置 / **实际会生成什么地址** / 地址来源 / 本机局域网 IP。 2. **改配置文件 / 环境变量** ```jsonc "CloudEye": { "PublicDomain": "https://live.your.com" } // 留空 = 自动探测 ``` 也支持环境变量 `CloudEye__PublicDomain=https://live.your.com`(容器部署方便)。 实现要点:`ShareUrlResolver` 用 `IOptionsMonitor`,配合文件配置源默认的 `reloadOnChange`,后台保存 appsettings.json 后**下一次生成二维码即生效**,不用重启进程。 裸域名会自动补 `https://`(如填 `live.your.com` → `https://live.your.com`)。 > ⚠️ 公网部署时,域名必须配 HTTPS:移动端/微信的 HLS 播放强制要求 HTTPS,否则画面拉不起来。 ## 七、快速开始 ```bash # 1. 建库:无需手动执行。SQLite 库文件 jiuduo-cloud.db 会在启动时由 EF Core EnsureCreated 自动创建(并播种默认管理员)。 # (如需手工初始化可参考 sql/schema.sql 的 SQLite 版本) # 2. 配置(src/CloudEye.Api/appsettings.json) # ConnectionStrings.Default -> Data Source=jiuduo-cloud.db(默认即可,可改为绝对路径) # CloudEye.ClientId/ClientSecret -> 云眸开发者账号 # CloudEye.PublicDomain -> 公开观看页公网域名(HTTPS);留空=自动探测(见「六·补二」) # 也可在管理后台「⚙️ 分享域名」面板在线配置,立即生效 # Auth.DefaultAdminPassword -> 改掉默认管理员密码 # 3. 运行 dotnet run --project src/CloudEye.Api # 管理后台登录: http://localhost:5041/admin/login # 落地页(功能导航): http://localhost:5041/ ``` ## 七·补 模拟模式与测试数据(无云眸凭据也能跑通全流程) 未配置 `CloudEye:ClientId`(或显式设 `MockEnabled: true`)时自动进入**模拟模式**:`ICloudEyeClient` 切换到 `MockCloudEyeClient`,E1–E6 全部本地造假数据。填入真实凭据后**自动切回**真实云眸,无需改代码。 **模拟数据内容** - 6 台模拟设备:5 台在线 + 1 台离线(`DEV-MOCK-004`)+ 1 台**已加密**(`DEV-MOCK-005`,用于验证建单拦截)。 - HLS 取流地址用**公开测试流**(`test-streams.mux.dev`、Apple BipBop 等),观看页**能真实出画面**, 便于验证手机端标签栏切画面、PC 端网格同屏。FLV 无公开测试源,返回 `*.invalid` 占位(PC 端播放实际走 hlsUrl)。 **一键造数据(管理后台 / 接口二选一)** ```bash # 管理后台:登录后「🧪 测试数据(模拟模式)」面板 → 生成测试数据 / 清空测试数据 # 该面板仅在模拟模式下出现(由 GET /api/dev/status 的 mockEnabled 控制) # 或直接用接口(需先登录拿 Cookie) curl -c ck.txt -X POST -H "Content-Type: application/json" \ -d '{"username":"admin","password":"Admin@123456"}' http://localhost:5041/api/auth/login curl -b ck.txt -X POST http://localhost:5041/api/dev/seed # 造数据 curl -b ck.txt -X POST http://localhost:5041/api/dev/reset # 清空 ``` `seed` 会同步 6 台设备并建 4 张覆盖不同有效期状态的直播单: | 直播单 | 路数 | 有效期 | 验证点 | |---|---|---|---| | 车间A-生产线监控 | 2 | 7 天后 | 默认场景,正常观看 | | 厂区周界巡检 | 3 | 1 小时后 | 后台/观看页倒计时 | | 仓库临时分享 | 1 | **已过期** | 打开提示「分享链接已过期」、meta 返回 410 | | 办公楼大堂直播 | 1 | 永久 | `expireAt=null` 永不拦截 | > ⚠️ `/api/dev/*` 仅在模拟模式可用,真实凭据下全部返回 400,避免误操作生产数据。 **完整业务流程自测路径** 登录 `/admin/login` → 同步设备 → 勾选设备(别选加密那台)+ 选有效期 → 创建直播间 → 下方「分享/二维码」生成链接 → 用手机/另一个浏览器打开 `/live/{token}` 免登录观看。 ## 八、部署要点(控制面) - 后端本质 = Web API + 小关系库:**不需要** ZLMediaKit / 流媒体服务器 / GPU / 转码 / 大带宽。 - 出站只需放通 `api2.hik-cloud.com:443`;视频 CDN 由观众浏览器直连。 - 公开观看页**必须 HTTPS**(微信/移动端 HLS 强制要求)。 - 管理后台走 Cookie 登录;**必须 HTTPS** 且建议限内网 / VPN / IP 白名单(Cookie 含登录态)。 - `.gitignore` 已忽略 `bin/ obj/ web/node_modules/`(.NET + 前端)。