# Cách sử dụng

> HTML: https://remote.ivjn.us/docs/vi/usage/

Quy trình dành cho người vận hành này bao gồm cài đặt CLI và Agent trên thiết bị, đăng nhập, thêm và kết nối thiết bị, chạy lệnh từ xa và mở shell. Các tài liệu được liên kết ở cuối trang hướng dẫn sử dụng Web Console, Mobile Console, Android Agent, ghép nối và tự cập nhật.

Thay thế địa chỉ ví dụ và mã thông báo bằng địa chỉ của riêng bạn. Mã thông báo chỉ xuất hiện một lần khi được tạo; không bao giờ đặt chúng vào kho lưu trữ.

**Danh tính có tên và quyền tài khoản.** Tùy chọn toàn cục `--profile <name>` được ưu tiên hơn `REMOTE_CLI_PROFILE`. Danh tính có tên lưu `config.toml`, khóa riêng seal, thông tin tin cậy gốc và bộ nhớ đệm quyền trong `<config_base>/remote-cli/profiles/<name>/`; `config_base` vẫn tuân theo quy ước XDG_CONFIG_HOME, HOME/.config hoặc APPDATA trên Windows. Tên gồm 1–64 chữ cái ASCII, chữ số, dấu chấm, gạch nối hoặc gạch dưới, ngoại trừ `.` và `..`. Hồ sơ có tên được ưu tiên hơn `REMOTE_CLI_CONFIG`; khi không chọn hồ sơ, đường dẫn và hành vi của `REMOTE_CLI_CONFIG` giữ nguyên. Đăng nhập riêng cho từng hồ sơ và chọn hồ sơ đó trong các lần gọi tiếp theo.

`operator set` nhận ID tài khoản hoặc tên duy nhất; đối số thiết bị là ID thiết bị. `--restricted` giới hạn khả năng xem ở các thiết bị được cấp quyền rõ ràng; `--unrestricted` khôi phục khả năng xem theo vai trò. Chỉ superadmin được thay đổi phạm vi. Superadmin quản lý vai trò và quyền; khi không có superadmin, quản trị viên được quản lý trong phạm vi cho phép, ngoại trừ chính mình. `operator grant list` chỉ trả về các quyền mà người gọi được xem. Quyền thiết bị trong cơ sở dữ liệu và quyền seal đã ký là hai bước kiểm tra riêng: thay đổi quyền thiết bị không thay thế `seal approve`. Việc tạo tài khoản không hỗ trợ gán phạm vi trong cùng một thao tác nguyên tử; hãy lưu mã thông báo chỉ hiển thị một lần từ `operator add`, sau đó gọi `operator set` / `operator grant set` bằng các yêu cầu riêng.

Mọi lệnh operator đều hỗ trợ `-o text|json|xml`. Yêu cầu JSON dùng `op=list|add|set|grant_list|grant_set|grant_remove`. `set` nhận `operator` và ít nhất một trong hai trường tùy chọn `role` / `restricted`; `grant_set` nhận `operator`, `device` và giá trị boolean bắt buộc `can_manage`. `grant_list` có thể nhận `operator`; `grant_remove` nhận `operator` và `device`. Không kết hợp `--json` với lệnh con.

```bash
remote-cli --profile alice login --server https://exchange.example.com
remote-cli --profile root operator set alice --restricted
remote-cli --profile root operator set alice --role readonly
remote-cli --profile root operator grant list --operator alice -o json
remote-cli --profile root operator grant set alice lab --view
remote-cli --profile root operator grant set alice lab --manage
remote-cli --profile root operator grant remove alice lab
remote-cli --profile root operator set alice --unrestricted
remote-cli --profile root operator --json '{"op":"grant_set","operator":"alice","device":"lab","can_manage":false}' -o json
```

## Yêu cầu và đầu ra XML

Kiểm tra `remote-cli --help` để biết các cờ được phiên bản đã cài đặt hỗ trợ. `--xml` và `--xml-file` thêm đầu vào XML vào các điểm nhập yêu cầu `--json` / `--json-file` hiện có. Bốn đầu vào loại trừ lẫn nhau và cung cấp phần thân hoàn chỉnh: không kết hợp chúng với các tùy chọn lệnh hoặc lệnh phụ giống nhau. Quy tắc vị trí thiết bị không thay đổi. Chọn đầu vào và đầu ra độc lập; `-o text|json|xml` mặc định là văn bản.

```powershell
remote-cli device --xml '<request><op>list</op></request>' -o xml
remote-cli exec my-device --xml-file request.xml -o xml
```

Các nút lá có kiểu mặc định là chuỗi; phần tử có nút con có kiểu mặc định là đối tượng. Dùng `type="number"`, `type="boolean"`, `type="array"` và `type="null"` cho số, giá trị boolean, mảng và null. Mảng phải có các nút con `<item>`; đối tượng rỗng phải chỉ định `type="object"`. Dùng `<field name="arbitrary key">value</field>` cho khóa có tên tùy ý và `<request type="object"/>` cho yêu cầu rỗng.

```xml
<request>
  <command>echo hello</command>
  <timeout_secs type="number">30</timeout_secs>
  <hold type="boolean">false</hold>
  <env><GREETING>hello &amp; welcome</GREETING></env>
</request>
```

Gốc đầu ra là `<response type="...">`, với các thành viên đối tượng `<field name="..." type="...">` và các thành viên mảng `<item type="...">`. Các loại là rõ ràng và văn bản được thoát cho XML 1.0. Lỗi thời gian chạy trả về `ok=false` / `error` với mã thoát khác 0; lỗi cú pháp dòng lệnh vẫn chuyển sang `stderr`.

Đầu ra XML hỗ trợ `device list/update`, `operator list/add/set/grant`, `exec`, `session list/kill`, `ui`, `ubus`, `sensors`, `net`, `metrics`, `preset`, `audit`, `browser`, bao gồm các hoạt động công việc điều hành. Các lệnh khác từ chối rõ ràng `-o xml`; họ vẫn có thể sử dụng các yêu cầu XML với các định dạng đầu ra hiện có của mình.

Truyền trực tuyến `exec` / `sensors --live` / `browser session` phát ra một tài liệu XML hoàn chỉnh trên mỗi dòng; phân tích từng dòng riêng biệt. Các sự kiện dữ liệu thực thi chứa `stream` / `encoding=base64` / `data`; Base64 giữ nguyên các byte gốc và lệnh thực thi đơn giản kết thúc bằng bản ghi trạng thái thoát. Đầu vào tương tác cho `browser session` vẫn là các dòng JSON. `ui xml` không có `-o xml` sẽ giữ lại XML phân cấp giao diện người dùng thô.

Yêu cầu được giới hạn ở 1 MiB và 64 cấp độ lồng nhau. Các trường trùng lặp, văn bản hỗn hợp và con, DTD và các thực thể bên ngoài đều bị từ chối. XML 1.0 không thể biểu thị mọi ký tự điều khiển; chọn JSON khi văn bản đó phải được giữ lại. Cấu hình Agent và giao thức truyền thông vẫn là JSON; XML chỉ chuyển đổi đầu vào và đầu ra CLI.

## Nhận remote-cli và remote-agent

Xây dựng từ kho lưu trữ gốc:

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

CLI là `target/release/remote-cli`. Lệnh tương tự cũng xây dựng `target/release/remote-agent`. Đối với các thiết bị có đèn flash hạn chế, hãy sử dụng Agent được tối ưu hóa kích thước:

```bash
cargo build -p agent --no-default-features --profile release-small
```

Đầu ra là `target/release-small/remote-agent`.

Windows, Linux và macOS cũng có thể cài đặt nhị phân bằng cách sử dụng tập lệnh cài đặt trang web; xem [Triển khai thiết bị đa nền tảng](/docs/vi/platform-installation.md#cài-đặt-một-lệnh-windowslinuxmacosfreebsdnetbsd). Các lệnh bên dưới giả sử `remote-cli` và `remote-agent` nằm trong `PATH`; nếu bạn chỉ xây dựng cục bộ, hãy sử dụng các đường dẫn `target/...` ở trên.

Đối với rơle tự lưu trữ, hãy làm theo [Development](/docs/vi/development.md) để khởi động `exchange` bằng `DATABASE_URL`, sau đó lấy mã thông báo quản trị viên từ nhật ký khởi động của nó. Đối với phiên bản công khai, hãy yêu cầu mã thông báo vận hành từ quản trị viên của phiên bản đó.

## Đăng nhập

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

Sử dụng `http://` hoặc `https://` cho `--server`. CLI lấy địa chỉ WebSocket có cùng mức độ bảo mật: `https` ánh xạ tới `wss` và `http` tới `ws`.

Sau khi đăng nhập thành công, cấu hình được ghi vào:

- Linux / macOS: `$XDG_CONFIG_HOME/remote-cli/config.toml` hoặc `~/.config/remote-cli/config.toml` khi `XDG_CONFIG_HOME` không được đặt.
- Windows: `%APPDATA%\remote-cli\config.toml`.

Tệp chỉ có hai khóa: `server` và `token`. Đặt `REMOTE_CLI_CONFIG` để sử dụng đường dẫn khác. Các lệnh `device`, `exec` và `shell` tiếp theo sẽ đọc cấu hình này, do đó bạn không cần phải cung cấp mã thông báo mỗi lần.

## Thêm thiết bị

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

`<id>` là ID thiết bị: chỉ các chữ cái, chữ số, `-`, `_` và `.`, tối đa 64 ký tự. `--name` là tùy chọn; tên hiển thị mặc định là ID. Mã thông báo thiết bị ở đầu ra chỉ được hiển thị một lần.

## Khởi động Agent

Trên máy cần quản lý, khởi động thiết bị Agent với máy chủ, ID thiết bị và mã thông báo thiết bị mới tạo:

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

Ba đối số này cũng hỗ trợ các biến môi trường: `REMOTE_SERVER`, `REMOTE_DEVICE_ID` và `REMOTE_TOKEN`.

`--server` phải bắt đầu bằng `ws://` hoặc `wss://`. Khi chỉ có một máy chủ được chỉ định (ví dụ: `wss://mgmt.example.com`), Agent sẽ thêm `/ws/device`; một đường dẫn rõ ràng được sử dụng không thay đổi. Đối với exchange cục bộ không có TLS, hãy sử dụng `ws://127.0.0.1:8080`.

Để loại bỏ mã thông báo khỏi các đối số của quy trình, hãy tạo JSON bằng các khóa `server`, `device_id` và `token`:

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

Sau đó chạy `remote-agent --config /path/to/config.json`. Để cài đặt và tự khởi động trên máy tính để bàn, hãy xem [Triển khai thiết bị đa nền tảng](/docs/vi/platform-installation.md).

Cả `remote-cli` và `remote-agent` WebSockets đều đọc cài đặt proxy theo thứ tự `HTTPS_PROXY` / `https_proxy` → `ALL_PROXY` / `all_proxy` → `HTTP_PROXY` / `http_proxy` và vinh danh `NO_PROXY` / `no_proxy`. Agent sử dụng cùng một đường dẫn kết nối ở chế độ không có giao diện và `--ui`. Proxy phải hỗ trợ HTTP CONNECT (SOCKS không được hỗ trợ); WSS chỉ quảng cáo `http/1.1` thông qua ALPN. Đặt các biến trong môi trường dịch vụ cho các dịch vụ nền; xem [Proxy bên ngoài và tính năng duy trì kết nối](/docs/vi/platform-installation.md#proxy-gửi-đi-và-duy-trì-kết-nối).

Sau khi thiết bị kết nối:

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

Danh sách hiển thị trạng thái trực tuyến của nó.

## Chạy lệnh từ xa

Mọi thứ sau `--` được chuyển đến thiết bị mà không cần CLI cục bộ phân tích cú pháp thêm:

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

Số lượng đối số sau `--` xác định cách phía từ xa diễn giải chúng:

- **Nhiều đối số** được chuyển dưới dạng argv, bảo toàn từng ranh giới đối số, như thể được nhập trực tiếp trên thiết bị. CLI bổ sung trích dẫn khi cần thiết (quy tắc PowerShell cho thiết bị Windows).
- **Một đối số** chuyển toàn bộ chuỗi tới vỏ thiết bị dưới dạng dòng lệnh, các đường dẫn hỗ trợ, `;`, ký tự đại diện và biến.

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

Với nhiều đối số, `*` theo nghĩa đen và `$VAR` được shell cục bộ chuyển qua (phổ biến trong PowerShell) vẫn giữ nguyên theo nghĩa đen và không được mở rộng từ xa. Để mở rộng chúng trên thiết bị, hãy sử dụng một đối số duy nhất, chẳng hạn như `-- 'ls /etc/*.conf'`.

exec cho phép giữ theo mặc định: thời gian chờ mặc định là 3600 giây (giới hạn cứng 86400 giây) và toán tử ngắt kết nối sẽ tách đầu ra mà không làm hỏng công việc. Đặt giới hạn thời gian với `--timeout`, ví dụ `remote-cli exec lab-router --timeout 120 -- uname -a`; `--hold-timeout` ghi đè giới hạn giữ. Thêm `--no-hold` để hủy việc ngắt kết nối của nhà điều hành với thời gian chờ mặc định là 60 giây. Khi lệnh trả về bình thường, mã thoát của nó sẽ trở thành mã thoát của `remote-cli`.

### Kiểm tra và dừng công việc cũng như giải phóng các khe phiên

```bash
remote-cli exec-holds lab-router
remote-cli exec-hold-kill lab-router <job_id>
remote-cli exec-hold-tail lab-router <job_id>
remote-cli exec-hold-cat lab-router <job_id>
remote-cli exec-attach lab-router <job_id>
remote-cli sessions lab-router
remote-cli session-kill lab-router <session_id>
```

`exec-holds` liệt kê các công việc thực thi và các lượt tải xuống, tải lên và truy vấn thư mục đang hoạt động, hiển thị `job_id`, `kind`, `status`, `age_secs`, `session_id` phía thiết bị hiện tại (nếu có) và tóm tắt lệnh/đường dẫn bị cắt ngắn. `exec-hold-kill` chấm dứt nhóm quy trình hoặc hủy bỏ quá trình truyền tệp theo ID công việc; tail, cat và attachment chỉ áp dụng cho các công việc thực thi.

`sessions` đọc trực tiếp bảng định tuyến Exchange, hiển thị `count/limit` hiện tại và ID phiên phía thiết bị. `session-kill` sử dụng ID **** phía thiết bị này để gửi yêu cầu hủy tới thiết bị và ngay lập tức giải phóng khe Exchange, ngay cả khi không có phản hồi của thiết bị. Cả hai thao tác đều không mở phiên thiết bị bổ sung hoặc sử dụng khe cắm đồng thời, khiến chúng hữu ích cho các phiên bị kẹt ở mức công suất. Tài khoản chỉ đọc không thể sử dụng chúng.

Thời gian chờ thực thi sẽ chấm dứt toàn bộ nhóm quy trình; việc thoát đầu ra và gửi thông báo hoàn thành đều có giới hạn thời gian. Ở giới hạn đồng thời, Exchange trước tiên lấy lại các tuyến đã mất nhà điều hành hoặc vượt quá thời hạn, sau đó thử phiên mới. Thời hạn thực thi là giới hạn thực thi thực tế cộng với 15 giây ân hạn; truyền tập tin cho phép 3600 giây cộng thêm 15 giây (thiết bị cũng có thời gian chờ 30 giây không hoạt động); các phiên khác cho phép 24 giờ. Trước thời hạn của nó, người thực thi lệnh giữ không bị hủy chỉ vì người vận hành ngắt kết nối; ngắt kết nối vẫn chỉ tách ra. `session-kill` rõ ràng hoặc vượt quá thời hạn sẽ hủy quá trình được giữ.

## Mở một cái vỏ

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

Đây là phiên PTY trên thiết bị chứ không phải SSH. Thoát khỏi shell kết thúc phiên.

## Các điểm vào khác

- Bảng điều khiển trình duyệt: [Bảng điều khiển web](/docs/vi/web-console-and-notifications.md)
- Bảng điều khiển di động: [Mobile client](/docs/vi/platform-installation.md)
- APK thiết bị Android: [Độc lập Android APK](/docs/vi/platform-installation.md#apk-độc-lập-android)
- Mã QR, mã sáu chữ số và tài khoản: [Khởi tạo và ghép nối](/docs/vi/pairing-and-enrollment.md)
- Tự cập nhật CLI và Agent: [Self-update](/docs/vi/self-update.md)

## Mã hóa đầu cuối (phiên kín)

`remote-cli exec <设备> -- <命令>` và `remote-cli shell <设备>` sử dụng các phiên kín từ đầu đến cuối theo mặc định mà không có cờ bổ sung. Exchange chỉ chuyển tiếp văn bản mã hóa và không thể xem lệnh, đầu ra hoặc nội dung đầu cuối. Các thiết bị chỉ tin tưởng vào thư mục gốc của không gian làm việc (khóa của quản trị viên cấp cao, được tạo tự động khi quản trị viên cấp cao đăng nhập) và các cấp có chữ ký của root đó. Máy khách gốc tự động cấp các khoản trợ cấp cho các thành viên theo vai trò tài khoản của họ. Xem thiết lập một lần trong [Ephiên kín từ đầu đến cuối](/docs/vi/sealed-sessions.md).

Tất cả các phiên thiết bị CLI chỉ sử dụng tính năng niêm phong từ đầu đến cuối mà không có cờ bổ sung. Thiếu thông tin về khả năng của thiết bị hoặc bắt tay kín không thành công không bao giờ gây ra sự chuyển đổi sang văn bản gốc. Kết nối mạng LAN trực tiếp và hoạt động của trình duyệt thực thi các yêu cầu niêm phong giống nhau.

## Nhiệm vụ nền bền vững

Đại lý quảng cáo `tasks` thực hiện các thao tác đơn lẻ hoặc DAG khai báo trên thiết bị. Công việc đã gửi vẫn tiếp tục sau khi Console ngắt kết nối. Kết nối lại để đọc tiến trình, đầu ra và các tạo phẩm cục bộ. Thời gian chạy khởi động lại đánh dấu công việc chưa hoàn thành `interrupted`; nó không bao giờ được phát lại tự động.

Việc tạo yêu cầu cấp `manage/owner` được niêm phong. Chọn các phần phụ thuộc, điều kiện cố định, tham chiếu Con trỏ JSON tổ tiên, chính sách lỗi và tối đa năm lần thử lại rõ ràng. Việc thử lại có thể lặp lại tác dụng phụ; việc hủy bỏ không đẩy chúng trở lại. Bảng điều khiển trên web và thiết bị di động cung cấp biểu mẫu và nhập/xuất JSON. Các giao diện máy tính để bàn, Android, trình duyệt và LuCI cục bộ cung cấp lịch sử, đầu ra, hủy và xóa.

Bắt đầu với danh mục hoạt động: hỗ trợ và loại trừ khác nhau tùy theo nền tảng. Giai đoạn tập tin trước khi tạo. Giới hạn mặc định là 30 ngày, 1000 tác vụ, tổng cộng 64 MiB, 8 văn bản MiB cho mỗi tác vụ, bốn bước song song (hai bước trên OpenWrt) và thời gian chờ bước 30 phút có thể định cấu hình lên đến 24 giờ. Đại lý cũ không hiển thị mục nhập nhiệm vụ.
```sh
remote-cli task DEVICE operations
remote-cli task DEVICE create pipeline.json --wait
remote-cli task DEVICE list
remote-cli task DEVICE get TASK_ID
remote-cli task DEVICE logs TASK_ID --offset 0
remote-cli task DEVICE cancel TASK_ID
remote-cli task DEVICE upload ./input.bin
remote-cli task DEVICE download TASK_ID STEP.artifact ./result.json
remote-cli task DEVICE delete TASK_ID
```

## Dịch vụ được giám sát

Chế độ Service của Task giám sát lệnh gốc chạy tiền cảnh, lưu trạng thái mong muốn, hỗ trợ chính sách khởi động lại, thời gian chờ tăng theo cấp số nhân, giới hạn tần suất và khôi phục sau khi Agent khởi động lại. Mặc định lưu ở trạng thái dừng; hãy dừng và chờ trước khi sửa hoặc xóa. Quyền hết hạn hoặc bị thu hồi sẽ dừng dịch vụ. DAG thông thường không chạy lại. Quản lý qua Web, di động, máy tính và Android; cấu hình LuCI qua Console hoặc CLI. Browser Agent không giám sát tiến trình hệ thống.

Dùng command.command hoặc command.argv cùng cwd/env, restart (never/on_failure/always), start_secs, stop_grace_secs, backoff_secs, max_backoff_secs, restart_window_secs và max_starts. Dừng có trật tự trên Windows cần stop_command; Unix dùng SIGTERM rồi buộc dừng cây tiến trình khi hết thời gian chờ. Cấu hình Agent tự chạy khi khởi động máy riêng. service get trả về run_id để dùng với task get/logs.

```sh
remote-cli task DEVICE service put worker.json
remote-cli task DEVICE service list
remote-cli task DEVICE service start worker
remote-cli task DEVICE service get worker
remote-cli task DEVICE service restart worker
remote-cli task DEVICE service stop worker
remote-cli task DEVICE service delete worker
remote-agent task service put worker.json
```