安装教程
约 2916 字大约 10 分钟
安装部署Docker源码安装
2025-03-03
联犀物联网平台支持多种安装方式,您可以根据实际需求选择最适合的部署方式。
📋 安装方式对比
| 安装方式 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| SaaS 版本(urops 一键部署) | 企业私有化交付、生产环境 | 一条命令部署、自动备份/升级/回退、license 授权 | 需要授权码 |
| Docker Compose | 生产环境、快速体验 | 一键部署、环境隔离 | 需要Docker环境 |
| 源码安装 | 开发环境、定制开发 | 完全控制、便于调试 | 环境配置复杂 |
🚀 SaaS 版本安装(urops 一键部署)
适用场景
SaaS 版本为企业私有化交付版:完整功能(含能源、停车、音视频等模块), 通过 urops 运维工具一条命令部署、升级、备份、回退,使用 license 授权码激活。
系统要求
- 操作系统:Linux(推荐 Ubuntu 22.04+,主机或虚拟机均可,支持 KVM/VMware 等)
- Docker 20.10+、Docker Compose 2.0+
- 内存:最低 4GB,推荐 8GB 以上
- 存储:最低 50GB(数据库 + 镜像约 10GB),推荐 100GB 以上
- 网络:可访问镜像仓库
docker.unitedrhino.com(节点联网部署时需可达云端saas.unitedrhino.com,见常见问题)
第一步:安装 urops 运维工具
免登录一键安装(自动查 Harbor 最新版本 + sha256 校验):
curl -fsSL https://doc.unitedrhino.com/urops/install.sh | sudo bash安装完成后,所有操作都在交互式菜单(TUI)中完成——终端直接输入 urops 回车即可进入:

也可固定版本安装:
UROPS_TAG=v1.1.11 curl -fsSL ... | sudo bash;urops update --check可随时检测并自动升级自身(TUI 界面进入时自动在底部提示新版本)。 首次使用建议先「环境准备 → 安装全部」自动装好 Docker/Compose 等环境(幂等)。
第二步:一键部署(TUI)
进入 TUI 后,「部署」→ 选择部署版本 → 选对象存储,全程菜单选择、自动拉镜像、自动初始化数据库:

常用部署版本:能源中心 energy(能耗管理)、基础版 edge(通用边缘节点)、芙崽 fuzai。 选完版本后按提示选择对象存储(rustfs 默认即可),TUI 会展示拉取镜像、启动容器、等待健康的实时进度: 部署完成后访问 http://<服务器IP>:7777/app/edge-self/(边缘自服务页)。
命令行方式(等价)
sudo urops up --type energy --oss-type rustfs第三步:激活 License(TUI)
「运维 → 激活许可」,粘贴云端签发的授权码回车即可:

申请授权前先看机器码:「运维 → 许可状态」(或浏览器打开 http://<服务器IP>:7777/app/edge-self/ 激活页)。 License Key、机器码、有效期、配额在「运行状态」一站式查看。
日常运维(TUI)

运行状态:容器 + 云端连通性 + license 一站式检查(执行页实时展示):

一键升级 / 回退镜像 / 备份数据库 / 恢复备份 / 卸载部署:均在「运维」菜单内菜单化执行,升级前自动备份数据库;
更新 urops:工具自身升级;远程运维:tailscale 组网(安装/连接/状态/设备列表/自检):

也有等价命令行(脚本/AI 场景):
urops status、urops upgrade、urops update、urops backup等。
常见问题
- 部署/升级时提示「云端不可达 HTTP 522」:云端域名直连被网关拦截时,节点可在 compose 应用服务配置
HTTPS_PROXY(同时配NO_PROXY含内部服务名)走代理;urops 探测/心跳复用容器代理(v1.1.1+)。 - 升级备份失败「the database system is in recovery mode」:数据库恢复中属正常,urops 会自动等待 数据库就绪后重试(v1.1.3+);也可
urops upgrade --no-backup跳过备份。 - 激活失败/授权文件校验失败:授权码为单机绑定,确认与机器码一致;旧镜像公钥可能不匹配, 请
urops update升至最新后重试。 - 前端页面 404:确认部署类型镜像包含对应应用(
urops status查看镜像版本),或联系联犀获取。 - VNC/控制台界面乱码:字符控制台(
TERM=linux)或非 UTF-8 locale 下 urops 自动切换英文(v1.1.18+);
需要中文可安装中文字体(如fonts-unifont)并确保 locale 为 UTF-8,或urops lang zh强制中文。
技术细节
- 升级/回退只重建应用服务,数据库等数据容器不动;升级前自动备份数据库(保留最近 10 份,
urops backup手动备份)。 - License 校验在边缘侧本地完成(编译内置公钥验签),离线可用;到期进入受限模式。
- 详细命令与配置见 urops 工具使用指南(在新窗口打开)。
🐳 Docker Compose 模式安装
推荐
Docker Compose 模式是最推荐的安装方式,适合生产环境和快速体验。
环境要求
- Docker 20.10+
- Docker Compose 2.0+
- 内存:最低2GB,推荐8GB+
- 存储:最低20GB,推荐100GB+
安装步骤
1. 安装 Docker(已安装可跳过)
Linux 环境安装(推荐 Ubuntu 系统):
# 使用一键安装脚本
bash <(curl -sSL https://linuxmirrors.cn/docker.sh)Windows 环境安装:
- 下载 Docker Desktop for Windows
- 安装后重启系统
macOS 环境安装:
- 下载 Docker Desktop for Mac
- 拖拽到应用程序文件夹
更多信息
- 官方安装文档:Docker 安装指南
- 国内镜像源:https://linuxmirrors.cn
2. 下载联犀代码
# 克隆代码仓库
git clone https://gitee.com/unitedrhino/things.git
cd things/deploy/docker/run-all3. 选择安装模式
根据您的需求选择合适的安装模式:
🚀 MariaDB 完整性能模式(推荐生产环境)
适用场景:对性能有要求的场景,数据量大,并发多,支持横向扩展
组件说明:
- NATS:内部消息队列,处理服务间通信
- etcd:服务发现和配置管理
- MariaDB:关系型数据库,存储业务数据
- TDengine:时序数据库,存储设备数据
- EMQX:MQTT消息服务器,支持十万级连接
- MinIO:对象存储,存储文件数据
- Redis:缓存数据库,提升性能
执行命令:
docker compose up -d🐘 PostgreSQL 完整性能模式
适用场景:与MariaDB模式相同,使用PostgreSQL数据库
特点:与MariaDB模式一致,只是将MariaDB替换为PostgreSQL
执行命令:
docker compose -f docker-compose-pg.yml up -d💻 最少依赖模式(企业版)
适用场景:设备量少或低性能服务器(内存最低2GB),不适合大规模场景
组件说明:
- NATS:内部消息队列
- etcd:服务发现
- Redis:缓存数据库
- PostgreSQL + TimescaleDB:时序数据存储在TimescaleDB中
- 内置MQTT Broker:使用comqtt,无需独立部署
- 本地文件存储:文件直接存储在服务器
执行命令:
docker compose -f docker-compose-min.yml up -d注意
最少依赖模式需要企业版源码,Windows安装包请联系我们获取。
4. 验证安装
安装完成后,访问 http://localhost:7777 体验联犀平台!
默认登录信息:
- 账号:
administrator - 密码:
iThings666
提示
首次访问可能需要等待几分钟,等待所有服务完全启动。
💻 源码安装模式
适用场景
源码安装模式适合开发环境、定制开发和深入学习平台架构。
视频教程:
环境要求
- Go 语言:1.23+
- Node.js:16+(前端开发)
- 数据库:MySQL 5.7+ 或 PostgreSQL 12+
- Redis:6.0+
- 其他依赖:NATS、etcd、TDengine、EMQX、MinIO
1. 代码拉取
# 共享库(不修改可以不clone)
git clone https://gitee.com/unitedrhino/share.git
# 中台模块
git clone https://gitee.com/unitedrhino/core.git
# 物联网模块
git clone https://gitee.com/unitedrhino/things.git2. 安装 Go 语言
下载安装:
- 访问 Go 官网 下载最新版本
- 安装版本需要 ≥ 1.23
配置环境变量:
# Linux/macOS
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
# Windows
# 在系统环境变量中设置 GOPATH 和 PATH验证安装:
go version3. 安装第三方依赖
方式一:Docker Compose 安装(推荐)
进入环境安装目录:
cd things/docker/run-env选择数据库模式执行:
# MariaDB 模式
docker compose up -d
# PostgreSQL 模式
docker compose -f docker-compose-pg.yml up -d方式二:物理机安装
需要手动安装以下组件:
| 组件 | 版本要求 | 说明 |
|---|---|---|
| Redis | 6.0+ | 高性能缓存数据库 |
| NATS | 2.9+ | 高性能消息队列 |
| MySQL | 5.7+ | 关系型数据库(推荐 MariaDB) |
| PostgreSQL | 12+ | 关系型数据库(可选) |
| etcd | 3.5+ | 微服务注册中心 |
| MinIO | 最新 | 对象存储服务 |
| TDengine | 3.0+ | 时序数据库 |
| EMQX | 5.0+ | MQTT消息服务器 |
推荐
建议使用 Docker Compose 方式安装依赖,可以避免环境配置问题。
配置修改
emqx配置修改
参考: emqx配置方法
运行
后端
# 运行core服务
cd core/server/apisvr
go mod download
go run .
# 另开一个窗口
# 运行物联网模块
cd things/server/apisvr
go mod download
go run .开发的时候涉及到多个库联动的时候建议使用go work来操作
- 在项目根路径下执行
go work init - 添加go的项目进go.work中,如下示例
go 1.21.4
use (
./core
./protocol-aliyun
./protocol-tencent
./protocol-wumei
./share
./things
)- 同步依赖
go work sync
这样就可以不使用replace就能修改依赖的仓库了
前端
开源版本前端运行
- 下载 前端压缩包(在新窗口打开)
- 复制到静态文件的目录
mkdir -p core/service/apisvr/dist/app
cd core/service/apisvr/dist/app
tar -xvzf frontFile_latest.tgz
rm frontFile_latest.tgz
cd -体验
访问 127.0.0.1:7777 体验联犀吧~
goland调试方法
在goland中直接运行服务会报找不到配置文件,我们需要做一个配置,参考下图,点击上面的按钮,然后点击编辑配置,会出现下面的页面,将工作目录修改为服务的main函数所在的位置即可正常启动

视频教程
fqa
- 产品及设备创建报错:
- 请检查数据库是否创建成功
- 联犀请求tdengine是通过http的方式请求,参考官方文档检查td的服务是否启动: https://docs.taosdata.com/connector/rest-api/
- 设备在线状态在服务器上不正确或设备可以订阅任何topic:检查
emqx_auth_http.conf这个文件配置的ip是否正确 - 联犀启动不起来,报mqtt连接不上:同样需要检查
emqx_auth_http.conf这个文件配置的ip是否正确,emqx需要通过http来请求联犀进行认证,如果实在起不来,可以先把emq的权限认证关了,等things服务起来之后再打开emqx的权限认证 - docker镜像拉取不下来: 这种情况一般是网络原因导致的,需要配置代理,简单的方式是可以安装1panel来一键配置代理
- 运行不起来,things服务报错tdengine没有ithings数据库,检查run-env下的init-db.sh的换行格式,如果是win的,需要换成linux的才可以执行
- 在拉取things模块的时候报core的包拉不下来 执行
go env -w GOPRIVATE=gitee.com
本地 AI 接入
平台部署完成后,想让 Claude Code / Cursor / Codex / Trae 等本地 AI 工具直接操控联犀平台(安装 ur CLI、认证、部署 Skills),请看 本地 AI 安装教程。
更新日志
2026/9/4 15:36
查看所有更新日志
355b6-docs(use): 安装教程 urops 部分改为 TUI 为主并配真实截图于66140-docs(use): urops 界面多语言说明与乱码 FAQ于c1424-docs(use): urops 安装改为 curl | bash 一键脚本于37dfa-docs(use): 安装教程新增 SaaS 版本安装章节 + urops 工具使用指南于af804-Merge #17 into master from feat/docs-local-ai-v2于bddea-docs: 更新文档结构、添加新内容并优化现有文档于054ea-doc于09eb8-doc于0aef7-doc于cf613-doc于51ff0-doc于d4fa0-doc: 更换皮肤到最新版于12463-feat: 支持pg于f4a75-doc: 完善文档于c12e0-doc: 完善文档于cc869-doc: 完善文档于6449d-doc: 完善文档于a7823-doc: 完善文档于6b3f8-doc: 完善文档于80a75-doc: 完善文档于2a8b3-doc: 完善文档于9ed31-doc: 完善文档于f4017-doc: 完善文档于79a65-doc: 完善文档于d999f-初始化于90f49-feat: 完善项目`于aef02-初始化于27289-初始化于cf61b-初始化于6055d-初始化于df9b4-初始化于
