联犀开发者文档

开源版安装教程

约 1704 字大约 6 分钟

开源安装Docker源码安装

2026-10-08

本篇介绍开源社区版的 Docker Compose 部署与源码运行，适合自行搭建、学习和二次开发。它与企业版私有化部署是不同路径；只想在线体验平台，可先看SaaS 演示与注册。

🐳 Docker Compose 模式安装

版本说明

下方命令以开源仓库当前默认分支的目录为准。Docker Compose 使用仓库现有镜像与配置；部署前请核对所选版本的 README、依赖和许可。

环境要求

  • 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 和 PostgreSQL 两种 Compose 文件，请按数据库需求选择其一。

🚀 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

4. 验证安装

容器启动后，用 docker compose ps 检查服务状态；选择 PostgreSQL 时，同样为检查命令加上 -f docker-compose-pg.yml。前端页面需要与所选版本匹配的静态资源；仓库中的 deploy/docker/conf/core/dist 默认不包含页面文件。准备好前端资源后，再访问 http://<服务器IP>:7777。

默认登录信息：

  • 账号：administrator
  • 密码：iThings666

提示

首次访问可能需要等待几分钟，等待所有服务完全启动。

💻 源码安装模式

适用场景

本节以开源 core、things、share 仓库为例。开源源码与企业版免费基础版的部署产物不同，请按各仓库 README 核对依赖。

视频教程：

环境要求

  • Go 语言：1.24.4+（以当前 core、things 仓库的 go.mod 为准）
  • 数据库：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.24.4

配置环境变量：

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

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

验证安装：

go version

3. 安装第三方依赖

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

进入环境安装目录：

cd things/deploy/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/service/apisvr
go mod download
go run .

# 另开一个终端，从共同父目录进入 things 服务
cd things/service/apisvr
go mod download
go run .

同时修改多个 Go 仓库时，在它们的共同父目录创建工作区：

go work init ./core ./things ./share
go work sync

前端

上述三个 Go 仓库不包含可直接使用的前端发行包。请按所选开源版本获取匹配的前端构建产物，并放入 core/service/apisvr/dist/app/；未准备静态资源时，只能验证后端服务，不能据此判断页面部署成功。

体验

后端与前端资源均准备完成后，访问 http://127.0.0.1:7777 验证页面。

GoLand 调试方法

在 GoLand 中运行服务时，将工作目录设置为对应服务的 service/apisvr，以便读取该目录下的配置文件。

GoLand 工作目录配置

常见问题

  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/10/8 20:29
查看所有更新日志
  • 9d62c-docs(安装): 拆分企业版与开源版并加入 SaaS 体验于