Trình hỗ trợ Wi-Fi của ADBKit: cài đặt, tùy chọn, xử lý lỗi
Tài liệu kỹ thuật về adbkit-bridge.mjs, công cụ nhỏ giúp ADBKit kết nối Android qua Wi-Fi: yêu cầu, tải về, chạy, mô hình bảo mật, API và cách sửa lỗi.
Trang web không thể mở kết nối TCP thô, trong khi điện thoại Android bật ADB qua Wi-Fi lại lắng nghe bằng TCP thường (mặc định cổng 5555). Trình hỗ trợ Wi-Fi của ADBKit (adbkit-bridge.mjs) lấp khoảng trống đó: một file JavaScript duy nhất chạy trên máy tính của bạn, chuyển tiếp dữ liệu giữa tab ADBKit và điện thoại. Trang này là tài liệu tham khảo để cài đặt, chạy, bảo mật và xử lý lỗi cho nó.
Cách hoạt động
Tab ADBKit (trình duyệt)
│ WebSocket ws://127.0.0.1:8730/connect?host=<ip-điện-thoại>&port=5555
▼
adbkit-bridge.mjs (máy tính của bạn, chỉ lắng nghe 127.0.0.1)
│ TCP thường
▼
Điện thoại Android <ip-điện-thoại>:5555 (adbd)Công cụ này không hiểu giao thức ADB. Nó chỉ sao chép byte hai chiều, nên bước bắt tay ADB và xác thực khóa RSA vẫn diễn ra giữa ADBKit và điện thoại, và bạn vẫn phải chạm Cho phép trên điện thoại. Ngoài ra nó trả lời hai yêu cầu HTTP đơn giản: kiểm tra trạng thái và quét mạng.
Yêu cầu
| Hạng mục | Yêu cầu |
|---|---|
| Máy tính | Hệ điều hành chạy được Node.js: Windows, macOS hoặc Linux |
| Node.js | Bản LTS hiện hành. Công cụ được phát triển và kiểm thử trên Node.js 22 và chỉ dùng module có sẵn, nên không cần npm install |
| Trình duyệt | Chrome hoặc Edge trên máy tính, mở workspace ADBKit |
| Điện thoại | Đã bật ADB qua TCP/IP (xem bên dưới), cùng mạng Wi-Fi với máy tính |
| Mạng | Router phải cho phép các thiết bị liên lạc với nhau. Tính năng "AP isolation" hoặc "client isolation" sẽ chặn việc này |
Tải về và chạy
- Tải công cụ: adbkit-bridge.mjs. Lưu ở bất kỳ đâu, ví dụ thư mục cá nhân của bạn.
- Mở terminal trong thư mục đó và chạy:
node adbkit-bridge.mjs- Bạn sẽ thấy:
ADBKit bridge listening on ws://127.0.0.1:8730
Allowed pages: http://localhost:3000, http://127.0.0.1:3000, https://adbkit.com, https://www.adbkit.com
Leave this window open while you use Wi-Fi in ADBKit. Ctrl+C to stop.- Để cửa sổ này mở. Nhấn
Ctrl+Cđể dừng. Không có gì được cài vào máy; xóa file là gỡ xong.
Kiểm tra công cụ đang chạy
Mở http://127.0.0.1:8730/health trong một tab trình duyệt, hoặc chạy:
curl http://127.0.0.1:8730/healthKết quả trả về là {"name":"adbkit-bridge","version":1}.
Bật ADB qua Wi-Fi trên điện thoại
Công cụ chỉ tới được điện thoại nếu điện thoại đang lắng nghe ADB trên mạng.
- Ngay trong ADBKit (khuyên dùng): cắm điện thoại bằng USB, mở menu thiết bị, chọn Add device over TCP/IP… rồi bấm Turn on Wi-Fi debugging. ADBKit chạy
adb tcpip 5555giúp bạn và hiện địa chỉ Wi-Fi của điện thoại. - Dùng adb trên máy tính: chạy
adb tcpip 5555khi điện thoại đang cắm USB.
Chế độ TCP cổ điển giữ nguyên cho tới khi điện thoại khởi động lại. Muốn tắt sớm hơn, chạy adb usb khi điện thoại đang kết nối.
Warning: khi ADB qua Wi-Fi đang bật, mọi thiết bị trong cùng mạng đều có thể thử kết nối tới cổng này. Android vẫn hỏi bạn duyệt từng máy tính, nhưng chỉ nên dùng trên mạng đáng tin và tắt đi khi dùng xong.
Kết nối từ ADBKit
- Chạy công cụ.
- Trong ADBKit, mở menu thiết bị và chọn Add device over TCP/IP… để nhập địa chỉ (cổng 5555), hoặc Scan network… để tự tìm điện thoại. Ở màn hình bắt đầu, các lựa chọn này nằm trong Connect over Wi-Fi.
- Chạm Cho phép trên điện thoại nếu máy hỏi cho phép gỡ lỗi từ máy tính này.
Các địa chỉ gần đây được nhớ trong trình duyệt để bạn kết nối lại chỉ bằng một cú nhấp.
Tùy chọn
| Tùy chọn | Tác dụng |
|---|---|
--port <số> | Cổng công cụ lắng nghe. Mặc định 8730. Hiện ADBKit tìm cổng 8730, nên chỉ đổi khi dùng cho môi trường phát triển riêng |
--origin <url> | Thêm một origin trang web được phép dùng công cụ, ví dụ bản ADBKit tự host. Có thể lặp lại |
ADBKIT_BRIDGE_ORIGINS | Biến môi trường chứa các origin bổ sung, phân tách bằng dấu phẩy |
Mặc định chỉ http://localhost:3000, http://127.0.0.1:3000, https://adbkit.com và https://www.adbkit.com được dùng công cụ.
Mô hình bảo mật
- Chỉ lắng nghe trên
127.0.0.1, nên máy khác không truy cập được. - Mọi yêu cầu phải đến từ origin được phép. Trang web khác bị từ chối với mã
403. - Chỉ kết nối tới địa chỉ IPv4 loopback, mạng riêng và link-local (
127.x,10.x,172.16–31.x,192.168.x,169.254.x). Không thể dùng nó để ra internet. - Không lưu gì và không ghi log nội dung nó chuyển tiếp.
- Xác thực của ADB vẫn nguyên vẹn: điện thoại vẫn phải duyệt khóa của máy tính bạn.
Quét mạng hoạt động thế nào
Scan network yêu cầu công cụ thử cổng ADB trên mọi địa chỉ của mạng /24 thuộc từng card mạng IPv4 riêng của máy bạn (ví dụ từ 192.168.1.1 đến 192.168.1.254). Công cụ dò tối đa 128 địa chỉ cùng lúc, chờ khoảng nửa giây mỗi địa chỉ và trả về những nơi chấp nhận kết nối. Quét tìm mọi thứ đang lắng nghe trên cổng đó, không riêng điện thoại. Điện thoại chưa bật ADB qua Wi-Fi sẽ không xuất hiện.
Tài liệu kỹ thuật
| Endpoint | Mục đích |
|---|---|
GET /health | Trả về {"name":"adbkit-bridge","version":1}. Cho phép từ mọi origin |
GET /scan?port=5555 | Trả về {"devices":[{"host":"192.168.1.42","port":5555}]}. Cần origin được phép |
WebSocket /connect?host=<ip>&port=<cổng> | Mở kết nối TCP tới điện thoại và chuyển tiếp thông điệp nhị phân hai chiều |
Mã lỗi: 403 khi origin không được phép, 400 khi host không phải địa chỉ mạng riêng hoặc cổng không hợp lệ, 502 khi điện thoại không chấp nhận kết nối.
Xử lý lỗi
| Triệu chứng | Nguyên nhân có thể | Cách sửa |
|---|---|---|
| "The ADBKit bridge isn't running on this computer" (cầu nối ADBKit chưa chạy) | Công cụ chưa chạy, hoặc cổng 8730 bị chương trình khác dùng | Chạy node adbkit-bridge.mjs. Nếu báo lỗi "address in use", hãy đóng chương trình đang chiếm cổng |
| Trình duyệt hỏi cho phép truy cập thiết bị trong mạng cục bộ | Chrome bảo vệ mạng nội bộ | Chọn Allow cho trang ADBKit |
| "The device didn't answer over Wi-Fi" (thiết bị không phản hồi qua Wi-Fi) | Khác mạng, router cô lập thiết bị, hoặc ADB qua Wi-Fi đang tắt | Đưa cả hai vào cùng Wi-Fi, tắt cô lập thiết bị, chạy lại Turn on Wi-Fi debugging |
| Quét không thấy gì | Điện thoại không lắng nghe cổng 5555, hoặc máy tính ở subnet khác | Bật ADB qua Wi-Fi; nhập địa chỉ điện thoại thủ công |
| Đang chạy được rồi ngừng sau khi điện thoại khởi động lại | Chế độ TCP cổ điển bị đặt lại khi khởi động | Bật lại gỡ lỗi Wi-Fi qua USB |
| "The device declined the authorization request" (thiết bị từ chối xác thực) | Hộp thoại trên điện thoại bị bỏ qua | Kết nối lại và chạm Cho phép |
| Cần "Wireless debugging" của Android 11+ bằng mã ghép đôi | Chưa được hỗ trợ | Dùng cách cổ điển ở trên |
Nếu không tìm thấy điện thoại, xem Cách sửa lỗi ADB "device busy", "unauthorized" và "no devices". Muốn hiểu nền tảng về ADB qua Wi-Fi, đọc ADB qua Wi-Fi: kết nối thiết bị Android không cần cáp. Khi công cụ đã chạy, mở workspace ADBKit và chọn Connect over Wi-Fi.