# 使用说明

这条路径面向操作员：拿到命令行和设备端，登录，添加一台设备，让设备连上，然后执行一条远程命令并打开 shell。浏览器控制台、手机控制台、Android 设备端、配对和自更新见文末链接，这里不重复那些页面的步骤。

示例里的地址和令牌请换成你自己的。令牌只在创建时出现一次，不要把它写进仓库。

## 拿到 remote-cli 和 remote-agent

在仓库根目录构建：

```bash
cargo build --release
```

命令行是 `target/release/remote-cli`。同一命令也会编出 `target/release/remote-agent`。给 flash 紧张的设备用体积优先的 agent：

```bash
cargo build -p agent --profile release-small
```

产物是 `target/release-small/remote-agent`。

Windows、Linux、macOS 也可以用网站上的安装脚本一次装好其中一个二进制，说明在 [多平台设备部署](platforms.md#一条命令安装windows--linux--macos)。下面的命令假定 `remote-cli` 和 `remote-agent` 已经在 `PATH` 里；若刚在本机编出来，改用上面的 `target/...` 路径。

自建中转服务时，先按 [开发说明](development.md) 用 `DATABASE_URL` 启动 `exchange`，从启动日志拿到管理员令牌。使用公共实例时，向管理员要运维令牌即可。

## 登录

```bash
remote-cli login --server http://127.0.0.1:8080 --token '<运维令牌>'
```

`--server` 填 `http://` 或 `https://`。命令行会按同样的安全级别推导 WebSocket 地址：`https` 对应 `wss`，`http` 对应 `ws`。

登录成功后，配置写在：

- Linux / macOS：`$XDG_CONFIG_HOME/remote-cli/config.toml`，未设置 `XDG_CONFIG_HOME` 时为 `~/.config/remote-cli/config.toml`
- Windows：`%APPDATA%\remote-cli\config.toml`

文件里只有两个键：`server` 和 `token`。要用别的路径时设置 `LUCI_CLI_CONFIG`。之后的 `device`、`exec`、`shell` 都读这份配置，不必每次再传令牌。

## 添加设备

```bash
remote-cli device add lab-router --name "实验室路由"
```

`<id>` 是设备 ID，只能含字母、数字和 `-` `_` `.`，最长 64 个字符。`--name` 可省略，省略时显示名与 ID 相同。命令输出里的设备令牌只显示这一次。

## 启动 agent

在要被管理的机器上启动设备端，并带上服务端、设备 ID 和刚才的设备令牌：

```bash
remote-agent --server wss://127.0.0.1:8080 --device-id lab-router --token '<设备令牌>'
```

三个参数也可以用环境变量：`LUCI_SERVER`、`LUCI_DEVICE_ID`、`LUCI_TOKEN`。

`--server` 必须以 `ws://` 或 `wss://` 开头。只写主机（例如 `wss://mgmt.example.com`）时，agent 会自动补上 `/ws/device`；已经写了路径则原样使用。本地 exchange 若没有 TLS，用 `ws://127.0.0.1:8080`。

不想把令牌放在进程参数里时，写一份 JSON，键名为 `server`、`device_id`、`token`：

```json
{
  "server": "wss://mgmt.example.com",
  "device_id": "lab-router",
  "token": "<设备令牌>"
}
```

然后 `remote-agent --config /path/to/config.json`。桌面系统的安装与自启动见 [多平台设备部署](platforms.md)。

`remote-cli` 与 `remote-agent` 的 WebSocket 都按 `HTTPS_PROXY` / `https_proxy` → `ALL_PROXY` / `all_proxy` → `HTTP_PROXY` / `http_proxy` 读取代理，并遵守 `NO_PROXY` / `no_proxy`；agent 无界面和 `--ui` 模式使用同一连接路径。代理须支持 HTTP CONNECT（不支持 SOCKS），WSS 的 ALPN 仅声明 `http/1.1`。后台服务请在服务环境中设置变量，详见 [出站代理与连接保活](platforms.md#出站代理与连接保活)。

设备连上之后：

```bash
remote-cli device list
```

列表里能看到这台设备的在线状态。

## 执行远程命令

`--` 后面的内容交给设备，不再由本机命令行解析：

```bash
remote-cli exec lab-router -- uname -a
```

`--` 后面给几个参数，决定了远端怎么理解它们：

- **多个参数**按 argv 原样传过去，每个参数的边界都保留，和在设备上直接敲这几个参数效果一样。需要时 CLI 会自动加引号（Windows 设备按 PowerShell 规则）。
- **只有一个参数**时，整串交给设备的 shell 当命令行解析，可以用管道、`;`、通配符和变量。

```bash
remote-cli exec lab-router -- sh -c 'uname -a; cat /proc/uptime'   # 多个参数，第三个参数完整交给 sh -c
remote-cli exec lab-router -- 'dmesg | tail -20'                    # 一个参数，管道在设备上执行
```

注意：多参数形式下，本地 shell 原样传过来的 `*`、`$VAR`（在 PowerShell 里很常见）会被当作字面量，不会在远端展开。想让设备来展开，就写成单个参数，例如 `-- 'ls /etc/*.conf'`。

exec 默认开启 hold：超时默认 3600 秒（硬上限 86400 秒），运维端断开只分离输出，不杀作业。用 `--timeout` 指定时限，例如 `remote-cli exec lab-router --timeout 120 -- uname -a`；`--hold-timeout` 可覆盖 hold 时限。加 `--no-hold` 恢复运维端断开即取消的行为，默认超时 60 秒。命令正常返回时，其退出码会成为 `remote-cli` 的退出码。

## 打开 shell

```bash
remote-cli shell lab-router
```

这是设备上的一个 PTY 会话，不是 SSH。退出 shell 即结束这次会话。

## 其它入口

- 浏览器控制台：[Web 控制台](web-console.md)
- 手机控制台：[移动客户端](../mobile/README.md)
- Android 设备端 APK：[Android 独立 APK](platforms.md#android-独立-apk)
- 二维码、六位码和账号：[初始化与配对](pairing.md)
- 命令行与 agent 的自更新：[自更新](self-update.md)