Khởi tạo, Mã QR thiết bị và Đăng nhập mã sáu chữ số

Agent mặc định là Exchange tại wss://exchange.ivjn.us; API quản lý CLI/Console sử dụng https://exchange.ivjn.us. Cấu hình hiện tại được ưu tiên nên các địa chỉ Exchange tự lưu trữ sẽ được giữ nguyên.

Đăng ký SaaS và đăng nhập lần đầu

remote-cli register --username alice --email alice@example.com
# 按隐藏输入提示设置密码，注册后向邮箱发送验证码。
remote-cli verify-email --username alice
# 隐藏输入邮件中的 8 位数字验证码，然后登录。
remote-cli login --email alice@example.com
# init 是 login 的别名，不带 --email 时交互输入邮箱和密码。
remote-cli init
# 原有令牌仍可使用：
remote-cli login --server https://exchange.ivjn.us --token-stdin

Đăng ký và đăng nhập kết nối với https://exchange.ivjn.us theo mặc định; thêm --server cho dịch vụ tự lưu trữ. Đăng nhập sử dụng địa chỉ email làm nhận dạng tài khoản. Dấu cách bị xóa và địa chỉ được chuyển thành chữ thường; định dạng không hợp lệ sẽ bị từ chối ngay lập tức. Tên người dùng là tên không gian làm việc được chọn trong quá trình đăng ký (3–64 chữ cái, chữ số hoặc ._-). Mật khẩu tài khoản không có giới hạn về độ dài hoặc định dạng ký tự; máy chủ chỉ lưu trữ các hàm băm mật khẩu. Tự động hóa có thể sử dụng --password-stdin; không đặt mật khẩu vào đối số lệnh. Tài khoản mới không thể đăng nhập cho đến khi địa chỉ email của họ được xác minh. CLI chỉ lưu trữ mã thông báo phiên được trả về, không bao giờ lưu trữ mật khẩu và duy trì thông tin đăng nhập hiện có trong khi chờ đăng ký xác minh.

Mỗi lần đăng ký sẽ tạo một không gian làm việc riêng, với tài khoản đăng ký là quản trị viên. Các thiết bị, thành viên, phiên từ xa, số liệu và hồ sơ kiểm tra đều bị cô lập; các không gian làm việc khác nhau có thể sử dụng cùng một ID thiết bị. Việc phê duyệt mã gồm sáu chữ số sẽ thêm thiết bị hoặc thành viên mới vào không gian làm việc của người phê duyệt. Để tham gia không gian làm việc hiện có, hãy sử dụng mã thông báo hoặc ủy quyền gồm sáu chữ số do quản trị viên cung cấp.

Android Console cũng hỗ trợ đăng ký, đăng nhập bằng mật khẩu, đăng nhập bằng mã thông báo hiện có và đăng nhập bằng mã sáu chữ số. Mật khẩu chỉ được sử dụng cho yêu cầu hiện tại; thông tin đăng nhập được lưu trữ trong SecureStore.

Phiên đăng nhập mật khẩu kéo dài 30 ngày, với tối đa 32 phiên hoạt động cho mỗi tài khoản; đăng nhập lại không đuổi các khách hàng khác. POST /api/auth/logout thu hồi mã thông báo phiên Bearer hiện tại và WebSockets đã thiết lập sẽ đóng trong vòng tối đa 5 giây. Đăng nhập lại sau khi hết hạn. Mã thông báo thiết bị và mã thông báo hoạt động hiện tại vẫn giữ nguyên thời gian tồn tại ban đầu của chúng.

Danh tính chỉ có mã thông báo không có tài khoản mật khẩu và không thể khôi phục quyền truy cập qua email. Việc thanh toán và định tuyến WebSocket đa phiên bản hiện nằm ngoài phạm vi triển khai này.

Xác minh email và khôi phục mật khẩu

remote-cli resend-verification --email alice@example.com
remote-cli verify-email --username alice
remote-cli forgot-password --email alice@example.com
remote-cli reset-password --email alice@example.com
# 按提示输入邮件验证码、新密码，再重新登录。

# 已登录的旧密码账号绑定或更换邮箱，需要再次验证当前密码。
remote-cli set-email --email alice@example.com
remote-cli verify-email --username alice

Việc xác minh và khôi phục sử dụng mã tám chữ số riêng biệt, dành riêng cho mục đích cụ thể. Mã hết hạn sau 15 phút hoặc năm lần thử sai liên tiếp; gửi email mới sẽ làm mất hiệu lực mã trước đó. Mỗi tài khoản có thể yêu cầu một email cho mỗi mục đích mỗi phút. Các lệnh xác minh và đặt lại chấp nhận --code để tự động hóa; theo mặc định, mục nhập mã bị ẩn. Việc đặt lại thành công sẽ thu hồi mọi phiên đăng nhập cho tài khoản đó, đồng thời các WebSockets đã thiết lập sẽ bị ngắt kết nối trong vòng tối đa 5 giây. Các thành viên và thiết bị không gian làm việc khác không bị ảnh hưởng.

Nhập địa chỉ email trên trang đăng ký Console, sau đó tiếp tục xác minh. Trang đăng nhập cung cấp các hành động Xác minh email và Quên mật khẩu. Khi thay đổi địa chỉ email, địa chỉ cũ vẫn hoạt động cho đến khi quá trình xác minh hoàn tất. Gửi lại yêu cầu xác minh và khôi phục sẽ trả về cùng một thông báo chung bất kể email đó có được đăng ký hay không.

Email yêu cầu di chuyển cấu hình 0004_email.sql và SMTP: SMTP_HOST, SMTP_PORT, SMTP_FROM, SMTP_USERNAME, SMTP_PASSWORD và SMTP_SECURITY. STARTTLS là mặc định; TLS ngầm cũng được hỗ trợ. SMTP không được mã hóa chỉ được phép trên các địa chỉ loopback để kiểm tra cục bộ. Giữ thông tin xác thực SMTP trong tệp môi trường dịch vụ và ngoài Git. Nếu không có cấu hình email, điểm cuối đăng ký và gửi email mới sẽ trả về 503; đăng nhập tài khoản hiện tại vẫn có sẵn. Định cấu hình gửi email trước khi cho phép đăng ký sản xuất. Lỗi SMTP tạm thời có thể khiến tài khoản đang chờ xác minh; khi dịch vụ phục hồi, hãy gửi lại email xác minh thay vì đăng ký lại.

API tài khoản Exchange

Đăng nhập thành công sẽ trả về username, email (nếu bị ràng buộc), tenant_id, token và expires_in, cùng với Cache-Control: no-store. Mật khẩu tài khoản được thêm salt rồi lưu trữ bằng Argon2id với thông số mặc định. Yêu cầu tài khoản được giới hạn ở mức 20 yêu cầu mỗi phút cho mỗi IP nguồn TCP và 10 yêu cầu mỗi phút cho mỗi tên người dùng, với tối đa bốn lần băm mật khẩu đồng thời. IP chuyển tiếp do khách hàng cung cấp không đáng tin cậy. Khách hàng sử dụng proxy ngược chia sẻ hạn ngạch IP của nó; triển khai công khai nên đặt cấu hình giới hạn tốc độ bổ sung ở mức xâm nhập đáng tin cậy.

Rust Exchange tắt đăng ký công khai theo mặc định. Kích hoạt nó một cách rõ ràng với EXCHANGE_ALLOW_REGISTRATION=true và định cấu hình SMTP; false vô hiệu hóa đăng ký mới trong khi tài khoản hiện tại vẫn có thể đăng nhập.

Hiển thị mã sáu chữ số trên Agent

Android Remote Agent có địa chỉ mặc định được điền sẵn. Nhấn vào Kết nối với mã gồm sáu chữ số để hiển thị mã hợp lệ trong 5 phút. Trên CLI quản trị viên đã đăng nhập, hãy chạy:

remote-cli pair 012345
# 可选：覆盖默认 ID 和显示名称
remote-cli pair 012345 --device-id my-android --name "我的手机"

Khi truy xuất mã kết nối, CLI hiển thị tên thiết bị, loại nhận dạng và ID thiết bị được đề xuất. Hãy xác minh rằng đó là thiết bị của bạn trước khi phê duyệt. ID mặc định sử dụng các chữ cái, chữ số ASCII viết thường và ._- khỏi tên thiết bị, loại bỏ dấu cách và các ký tự khác. Nó quay trở lại device khi không còn ký tự nào có thể sử dụng được và bị giới hạn ở 64 ký tự. Nếu ID được lấy trong cùng một không gian làm việc, một số sẽ được thêm vào, chẳng hạn như realmev5, realmev51 và realmev52; ID cơ sở được rút ngắn khi cần thiết. Exchange xử lý các xung đột đồng thời trong quá trình tạo và CLI in ID được phân bổ cuối cùng. ID được chỉ định thủ công cũng nhận được hậu tố số khi xảy ra xung đột. Android sử dụng tên thiết bị hệ thống, quay lại kiểu máy; Đại lý gốc sử dụng tên máy chủ. Agent tự động nhận mã thông báo thiết bị riêng, lưu trữ mã hóa và kết nối. Khả năng truy cập và điều khiển màn hình không được bật tự động. Việc hủy, hết hạn hoặc xác thực không thành công sẽ bảo toàn cấu hình hiện có; dừng Agent đang kết nối trước khi ghép nối.

Thêm máy tính, bộ định tuyến và đại lý Linux

Đại lý Windows, macOS, OpenWrt và Linux có thể sử dụng một trong hai phương thức mà không cần nhập mã thông báo thiết bị theo cách thủ công:

Method 1: Agent yêu cầu mã gồm sáu chữ số có giá trị trong 5 phút và hiển thị mã QR chứa remote://pair?code=012345&server=wss%3A%2F%2Fexchange.ivjn.us (không có thông tin xác thực). Quản trị viên có thể chọn bất kỳ tùy chọn nào sau đây: Android Console Thêm thiết bị → Nhập mã ghép nối → Quét mã QR thiết bị (quét bằng camera, xác minh máy chủ trùng khớp, sau đó tra cứu và phê duyệt yêu cầu); nhập trực tiếp mã sáu chữ số; sử dụng Web Console Phê duyệt mã ghép nối để nhập mã hoặc dán remote://pair?...; hoặc chạy remote-cli pair 012345 (cũng chấp nhận URI đó). Sau khi được phê duyệt, Agent sẽ lưu mã thông báo và tự động kết nối.

Method 2: Trong Android Console, quản trị viên chọn Thêm thiết bị → Thêm bằng cách quét để tạo lời mời một lần, sau đó chạm vào Sao chép lời mời (dán trên máy tính / bộ định tuyến); cách khác, hãy chạy remote-cli qr --device-id pc-01 --text. Lời mời là JSON được nhúng trong mã QR ({"type":"remote-enrollment",...}), có giá trị trong 5 phút và có thể sử dụng được một lần. Nội dung của mã QR mã thông báo thiết bị (remote-cli device qr) cũng được chấp nhận.

Vị trí lưu trữ và hành vi kết nối:

• Giao diện người dùng máy tính để bàn: Ghi vào tệp cấu hình hiện tại (theo mặc định %LOCALAPPDATA%\remote-agent\config.json / ~/.config/remote-agent/config.json) và kết nối ngay lập tức.
• OpenWrt: Ghi UCI remote-agent.main (server/device_id/token, enabled=1), sau đó khởi động lại dịch vụ procd.
• Dòng lệnh: Mặc định là đường dẫn cấu hình máy tính để bàn (UCI trên OpenWrt). --config PATH chọn tệp JSON; --uci buộc lưu trữ UCI. Sau khi lưu, kết nối ở nền trước (--no-connect chỉ lưu). Khởi động lại mọi dịch vụ hiện có bằng cấu hình đó.

Theo mặc định, thông tin xác thực hiện có được bảo vệ khỏi bị thay thế: dòng lệnh yêu cầu --force, trong khi giao diện người dùng trên máy tính để bàn và LuCI yêu cầu xác nhận. Các phương thức dựa trên mã thông báo hiện có (--device-id/--token, tệp cấu hình và cài đặt LuCI) vẫn khả dụng.

remote-agent pair                       # 显示六位码 + 二维码，批准后保存并连接
remote-agent pair --server wss://your-exchange.example.com --config ./agent.json
remote-agent join '{"type":"remote-enrollment","version":1,...}'
remote-agent join - < invite.txt --no-connect

Ghép nối gốc yêu cầu wss://; ws:// chỉ được phép ở vòng lặp để thử nghiệm. Việc ghép nối Android và Console yêu cầu HTTPS/WSS.

Đăng nhập mã sáu chữ số Console

Trên trang đăng nhập Android Remote Console, nhấn Đăng nhập bằng mã gồm sáu chữ số. Trong Web Console (/console), chọn tab Sáu chữ số trong thẻ đăng nhập và yêu cầu mã đăng nhập. Quản trị viên có thể phê duyệt bằng một trong hai phương pháp:

remote-cli pair 012345 --operator-name mobile-alice
# 只读客户端：追加 --role readonly

Ngoài ra, trong không gian làm việc Web Console đã được xác thực, hãy nhấp vào Phê duyệt mã ghép nối (chỉ quản trị viên mới nhìn thấy; người vận hành chỉ đọc không có hành động như vậy). Nhập mã hiển thị trên màn hình của khách hàng khác, xác minh loại và nhãn của nó rồi phê duyệt.

Theo mặc định, điều này sẽ tạo một tài khoản operator riêng thay vì sao chép mã thông báo của quản trị viên. Quản trị viên có thể chỉ định rõ ràng --role admin hoặc --role readonly. Sau khi nhận được ủy quyền, Android Console xác thực lại thông tin đăng nhập, lưu chúng vào SecureStore và mở danh sách thiết bị. Web Console lưu giữ thông tin xác thực của nhà điều hành trong bộ nhớ của trang hiện tại (như khi đăng nhập tài khoản/mã thông báo) và mở danh sách thiết bị. Nếu bị hủy hoặc không thành công, thông tin đăng nhập bằng tài khoản hoặc mã thông báo hiện tại vẫn có sẵn và thông tin nhập vào sau đó cho các phương thức đăng nhập khác sẽ được giữ nguyên.

Quét mã CLI bằng Remote Agent

remote-cli qr --device-id my-phone
# 输出 SVG 供手机扫描：
remote-cli qr --device-id my-phone --output ./phone-login.svg

Tạo mã QR từ CLI quản trị viên được xác thực. Trên điện thoại, mở Remote Agent và nhấn vào Quét mã QR kết nối, xác minh máy chủ và ID thiết bị, sau đó nhấn vào Connect. Mã QR chỉ chứa một vé tạm thời 256 bit ngẫu nhiên, có giá trị trong 5 phút và có thể liên kết với một thiết bị; nó không chứa mã thông báo thiết bị tồn tại lâu dài. Sau khi quét, Exchange phát hành mã thông báo thiết bị mà điện thoại lưu trữ trong Keystore trước khi kết nối. Mã QR phải đặt tên cho ID thiết bị mới; nó không thay thế thiết bị hiện có hoặc xoay mã thông báo của nó.

Các xác nhận quyền sở hữu từ cùng một điện thoại sử dụng claim_id ngẫu nhiên ổn định, do đó, việc thử lại sau khi xảy ra lỗi kết nối có thể truy xuất kết quả tương tự; một claim_id khác không thể lấy lại vé. Sau khi lưu, điện thoại xác nhận rằng vé có thể bị xóa. Vé tạm thời tồn tại trong bộ nhớ xử lý và trở nên không hợp lệ khi Exchange khởi động lại. Kết quả xác nhận quyền sở hữu đã được truy xuất sẽ được giữ lại tối đa 5 phút nữa để khách hàng ban đầu có thể thử lại.

Tạo mã QR thiết bị

# 创建设备，同时在终端显示二维码
remote-cli device add my-android --qr
# 新建 SVG 文件，可在电脑打开后供手机扫描
remote-cli device add another-phone --qr-output ./another-phone.svg
# 使用手里已有的设备令牌，不创建或轮换设备
remote-cli device qr my-android --output ./my-android.svg
# 明确轮换令牌并生成二维码；原令牌立即失效
remote-cli device rotate-token my-android --qr

device qr đọc mã thông báo thiết bị thông qua đầu vào ẩn và cũng hỗ trợ --token-stdin. Mã QR của thiết bị chỉ chứa mã thông báo thiết bị; mã thông báo hoạt động không thể được sử dụng. Các tệp đầu ra từ chối ghi đè lên các tệp hiện có và chứa thông tin xác thực: bảo vệ chúng và xóa chúng sau khi sử dụng. Mã QR yêu cầu HTTPS/WSS.

Android Console hiển thị mã QR của thiết bị ngay sau khi tạo thiết bị. Trong phần chi tiết về thiết bị, Rotate mã thông báo và tạo mã QR giải thích tác động ngắt kết nối và yêu cầu xác nhận trước tiên. Máy chủ chỉ lưu trữ mã băm mã thông báo và không thể khôi phục mã QR cũ từ bản ghi thiết bị hiện có, do đó việc xem mã QR không bao giờ âm thầm xoay mã thông báo.

API ghép nối Exchange

Mã sáu chữ số chỉ cho phép quản trị viên được xác thực xác định vị trí và xác nhận yêu cầu; nó không thể được sử dụng để thăm dò ý kiến ​​hoặc lấy thông tin xác thực. Thông tin xác thực bỏ phiếu là bí mật 256 bit ngẫu nhiên và không bao giờ được đặt trong URL. Phê duyệt trùng lặp bị từ chối. Việc tạo danh tính không thành công sẽ giải phóng phần đặt trước phê duyệt để có thể thử lại. Kết quả đã được phê duyệt có thể được đọc lại với cùng thông tin xác thực bỏ phiếu riêng tư, ngăn chặn việc mất thông tin xác thực vĩnh viễn do phản hồi mạng bị rớt. Khách hàng xác nhận việc xóa sau khi lưu.

Các yêu cầu chờ phê duyệt và kết quả đã được phê duyệt đang chờ thu thập đều được giữ lại tối đa 5 phút. Nếu không có REDIS_URL, các phiên tạm thời chỉ tồn tại trong bộ nhớ của quy trình Exchange hiện tại; sau khi khởi động lại, hãy yêu cầu mã mới và định tuyến các yêu cầu ghép nối đến cùng một phiên bản trong quá trình triển khai nhiều phiên bản. Với Redis được định cấu hình, các mục ghép nối và bộ đếm giới hạn tốc độ được lưu trữ trong Redis (được căn chỉnh với TTL 5 phút), cho phép các yêu cầu tiếp cận bất kỳ phiên bản nào có yêu cầu về mối quan hệ phiên no. Mỗi IP nguồn TCP thực tế có thể yêu cầu tối đa 10 mã mỗi phút; quản trị viên có thể thực hiện tối đa 20 lần tra cứu hoặc phê duyệt mỗi phút. Chế độ bộ nhớ cũng có giới hạn toàn cầu là 256 phiên đang chờ xử lý. IP máy khách được chuyển tiếp proxy không được tin cậy để giới hạn tốc độ; người dùng sử dụng cùng một proxy ngược chia sẻ hạn ngạch nguồn của nó. TTL hết hạn và dọn dẹp theo lịch sẽ loại bỏ dữ liệu đã hết hạn. Các phản hồi được đặt Cache-Control: no-store và cả bí mật ghép nối cũng như mã thông báo văn bản gốc đã phát hành đều không được ghi lại.

ID/tài khoản thiết bị phụ trợ hiện tại không thể bị ghi đè bằng yêu cầu ghép nối. Quản trị viên nên xác minh cả mã và ứng dụng khách yêu cầu; không phê duyệt mã đăng nhập được cung cấp thông qua thao tác của người khác.

API mã kết nối: POST /api/pairing/start chấp nhận device_name tùy chọn và trả về tên đó. Tra cứu quản trị viên GET /api/pairing/{code} trả về device_name và suggested_device_id của không gian làm việc hiện tại; tra cứu nó không bảo lưu ID. Thiết bị identity trong POST /api/pairing/approve có thể bị bỏ qua. Thành công trả về 200 với {identity} (ID cuối cùng, không có mã thông báo). WebSocket /ws/pairing?device_name=... gốc hỗ trợ tên thiết bị được mã hóa URL.