VLStream-Cloud

VLStream Cloud

AI-Driven Open-Source Video IoT and Intelligent Stream Management Platform

简体中文 | English

Quick Start • Key Features • System Screenshots • Application Scenarios • Architecture • Technology Stack • Deployment • Help

[!IMPORTANT] Online environment: https://vlstream.oortcloudsmart.com:2443/bus/vls-ui/login Default account: admin / Codex@123456

📖 Project Description

VLStream Cloud is an open-source Video IoT platform for device and stream management, intelligent video analysis, algorithm lifecycle management, monitoring, and alerting. It combines a Vue-based management console with a Spring Boot multi-module backend and provides workflow, permission, scheduling, object storage, and operational support for enterprise video applications.

Extended introduction: VLStream Visual AI Platform

[!IMPORTANT] Connect only devices and video streams that you are authorized to access. Make sure your deployment and use of intelligent analysis comply with applicable privacy, security, and data-protection requirements.

✨ Key Features

Single-Node GPU Training Scheduler

Algorithm training supports an exclusive single-GPU queue on one physical GPU server. A Docker container is created when a training job starts. Jobs wait automatically while the GPU is busy, and the container is removed when training finishes while job records, logs, and model artifacts are retained. See Single-Node GPU Training Scheduler.

Hi3519DV500 Model Deployment

VLStream delivers trained models to devices through MQTT. Hardware connection, model delivery, event reporting, media upload, status receipts, and integration acceptance follow the VLS Platform and Camera Unified Communication Protocol.

Configure these environment variables:

VLSTREAM_MQTT_HOST=127.0.0.1
VLSTREAM_MQTT_PORT=1883
VLSTREAM_MQTT_USERNAME=vlstream
VLSTREAM_MQTT_PASSWORD=replace-me
VLSTREAM_MODEL_PUBLIC_BASE_URL=https://vlstream.example.com
VLSTREAM_MODEL_DOWNLOAD_SIGNING_SECRET=replace-with-a-long-random-secret

VLSTREAM_MODEL_PUBLIC_BASE_URL must be the backend address reachable by the devices, not the browser-facing frontend address. Model download URLs use short-lived HMAC signatures. Generate and inject a unique random signing secret for each environment; never commit the real secret to Git.

🖥️ System Screenshots

Video Ingestion • VLStream Protocol Devices	Video Ingestion • RTSP Protocol Cameras
Video Ingestion • GB28181 Protocol Devices	Decision AI • Active Safety Event Center
Algorithm Warehouse • Preset Model Library	Algorithm Training • Dataset & Sample Management
Algorithm Training • Data Annotation Management	Algorithm Training • No-Code Training Console

Click any screenshot to view it at full resolution.

🌐 Application Scenarios

Chemical Production Safety	Smart Water Conservancy	Wastewater Treatment
Smart Construction Site	Smart Community	Gas Station Safety
Smart Kitchen	Smart Campus	Smart City Management

🧰 Technology Stack

Backend

Frontend

🏗️ Architecture and Project Structure

VLStream Cloud’s core business architecture is organized into three categories:

• Hardware: IPC, BOX, and NVR devices. The lifecycle covers production provisioning, installation and protocol access, platform operations, and device transfer.
• Platform servers: VLS owns AI events, model delivery, and platform business; WVP is the sole video-device center for VLStream and other protocols, device state, and video control; ZLMediaKit provides the media server behind WVP; MQTT, MySQL, Redis, and MinIO provide messaging, persistence, cache, and object storage.
• Client: VLStream-ui provides platform operations, while the WVP UI provides video preview, playback, PTZ, and channel management.

The complete lifecycle sequence diagram and dependency inventory are maintained in Core Business and Technical Architecture.

Runtime Server Dependencies

Before connecting a newly rented AutoDL GPU, follow the new GPU onboarding guide and run bootstrap-autodl.sh to install the fixed core versions and cache preset weights. The platform checks the environment and weights. The project team’s P100 is a development/test machine, not a deployment dependency.

New deployments automatically generate the SSH credential encryption key on first use and retain it in the backend data volume. No key entry is required. Preserve this volume across upgrades and share it across backend replicas; deployments with an existing explicit key must keep that original key. See credential storage and recovery.

The following versions are taken from the current release Compose or project configuration. A version marked not pinned must be fixed in the formal deployment manifest before production release.

Nginx or an equivalent gateway is normally required for frontend static files and reverse proxying. WebRTC Streamer v0.8.16 is optional for the VLS direct RTSP-to-WebRTC path; FFmpeg is an optional WVP/ZLMediaKit pull and conversion helper, not another standalone media platform.

Optional model conversion dependencies: VLS coordinates conversion tasks, but the Java application does not include the Python or vendor conversion tools. The existing default-GPU ONNX/RKNN path invokes remote tools over SSH. AutoDL detection training can enable an optional standalone CPU worker: after PT archival, VLS converts it to Hi3519DV500 OM, archives the result in MinIO and updates the same model version. Without the worker, PT and class files remain available. AutoDL needs no ATC installation or development-P100 connection.

Deploy the OM conversion environment only if HiSilicon OM output is needed. It requires an SDK/toolchain matching the target chip, the HiSilicon YOLO exporter, the SVP/ATC environment, AIPP configuration, and calibration images. Configure VLSTREAM_HISILICON_EXPORTER_SCRIPT, VLSTREAM_ATC_ENV_SCRIPT, VLSTREAM_ATC_INSERT_OP_CONFIG, VLSTREAM_ATC_SOC_VERSION, and VLSTREAM_ATC_CALIBRATION_IMAGE_COUNT for that environment. These paths refer to the host executing conversion, not automatically to the VLS application host.

Use deploy/release/compose.om.yaml and VLSTREAM_OM_CONVERSION_ENABLED for the standalone worker, with a separately supplied licensed SVP/ATC toolkit mounted read-only. See automatic OM conversion for setup, supported models and recovery. The legacy SSH settings above apply only to the default-host chain; they do not configure the standalone container. Legacy conversion failures continue to preserve PT output.

Repository layers

The backend paths in the following table are relative to VLStream-Cloud-Backend-Server/vls-stream/.

Top-level layout

VLStream-Cloud/
├── VLStream-Cloud-Backend-Server/
│   └── vls-stream/                  # Java 8 / Spring Boot Maven reactor
│       ├── ruoyi-admin/             # Executable application and REST APIs
│       ├── ruoyi-vlstream/          # Devices, streams, AI, events, and models
│       ├── ruoyi-system/            # Users, roles, permissions, and system services
│       ├── ruoyi-framework/         # Web, security, and framework configuration
│       ├── ruoyi-flowable/          # Workflow and approval services
│       ├── ruoyi-common/            # Shared models, utilities, and base components
│       ├── ruoyi-generator/         # Code generation
│       ├── ruoyi-job/               # Scheduled jobs
│       ├── ruoyi-oss/               # Object storage integration
│       ├── ruoyi-sms/               # SMS integration
│       ├── ruoyi-extend/            # Monitoring and XXL-Job services
│       ├── ruoyi-demo/              # Examples and integration tests
│       ├── deploy/                  # Backend deployment resources
│       └── script/                  # Database and Docker scripts
├── VLStream-Web/
│   └── VLStream-ui/                 # Vue 3 management console
├── sdk/                             # Hi3519DV500 native camera business SDK
├── deploy/                          # Repository-level deployment assets
├── docs/                            # Repository-level documentation and application assets
│   ├── assets/                      # Screenshots and application imagery
│   └── architecture/                # Core business and technical architecture
├── tools/                           # Development and validation tools
├── LICENSE
├── README.md                        # English documentation (default)
└── README.zh-CN.md                  # Simplified Chinese documentation

Device SDK (sdk/)

The sdk/ directory is the camera-side native component, not a Maven or npm module. It exports the business source used to build the rtsp_streamer executable for the Hi3519DV500 board and depends on the original HiSilicon MPP/ACL SDK, the cross toolchain, and an external WebRTC Streamer SDK.

The SDK is intentionally kept separate from the server build: the root Maven and frontend commands do not compile it. For prerequisites, original project paths, excluded vendor binaries, and board-side build instructions, see the SDK guide.

🚀 Quick Start

Requirements

WebRTC Live-Preview Dependency

Browsers cannot play RTSP directly. Camera live preview uses WebRTC Streamer to convert RTSP to WebRTC. The pinned, validated Docker image for this project is mpromonet/webrtc-streamer:v0.8.16. Keep this exact tag instead of using an untested latest image or an older Windows binary.

To start it independently on a local machine:

docker run -d --name vlstream-webrtc --restart unless-stopped -p 8000:8000 `
  mpromonet/webrtc-streamer:v0.8.16 -H 0.0.0.0:8000 -vvv

Verify the runtime with curl.exe http://127.0.0.1:8000/api/version; it should report v0.8.16/Linux-x86_64. The backend declaration is in ruoyi-admin/src/main/resources/application.yml:

VLSTREAM_WEBRTC_ENABLED=true
VLSTREAM_WEBRTC_RUNTIME_IMAGE=mpromonet/webrtc-streamer:v0.8.16
VLSTREAM_WEBRTC_INTERNAL_URL=http://127.0.0.1:8000
VLSTREAM_WEBRTC_PUBLIC_URL=/bus/webrtc-streamer-server

The release Compose deployment uses the same version through WEBRTC_STREAMER_IMAGE=mpromonet/webrtc-streamer:v0.8.16 in deploy/release/.env. runtime-image is a backend declaration and status value only; the backend does not pull or start Docker containers.

1. Clone the Repository

git clone https://github.com/OortCloudGroup/VLStream-Cloud.git
cd VLStream-Cloud

2. Initialize and Upgrade the Database

CREATE DATABASE vlstream CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

cd VLStream-Cloud-Backend-Server/vls-stream
mysql -u root -p vlstream --execute="source script/sql/mysql/mysql_ry_v0.8.X.sql"

SQL initialization scripts for Oracle, PostgreSQL, and SQL Server are also available under script/sql/. Application schema upgrades are managed by Flyway when the backend starts. Add every new database change as a new, immutable migration under ruoyi-admin/src/main/resources/db/migration/; do not edit a migration that has already run. See DATABASE_MIGRATIONS.md.

3. Configure and Start the Backend

Review the main configuration and the active profile configuration:

• ruoyi-admin/src/main/resources/application.yml
• ruoyi-admin/src/main/resources/application-dev.yml
• ruoyi-admin/src/main/resources/application-prod.yml

The Maven profiles are dev, local, and prod; dev is active by default.

Required Configuration Before Deployment

Do not use repository test addresses or example passwords for a complete deployment. Configure at least the following services before startup:

Inject secrets through the deployment environment and never commit real passwords or keys:

MYSQL_HOST=mysql.example.internal
MYSQL_PORT=3306
MYSQL_DB_NAME=vlstream
MYSQL_USERNAME=vlstream
MYSQL_PASSWORD=replace-me

REDIS_HOST=redis.example.internal
REDIS_PORT=6379
REDIS_PASSWORD=replace-me

# WVP is required; this address must be reachable from the VLS backend
VLSTREAM_WVP_INTERNAL_BASE_URL=http://wvp-server:9080
VLSTREAM_NATIVE_DEVICE_LEGACY_ENABLED=false

VLSTREAM_SSH_HOST=gpu.example.internal
VLSTREAM_SSH_PORT=22
VLSTREAM_SSH_USERNAME=vlstream
VLSTREAM_SSH_PASSWORD=replace-me
VLSTREAM_TRAINING_HOST_DATA_DIR=/data/work
VLSTREAM_TRAINING_WORK_DIR=/data/work/ultralytics_yolov8-main/datasets

VLSTREAM_MQTT_HOST=127.0.0.1
VLSTREAM_MQTT_PORT=1883
VLSTREAM_MQTT_USERNAME=vlstream
VLSTREAM_MQTT_PASSWORD=replace-me
VLSTREAM_MQTT_QOS=1

VLSTREAM_MODEL_PUBLIC_BASE_URL=https://vlstream.example.com
VLSTREAM_MODEL_DOWNLOAD_SIGNING_SECRET=replace-with-a-long-random-secret
VLSTREAM_MODEL_DOWNLOAD_URL_TTL_SECONDS=1800
VLSTREAM_MODEL_DISPATCH_MQTT_CLIENT_ID=vls-model-dispatch-backend-01

VLSTREAM_DEVICE_MEDIA_OSS_CONFIG_KEY=vlstream-events
VLSTREAM_DEVICE_MEDIA_UPLOAD_TTL_SECONDS=600
VLSTREAM_DEVICE_MEDIA_MAX_IMAGE_BYTES=10485760
VLSTREAM_DEVICE_MEDIA_ALLOW_UNAUTHENTICATED=false

WVP owns VLStream device registration, heartbeat, video streams, and firmware jobs. VLS keeps the existing hardware-facing HTTP and MQTT contracts and calls WVP internally when issuing media upload URLs or consuming device events. Start WVP before VLS. Keep VLSTREAM_NATIVE_DEVICE_LEGACY_ENABLED=false; the switch exists only to roll back to the legacy VLS device-management implementation.

Each backend instance must use a unique VLSTREAM_MODEL_DISPATCH_MQTT_CLIENT_ID. MQTT topics, ACL rules, and hardware behavior are defined by VLS-Protocol.md.

MinIO and Algorithm Annotation

Annotation uploads use the enabled config_key=minio record in sys_oss_config, not fixed credentials in application.yml. Configure the access key, secret key, bucket, API endpoint, external domain, HTTPS flag, access policy, and enabled status. Persist MinIO data and verify that the backend, browser, and GPU server can all reach the generated object URLs.

For device event images, reuse the MinIO service but configure a separate private OSS entry and bucket (for example config_key=vlstream-events). Devices receive only short-lived, single-object presigned PUT URLs and must never receive MinIO credentials. The unauthenticated upload-grant endpoint is for LAN development only and must remain disabled in production. Apply db/2026-07-29-vls-device-event-media.sql before enabling MQTT event ingestion.

GPT/AI Service

The frontend calls apaas-ai through the configured APaaS gateway:

{APaaS gateway prefix}/apaas-ai/api/v1/text_completion
{APaaS gateway prefix}/apaas-ai/api/v1/text_img

Configure the provider base URL, API key, model names, timeout, retries, and network access in the separate apaas-ai service. That service is not included in this repository.

mvn -ntp -Pdev clean package
mvn -ntp -Pdev -pl ruoyi-admin spring-boot:run

After startup:

• Knife4j: http://localhost:8080/doc.html
• Swagger UI: http://localhost:8080/swagger-ui.html

[!NOTE] The backend parent POM references internal Maven repositories. Dependency resolution may require access to the project network or a compatible mirror in your Maven settings.xml.

4. Start the Frontend

Open a new terminal from the repository root:

cd VLStream-Web/VLStream-ui
npm install
npm run dev

For local development, configure:

VITE_DEV_PROXY_TARGET=http://127.0.0.1:8080
VITE_APAAS_PROXY_TARGET=http://apaas-gateway.example.internal:21410

Use npm run build to create a production frontend bundle. For deployment-specific ZLM signaling and RTC candidate configuration, see browser playback configuration. Empty candidate settings preserve the existing VM/local/self-hosted playback behavior.

Post-Startup Acceptance

1. Verify /actuator/health and MySQL/Redis connectivity.
2. Upload an image and open the returned MinIO URL.
3. Create an annotation job and save annotation results.
4. Verify that an AI text request reaches apaas-ai.
5. Complete MQTT and model-delivery checks defined in VLS-Protocol.md.
6. Run one training job and verify scheduling, logs, and model artifacts.

🔌 API Preview

Device Management

Standard API responses use the shared R<T> structure:

{
  "code": 200,
  "msg": "Operation successful",
  "data": {}
}

Use the generated OpenAPI documentation for the complete and current API list.

🐳 Deployment

Download the deployment package from GitHub Releases, extract it, copy the environment template, and start the bundled services:

Copy-Item .env.example .env
docker compose up -d

Stop the services with:

docker compose down

[!TIP] The package includes MySQL, Redis, MinIO, WebRTC-streamer, the backend, and the frontend. Existing external infrastructure is also supported. See the deployment guide for configuration and upgrade instructions.

📚 Documentation

🤝 Help and Support

• Project Homepage: vls.oortcloudsmart.com
• Issue Tracker: GitHub Issues
• Technical Support: [email protected]

Contributions are welcome. You can report bugs, propose features, improve the documentation, or submit pull requests.

📄 License

VLStream Cloud is released under the MIT License.