urops 工具使用指南
约 1130 字大约 4 分钟
urops运维边缘节点license
2026-09-02
urops 是联犀 SaaS 版（边缘节点/私有化交付）的一站式运维工具： 环境准备、一键部署、许可激活、镜像升级/回退、数据库备份/恢复、云端连通性与 license 检查，以及自身更新。
安装见 安装教程 → SaaS 版本安装；本文覆盖工具本身的完整用法。
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。 如需固定版本：UROPS_TAG=v1.1.11 curl -fsSL ... | sudo bash；如需自定义路径：UROPS_DEST=/opt/urops ...。
自我更新（更新 urops 自身）
urops update --check：检测是否有新版本（对比 Harbor 公开制品源；结果缓存 5 分钟，离线静默）。urops update --yes：自动升级——下载 + sha256 校验 → 备份旧版（/usr/local/bin/urops.bak-<版本>）→ 原子替换 → 重启uropsagent。- 非 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 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. 关键行为说明
升级（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）
- urops 提示「云端不可达 HTTP 522」：云端域名网关拦截；为容器加
HTTPS_PROXY（务必同步NO_PROXY包含etcd,redis,postgres,nats,rustfs,emqx,localhost,127.0.0.1）。 - 升级备份失败 recovery mode：数据库启动/恢复中，v1.1.3+ 自动等待就绪（最多 3 分钟 + 重试 3 次）；
--no-backup可跳过。 - 激活报「授权文件校验失败」：授权码与机器码不匹配，或节点镜像内置公钥过旧——
urops update升级到最新版后重试。 - TUI 被密码圈挡：部署需 root（
sudo urops）。 - 如何出包/发布新版本：
tools/urops/release.sh vX.Y.Z（仓库内）自动构建+推 Harbor public 制品并输出外发链接。
更新日志
2026/9/2 18:23
查看所有更新日志
c1424-docs(use): urops 安装改为 curl | bash 一键脚本于37dfa-docs(use): 安装教程新增 SaaS 版本安装章节 + urops 工具使用指南于
