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

Live Platform 四层架构

Homelab 一键直播系统的具体优化路线图见 HOMELAB_OPTIMIZATION_PLAN.md，该文档把 live.local 面板、YouTube 多频道 Pro、Neko、TikTok HDMI、安卓云控和网络代理拆成可验收的实施项。

分层

层	职责	代码/路径
Core OS	用户、SSH、mDNS、Wi‑Fi、WebTTY、Docker、systemd、日志	scripts/linux/install_hub.sh 及系统包
Infra Service	ShellCrash、Caddy、Netdata、SRS、Neko、ws-scrcpy、FRP、WireGuard 占位	services/*、scripts/linux/service_ctl.sh
Business	无人直播 douyinyoutube（FFmpeg/HDMI/推流），可脱离控制台运行	仓库根业务脚本、install-live.sh
Web Console	仅通过 API 与配置中心「控制」，不实现业务算法	web.py、web-console、/hub/* API

配置中心

• 安装目标：/opt/live/config/
• 默认模板：live-platform/config/defaults/
• 文件：system.json、network.json、services/*.json、business/*.json
• 生成兼容层：live-platform/tools/render_stack_env.py → /opt/live/generated/system-stack.env（供现有 shell 读取，逐步淘汰分散 .env）

一键脚本（幂等）

脚本	作用
./install-core.sh	同步 JSON → /opt/live/config，生成 env，调用 install_hub.sh（无业务）
./install-live.sh	仅业务模块，调用 install_business.sh
./doctor.sh	网络、端口、adb、ffmpeg、docker、API 健康检查

API

• GET /hub/dashboard：快照 + 服务 + 安卓 + 直播进程状态
• GET /hub/config：配置中心只读聚合
• POST /hub/business/douyinyoutube：业务元数据（如抖音 URL 声明）
• 既有：/service_action、/android/*、/process_monitor、/save_url_config 等

前端

• /：LiveControlApp 产品壳（总览、服务、直播、安卓、网络、设置）
• /console：高级遗留控制台（全功能）
• 开发：middleware 将 /hub 代理到本机 FastAPI

live.local（无端口验收）

• install_hub.sh 末尾执行 install_live_edge_proxy：安装/启用 live-edge.service（Caddy），将 http://live.local（:80） 反代到 127.0.0.1:${PORT}（默认 8001），并启用 live-edge-watch.service 自动拉起/修复 80 入口。
• Homepage 默认改绑 HOMEPAGE_PORT=3080，避免与 Caddy 抢 80。
• 仅更新反代：sudo bash scripts/linux/reinstall_live_edge.sh
• ENABLE_LIVE_EDGE_PROXY=0 可关闭（system-stack.env）。

Neko 动态实例

• scripts/linux/service_ctl.sh neko start|restart 与安装流程都会先调用 tools/render_neko_compose.py，输出 services/neko/docker-compose.generated.yml，再由 Docker Compose 启动 live-neko-1..N。
• NEKO_INSTANCE_COUNT 最少为 2，NEKO_MAX_INSTANCE_COUNT 默认封顶 64；YouTube PRO 保存频道时由 src/neko_capacity.py 把实例数提升到频道数所需容量。
• 每个实例独立分配 profile、HTTP 端口、TCPMUX、UDPMUX 和 UDP range。第 4 个及以后实例从 52400-52499 起按百段分配 UDP range，避免与前 3 个实例的 mux 端口冲突。
• 默认 NEKO_MANAGED_POLICIES=0，Neko 不挂 Chrome enterprise policy，因此浏览器不应显示“由组织管理”，并且不会通过启动参数禁用 Google Sync。若必须强制下发 Tampermonkey/浏览器策略，可设为 1，但 Chrome 会按设计显示 managed by organization。
• 新 profile 启动前会调用 seed_neko_tampermonkey_profile，从 1 号健康 profile 补种 Tampermonkey 扩展目录、脚本存储和扩展设置；这样新频道新 Neko 不依赖 Chrome Web Store 当场下载，弱网/中国网络下也能看到默认脚本。
• services/neko/browser-launch.sh 必须保持可执行位；本地 verifier 会检查每个 Neko 里的 google-chrome/chromium supervisor 进程，防止只看到 Neko 容器健康但浏览器实际没启动。
• services/neko/docker-compose.yml 仅保留为兼容模板和排障参考；生产运行以生成文件为准。
• live-neko-ip-watch.service 监测 LAN IP 变化，更新 NEKO_WEBRTC_NAT1TO1 后重启 Neko，避免换网后 WebRTC、iframe 或局域网入口继续指向旧地址。

安卓 Web 控制

• /android/screenshot 提供 PNG 截图兜底，/android/action 支持 tap、double tap、long press、text、keyevent、swipe 等操作。
• 前端优先尝试 /android/scrcpy/ws 真流；WebSocket、WebCodecs 或 scrcpy-server 不可用时自动降级到截图轮询，仍可按截图坐标触控。
• Redroid 和真实 ADB 设备统一走 ADB 发现；Redroid 启动后自动尝试 adb connect 127.0.0.1:5555。