# Managed Portal 管理端

`managed-portal` 是从原 `video_recognition_local` 项目中拆出的独立管理端，负责管理“被管理服务”和“网页设备”两类能力。它不依赖原 `3000` 端口主项目运行，默认以前端 `13000` 端口对外提供入口，后端默认监听 `9080`。

## 功能范围

- 被管理服务：查看服务列表、服务详情、容器状态、RTSP 配置、重启容器、结果摘要、结果文件预览和下载
- 网页设备：扫描本机所在网段的 80 端口网页设备，生成代理访问地址和直连转发地址
- 子服务源码：已内置 `store_dwell_alert` 和 `people_flow_project` 两个子项目源码

## 目录结构

```text
managed-portal/
├── cmd/managed-portal/        # Go 后端入口
├── internal/                  # Go 后端模块
├── web/                       # Vue3 + Element Plus 前端
├── managed/                   # 被管理子服务源码
│   ├── store_dwell_alert/
│   └── people_flow_project/
├── deploy/                    # Docker Compose 部署文件
├── managed_services.yaml      # 被管理服务注册表
└── Dockerfile                 # 门户后端镜像
```

## 默认端口

- 门户后端：`9080`
- 门户前端：`13000`
- `store-dwell-alert` 子服务 API：`18081`
- `people-flow-project` 子服务 API：`18082`

后端端口可通过环境变量覆盖：

```bash
MANAGED_PORTAL_HTTP_ADDR=:9080
```

## 本机开发

后端：

```bash
go test ./...
go run ./cmd/managed-portal
```

前端：

```bash
cd web
pnpm install
pnpm dev
pnpm build
```

本机开发时，前端默认会把 `/api` 和 `/proxy` 代理到 `http://localhost:9080`。如果后端用其他端口启动，可以覆盖：

```bash
VITE_API_PROXY_TARGET=http://127.0.0.1:9080 pnpm dev --host 127.0.0.1 --port 13000
```

## Docker 部署

完整独立栈包含四个服务：

- `managed-portal`
- `managed-portal-web`
- `store-dwell-alert`
- `people-flow-project`

启动：

```bash
cd deploy
docker compose --env-file managed-portal.env up -d --build
```

访问：

```text
http://<服务器IP>:13000/
```

## OTA 发布包

OTA 安装脚本默认从发布目录下载一个主 ZIP，再用 `deploy/docker-compose.ota-release.yml` 启动服务。主 ZIP 现在只需要包含安装端真正依赖的内容：

- `deploy/docker-compose.ota-release.yml`
- `deploy/Dockerfile.runtime-overlay`
- `deploy/managed-portal.release.env`
- `release-manifest.env`
- `managed/store_dwell_alert/config/`
- `managed/people_flow_project/config/`

仓库提供了一个最小打包脚本：`deploy/package-managed-portal-ota.sh`。

示例：

```bash
RELEASE_VERSION=20260518-7b32b21-11 \
RELEASE_MANIFEST_SOURCE=/path/to/release-manifest.env \
RELEASE_ENV_SOURCE=deploy/managed-portal.10.8.0.12.env \
sh deploy/package-managed-portal-ota.sh
```

默认情况下，主 ZIP 不包含 `managed/people_flow_project/weights/`。打包脚本会额外生成一个独立的 `people-flow-weights-<RELEASE_VERSION>.tar.gz`，用于 Ubuntu 新机器首次安装；如果权重目录里只有 `yolo11n.pt` 缺失，还会使用小体积的 `people-flow-yolo11n-<RELEASE_VERSION>.tar.gz` 单独补齐，避免为了一个小模型重新下载 1GB+ 的完整权重包。已有机器升级时，OTA installer 会优先复用主机上的共享权重目录，避免每次只改安装脚本或配置时都重复打包、上传大体积权重。

只有两种场景才建议重新发布这个独立权重包：

- 首次在一台没有预置权重的新主机上安装
- `people_flow_project` 的权重文件本身发生变更

只有在你明确想把权重重新并回主 ZIP 时，才需要临时打开：

```bash
INCLUDE_WEIGHTS=1 sh deploy/package-managed-portal-ota.sh
```

Ubuntu 新机器首次安装时，如果系统没有 `unzip`，OTA installer 会自动用 `apt-get` 安装；然后在共享权重目录不存在时自动下载 `people-flow-weights-<RELEASE_VERSION>.tar.gz`。如果 DeepFace 权重已经存在但缺少 `yolo11n.pt`，installer 只下载 `people-flow-yolo11n-<RELEASE_VERSION>.tar.gz`。

## 模型权重

子服务镜像构建前需要以下权重文件：

- `managed/store_dwell_alert/weights/yolo11n.pt`
- `managed/people_flow_project/weights/yolo11n.pt`
- `managed/people_flow_project/weights/deepface/age_model_weights.h5`
- `managed/people_flow_project/weights/deepface/gender_model_weights.h5`
- `managed/people_flow_project/weights/deepface/retinaface.h5`

这些权重文件体积较大，默认被子项目 `.gitignore` 忽略，不会随 Git 提交上传。部署机器上需要提前放到对应路径，或通过制品仓库、对象存储、Git LFS 等方式分发。

## 被管理服务注册表

`managed_services.yaml` 描述门户要管理的子服务。Docker Compose 部署时，默认通过容器 DNS 访问：

```yaml
api_base_url: http://store-dwell-alert:18081
api_base_url: http://people-flow-project:18082
```

如果改成本机进程方式运行子服务，可以把地址调整为 `http://127.0.0.1:18081` 和 `http://127.0.0.1:18082`。