Matcha View

Matcha View là agent điều khiển máy tính Linux trong cùng mạng LAN từ trình duyệt. Agent truyền màn hình bằng WebRTC, nhận thao tác chuột và bàn phím qua WebRTC DataChannel, đồng thời cung cấp giao diện tối ưu cho cả máy tính và điện thoại.

Warning

Phiên bản hiện tại dùng HTTP và token trong URL. Chỉ triển khai trong mạng LAN tin cậy; không mở trực tiếp cổng dịch vụ ra Internet.

Tính năng

• Xem màn hình Linux gần thời gian thực qua WebRTC video.
• Điều khiển chuột: di chuyển tuyệt đối/tương đối, giữ/thả nút và click trái, giữa, phải.
• Gửi văn bản và các phím đặc biệt từ bàn phím máy tính hoặc điện thoại.
• Touchpad ảo và bàn phím di động tích hợp trong giao diện web.
• Đồng bộ clipboard hai chiều khi máy đích có xclip hoặc xsel.
• Token ngẫu nhiên cho mỗi lần chạy, hoặc token cố định qua AUTH_TOKEN.
• Tùy chọn VP8/H.264, encoder phần mềm hoặc NVIDIA NVENC.
• Cấu hình ICE server để hỗ trợ các mô hình mạng phức tạp hơn.

Kiến trúc

flowchart LR
    B["Trình duyệt trong LAN"] -->|"HTTP: giao diện và signaling"| A["Matcha View agent"]
    A -->|"WebRTC video"| B
    B -->|"WebRTC DataChannel: chuột và bàn phím"| A
    A --> F["FFmpeg: chụp và mã hóa màn hình"]
    A --> X["xdotool: điều khiển X11"]
    A --> C["xclip/xsel: clipboard"]

Loading

Agent Go nhúng trực tiếp giao diện web và signaling HTTP. FFmpeg lấy hình ảnh từ X11, mã hóa thành VP8 hoặc H.264 rồi chuyển RTP vào Pion WebRTC. Trình duyệt gửi lệnh điều khiển dạng JSON qua DataChannel.

Xem chi tiết tại docs/ARCHITECTURE.md.

Yêu cầu

• Linux desktop sử dụng X11.
• Go 1.26 trở lên nếu build từ mã nguồn.
• ffmpeg và xdotool.
• xclip hoặc xsel nếu cần đồng bộ clipboard.

Ubuntu/Debian:

sudo apt update
sudo apt install -y ffmpeg xdotool xclip golang

Chạy nhanh

git clone git@github.com:digital-enterprise-projects/matcha-view.git
cd matcha-view
go run .

Mặc định agent lắng nghe trên 0.0.0.0:4783. Khi khởi động, terminal hiển thị URL LAN và URL có token:

Matcha View (WebRTC)
Listening on 0.0.0.0:4783
LAN URL:  http://192.168.1.20:4783
Auth URL: http://192.168.1.20:4783/?token=...

Mở Auth URL bằng trình duyệt trên thiết bị khác trong cùng mạng LAN.

Build binary Linux

go build -trimpath -o matcha-view .

Cross-compile Linux x86-64 từ macOS hoặc Linux:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o matcha-view-linux-amd64 .

Cấu hình

Biến	Mặc định	Mô tả
HOST	0.0.0.0	Địa chỉ HTTP server lắng nghe.
PORT	4783	Cổng HTTP/signaling.
DISPLAY	:0	X11 display cần điều khiển.
XAUTHORITY	rỗng	Đường dẫn Xauthority khi phiên đồ họa yêu cầu.
AUTH_TOKEN	ngẫu nhiên	Token truy cập; nên dùng giá trị dài và khó đoán.
VIDEO_WIDTH	1920	Chiều rộng video đầu ra.
VIDEO_FPS	20	Số khung hình mỗi giây.
VIDEO_BITRATE	4500k	Bitrate video.
VIDEO_CODEC	vp8	vp8 hoặc h264.
VIDEO_ENCODER	auto	auto, software hoặc nvenc.
QUALITY_PRESET	smooth	smooth hoặc sharp.
CAPTURE_MODE	auto	auto, x11 hoặc gnome-screenshot.
ICE_SERVERS	rỗng	Mảng JSON chứa cấu hình STUN/TURN.

Ví dụ chạy với cấu hình rõ ràng:

HOST=0.0.0.0 \
PORT=4783 \
DISPLAY=:0 \
AUTH_TOKEN='replace-with-a-long-random-token' \
VIDEO_CODEC=vp8 \
VIDEO_FPS=20 \
go run .

Ví dụ ICE_SERVERS:

export ICE_SERVERS='[
  {"urls":["stun:stun.l.google.com:19302"]},
  {"urls":["turn:turn.example.com:3478"],"username":"user","credential":"pass"}
]'

Sử dụng trên điện thoại

• Kéo trong vùng touchpad để di chuột tương đối.
• Chạm một lần để click trái; dùng nút riêng cho click phải.
• Bấm Bật bàn phím để gửi ký tự và các phím Backspace, Enter, Tab, Escape theo thời gian thực.
• Dùng ô nhập nhanh khi cần gửi một đoạn văn bản dài.

Bảo mật triển khai

• Không chuyển tiếp cổng 4783 từ router ra Internet.
• Đặt AUTH_TOKEN dài, ngẫu nhiên và không chia sẻ qua kênh công khai.
• URL chứa token có thể xuất hiện trong lịch sử trình duyệt hoặc log; hãy đóng phiên và đổi token sau khi hỗ trợ xong.
• Nếu cần truy cập ngoài LAN, đặt agent sau reverse proxy HTTPS và bổ sung kiểm soát phiên/phê duyệt kết nối.
• /health không yêu cầu xác thực; không đưa thông tin nhạy cảm vào endpoint này.

Xem thêm SECURITY.md.

Giới hạn hiện tại

• Tối ưu cho Linux X11; Wayland native chưa được hỗ trợ đầy đủ.
• Mỗi agent ưu tiên một viewer hoạt động tại một thời điểm.
• Chưa truyền âm thanh.
• Chưa có TLS tích hợp, xác thực nhiều người dùng hoặc phê duyệt phiên tại máy đích.
• Signaling hiện nằm chung trong agent và dùng one-shot SDP, chưa có trickle ICE.

Kiểm tra

go test ./...
go vet ./...

Smoke test WebRTC sau khi agent chạy:

go run ./cmd/smoke-webrtc -url http://127.0.0.1:4783 -token "$AUTH_TOKEN"

Cấu trúc dự án

.
├── main.go                 # HTTP server và thông tin LAN
├── config.go               # Cấu hình qua biến môi trường
├── controller.go           # API, token auth và quản lý phiên
├── session.go              # WebRTC, RTP và pipeline FFmpeg
├── input.go                # Chuột, bàn phím và clipboard
├── web/                    # Giao diện điều khiển nhúng trong binary
└── cmd/smoke-webrtc/       # Client smoke test

Trạng thái

v0.1.0 là bản thử nghiệm đầu tiên dành cho mạng LAN tin cậy. API và cấu hình có thể còn thay đổi.