UVP

DEPLOYMENT GUIDE · LINUX

UVP-GB28181 Linux 部署手册

把统一视频接入平台装到一台 Linux 服务器上：下载、校验、启动、放行防火墙、登录初始化，到第一次看到设备接入信息，全程约 15 分钟。所有截图来自 1.1.13 版本的真实部署过程。

版本说明：下文命令以 1.1.13 为例，实际版本号请以[下载页](/downloads/uvp-gb28181)当前发布的为准，把命令里的 1.1.13 换成对应版本即可，步骤完全相同。

1. 环境要求 ​

「独立部署包」是绿色包：数据库（SQLite）、缓存（Redis）、流媒体服务（ZLMediaKit）、Web 服务器（nginx）全部随包自带，目标机不需要预装任何运行时和依赖，也不用 Docker。

项目要求
CPU 架构x86_64（amd64 包）或 aarch64（arm64 包），按机器选对应安装包
操作系统glibc 2.28 及以上：CentOS / RHEL / 银河麒麟 V10 SP2 / 统信 UOS / openEuler / Ubuntu 等均可
内存建议 2 GB 及以上
磁盘建议 10 GB 以上可用空间（数据库与录像索引会持续增长）
运行身份普通用户即可运行，只有注册开机自启才需要 root
浏览器Chrome / Edge / Firefox 近两年版本

端口使用连续的 51000–51064 一段（共 65 个），启动时会逐个实测，被占用会当场报错并提示改哪一项。

2. 部署步骤总览 ​

  1. 在[下载页](/downloads/uvp-gb28181)选择与系统、架构匹配的安装包并下载
  2. 核对 SHA-256 校验值，确认文件完整
  3. 解压到目标目录，认识包根结构
  4. 执行 ./uvp-gb28181-ctl.sh start 启动全部服务
  5. 在防火墙放行 51000–51064（局域网访问才需要）
  6. 浏览器打开管理页面，用初始账号登录并立即修改口令
  7. 完成首次登录的接入向导（部署方式、网络地址、SIP 身份）
  8. 记录 SIP 接入信息，交给设备侧配置使用
  9. 检查「设备接入地址」是否指向本机
  10. 按需开启 HTTPS、注册开机自启

3. 第一步：下载安装包 ​

打开官网下载页，在「Linux 独立部署包」里按架构选择（ Intel / AMD 机器选 amd64，鲲鹏、飞腾等选 arm64），点击下载。

官网下载页，Linux 独立部署包区域
官网下载页：每个安装包都标注了文件大小与 SHA-256 校验值

下载完成后核对校验值，确认传输过程没有损坏。在下载目录执行：

终端：curl 下载后执行 sha256sum 校验
用 sha256sum 核对：输出应与下载页标注的 SHA-256 完全一致

把输出的哈希值和下载页该安装包标注的 SHA-256 逐字符比对，一致才算完整。不一致说明下载损坏，重新下载即可。

4. 第二步：解压并认识包根 ​

把安装包解压到目标目录（示例用 /opt/uvp，可以换成任何有权限的路径）：

bash
mkdir -p /opt/uvp && cd /opt/uvp
tar -xzf uvp-gb28181-linux-amd64-1.1.13.tar.gz
cd uvp-gb28181-linux-amd64-1.1.13

解压出来的目录就是「包根」，后面的命令都在这个目录里执行。目录结构如下：

终端：ls -la 展示包根目录结构
包根目录：日常只需要关心 ctl 脚本、config、data 三个
目录 / 文件作用
uvp-gb28181-ctl.sh唯一入口：启动、停止、重启、查状态、重置口令
uvp-gb28181-service-install.sh注册成 systemd 服务、开机自启（可选，需要 root）
bin/平台程序本体：后端 uvp-server、初始化工具 uvp-setup、升级助手
vendor/自带 Redis、ZLMediaKit、nginx，不用另装
config/全部配置：config.yml（业务配置）+ config.env（端口段与密钥）
data/全部业务数据：数据库、Redis 落盘、运行期密钥
logs/全部日志：业务、流媒体、nginx
run/运行期临时文件（pid 等），重启自动重建

记住两个目录：备份和迁移只需要 data/ 和 config/，其他目录都可以由安装包重新生成。

5. 第三步：启动服务 ​

在包根执行一条命令即可启动全部组件：

bash
./uvp-gb28181-ctl.sh start

首次启动会自动完成建库和初始化（约 1 分钟），结束后打印访问地址和端口规划：

终端：首次启动完整输出，包含三阶段进度与访问地址
首次启动完整输出：环境检查 → 初始化数据 → 启动服务，最后给出访问地址

输出分三个阶段，重点看这几行：

  • 阶段 1 · 环境检查：逐个实测 51000–51064 是否可绑定。报「端口冲突」就按提示改 config/config.env 里的端口段再重试。
  • 阶段 2 · 初始化数据：建 114 张表、灌入初始数据、创建管理员账号（admin）。中间「有 9 条 CREATE 语句不会生效」是 SQLite 的库级唯一约束提示，属正常现象，不影响使用。
  • 阶段 3 · 启动服务：Redis、ZLMediaKit、nginx、后端依次起来。用普通用户启动时「防火墙代理」会提示未启动，只影响内核级封禁，不影响平台使用。
  • 结尾：打印访问地址、登录账号，以及需要放行防火墙时该执行的命令。

不要把最后几行关掉：访问地址、防火墙命令都在里面。关掉了执行 ./uvp-gb28181-ctl.sh status 可以再查一遍。

6. 第四步：放行防火墙（局域网访问） ​

如果这台服务器只给本机用，跳过这一步。要让局域网内的设备、其他电脑访问，需要放行 51000–51064 一段端口。按系统类型选一条：

bash
# Ubuntu / 统信 UOS（ufw）
sudo ufw allow 51000:51064/tcp
sudo ufw allow 51000:51064/udp

# CentOS / RHEL / 银河麒麟 / openEuler（firewalld）
sudo firewall-cmd --permanent --add-port=51000-51064/tcp
sudo firewall-cmd --permanent --add-port=51000-51064/udp
sudo firewall-cmd --reload

以 start 收尾打印的那条为准，直接照抄即可。云服务器还要在控制台的安全组里放行同样范围。

7. 第五步：登录并修改初始口令 ​

浏览器访问启动时打印的地址（形如 http://<服务器IP>:51000），首次登录使用初始账号：

  • 账号：admin
  • 口令：123456
UVP-GB28181 登录页面，右上角显示版本号
登录页面：右上角可以看到当前版本号（图为 v1.1.13）

输入验证码后登录，系统会强制要求先修改口令：

强制修改密码页面
首次登录后强制修改初始口令，按复杂度要求设置新口令

改完口令会自动进入首次登录的接入向导。

8. 第六步：完成接入向导 ​

向导引导录入四项基础信息，按现场实际情况填写：

  1. 部署方式：局域网部署或公网部署；
  2. 网络地址：平台对外提供访问的地址与端口；
  3. SIP 身份：SIP 服务端口、平台编号（服务器 ID）、SIP 域、SIP 口令 —— 这些就是之后设备侧要配的参数；
  4. 确认信息：核对无误后点「保存并启动」。
接入向导第三步：SIP 身份配置
向导第三步「SIP 身份」：这些参数之后要原样填到设备侧

保存后进入仪表盘，左侧出现完整菜单，部署基本完成：

平台仪表盘页面
仪表盘：能看到在线设备、通道、流量等总览信息

9. 第七步：记录 SIP 接入信息 ​

进入左侧菜单「SIP 接入信息」，这一页汇总了设备侧需要的全部参数，建议直接截图保存：

SIP 接入信息页面，包含 SIP 服务器地址、端口、平台编号、域与口令
SIP 接入信息：设备侧按这五项配置即可注册到平台

把「SIP 服务器地址、端口、平台 ID、SIP 域、SIP 口令」交给设备或摄像头厂商，在设备侧配成相同的值，设备即可注册上线。详细的设备接入步骤见使用手册总览。

10. 第八步：检查「设备接入地址」 ​

进入「国标服务配置」页面，翻到最底部的「设备接入地址」段，确认两个地址指向的是这台服务器的当前地址：

国标服务配置页面底部的设备接入地址
国标服务配置 → 设备接入地址：扫码配网与抓拍回传各一项
  • 扫码配网地址：App 扫码配网时下发给手机的入口地址，端口为后端端口（51002）；
  • 抓拍回传地址：GB/T 28181-2022 抓拍图片回传入口，端口为 nginx 明文口（51000），必须是明文 http://（设备不认自签证书）。

如果这里显示的不是本机地址（例如残留了其他机器的 IP、或还是默认值），请手工改成本机当前地址。地址不对时，扫码配网和图片回传会静默失败，平台侧没有任何报错。

同一页里还集中了国标相关的运行开关（传输模式、订阅项、超时时间等），保持默认即可，需要时再按现场调整。

11. 第九步：开启 HTTPS（可选） ​

默认是明文 HTTP，局域网内可用。要启用 HTTPS：进入「系统管理 → 系统配置 → HTTPS」标签，打开「是否启用 HTTPS」开关。安装包已内置自签证书，无需自己准备；切换后访问地址变为 https://<服务器IP>:51001。

系统配置 HTTPS 标签页
系统配置 → HTTPS：打开开关即启用内置证书，可改为上传自有证书

自签证书浏览器会提示不受信任，属正常现象；需要正式证书时在同一页上传 PEM 证书与私钥文件。ZLMediaKit 的 HTTPS / WSS 端口保持开启，不受此开关影响。

12. 第十步：注册开机自启（可选） ​

希望服务器重启后平台自动恢复，注册成 systemd 服务（需要 root）：

bash
sudo ./uvp-gb28181-service-install.sh --now

之后服务名为 uvp-gb28181，可用 systemctl status uvp-gb28181 查看，用 systemctl 标准命令管理。卸载注册（只删服务、不动数据）执行 sudo ./uvp-gb28181-service-uninstall.sh。

13. 日常运维 ​

所有操作都通过包根里的一个脚本完成：

操作命令
启动./uvp-gb28181-ctl.sh start
停止./uvp-gb28181-ctl.sh stop
重启./uvp-gb28181-ctl.sh restart
查看状态./uvp-gb28181-ctl.sh status
重置登录口令./uvp-gb28181-ctl.sh reset-password
终端：status 命令输出，五项组件全部运行中
status 输出：Redis、ZLM、后端、nginx、升级助手五项状态

备份

停服后只打包 `data/` 和 `config/` 两个目录即可：
bash
./uvp-gb28181-ctl.sh stop
tar -czf uvp-backup-$(date +%F).tar.gz data config

升级

解压新版本安装包覆盖原目录，data/ 和 config/ 原样保留（不要删），然后 `restart`。升级日志见[版本记录](/changelog/uvp-gb28181)。

迁移

把 `data/` 和 `config/` 拷到新机器，装同版本包后 `start`。跨平台迁移要同时修改 `config/config.env` 的端口段（Linux 用 51000 段、Windows 用 15500 段）。

14. 常见问题 ​

页面打不开

先执行 `./uvp-gb28181-ctl.sh status`，看四项（Redis / ZLM / 后端 / nginx）是否都「运行中」。都正常却打不开，确认用的是 `http://` + `51000`（开过 HTTPS 才是 `https://` + `51001`），写成后端端口 `51002` 是不对的；只有「管理页面」没起来时看 `logs/nginx.log`。

登录页报 no such table

库里没建好，多半是首次启动中途被打断。重跑 `./uvp-gb28181-ctl.sh start`（检测到库不完整会自动重建）；仍不行就停服后删掉 `data/uvp.db` 再启动 —— 只在还没录入业务数据时这么做，删库等于清空业务数据。

提示端口已被占用

按提示先 `stop`；仍被占用就是其他软件在用。打开 `config/config.env` 最上面的端口区（16 个常用端口都能改），改完 `restart`，再按新打印的防火墙命令放行。

忘记登录口令

执行 `./uvp-gb28181-ctl.sh reset-password`，口令还原成出厂口令并要求下次登录修改，不碰设备、通道、录像数据。

Permission denied（没有执行权限）

解压工具丢了可执行位，执行一次 `chmod +x uvp-gb28181-ctl.sh bin/uvp-setup bin/uvp-server updater/uvp-updater`，或者用 `bash uvp-gb28181-ctl.sh start` 启动。

15. 继续阅读 ​