申视通 (OmniSight C2) — Web端通用指挥调度与应急协同系统

轻量化 · 全终端 · 毫秒级低延迟 · 现代化 GIS 可视化指挥调度平台

---

📖 目录

• 1. 项目简介
• 2. 核心特性与业务能力
• 3. 系统架构
  • 3.1 总体架构图
  • 3.2 通信时序设计
  • 3.3 双服务模式设计
• 4. 项目代码结构 (Monorepo)
• 5. 终端矩阵与功能清单
  • 5.1 PC 指挥大屏 (Web / Windows)
  • 5.2 移动单兵端 (H5 / Android)
  • 5.3 后台管理系统
• 6. 技术栈清单
• 7. 快速开始与本地开发
  • 7.1 环境依赖
  • 7.2 安装依赖
  • 7.3 环境变量配置
  • 7.4 数据库初始化与 Seed 初始账户
  • 7.5 生成本地 SSL 自签名证书
  • 7.6 启动开发服务
  • 7.7 默认访问地址与登录信息
• 8. 客户端打包与构建
  • 8.1 Web 端静态资源构建
  • 8.2 Windows 桌面端安装包打包
  • 8.3 Android 原生 APK 打包
• 9. Docker 容器化部署
• 10. 常见问题排查 (FAQ)
• 11. 详细文档索引
• 12. 开源许可

---

1. 项目简介

申视通 (OmniSight C2) 是一套基于 B/S 架构演化的高性能、轻量级一体化指挥调度与协同系统（Command & Control System）。系统专为应急管理、现场救援、大型活动安保、网格化治安巡查、外勤作业调度等场景量身定制。

系统实现了指挥中心与一线外勤单兵之间的多维即时联动，打破信息孤岛，实现 “看得到现场、听得到声音、指得到位置、呼得到人员” 的综合指挥调度体验。

---

2. 核心特性与业务能力

• 🗺️ 实时 GIS 态势大屏：基于高德地图 JS API 2.0 深色科技主题，毫秒级呈现外勤人员/车辆/智能设备的 GPS 实时坐标、移动朝向与运动状态。
• 📹 多路低延迟视频监控墙：基于 WebRTC P2P 架构，一线单兵一键推流，指挥端支持 1 / 4 / 9 宫格分屏实时监控，支持全屏放大、单路音频监听与全局静音。
• 🎙️ 实时语音对讲 (PTT - Push-To-Talk)：支持单呼、组呼、广播全呼，按住说话，内置 WebRTC 硬件级回声消除（AEC）、降噪（ANS）与自动增益（AGC），具备音频电平实时波形动效。
• 📍 实时轨迹追踪与历史回放：完整记录外勤人员的历史行动轨迹，支持按时间范围筛选、航迹连线渲染与轨迹动画回放。
• 👥 组织架构与多级权限体系：支持管理员 (ADMIN)、指挥员/操作员 (OPERATOR)、普通观察员 (OBSERVER) 权限隔离，支持群组树形管理与成员调度。
• 📱 全平台、多终端覆盖：
  • PC 网页端 / Windows 桌面端 (Electron)：面向指挥中心大屏及座席工作台。
  • 移动端 H5 / Android 原生端 (Capacitor)：面向一线执勤人员移动设备，自适应竖屏手持交互。

---

3. 系统架构

3.1 总体架构图

┌────────────────────────────────────────────────────────────────────────┐
│                     OmniSight C2 整体系统架构                          │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────────┐  │
│  │   PC Web 指挥端   │  │   移动单兵端 H5   │  │   Windows 客户端     │  │
│  │  (Vue 3 + Vite)  │  │  (Vue 3 + Vite)  │  │   (Electron Shell)   │  │
│  │   Port: 5173     │  │   Port: 5174     │  │  (内置 PC 指挥端)    │  │
│  └────────┬─────────┘  └────────┬─────────┘  └──────────┬───────────┘  │
│           │                     │                       │              │
│           │            ┌────────┴─────────┐             │              │
│           │            │   Android APK    │             │              │
│           │            │ (Capacitor 壳)   │             │              │
│           │            └────────┬─────────┘             │              │
│           │                     │                       │              │
│           └─────────────────────┼───────────────────────┘              │
│                                 │                                      │
│                     ┌───────────▼───────────┐                          │
│                     │    Socket.IO 信令网关 │                          │
│                     │  (WebRTC / 状态 / 坐标)│                         │
│                     └───────────┬───────────┘                          │
│                                 │                                      │
│           ┌─────────────────────┼─────────────────────┐                │
│           │                     │                     │                │
│    ┌──────▼──────┐       ┌──────▼──────┐       ┌──────▼──────┐         │
│    │ Express API │       │ LiveKit SFU │       │  Prisma ORM │         │
│    │ RESTful 服务│       │ 流媒体服务  │       │  SQLite 存储│         │
│    │  :3000/:3001│       │ (可选扩展)  │       │    dev.db   │         │
│    └─────────────┘       └─────────────┘       └─────────────┘         │
└────────────────────────────────────────────────────────────────────────┘

3.2 通信时序设计

sequenceDiagram
    autonumber
    participant M as 移动单兵端 (Mobile)
    participant S as 服务端 (Socket.IO + Express)
    participant P as PC 指挥端 (PC Client)

    Note over M,P: 1. 上线鉴权与状态同步
    M->>S: 建立连接 & 发送 join(userId, name, groupId)
    S->>P: 广播 user:joined 事件
    S->>P: 全量同步 users:sync 在线列表

    Note over M,P: 2. 实时高精度 GPS 位置更新
    loop 持续定位刷新
        M->>S: 发送 location:update (经纬度, 航向, 速度, 精度)
        S->>S: 异步持久化至 LocationRecord
        S->>P: 广播 location:broadcast
        P->>P: 地图平滑移动与标记更新
    end

    Note over M,P: 3. WebRTC P2P 实时音视频协同
    M->>S: stream:start (开始推流)
    S->>P: 广播 stream:started (包含推流者信息)
    P->>S: webrtc:request-offer (请求音视频轨道)
    S->>M: 转发信令请求
    M->>S: webrtc:offer (本地 SDP)
    S->>P: 转发 SDP Offer
    P->>S: webrtc:answer (指挥端 SDP Answer)
    S->>M: 转发 SDP Answer
    M<<-->>P: ICE 候选交换 & P2P 实时流媒体通道建立

    Note over M,P: 4. PTT 对讲 (单呼 / 组呼 / 全呼)
    M->>S: ptt:start (targetUserId / targetGroupId)
    S->>P: ptt:active (启用语音下发)
    M->>S: ptt:stop
    S->>P: ptt:active (结束通话)

3.3 双服务模式设计

为了解决移动端和桌面端的混合网络诉求，后端服务提供双端口架构：

• 主服务器 (默认端口 3000)：支持 HTTPS/WSS（配置本地证书后启用），满足浏览器环境下调用摄像头 (getUserMedia) 与高精度定位 (Geolocation API) 的强安全策略。
• 辅助服务器 (默认端口 3001)：采用纯 HTTP/WS，专门支持 Android 原生 APK 等无证书验证负担的内网调试场景。

---

4. 项目代码结构 (Monorepo)

本项目采用 npm workspaces 规范进行多包治理：

omnisightc2/
├── packages/
│   ├── pc-client/             # PC 指挥大屏 (Vue 3 + Vite + TypeScript)
│   │   ├── src/
│   │   │   ├── components/    # 地图容器、视频监控墙、用户列表、群组面板等
│   │   │   ├── views/         # 登录页、主指挥中心、后台管理、历史轨迹页
│   │   │   ├── services/      # Socket 通信、高德地图适配层、WebRTC 接收服务
│   │   │   └── stores/        # Pinia 状态库 (auth, users, audio)
│   │   └── vite.config.ts
│   │
│   ├── mobile-client/         # 移动单兵端 (Vue 3 + Vite + Capacitor)
│   │   ├── src/
│   │   │   ├── views/         # 登录页、移动执勤主页 (DutyPage)
│   │   │   └── services/      # GPS 高精度定位、WebRTC 推流、Socket 通信
│   │   └── capacitor.config.json # Android 原生打包配置
│   │
│   ├── windows-client/        # Windows 桌面客户端 (Electron 28)
│   │   ├── src/               # Electron 主进程与预加载脚本
│   │   └── package.json       # Electron-Builder 打包与 NSIS 配置
│   │
│   └── server/                # 后端服务 (Node.js + Express + Socket.IO)
│       ├── prisma/            # SQLite 数据库模型与初始种子脚本
│       └── src/
│           ├── gateways/      # WebSocket/Socket.IO 信令网关
│           ├── routes/        # REST API 路由 (Auth, User, Group, LiveKit)
│           └── services/      # 用户状态管理、DB 持久化、JWT 认证服务
│
├── shared/                    # 前后端强类型共享模块 (@omnisight/shared)
│   └── types/                 # 用户模型、地图标记、信令事件常量定义
├── docker/                    # Docker 容器化配置 (Dockerfile & Compose)
├── scripts/                   # 辅助工程脚本 (自签名 SSL 证书生成、资源处理)
├── docs/                      # 详细设计与交付文档
└── package.json               # 根 Workspace 编排定义

---

5. 终端矩阵与功能清单

5.1 PC 指挥大屏 (Web / Windows)

功能模块	对应组件 / 页面	能力说明
GIS 态势地图	MapContainer.vue	深色科技主题、支持缩放/平移/复位、单兵/车辆/智能装备动态图标渲染与轨迹跟随。
视频监控监控墙	VideoWall.vue	自由切换 1 宫格、4 宫格、9 宫格；支持推流画面自动挂载、独立全屏、通道音频静音/解静音。
在线用户列表	UserList.vue	实时查看在线/离线/推流/通话状态；支持一键在地图上“追踪定位”、一键发起一对一 PTT 呼叫。
群组调度面板	GroupPanel.vue	展示部门/分队组织树，支持按分组发起协同指挥对讲与信息查看。
历史轨迹回放	HistoryTrace.vue	根据用户与时间范围查询行动足迹，绘制带方向箭头的轨迹航线并支持播放控制。

5.2 移动单兵端 (H5 / Android)

功能模块	对应组件 / 页面	能力说明
单兵执勤主界面	DutyPage.vue	专为户外执勤设计的深色高对比度 HUD 界面，实时展示坐标、航向角、移动速度、海拔高度。
摄像头采集与推流	WebRTCService.ts	实时调用机载摄像头，支持前置/后置摄像头自由切换，内置可拖动、可全屏的浮动画中画 (PIP) 预览。
按住说话 (PTT)	DutyPage.vue	底部超大易触控 PTT 按钮，触感震动反馈，支持实时音频波形振幅动效反馈。
高精度 GPS 定位	LocationService.ts	融合 HTML5 Geolocation API，持续后台/前台轮询上报精准位置与速度。

5.3 后台管理系统

模块	路径	能力说明
用户管理	/admin	支持用户的增删改查、分配角色（管理员、操作员、观察员）、重置密码。
群组管理	/admin	创建业务群组、指定群组负责人、添加/移除群组成员。

---

6. 技术栈清单

层次	核心技术	说明
前端框架	Vue 3 (Composition API) + TypeScript	响应式状态模型与严谨类型检查
构建工具	Vite 5.x	秒级热更新开发服务器与现代化打包
UI 样式	原生 CSS / SCSS 变量设计系统	深色指挥大屏科技感主题，无需繁重第三方 UI 库干扰
地图引擎	高德地图 JS API 2.0 (@amap/amap-jsapi-loader)	国内高精度矢量地图，支持自定义标记、矢量折线与轨迹动画
实时通信	Socket.IO 4.7 (socket.io & socket.io-client)	提供全双工信令传输、断线重连、房间管理与状态广播
音视频通信	WebRTC (原生 RTCPeerConnection)	毫秒级 P2P 极低延迟视频传输与语音对讲；预留 LiveKit SFU 架构
后端运行时	Node.js (ES Module) + Express 4.18	RESTful 业务服务与静态资产托管
数据持久化	Prisma ORM 5.x + SQLite	轻量免装独立数据库文件，易于开箱即用与快速交付
安全鉴权	JSON Web Token (JWT) + bcryptjs	无状态 Token 鉴权与高强度加盐密码哈希存储
桌面客户端	Electron 28 + electron-builder	一键打包 Windows 独立 NSIS 可执行安装包
移动客户端	Capacitor 8.1	将移动端 H5 包装为原生 Android 应用，具备原生调用能力

---

7. 快速开始与本地开发

7.1 环境依赖

• Node.js: v18.0.0 及以上（推荐使用 LTS 版本）
• npm: v9.0.0 及以上
• 高德地图 Key: 必须拥有高德开放平台 [Web端 (JS API)] 的 Key 与 安全密钥 (Security Code)

7.2 安装依赖

在项目根目录下执行一次安装即可完成所有 workspace 子模块的依赖安装：

# 根目录执行
npm install

7.3 环境变量配置

复制各子模块的环境变量示例模板：

# 后端环境变量
cp packages/server/.env.example packages/server/.env

# PC 指挥端环境变量
cp packages/pc-client/.env.example packages/pc-client/.env

# 移动单兵端环境变量
cp packages/mobile-client/.env.example packages/mobile-client/.env

配置参数说明：

• packages/server/.env:

  DATABASE_URL="file:./prisma/dev.db"
  PORT=3000
  JWT_SECRET=your_hyper_secure_secret_string_here
  LIVEKIT_API_KEY=devkey
  LIVEKIT_API_SECRET=secret
  

• packages/pc-client/.env:

  VITE_API_URL=https://localhost:3000/api
  VITE_SOCKET_URL=https://localhost:3000
  VITE_AMAP_KEY=你的高德地图Web端Key
  VITE_AMAP_SECRET=你的高德地图安全密钥
  

• packages/mobile-client/.env:

  # 注意：若用手机真机访问，请填写真实的局域网 IP (如 https://192.168.1.100:3000)
  VITE_API_URL=https://localhost:3000/api
  VITE_SOCKET_URL=https://localhost:3000
  VITE_AMAP_KEY=你的高德地图Web端Key
  

7.4 数据库初始化与 Seed 初始账户

在后端目录中同步 Prisma 数据表结构并写入预置数据：

cd packages/server
npx prisma db push
npm run seed
cd ../..

💡 预置的初始管理员账户：
用户名：admin
密码：admin123

7.5 生成本地 SSL 自签名证书

⚠️ 强烈推荐：现代浏览器（Chrome / Edge / Safari）限制只有在 HTTPS 或 localhost 环境下才允许调用摄像头、麦克风及高精度 GPS 定位。为了支持局域网内手机多机调试，项目提供了自动化证书脚本：

# 根目录下执行
node scripts/generate-certs.js

执行后将在 packages/server/certs/ 目录下生成 server.key 与 server.crt。启动服务端时会自动载入并开启 HTTPS 服务。

7.6 启动开发服务

# 方式一：一键启动所有前端与后端开发服务 (推荐)
npm run dev

# 方式二：按需单独启动子模块
npm run dev:server   # 仅启动后端 API & 信令服务
npm run dev:pc       # 仅启动 PC 指挥中心前端
npm run dev:mobile   # 仅启动移动单兵端 H5

7.7 默认访问地址与登录信息

终端	本地访问入口	局域网真机调试入口
PC 指挥大屏	https://localhost:5173	https://<你的电脑局域网IP>:5173
移动单兵端 H5	https://localhost:5174	https://<你的电脑局域网IP>:5174
后端 API (主 HTTPS)	https://localhost:3000	https://<你的电脑局域网IP>:3000
后端 API (辅 HTTP)	http://localhost:3001	http://<你的电脑局域网IP>:3001

🔑 默认登录凭据：
账号：admin
密码：admin123

---

8. 客户端打包与构建

8.1 Web 端静态资源构建

# 对所有模块执行生产构建打包
npm run build

各模块构建产物将分别生成在对应包下的 dist 目录中。

8.2 Windows 桌面端安装包打包

Windows 桌面客户端基于 Electron 构建，打包过程自动集成最新的 PC 指挥端编译产物：

# 1. 确保已编译 PC 端代码
npm run build --workspace=packages/pc-client

# 2. 将产物同步至 windows-client 并运行构建
cd packages/windows-client
npm run build

构建成功后，在 packages/windows-client/release/ 下生成 OmniSight Setup x.x.x.exe 安装文件。

8.3 Android 原生 APK 打包

移动单兵端通过 Capacitor 支持快速打包为 Android 原生安装包：

# 1. 构建移动端 H5 生产产物
npm run build --workspace=packages/mobile-client

# 2. 进入移动端目录同步原生工程
cd packages/mobile-client
npx cap sync android

# 3. 使用 Android Studio 打开原生项目或进行命令行构建
npx cap open android

在 Android Studio 中选择 Build -> Build Bundle(s) / APK(s) -> Build APK(s) 即可完成打包。

---

9. Docker 容器化部署

系统提供了生产就绪的 Docker 配置，支持快速容器化部署：

# 位于 docker/ 目录
cd docker

# 使用 Docker Compose 一键启动后端与 LiveKit 服务
docker-compose up -d

• Dockerfile.server：采用多阶段构建（Node.js Alpine），精简体积并自动执行 Prisma 生成。
• docker-compose.yml：集成后端容器网络与 LiveKit SFU 媒体服务编排。

---

10. 常见问题排查 (FAQ)

Q1: 移动端真机访问时，无法获取 GPS 定位或无法调起摄像头？

• 原因：现代浏览器对于获取敏感权限（地理位置与媒体输入）有严格安全策略，非 localhost 的连接必须通过 HTTPS 协议访问。
• 解决办法：
  1. 使用 node scripts/generate-certs.js 生成证书，确保后端和前端以 HTTPS 协议运行；
  2. 手机在访问 https://<PC_IP>:5174 时，因自签名证书会提示“不安全/证书无效”，点击“高级”并选择“继续前往”；
  3. 亦可通过 Android 原生 APK 形式运行，原生应用在授予权限后不受浏览器 HTTPS 域名限制。

Q2: 高德地图显示白屏或提示 KEY 鉴权错误？

• 原因：未配置或错误配置了 VITE_AMAP_KEY 及 VITE_AMAP_SECRET。
• 解决办法：在 高德开放平台 创建应用并添加 Web 端 (JS API) 类型的 Key。如果设置了安全密钥，需同时配置 VITE_AMAP_SECRET。

Q3: WebRTC 视频推流提示连接失败或画面黑屏？

• 原因：WebRTC P2P 模式需要两端网络直通或 ICE 候选者成功交换。在复杂子网或跨网段场景下可能需要 STUN/TURN 服务器配合。
• 解决办法：
  1. 保证 PC 指挥端与移动端处于同一局域网（Wi-Fi）内；
  2. 检查两端控制台网络请求，确保 Socket.IO 信令握手成功（没有连接超时报错）。

---

11. 详细文档索引

本项目在 docs/ 目录下维护了完整的工程规范与设计文档：

• 📘 软件开发架构文档 (Software Development Document)：包含领域模型、Prisma Schema、信令接口规范与系统扩展机制。
• 📕 操作员与用户使用手册 (User Manual)：面向指挥员与一线人员的完整图文功能操作指引与权限说明。
• 📗 生产部署运维手册 (Deployment Guide)：Nginx 反向代理、SSL 证书配置、环境调优指南。
• 📙 里程碑与开发规划表 (OmniSight_C2_开发计划.md)：功能演进路标与未来迭代规划。

---

12. 开源许可

本项目采用 MIT License 开源许可证。