VITTOR · 用户手册

简体中文

English

简体中文

English

主题

系统部署 ​

本页面只介绍新环境的首次部署。已有环境升级请阅读已有环境升级，出现异常需要恢复时请阅读异常回退。部署前请以交付清单确认版本、主机和网络地址；真实密码、人员资料和设备参数应保存在受控交付记录中，不写入公开手册。

部署范围 ​

首次部署需要准备指定版本的镜像交付包、主机和网络信息。本页按“主机检查 → 加载镜像 → 空数据卷初始化 → 首次配置 → 上线验收”的顺序说明。

系统组成与端口 ​

服务端由三个容器组成，录入端和大屏端安装在对应的 Android 终端。

组件作用默认入口
vittor_web提供管理页面并转发业务请求宿主 HTTP 80，可用 WEB_PORT 修改
vittor_server提供业务接口、人员同步、识别事件和节点发现容器 HTTP 8000；宿主 UDP 20785
vittor_mysql保存人员、空间、设备、识别事件和运行数据容器 3306；宿主默认只绑定 127.0.0.1:3306
录入端读取证件、采集照片并提交人员资料终端管理 HTTP 8182；UDP 20785
大屏端接收识别结果并展示现场状态终端管理 HTTP 8181；按模式使用本地或云端接收端口

数据库、终端管理接口和 UDP 发现端口只应开放给需要的维护网络。中心服务中的人员同步和节点发现需要持续运行。

部署前检查 ​

  1. 在主机安装 Docker Engine、Docker Compose v2、Bash 和 curl。
  2. 确认 Web 端口、数据库回环端口和 UDP 20785 没有冲突；终端所在网络能够访问中心主机的局域网地址。
  3. 准备组织或主体、管理员、空间结构、录入端和识别设备的初始化资料。
  4. 确认数据库、人员照片和其他文件资源的保存位置与责任人；不要用清空数据卷的方式处理登录或业务数据问题。
  5. 将数据库密码、管理员凭证、设备密钥和人员照片保存在受控位置；对外分享截图、日志和导出包前先脱敏。

部署参数 ​

部署脚本从当前终端会话读取参数。不要把真实密码写入 Compose 文件、脚本或公开文档。

参数默认值用途
MYSQL_ROOT_PASSWORD无默认值首次启动必填；复用已有数据时必须与现有数据匹配
MYSQL_DATABASEface_tp数据库名称
WEB_PORT80Web 宿主端口
MYSQL_PORT3306数据库宿主端口，仅绑定 127.0.0.1
DISCOVERY_HOST自动检测终端可访问的中心主机地址
DISCOVERY_HTTP_BASE_URL根据主机地址生成广播给终端的完整中心地址
DISCOVERY_PORT20785局域网发现 UDP 端口
DISCOVERY_TIMEOUT45 秒超过该时间没有新广播时判为离线
VITTOR_PUSH_WORKER1是否启动人员同步任务
VITTOR_PUSH_INTERVAL5 秒人员同步任务间隔
VITTOR_DISCOVERY_WORKER1是否启动节点发现任务
HUIYAN_URL空默认慧眼或大屏地址
HEARTBEAT_TIMEOUT60 秒服务心跳离线判断时间

多网卡、虚拟机或容器环境必须显式核对 DISCOVERY_HOST 和 DISCOVERY_HTTP_BASE_URL。不要把容器内部地址或 127.0.0.1 广播给其他终端。

使用镜像交付包 ​

将交付清单指定的部署包复制到主机并进入该目录。下面示例使用 Bash：

bash
cd /path/to/deployment-package
export MYSQL_ROOT_PASSWORD='请通过受控方式设置'
export DISCOVERY_HOST='192.168.1.20'
export DISCOVERY_HTTP_BASE_URL="http://${DISCOVERY_HOST}:${WEB_PORT:-80}"

# 加载镜像、创建数据卷并启动服务
bash deploy/load-and-start.sh

如果镜像已经加载过，只需执行：

bash
bash deploy/start.sh

脚本会检查 Docker Compose、创建外部数据卷、等待数据库健康，并尝试访问心跳接口。默认从部署包内读取 vittor-images.tar.gz；镜像文件放在其他位置时，可通过 IMAGE_ARCHIVE 指定路径。

首次启动与初始化 ​

首次使用空数据卷时，系统会按交付版本自动创建基础数据结构和初始配置；已有数据卷不会因更换镜像、修改环境变量或重启服务而重复初始化。

初始管理员仅用于首次进入系统。登录后立即修改密码，并确认组织、管理员权限、空间结构和设备配置。初始化完成不代表业务关系已经配置完成，仍需按“首次配置”和“上线验收”继续操作。

首次配置顺序 ​

  1. 执行 bash deploy/status.sh，确认 vittor_mysql、vittor_server 和 vittor_web 稳定运行且没有持续重启。
  2. 登录 Web 管理端，确认组织、管理员权限和基础空间结构。
  3. 让录入端和大屏端连接同一局域网，检查它们是否通过 UDP 20785 出现在“系统配置”中。
  4. 在“系统配置”中下发中心服务地址。录入端管理接口为 http://设备地址:8182/api/config，大屏端管理接口为 http://设备地址:8181/api/config；修改后从终端确认保存结果。
  5. 按现场模式配置慧眼或大屏地址，保存后重新检查连接状态。

上线验收 ​

从基础设施到现场业务按顺序验收：

层级检查通过标准
服务docker compose ps、服务日志三个服务稳定运行，数据库健康，无持续重启
Web打开管理页面实际操作电脑可以访问首页和登录页
中心服务GET /api/heartbeat返回 state=1，响应时间和服务信息正常
数据登录后查询一条已知组织、空间和人员数据正确，照片或文件资源可读取
节点发现GET /api/discovery/nodes录入端和大屏端能被发现，地址可从终端访问
终端配置下发中心地址两类终端保存配置并恢复连接
人员同步新增或修改一名测试人员中心记录、目标设备资料和处理结果一致
识别闭环完成一次真实测试识别接收端和大屏显示同一人员、设备和时间

默认 Web 端口下，可执行以下只读检查；修改端口后替换地址：

bash
bash deploy/status.sh
curl --fail http://127.0.0.1/api/heartbeat
curl --fail http://127.0.0.1/api/device/online-count
curl --fail http://127.0.0.1/api/discovery/nodes

首页能打开、数据库健康和心跳成功分别只证明单个环节，不能替代登录、数据、同步和识别验收。节点数量也不能直接等同于在线识别设备数量。

相关接口 ​

接口用途说明
GET/POST /api/heartbeat中心服务心跳不查库、不写业务数据
GET /api/discovery/nodes查看最近发现的系统节点受 DISCOVERY_TIMEOUT 影响
POST /api/discovery/configure向已发现终端下发中心地址仅限可信内网和管理员操作
GET/POST /api/huiyan/route查看或修改慧眼地址需要管理员会话
GET /api/device/online-count查询已启用且在线的识别设备数量用于大屏统计，不代表节点发现数量

详细的业务链路和故障分层见故障排查。

连接人员、空间与设备。

© 沈阳微拓科技