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 | shWindows (PowerShell):
irm https://adbkit.com/install.ps1 | iexScript 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ập | Tác dụng | |
|---|---|---|
ADBKIT_NO_RUN=1 | Chỉ cài đặt, không chạy agent | |
--port 8730 | Cổ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.mjsBả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ăng | Bả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ạng | Có | 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ối | Có | Không |
| Cần cài môi trường chạy | Không | Node.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/healthMô 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:3000vàhttp://127.0.0.1:3000. Trang khác nhận lỗi403. 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ọn | Tá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_ORIGINS | Các origin bổ sung, ngăn cách bằng dấu phẩy |
--help | In ra các tùy chọn và khả năng |
Các endpoint
| Endpoint | Công dụng |
|---|---|
GET /health | Tê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=5555 | Các máy trong mạng /24 nội bộ chấp nhận kết nối ở cổng đó |
GET /discover?timeout=3000 | Dò mDNS tìm dịch vụ _adb-tls-connect và _adb-tls-pairing |
POST /pair | Ghé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ứng | Nguyên nhân có thể | Cách sửa |
|---|---|---|
| ADBKit báo agent chưa chạy | Không có gì lắng nghe ở cổng 8730 | Chạ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ày | Bạ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 được | Tường lửa, VPN hoặc phần mềm bảo mật chặn loopback hay ứng dụng | Cho 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 file | File tải về mới, chưa ký số nên bị cảnh báo | Kiể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ển | Gatekeeper 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ại | Khác mạng, hoặc router bật cách ly AP/client | Cho 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 5555 | Bậ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 được | Bạn đang chạy bản Node | Cà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ại | Chế độ TCP cổ điển bị đặt lại khi khởi động lại | Bậ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.