# Live Platform 四层架构

Homelab 一键直播系统的具体优化路线图见 [`HOMELAB_OPTIMIZATION_PLAN.md`](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 端口冲突。
- 新 profile 启动前会调用 `seed_neko_tampermonkey_profile`，从 1 号健康 profile 补种 Tampermonkey 扩展目录、脚本存储和 managed settings；这样新频道新 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`。