Kết nối máy chủ từ xa

Mọi máy khách đều là một lớp dựng giao diện trên một cc_server sở hữu dữ liệu. Ứng dụng máy tính có thể chạy một máy chủ ngay bên trong chính nó; ứng dụng web tại app.usectrl.dev thì không, vì một tab trình duyệt không thể làm máy chủ. Dù theo cách nào, hướng dẫn này giúp trỏ một máy khách tới một máy chủ đang chạy ở nơi khác — một chiếc máy nhỏ, một VM trên đám mây, một máy chủ build.

Điều kiện tiên quyết

Một cc_server đang chạy. Nếu bạn chưa có, xem Chạy máy chủ không giao diện.
Hoặc ba giá trị ghép nối mà máy chủ đã tạo — URL máy chủ (ws://…/rpc hoặc wss://…/rpc), một id thiết bị và một khóa ghép nối — hoặc một mã mời dùng một lần từ quản trị viên không gian làm việc. Đổi một mã mời sẽ cấp phát người dùng của bạn, ghi nhận tư cách thành viên và tạo thông tin xác thực của máy khách này thay bạn, nên bạn không bao giờ phải xử lý id thiết bị hay khóa.

Đảm bảo có thể truy cập tới máy chủ

Một máy chủ cục bộ không cần gì cả: ws://localhost:9030/rpc hoạt động từ cả ứng dụng máy tính lẫn trình duyệt, vì trình duyệt coi loopback là một origin đáng tin cậy.

Một máy chủ trên máy khác thì khác. app.usectrl.dev được phục vụ qua HTTPS, nên trình duyệt chỉ mở một socket wss:// với chứng chỉ mà nó đã tin cậy — và bản thân cc_server cũng từ chối bind một địa chỉ không phải loopback nếu không có TLS ngay từ đầu. Hãy cấp cho nó một trong những thứ sau:

một chứng chỉ trực tiếp, với --tls-cert và --tls-key
một reverse proxy kết thúc TLS ở phía trước, với máy chủ được khởi động --insecure (dữ liệu thuần phía sau proxy, chỉ trên mạng tin cậy)
một tunnel hoặc VPN cung cấp chứng chỉ — Tailscale, cloudflared, hoặc tương tự. Cài đặt → Máy chủ → Kết nối & trạng thái có tùy chọn tunnel tích hợp sẵn dưới mục Chia sẻ máy chủ này.

Hai thiết lập phía máy chủ rất dễ bị bỏ sót. Khi đứng sau proxy, NAT hoặc tunnel, hãy đặt --public-url thành địa chỉ mà máy khách thực sự nên gọi tới — nó mặc định lấy theo bind cục bộ, nên nếu thiếu, máy khách sẽ thử nhầm máy chủ. Và nếu bạn tự lưu trữ bản dựng web của riêng mình, hãy thêm origin của nó vào --allowed-origins, vốn mặc định chỉ có https://app.usectrl.dev; loopback và các máy khách native luôn được cho phép.

Kết nối ứng dụng máy tính

Khi cài đặt mới:

Khởi chạy Control Center. Màn hình lần chạy đầu tiên hỏi Control Center nên chạy như thế nào?
Thay vì Chạy trong ứng dụng này, hãy điền vào các trường kết nối: URL máy chủ, cùng với mã mời hoặc id thiết bị và khóa ghép nối.
Nhấp vào Kết nối. Control Center gọi tới máy chủ và đưa bạn đến hộp thư của không gian làm việc.

Trên một ứng dụng máy tính đã chạy máy chủ của riêng nó:

Mở Cài đặt → Máy chủ → Kết nối & trạng thái.
Nhấp vào Thêm máy chủ. Nhập URL máy chủ (wss://host:9030/rpc) cùng mã mời hoặc id thiết bị và khóa ghép nối. Nút ở cuối trường URL sẽ dò tìm các phiên bản cc_server trên LAN hoặc tailnet của bạn.
Nhấp vào Kết nối, rồi Chuyển trên hàng của máy chủ mới.

Việc chuyển đổi diễn ra ngay lập tức: ứng dụng dựng lại quanh phiên mới ngay tại chỗ, không cần khởi động lại. Nếu kết nối thất bại, bạn vẫn ở máy chủ hiện tại và thấy lỗi. Hàng của máy chủ bạn đang dùng không có thao tác Chuyển; máy chủ cục bộ là hàng đầu tiên, được gắn nhãn Chạy trong ứng dụng này.

Sau khi chuyển, ứng dụng máy tính không còn sở hữu cơ sở dữ liệu nào. Mọi màn hình đều đọc và ghi qua máy chủ từ xa thông qua WebSocket.

Kết nối máy khách web

Bản dựng web luôn ở chế độ từ xa.

Mở app.usectrl.dev, hoặc bản sao bản dựng web của riêng bạn.
Nhập URL máy chủ cùng mã mời hoặc id thiết bị và khóa ghép nối.
Máy khách gọi tới máy chủ và dựng đúng giao diện mà ứng dụng máy tính dựng.

Nếu URL có chứa một deep link ghép nối, các trường sẽ được điền sẵn. Khóa ghép nối nằm trong fragment của URL, thứ mà trình duyệt không bao giờ gửi tới máy chủ lưu trữ trang, nên máy chủ tĩnh không bao giờ thấy nó.

Những gì trình duyệt không làm

Máy khách web đọc và ghi trên cùng máy chủ như ứng dụng máy tính, nhưng một vài bề mặt cần một cửa sổ native hoặc chính các thiết bị của máy:

không có thông báo nổi của hệ điều hành, âm thanh thông báo, hay dải banner nền (trung tâm thông báo trong ứng dụng vẫn hoạt động)
không có dò tìm máy chủ trên LAN hay tailnet trong hộp thoại Thêm máy chủ
không có trình đọc bài viết trong ứng dụng — các bài trên bảng tin mở trong tab mới
không chạy lại được bản tóm tắt cuộc họp và không hủy được bản tóm tắt đang xử lý

Hai thứ hoạt động khác đi chứ không phải biến mất. Việc ghi âm cuộc họp hoạt động trong trình duyệt, thu micrô của bạn cùng một bản chia sẻ màn hình có kèm track âm thanh. Mở trong IDE cũng hoạt động, nhưng yêu cầu máy chủ khởi chạy trình soạn thảo trên màn hình của máy chủ, nên nút này tự ẩn khi gặp một máy không giao diện không cài trình soạn thảo nào.

Khắc phục sự cố

Kết nối bị quá thời gian chờ: máy chủ phải tiếp cận được từ máy khách. Hãy kiểm tra bind (--bind any), rằng cổng đang mở và rằng --public-url nêu đúng địa chỉ mà máy khách thực sự có thể gọi tới. Trên mạng internet công khai, TLS là bắt buộc — một bind không phải loopback ở dạng thuần sẽ bị từ chối khi khởi động, trừ khi máy chủ được khởi động với --insecure phía sau một proxy.
Trình duyệt từ chối kết nối nhưng máy khách native vẫn hoạt động: origin của trình duyệt không nằm trong danh sách --allowed-origins của máy chủ. Mặc định chỉ cho phép https://app.usectrl.dev (cùng loopback).
Khóa ghép nối bị từ chối: chạy lại cc_server pair trên máy chủ để xoay khóa của thiết bị đó, rồi nhập khóa mới. Một thiết bị đã bị thu hồi sẽ thấy thông tin xác thực của mình biến mất và bị từ chối truy cập; việc thu hồi cắt một phiên đang hoạt động trong vài giây.
Sai không gian làm việc: không gian làm việc là một phần của URL (/workspaces/:workspaceId/…) và đi kèm mọi lời gọi, nên việc chuyển không gian làm việc trong một máy khách chỉ thay đổi góc nhìn của riêng bạn. Bạn chỉ có thể truy cập những không gian làm việc mà mình là thành viên — bất cứ thứ gì khác đều bị từ chối với “Not a member of this workspace”. Xem Không gian làm việc và cô lập.

Hướng dẫn liên quan

Chạy máy chủ không giao diện
Ghép nối thiết bị: con đường qua relay điện thoại