联犀

安装教程

约 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 主菜单

也可固定版本安装：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 等。

常见问题

  1. 部署/升级时提示「云端不可达 HTTP 522」：云端域名直连被网关拦截时，节点可在 compose 应用服务配置 HTTPS_PROXY（同时配 NO_PROXY 含内部服务名）走代理；urops 探测/心跳复用容器代理（v1.1.1+）。
  2. 升级备份失败「the database system is in recovery mode」：数据库恢复中属正常，urops 会自动等待 数据库就绪后重试（v1.1.3+）；也可 urops upgrade --no-backup 跳过备份。
  3. 激活失败/授权文件校验失败：授权码为单机绑定，确认与机器码一致；旧镜像公钥可能不匹配， 请 urops update 升至最新后重试。
  4. 前端页面 404：确认部署类型镜像包含对应应用（urops status 查看镜像版本），或联系联犀获取。
  5. 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 环境安装：

macOS 环境安装：

更多信息

2. 下载联犀代码

# 克隆代码仓库
git clone https://gitee.com/unitedrhino/things.git
cd things/deploy/docker/run-all

3. 选择安装模式

根据您的需求选择合适的安装模式：

🚀 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.git

2. 安装 Go 语言

下载安装：

  • 访问 Go 官网 下载最新版本
  • 安装版本需要 ≥ 1.23

配置环境变量：

# Linux/macOS
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

# Windows
# 在系统环境变量中设置 GOPATH 和 PATH

验证安装：

go version

3. 安装第三方依赖

方式一：Docker Compose 安装（推荐）

进入环境安装目录：

cd things/docker/run-env

选择数据库模式执行：

# MariaDB 模式
docker compose up -d

# PostgreSQL 模式
docker compose -f docker-compose-pg.yml up -d

方式二：物理机安装

需要手动安装以下组件：

组件版本要求说明
Redis6.0+高性能缓存数据库
NATS2.9+高性能消息队列
MySQL5.7+关系型数据库（推荐 MariaDB）
PostgreSQL12+关系型数据库（可选）
etcd3.5+微服务注册中心
MinIO最新对象存储服务
TDengine3.0+时序数据库
EMQX5.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来操作

  1. 在项目根路径下执行 go work init
  2. 添加go的项目进go.work中,如下示例
go 1.21.4

use (
	./core
	./protocol-aliyun
	./protocol-tencent
	./protocol-wumei
	./share
	./things
)
  1. 同步依赖 go work sync

这样就可以不使用replace就能修改依赖的仓库了

前端

开源版本前端运行
  1. 下载 前端压缩包
  2. 复制到静态文件的目录
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

  1. 产品及设备创建报错:
    1. 请检查数据库是否创建成功
    2. 联犀请求tdengine是通过http的方式请求,参考官方文档检查td的服务是否启动: https://docs.taosdata.com/connector/rest-api/
  2. 设备在线状态在服务器上不正确或设备可以订阅任何topic:检查emqx_auth_http.conf这个文件配置的ip是否正确
  3. 联犀启动不起来,报mqtt连接不上:同样需要检查emqx_auth_http.conf这个文件配置的ip是否正确,emqx需要通过http来请求联犀进行认证,如果实在起不来,可以先把emq的权限认证关了,等things服务起来之后再打开emqx的权限认证
  4. docker镜像拉取不下来: 这种情况一般是网络原因导致的,需要配置代理,简单的方式是可以安装1panel来一键配置代理
  5. 运行不起来,things服务报错tdengine没有ithings数据库,检查run-env下的init-db.sh的换行格式,如果是win的,需要换成linux的才可以执行
  6. 在拉取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-初始化于

联犀 AIoT 平台持续进化中 🚀

📢 查看平台更新说明

微信扫码关注公众号，掌握最新进展；回复“加群”进群