联犀开发者文档

urops 工具使用指南

约 2674 字大约 9 分钟

urops运维边缘节点license

2026-09-02

urops 是联犀私有部署与边缘节点的一站式运维工具： 环境准备、一键部署、许可激活、镜像升级/回退、数据库备份/恢复、云端连通性与 license 检查，以及自身更新。

安装见基础版私有部署教程；云端 SaaS 无需安装 urops，可直接演示体验或注册使用。基础版软件永久免费，行业应用与人工服务另行选择，详见官网合作与报价。

1. 安装与更新

安装（免登录一键，自动取 Harbor 最新版 + sha256 校验）

curl -fsSL https://doc.unitedrhino.com/urops/install.sh | sudo bash

脚本逻辑：查询 Harbor public 制品最新版本（vX.Y.Z）→ 匿名 token → 下载二进制与校验和 → sha256sum 校验 → 安装到 /usr/local/bin/urops → 重启 urops agent。 固定版本或自定义路径时，应将环境变量传给执行安装脚本的进程，而非只传给 curl。例如以下固定版本示例（先确认该版本可用）：

curl -fsSL https://doc.unitedrhino.com/urops/install.sh | sudo env UROPS_TAG=v1.1.11 bash

自定义安装路径同理，在 sudo env 后设置 UROPS_DEST=/opt/urops。

Windows 安装（免登录一键，自动取 Harbor 最新版）

Windows 版 urops 仅支持远程运维：只提供 tailscale 组网的远程运维能力（安装/连接/断开/状态/修复/诊断、边缘节点设备列表），不支持在 Windows 本机部署服务（部署/升级/备份等命令为 Linux 专用）。需要部署或升级边缘服务时，请在目标 Linux 服务器上安装 Linux 版 urops；Windows 版适合作为组网后的远程运维入口。

在 PowerShell（5.1+，Windows 10/11 自带，无需管理员）中执行：

irm https://doc.unitedrhino.com/urops/install.ps1 | iex

脚本逻辑：查询 Harbor public 制品最新版本（vX.Y.Z）→ 匿名 token → 下载二进制与校验和 → sha256 校验 → 安装到 %LOCALAPPDATA%\Programs\urops → 加入用户 PATH（新开的终端即可直接运行 urops）→ 打印版本。已安装时同样适用：自动检测当前版本，升级时打印「旧版 → 新版」（幂等）。 如需固定版本：$env:UROPS_TAG="v1.1.43"; irm https://doc.unitedrhino.com/urops/install.ps1 | iex；如需自定义路径：$env:UROPS_DEST="D:\tools\urops"; irm https://doc.unitedrhino.com/urops/install.ps1 | iex。

安装后运行 urops 打开 TUI：在「远程运维」中安装并连接 tailscale 后，即可远程运维已组网的边缘 Linux 服务器。

自我更新（更新 urops 自身）

  • urops update --check：检测是否有新版本（对比 Harbor 公开制品源；结果缓存 5 分钟，离线静默）。
  • urops update --yes：自动升级——下载 + sha256 校验 → 备份旧版（/usr/local/bin/urops.bak-<版本>）→ 原子替换 → 重启 urops agent。
  • 非 root 运行时会提示 sudo urops update --yes。
  • TUI 每次进入自动在后台检查新版本，发现新版在界面底部提示「⚠ 发现新版本 vX.Y.Z」。

2. 命令总览

命令说明
urops进入交互式 TUI 菜单（部署/运维/许可/升级…）
urops install all环境准备（docker/compose/ssh 等，幂等）
urops up --type <type>一键部署（energy/edge/allinone/fuzai，--oss-type rustfs 等选项）
urops status容器状态 + 云端连通性 + License + 版本 + 访问地址（一屏总览，--json 结构化）
urops license status查看 license 状态/机器码（申请授权用）
urops license activate <授权码或Bundle>激活（自动识别授权码/SignedBundle）
urops upgrade升级到最新镜像（备份→拉镜像→重建→健康等待，四阶段进度）
urops rollback回退上一版本镜像（数据不动）
urops backup / urops restore手动备份/恢复数据库（升级前自动备份，保留 10 份）
urops doctor环境自检（docker/ssh/tailscale/headscale 配置）
urops tailscale up/status内网组网（headscale）管理与状态
urops edge-list查看云端已接入的边缘节点
`urops update [--check--yes]`
urops lang [zh|en|auto]查看/切换界面语言（默认 auto）
urops version版本与编译时间

3. 配置

urops 配置目录：root 为 /root/.urops/，普通用户为 ~/.urops/。

  • config.json：saasBaseURL（云端地址，默认 https://saas.unitedrhino.com）、registryURL/User/Pass（镜像仓库，默认 docker.unitedrhino.com）、headscale（serverURL/authKey）。
  • deploy/：部署产物（docker-compose.yml、conf/、state.json 部署状态、backups/ 备份、operations.log 操作日志）。
  • update-cache.json：更新检查缓存（5 分钟 TTL，自动维护）。

4. 关键行为说明

界面语言（v1.1.18+）

  • 默认中文；切换方式：
    • CLI：urops lang en（英文）/ urops lang zh（中文）/ urops lang auto（自动，默认）；
    • TUI：运维菜单 →「语言：中文 / English / 自动」，选中立即生效；
    • urops lang（不带参数）显示当前语言与生效原因。
  • auto 自动检测：TERM=linux（字符控制台，内核字体无法显示中文）或 LC_ALL/LC_CTYPE/LANG 全部非 UTF-8（C/POSIX/GBK 等）时自动切换英文；SSH 终端 + UTF-8 保持中文。
  • 手动设置（zh/en）写入 config.json 的 language 字段，优先级高于自动检测。
  • 配置目录在 root 与普通用户下独立（见第 3 节），sudo 提升后以 root 配置为准。
  • 当前版本覆盖：菜单/执行页/状态/许可/升级检查等高频输出；命令帮助（--help）与部分内部错误详情暂为中文，后续迭代。

升级（urops upgrade）

阶段化输出（TUI 可见）：① 备份数据库（等待数据库就绪，恢复中自动等待/重试）→ ② 拉取镜像 → ③ 重建应用服务（增量模式：只重建应用服务，数据容器不动）→ ④ 等待服务健康。升级后新版本菜单/前端自动生效。

License

  • 边缘侧本地验签（编译内置 Ed25519 公钥）+ 有效期 + 机器码（SHA256）校验，离线可用；到期进入受限模式。
  • 永久授权约定 expireAt=-1，前端展示「永久」；expireAt 以毫秒时间戳字符串输出（json:",string"）。
  • 授权码单机绑定：已绑定其他设备会拒绝；换绑需在云端重新签发。

云端连通性

  • urops status 展示「云端连通性」（与 edge 容器同代理口径：复用运行容器 HTTPS_PROXY/NO_PROXY）。
  • 容器可连云而 urops 报 522：检查宿主机到云端链路或为 urops 复用的代理配置（v1.1.1+ 自动读取容器代理）。
  • CLOUD_ADDR（compose 应用服务）为节点连云地址，saasBaseURL（urops 配置）为 agent 心跳/探测目标。

5. 常见问题（FAQ）

  1. urops 提示「云端不可达 HTTP 522」：云端域名网关拦截；为容器加 HTTPS_PROXY（务必同步 NO_PROXY 包含 etcd,redis,postgres,nats,rustfs,emqx,localhost,127.0.0.1）。
  2. 升级备份失败 recovery mode：数据库启动/恢复中，v1.1.3+ 自动等待就绪（最多 3 分钟 + 重试 3 次）；--no-backup 可跳过。
  3. 激活报「授权文件校验失败」：授权码与机器码不匹配，或节点镜像内置公钥过旧——urops update 升级到最新版后重试。
  4. TUI 被密码圈挡：部署需 root（sudo urops）。
  5. 控制台/VNC 乱码：内核 VGA 字符控制台（TERM=linux）或非 UTF-8 locale 下，urops 自动切换英文界面（v1.1.18+）；仍想显示中文可安装 fonts-unifont/kmscon 后调整 locale 为 UTF-8。也可手动 urops lang en/zh 强制。
  6. 部署卡在「启动容器（docker compose up）」后超时：多为依赖镜像拉取失败（postgres/redis 等大层镜像在慢网络或 Harbor 大 blob 限速约 50KB/s 时十几分钟拉不完）。排查：docker images 看依赖镜像是否齐全；手动 cd ~/.urops/deploy && docker compose up -d 看拉取报错（v1.1.24+ TUI 会打印 compose 返回错误）。处理：a) 配置可用的镜像加速器（/etc/docker/daemon.json 的 registry-mirrors，注意数组格式，两个源分两个元素），b) 预拉小镜像依赖后部署，c) 生产网络不允许时联系联犀获取镜像包。
  7. 如何出包/发布新版本：tools/urops/release.sh vX.Y.Z（仓库内）自动构建+推 Harbor public 制品并输出外发链接；每个版本需在 tools/urops/CHANGELOG.md 登记条目或使用 --note，二者都没有发布会直接失败。

6. 慢网络部署加速（Harbor 大 blob 限速场景）

现象：Harbor 上单层 ≥1GB 的镜像（timescaledb-ha 2.05GB / postgres-walg 1.51GB 等）下载仅 ~50-90KB/s，部署必超时；多层小层镜像（allinone 最大层 187MB 约 700KB/s、nats 等小镜像秒下）正常。慢的是超大单 blob，不是 Harbor 整体。

推荐路径（TUI 操作为主）

① 环境准备：运行 sudo urops 打开 TUI →「环境准备 → 安装全部」。装好 ssh/docker/compose 的同时，v1.1.25+ 会自动校验并修复 docker 镜像加速器（registry-mirrors）。加速器只作用于 docker.io 官方镜像，Harbor 私有镜像不受影响。

② 发起部署：TUI「部署 → 能源中心 energy（或 基础版 edge / 芙崽 fuzai）→ 按需选择 基础部署 / 带AI / 带音视频 / 自定义…」，选中即开始；依赖安装 → 拉镜像 → 启动容器 → 健康等待各阶段进度都在 TUI 里可见。v1.1.26+ 部署超时改为活动检测：compose 持续有输出就一直等待，不再有固定总时长。

③ 仍卡在数据库镜像时，换小层镜像：默认数据库镜像（不带 AI 为 saas/timescaledb-ha、带 AI 为 postgres-walg）都是 GB 级大层，慢网络下必卡。Harbor 已有切好小层的等价镜像（层小、不受大 blob 限速影响，已实测存在）：

镜像 tag适用
docker.unitedrhino.com/unitedrhino/postgressql:pg16-timescale-postgis基础版（PostGIS + TimescaleDB）
docker.unitedrhino.com/unitedrhino/postgressql:pg16-timescale-postgis-vectorAI 版（另含 pgvector 向量/图库）

当前 TUI 暂无选择数据库镜像的入口，用下面一条命令，等价于 TUI「基础部署」+ 指定小镜像（其余流程与 TUI 部署完全一致）：

sudo urops up --type energy --postgres-image docker.unitedrhino.com/unitedrhino/postgressql:pg16-timescale-postgis

另一个省时间的做法：部署前先把依赖镜像 docker pull 好，compose 阶段就不再拉取。

进阶参考：自建等价小镜像

无法访问 Harbor 时，可本地自建（postgres:16 + PostGIS + TimescaleDB，全程走 docker.io 加速器）：

# 保存为 Dockerfile 后执行：docker build -t pgfull:latest .
# 部署时指定：sudo urops up --type energy --postgres-image pgfull:latest
FROM postgis/postgis:16-3.5   # 官方镜像（PG 16.9 + PostGIS，走镜像加速器 1-2 分钟可拉）
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl gnupg ca-certificates \
 && curl -fsSL https://packagecloud.io/timescale/timescaledb/gpgkey | gpg --dearmor -o /usr/share/keyrings/timescaledb.gpg \
 && echo "deb [signed-by=/usr/share/keyrings/timescaledb.gpg] https://packagecloud.io/timescale/timescaledb/debian/ $(grep VERSION_CODENAME /etc/os-release | cut -d= -f2) main" > /etc/apt/sources.list.d/timescaledb.list \
 && apt-get update \
 && cd /tmp && apt-get download timescaledb-2-loader-postgresql-16 timescaledb-2-postgresql-16 \
 && for f in timescaledb-2-*.deb; do dpkg -x "$f" /; done \
 && rm -f /tmp/timescaledb-2-*.deb && rm -rf /var/lib/apt/lists/* && apt-get clean
CMD ["postgres", "-c", "shared_preload_libraries=timescaledb"]
  • timescaledb 使用 dpkg -x 解包（不执行 postinst，避免其 myspell 字典构建在容器内卡死）；shared_preload_libraries=timescaledb 必须配置，否则 CREATE EXTENSION timescaledb 报错。
  • 应用侧 tsDBType=pgsql 时 timescale 缺失可降级（HasTimescale 为假则跳过 hypertable），但 PostGIS 是硬依赖（geometry 列），标准 postgres 镜像不可用。

更新日志

2026/9/30 05:44
查看所有更新日志
  • 54945-docs(文档站): 统一官网入口并完善 AI 辅助接入说明于
  • f45d6-docs(urops): 慢网络部署说明改为 TUI 主流程于
  • 9b1fc-docs(urops): 上线 Windows 安装方案（install.ps1 + 指南新增「Windows 安装」小节）于
  • 12a1a-docs(use): 补充 Harbor 小镜像 tag（pg16-timescale-postgis[-vector]）于
  • 99fc0-docs(use): urops 指南补慢网络部署加速（Harbor 大 blob 限速）与压缩镜像构建法于
  • eb14e-docs(use): urops FAQ 补部署卡镜像拉取排查条目于
  • 66140-docs(use): urops 界面多语言说明与乱码 FAQ于
  • c1424-docs(use): urops 安装改为 curl | bash 一键脚本于
  • 37dfa-docs(use): 安装教程新增 SaaS 版本安装章节 + urops 工具使用指南于