gitlab-instance-0a899031_sh/d2ypp2/docs/HOMELAB_OPTIMIZATION_PLAN.md

Homelab 一键直播系统优化方案

本方案把 /home/eric/sh/d2ypp2 作为核心源码与发布来源，目标是在 x86_64 / arm64 Linux 主机上通过一键脚本安装统一服务，并在 http://live.local 提供可展示、可控制、可诊断的 Web 面板。

目标状态

• 一键安装：install-all.sh 可在 Debian / Ubuntu / Armbian 类系统上完成 Core OS、Infra Service、Business、Web Console 四层安装；install-core.sh 与 install-live.sh 可独立运行。
• 统一入口：live.local 由 Caddy live-edge.service 承接，默认反代到 live-console.service，并由 live-edge-watch.service 持续自愈，控制台无需记端口。
• 总览：展示硬件、软件、网络、直播业务状态，并给出健康检查、失败原因与下一步操作。
• 服务：展示 ShellCrash、SRS、Neko、Redroid、ADB、File Browser、Netdata、WebTTY 等服务的安装、运行、端口与控制按钮。
• YouTube 无人直播：单频道与多频道 Pro 共存。每条 Pro 线路独立保存 URL、推流密钥、PM2 进程、日志、Neko 工作室入口。
• TikTok 无人直播：视频源转发到设备 HDMI，面板可检测输出设备、预览命令、启动/停止链路。
• 安卓：Redroid 与真实手机都通过 ADB 识别；Web 面板可看屏、点按、长按、输入、安装 APK、批量执行命令。
• 网络：ShellCrash 解决单机代理上网，面板展示实时/累计上行下行、代理状态、DNS 与出口连通性。

源码与部署边界

当前说明里提到“核心源码”和“实际部署同步另一个文件夹”分离，后续必须固定一个发布流程：

• 源码目录只以 /home/eric/sh/d2ypp2 为准，实际部署目录不手工改代码。
• upgrade-live.sh 负责从源码构建前端、刷新 systemd 单元、同步配置模板、重启 live-console 与 live-edge。
• /opt/live/config 是设备上的运行配置中心；源码里的 live-platform/config/defaults/ 只提供默认模板。
• 用户数据与账号态必须持久化到 /opt/live/state、/opt/live/logs、/opt/live-modules/*，不能随升级覆盖。

P0：先修可用性闭环

1. 安卓 Web 画面与触控

现状：已有 /android/screenshot、/android/action、/android/scrcpy/ws，前端也有截图轮询和 scrcpy H.264 WebSocket。但在 scrcpy-server、WebCodecs、ADB forward、无线断连、Redroid 启动未完成时，界面容易表现为空白，用户误以为安卓不可控。

优化：

• WebSocket 真流失败时自动降级到 PNG 截图轮询，仍保留点按/双击/长按。
• 在安卓页显式展示 adb devices -l、scrcpy-server jar、WebCodecs、截图接口、触控接口的诊断结果。
• Redroid 启动后自动 adb connect 127.0.0.1:5555，真实手机则提示 USB 授权或无线配对。
• 触控坐标优先按截图/Canvas 实际像素映射；旋转后重新读取 wm size 与截图尺寸。

涉及文件：

• web-console/components/live-product/LiveAndroidStreamConsole.tsx
• src/android_control.py
• src/scrcpy_stream.py
• src/redroid_control.py
• web.py

验收：

• scrcpy-server 不存在或 WebSocket 失败时，安卓页仍能显示截图并可点按。
• Redroid、USB 手机、无线 ADB 至少各有一条诊断路径。
• pytest tests/test_android_redroid.py 通过，前端 npm run build 通过。

2. Neko 基线与 Google 友好

现状：Neko 运行路径已经改为动态生成 compose。NEKO_INSTANCE_COUNT 默认保底 2，最大受 NEKO_MAX_INSTANCE_COUNT 限制并封顶 64；每个实例都有独立 profile、HTTP/WebRTC 端口、Tampermonkey 持久化、开发者模式与 IP 变更 watchdog。默认是个人管理员浏览器模式，不挂 Chrome 企业策略、不禁用 Google Sync。

优化：

• 保底实例数为 2；多频道 Pro 线路数超过实例数时，保存频道会自动提升 NEKO_INSTANCE_COUNT 并后台重启 Neko。
• 每个实例独立 NEKO_PROFILE_HOST_DIR_N，账号态、Tampermonkey、YouTube Studio 页面保持持久化。
• 新建 profile 会从 1 号健康 profile 自动补种 Tampermonkey 扩展目录、脚本 LevelDB 与扩展设置，避免新频道新 Neko 依赖 Chrome Web Store 实时下载后才出现默认脚本。
• Neko 默认启用超级管理员入口，管理员密码来自 NEKO_ADMIN_PASS，普通观看/操作密码来自 NEKO_USER_PASS。
• 浏览器默认打开开发者模式。NEKO_MANAGED_POLICIES=0 时不挂企业策略，因此不会显示“由组织管理”；如必须强制安装/导入 Tampermonkey，可改为 NEKO_MANAGED_POLICIES=1，代价是 Chrome 会显示 managed by organization。
• 默认使用 Google/YouTube 登录入口，保留完整 ICE，避免更换 Wi-Fi 后 WebRTC 仍指向旧局域网 IP。
• Tampermonkey 默认脚本继续使用 services/neko/provisioning/youtube-studio-auto-dismiss.user.js，来源 URL 固定为 https://greasyfork.org/en/scripts/557378-youtube-studio-auto-dismiss/code；企业策略模式开启时会通过 Chrome policy 导入。

涉及文件：

• services/neko/docker-compose.yml
• tools/render_neko_compose.py
• services/neko/browser-launch.sh
• services/neko/policies/policies.json
• services/neko/provisioning/*
• tools/render_tampermonkey_provisioning.py
• scripts/linux/neko_ip_watch.sh
• scripts/linux/service_ctl.sh

验收：

• 新安装后至少有 Neko 1、Neko 2 两个入口。
• service_ctl.sh neko restart 会生成 services/neko/docker-compose.generated.yml，按 NEKO_INSTANCE_COUNT 启动 live-neko-1..N。
• tools/verify_local_install.py 会逐实例检查浏览器 supervisor、Tampermonkey provisioning server、默认脚本 payload 与脚本存储落盘。
• 切换局域网 IP 后 live-neko-* 重启并刷新 NEKO_WEBRTC_NAT1TO1。
• Chrome/Chromium 默认开发者模式可见，Tampermonkey 脚本已启用。

3. YouTube 多频道 Pro

现状：多频道列表已落盘 SQLite，每条线路可独立生成 youtube.<pm2>.ini 与 URL_config.<pm2>.ini，PM2 名使用 youtube2__<channelId>；保存频道时会调用 src/neko_capacity.py 保证 Neko 容量不小于频道数且最少 2 个。

优化：

• 新建线路保存成功后，自动保证对应配置文件存在，并在进程列表显示该线路。
• 新建线路保存成功后，自动保证存在对应 Neko 实例，动态 compose 按线路数生成 Neko 1..N。
• 线路和 Neko 实例建立稳定映射：线路 1 -> Neko 1，线路 2 -> Neko 2，线路 N -> Neko N；超过设备上限时进入“需要扩容硬件/降低实例数”的明确状态。
• 开始直播前校验：抖音 URL、YouTube key、FFmpeg、PM2、SRS/RTMP 端口、Neko 可达性。
• 日志按线路隔离，面板展示最近错误、推流中/等待上游/密钥异常/心跳过期。

涉及文件：

• web-console/components/live-product/LiveYoutubeUnmannedView.tsx
• web-console/lib/youtubeProChannels.ts
• src/youtube_pro_runtime.py
• src/hub_kv_store.py
• web.py

验收：

• 新增线路保存后刷新页面仍存在。
• 每条线路的 URL 与 key 不互相覆盖。
• 未填 key 或 URL 时不能启动，提示具体原因。

P1：补齐设备与网络体验

4. TikTok HDMI 链路

优化：

• 自动探测 /dev/dri/card*、/dev/fb*、/dev/video*、USB HDMI 采集卡、EDID。
• 提供 mpv --drm-*、ffmpeg -> kms/drm、v4l2loopback 的候选命令与失败解释。
• 将视频源、输出接口、音频输出、分辨率、帧率、重试策略写入配置中心。

涉及文件：

• web-console/components/live-product/LiveTiktokHdmiView.tsx
• src/hdmi_control.py
• scripts/srt_to_hdmi_drm.example.sh
• tiktok/tiktok.py

验收：

• 有 HDMI/DRM 设备时面板显示推荐输出命令。
• 无设备时显示缺失项，不影响其他模块运行。

5. 网络与带宽统计

优化：

• 总览和网络页展示每个物理网卡的实时上行/下行、累计 RX/TX、链路速率、在线状态。
• ShellCrash 页保留配置编辑、启动/停止/重启、导入 YAML，并增加出口 IP / DNS / YouTube 连通性探测。
• 支持保存“代理健康检查”结果到 dashboard，业务启动前可选择是否强制检查代理。

涉及文件：

• src/control_plane.py
• web-console/components/live-product/LiveControlApp.tsx
• web-console/components/OverviewCharts.tsx
• live-platform/config/defaults/services/shellcrash.json

验收：

• /hub/dashboard 返回接口流量数据。
• 网络页无需 Netdata 也能看到基本带宽曲线。

P2：工程化与长期维护

6. 动态 Neko 扩容

已实现由配置中心生成 compose：

• NEKO_INSTANCE_COUNT=max(2, youtube_pro_lane_count)。
• 每个实例自动分配 HTTP、TCPMUX、UDPMUX、UDP_RANGE、profile 目录。
• service_ctl.sh neko restart 使用生成后的 compose 启动所需实例并停掉多余实例。
• 生成器：tools/render_neko_compose.py。
• 输出文件：services/neko/docker-compose.generated.yml；旧 services/neko/docker-compose.yml 保留为兼容模板和人工排障参考。

7. 安装验收矩阵

为每次部署固定验收：

• sudo bash doctor.sh
• sudo bash probe-live.sh
• python3 tools/verify_live_console.py
• pytest
• npm --prefix web-console run build

硬件矩阵：

• x86_64 小主机：Intel/AMD + VAAPI。
• ARM64 开发板：RK3588 / Raspberry Pi 5 / Armbian。
• 安卓：Redroid、USB 手机、无线 ADB。
• 网络：中国大陆单机代理、普通海外网络、换 Wi-Fi 后 mDNS 与 Neko WebRTC。

8. 面板信息架构

保持当前 7 个一级页面：

• 总览：硬件/软件/业务摘要、健康检查、关键链路。
• 服务：基础服务安装与运行控制。
• YouTube 无人直播：单频道、多频道 Pro、Neko 工作室。
• TikTok 无人直播：HDMI 输出链路。
• 安卓：Redroid 与真实手机云控。
• 网络：ShellCrash、带宽、出口连通性。
• 设置：配置中心、升级、备份恢复。

实施优先级

1. P0-1：安卓真流失败自动降级截图，补诊断。
2. P0-3：YouTube Pro 新建线路后保证配置、进程、Neko 映射一致。
3. P0-2：Neko 基线验收，确认 Tampermonkey 脚本、profile、IP watcher。
4. P1-5：网络带宽统计与代理连通性。
5. P1-4：TikTok HDMI 探测和启动链路。
6. P2-6：动态 Neko compose 已落地；后续重点是按硬件资源给出容量建议和超载保护。

当前代码落点

• 一键入口：install.sh、install-all.sh、install-core.sh、install-live.sh
• Linux 脚本：scripts/linux/lib/common.sh、scripts/linux/service_ctl.sh
• 控制平面：web.py、src/control_plane.py、src/hub_routes.py
• 前端面板：web-console/components/live-product/*
• Neko：services/neko/*、tools/render_neko_compose.py、src/neko_capacity.py
• 安卓：src/android_control.py、src/scrcpy_stream.py、src/redroid_control.py
• YouTube Pro：src/youtube_pro_runtime.py、web-console/lib/youtubeProChannels.ts