ADB KIT

Hướng dẫnĐăng ngày: 8 phút đọc

ADBKit agent: cài đặt, chạy, bảo mật và xử lý lỗi

Tài liệu về ADBKit agent, chương trình nhỏ giúp trình duyệt kết nối Android qua Wi-Fi: cài một dòng lệnh, bản Node, khả năng hỗ trợ, bảo mật và cách sửa lỗi.

Trang web không thể mở socket TCP thô, không thể dò thiết bị trong mạng nội bộ bằng mDNS và cũng không thể xuất trình chứng chỉ TLS của máy khách. Gỡ lỗi Android qua Wi-Fi lại cần cả ba thứ đó. ADBKit agent là một chương trình nhỏ chạy ngay trên máy tính của bạn, làm những việc này thay cho tab ADBKit. Bài này là tài liệu tham khảo: cách khởi động agent, mỗi phiên bản làm được gì, cơ chế bảo mật và cách xử lý khi tab không tìm thấy agent.

Kết nối USB không cần agent. Bạn chỉ cần nó cho ADB qua Wi-Fi và Gỡ lỗi không dây.

Cách hoạt động

Tab ADBKit (trình duyệt)
   │  HTTP + WebSocket  127.0.0.1:8730
   ▼
ADBKit agent  (máy tính của bạn, chỉ lắng nghe loopback)
   │  TCP / mDNS / TLS
   ▼
Điện thoại Android  <ip-điện-thoại>:<cổng>   (adbd)

Agent chỉ đóng vai trò trung chuyển. Nó không đọc, không lưu và không tải lên dữ liệu đi qua, và dịch vụ ADBKit không bao giờ thấy dữ liệu thiết bị của bạn. Với kết nối adb tcpip cổ điển, trình duyệt vẫn tự thực hiện bắt tay ADB và bạn bấm Cho phép trên điện thoại. Với Gỡ lỗi không dây, agent giữ một khóa riêng, ghép nối khóa đó với điện thoại một lần rồi thay trình duyệt kết nối qua TLS.

Ba cách khởi động agent

1. Trình cài đặt một dòng lệnh (khuyên dùng)

macOS và Linux:

curl -fsSL https://adbkit.com/install.sh | sh

Windows (PowerShell):

irm https://adbkit.com/install.ps1 | iex

Script tự nhận diện hệ thống, tải bản nhị phân phù hợp từ adbkit.com, kiểm tra checksum SHA-256, lưu vào ~/.adbkit/bin (trên Windows là %LOCALAPPDATA%\adbkit\bin) rồi chạy ngay ở tiền cảnh. Script không cần quyền quản trị, không sửa PATH và không gửi dữ liệu thống kê. Nhấn Ctrl+C để dừng agent.

Một số thiết lập hữu ích:

Thiết lậpTác dụng
ADBKIT_NO_RUN=1Chỉ cài đặt, không chạy agent
--port 8730Cổng lắng nghe: `curl -fsSL https://adbkit.com/install.sh \sh -s -- --port 8730`

Nếu không tải được bản nhị phân mà máy có Node.js 18 trở lên, trình cài đặt sẽ chuyển sang bản Node (bên dưới) và báo rõ rằng không ghép nối được. Muốn đọc script trước khi chạy, bạn có thể mở install.sh hoặc install.ps1. Phần chú thích đầu file liệt kê chính xác những gì nó làm.

2. Bản Node

Nếu đã có Node.js 18 trở lên, hãy tải adbkit-bridge.mjs và chạy:

node adbkit-bridge.mjs

Bản này chỉ dùng các module có sẵn của Node nên không phải cài thêm gì. Chạy node adbkit-bridge.mjs --help để xem các tùy chọn. Bản Node hỗ trợ kết nối adb tcpip cổ điển và tìm được thiết bị Gỡ lỗi không dây trong mạng, nhưng không thể ghép nối chúng.

3. Tự tải bản nhị phân

Tải adbkit-agent_<hệ-điều-hành>_<kiến-trúc> (thêm .exe trên Windows) và checksums.txt từ trang tải xuống, so SHA-256 của file với dòng tương ứng trong checksums.txt, cấp quyền thực thi (chmod +x) rồi chạy. Trên macOS, nếu Gatekeeper chặn, xem bảng xử lý lỗi bên dưới.

Mỗi phiên bản hỗ trợ những gì

Khả năngBản Go (trình cài đặt)Bản Node
tcpip: trung chuyển và quét thiết bị adb tcpip (cổng 5555)CóCó
mdns: tìm thiết bị Gỡ lỗi không dây trong mạngCóCó
pair: ghép nối bằng mã 6 chữ số (Android 11+)CóKhông
tls: kết nối tới thiết bị Gỡ lỗi không dây đã ghép nốiCóKhông
Cần cài môi trường chạyKhôngNode.js 18+

Tóm lại: với cách cổ điển (cắm USB rồi chuyển sang Wi-Fi), phiên bản nào cũng dùng được. Với Gỡ lỗi không dây Android 11+ dùng mã ghép nối, hãy dùng bản Go. Hướng dẫn từng bước nằm ở bài Kết nối Android qua Gỡ lỗi không dây từ trình duyệt. Để chọn giữa hai cách, đọc adb tcpip và Gỡ lỗi không dây khác nhau thế nào.

ADBKit nhận biết agent bằng cách nào

Khi bạn mở Kết nối qua Wi-Fi, trang gửi yêu cầu tới http://127.0.0.1:8730/health. Phản hồi cho biết ba điều: phiên bản của agent, môi trường chạy (go hoặc node) và các khả năng nó có. ADBKit chỉ hiển thị những bước mà agent của bạn làm được và nói rõ khi thiếu thứ gì, ví dụ "agent này không thể ghép nối". Nếu không có gì phản hồi, trang hướng dẫn cách khởi động agent. Nếu có phản hồi nhưng từ chối nguồn (origin) của trang, trang sẽ báo origin bị chặn.

Bạn có thể tự kiểm tra:

curl http://127.0.0.1:8730/health

Mô hình bảo mật

  • Agent chỉ lắng nghe trên 127.0.0.1, nên các máy khác không truy cập được.
  • Chỉ các trang web được phép mới dùng được: https://adbkit.com, https://www.adbkit.com, http://localhost:3000 và http://127.0.0.1:3000. Trang khác nhận lỗi 403. Chỉ có endpoint kiểm tra sức khỏe là mở, để trang phân biệt được "chưa chạy" với "bị chặn".
  • Agent chỉ kết nối tới địa chỉ loopback, mạng riêng và link-local (127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x, .local). Không thể dùng nó để đi ra internet.
  • Bản Go lưu một thứ duy nhất trên đĩa, trong ~/.adbkit/: khóa riêng dùng cho Gỡ lỗi không dây và tên các thiết bị đã ghép nối. Bạn có thể thu hồi trên điện thoại tại Gỡ lỗi không dây, mục Thiết bị đã ghép nối. Bản Node không lưu gì cả.
  • Không có nhật ký nào về lưu lượng được trung chuyển và không có gì được gửi về ADBKit.

Cổng, tham số và biến môi trường

Tùy chọnTác dụng
--port <số>Cổng lắng nghe. Mặc định 8730. ADBKit tìm ở cổng 8730, nên chỉ đổi khi bạn tự dựng môi trường riêng
--origin <url>Cho phép thêm một origin của trang web, ví dụ bản ADBKit tự lưu trữ. Dùng được nhiều lần
ADBKIT_BRIDGE_ORIGINSCác origin bổ sung, ngăn cách bằng dấu phẩy
--helpIn ra các tùy chọn và khả năng

Các endpoint

EndpointCông dụng
GET /healthTên, phiên bản, giao thức, môi trường chạy và khả năng. Mở cho mọi origin
GET /scan?port=5555Các máy trong mạng /24 nội bộ chấp nhận kết nối ở cổng đó
GET /discover?timeout=3000Dò mDNS tìm dịch vụ _adb-tls-connect và _adb-tls-pairing
POST /pairGhép nối bằng mã 6 chữ số (chỉ bản Go, bản Node trả về 501)
WebSocket /connect?host=&port=Trung chuyển tới điện thoại, tls=1 cho Gỡ lỗi không dây (chỉ bản Go)

Xử lý sự cố

Triệu chứngNguyên nhân có thểCách sửa
ADBKit báo agent chưa chạyKhông có gì lắng nghe ở cổng 8730Chạy trình cài đặt hoặc node adbkit-bridge.mjs và giữ nguyên cửa sổ. Nếu báo "address in use", hãy đóng chương trình đang chiếm cổng hoặc dùng --port
ADBKit báo agent đã chặn trang nàyBạn mở ADBKit từ một origin chưa được phép (bản tự lưu trữ, cổng khác)Khởi động lại agent với --origin https://trang-cua-ban.example
Chrome hỏi có cho phép truy cập thiết bị trong mạng nội bộChrome bảo vệ mạng cục bộChọn Cho phép với trang ADBKit
Agent đã chạy nhưng trình duyệt vẫn không kết nối đượcTường lửa, VPN hoặc phần mềm bảo mật chặn loopback hay ứng dụngCho phép adbkit-agent qua tường lửa trên mạng riêng, hoặc tạm tắt VPN để thử
Windows báo "Windows protected your PC" hoặc phần mềm diệt virus cách ly fileFile tải về mới, chưa ký số nên bị cảnh báoKiểm tra checksum, rồi chọn More info, Run anyway, hoặc thêm ngoại lệ cho %LOCALAPPDATA%\adbkit\bin. Nếu file bị xóa, chạy lại trình cài đặt
macOS báo không mở được vì không xác minh được nhà phát triểnGatekeeper cách ly file tải vềTrình cài đặt đã gỡ cờ này. Nếu tải thủ công, chạy xattr -d com.apple.quarantine adbkit-agent hoặc cho phép trong Cài đặt hệ thống, Quyền riêng tư & Bảo mật
Không tìm thấy điện thoạiKhác mạng, hoặc router bật cách ly AP/clientCho cả hai vào cùng Wi-Fi, tắt "AP isolation" hoặc "client isolation", tránh mạng khách
Quét không thấy gìĐiện thoại chưa lắng nghe ở cổng 5555Bật gỡ lỗi Wi-Fi qua USB trước, hoặc nhập địa chỉ thủ công
Không ghép nối đượcBạn đang chạy bản NodeCài bản Go bằng trình cài đặt một dòng lệnh
Đang dùng tốt rồi ngừng sau khi khởi động lạiChế độ TCP cổ điển bị đặt lại khi khởi động lạiBật lại qua USB, hoặc chuyển sang Gỡ lỗi không dây

Nếu ngay cả qua USB cũng không thấy điện thoại, xem Sửa lỗi ADB "device busy", "unauthorized" và "no devices". Khi agent đang chạy, mở không gian làm việc ADBKit và chọn Kết nối qua Wi-Fi.