Hướng dẫn tích hợp API kiểm tra mở cổng TCP/UDP, nhận diện Client IP và Quản trị hệ thống từ bên ngoài web.
Dành cho trang chủ, ứng dụng di động, tiện ích desktop hoặc lệnh curl tự động. Cho phép lấy IP/thông tin Client và kiểm tra khả năng mở của 1 cổng TCP hoặc UDP bất kỳ ngoài Internet.
GET /api/client-infoPOST /api/checkDành riêng cho quản trị viên, script CI/CD giám sát máy chủ hoặc bot quản lý hạ tầng. Cho phép quét dải cổng (X đến Y) song song, xem/sửa cấu hình hệ thống, quản lý mẫu preset và đọc log.
X-Admin-Key: <API_KEY> hoặc Authorization: Bearer <API_KEY>
application/json (hoặc text/plain với lệnh curl).
Trả về địa chỉ IP công cộng của client cùng thông tin phân tích mạng chuyên sâu (như trang ip-info): nhận diện User-Agent (trình duyệt, HĐH, thiết bị), kiểm tra Proxy/VPN/Cloudflare, tên miền phân giải ngược (PTR), cổng nguồn ephemeral port và ngôn ngữ.
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| format | string | Tùy chọn | Nhận json (mặc định) hoặc text (chỉ in raw IP, rất tiện cho lệnh bash/curl). |
# Lấy toàn bộ thông tin JSON chi tiết
curl -s https://portcheck.trong.pro/api/client-info
# Hoặc chỉ lấy địa chỉ IP dạng chuỗi văn bản (Plain Text)
curl -s "https://portcheck.trong.pro/api/client-info?format=text"
{
"client_ip": "113.161.45.12",
"ip": {
"client_ip": "113.161.45.12",
"remote_addr": "113.161.45.12",
"remote_port": 54210,
"reverse_dns": "static.viettel.vn",
"is_ipv6": false
},
"proxy": {
"is_proxy_or_vpn": false,
"verdict": "direct",
"label_vi": "Kết nối trực tiếp (Không phát hiện Proxy/VPN)",
"label_en": "Direct Connection (No Proxy/VPN Detected)",
"detected_headers": {},
"claimed_ip": null,
"is_trusted_proxy": false
},
"user_agent": {
"raw": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
"browser": { "name": "Google Chrome", "version": "122.0.0.0" },
"os": { "name": "Windows", "version": "10 / 11" },
"device_type": "Desktop"
},
"connection": {
"protocol": "HTTP/2.0",
"https": true,
"accept_language": "vi-VN,vi;q=0.9,en-US;q=0.8,en;q=0.7",
"primary_language": "Tiếng Việt (vi-VN)",
"accept_encoding": "gzip, deflate, br",
"connection_header": "keep-alive"
},
"timestamp": "2026-10-18T16:00:00Z"
}
Thực hiện kiểm tra tính khả dụng của đúng một cổng TCP (bắt tay 3 bước SYN-ACK) hoặc UDP (gói tin thăm dò socket & kiểm tra lỗi ICMP) tới một địa chỉ IP công cộng hoặc tên miền FQDN.
400 port_blocked đối với khách thông thường.
| Trường | Kiểu | Bắt buộc | Mô tả & Ràng buộc |
|---|---|---|---|
| target | string | Bắt buộc | Địa chỉ IPv4, IPv6 hoặc tên miền FQDN (VD: 203.0.113.25 hoặc example.com). |
| port | integer | Bắt buộc | Số nguyên từ 1 đến 65535 (đúng 1 cổng mỗi lượt gọi). |
| protocol | string | Bắt buộc | Chỉ chấp nhận "tcp" hoặc "udp". |
curl -X POST https://portcheck.trong.pro/api/check \
-H "Content-Type: application/json" \
-d '{
"target": "google.com",
"port": 443,
"protocol": "tcp"
}'
{
"target": "google.com",
"resolved_ip": "142.250.204.46",
"port": 443,
"protocol": "tcp",
"status": "open",
"method": "php_socket",
"latency_ms": 14.8,
"reason": "connection_succeeded",
"diagnostics": [
"Máy chủ đích đã chấp nhận kết nối TCP (SYN-ACK) và hoàn tất bắt tay 3 bước từ VPS."
],
"checked_at": "2026-10-18T16:05:00Z"
}
Mọi yêu cầu gửi tới Admin API từ app bên ngoài hoặc script tự động phải kèm theo Secret API Key thông qua một trong hai HTTP header:
* Lưu ý: Khi gọi bằng API Key, hệ thống tự động cho phép thực thi mà không cần token CSRF trình duyệt. Bạn có thể thay đổi API Key này trong tệp config/config.php.
Quét song song đa cổng trong dải từ start_port đến end_port (tối đa 100-200 cổng cùng lúc) bằng kiến trúc Non-blocking Socket (stream_select) với tốc độ chỉ 1–2 giây. Bỏ qua hoàn toàn danh sách cổng bị chặn (blocked_ports).
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| target | string | Bắt buộc | IP công cộng hoặc FQDN của máy chủ cần quét. |
| start_port | integer | Bắt buộc | Cổng bắt đầu dải (VD: 20). |
| end_port | integer | Bắt buộc | Cổng kết thúc dải (VD: 100). Khoảng cách tối đa tuân theo cấu hình max_scan_range. |
| protocol | string | Bắt buộc | "tcp" hoặc "udp". |
curl -X POST https://portcheck.trong.pro/api/admin/scan \
-H "X-Admin-Key: portcheck_admin_secret_key_2026" \
-H "Content-Type: application/json" \
-d '{
"target": "scanme.nmap.org",
"start_port": 20,
"end_port": 100,
"protocol": "tcp"
}'
{
"success": true,
"target": "scanme.nmap.org",
"resolved_ip": "45.33.32.156",
"protocol": "tcp",
"start_port": 20,
"end_port": 25,
"count": 6,
"results": [
{ "port": 20, "status": "closed", "latency_ms": 210.4 },
{ "port": 21, "status": "closed", "latency_ms": 208.7 },
{ "port": 22, "status": "open", "latency_ms": 215.1 },
{ "port": 23, "status": "closed", "latency_ms": 209.3 },
{ "port": 24, "status": "closed", "latency_ms": 211.0 },
{ "port": 25, "status": "filtered", "latency_ms": null }
]
}
Truy xuất hoặc cập nhật động cấu hình hệ thống: danh sách cổng cấm blocked_ports, thời gian chờ timeout, giới hạn tần suất rate-limits, mức concurrency và dải cổng scan tối đa.
curl -s https://portcheck.trong.pro/admin/api.php?action=get_config \
-H "X-Admin-Key: portcheck_admin_secret_key_2026"
Truy xuất nhật ký kiểm tra cổng và chẩn đoán gần nhất của hệ thống phục vụ giám sát và lưu trữ kiểm toán.
curl -s https://portcheck.trong.pro/admin/api.php?action=get_logs \
-H "X-Admin-Key: portcheck_admin_secret_key_2026"
| Mã HTTP | Trạng thái / Error Code | Ý nghĩa & Biện pháp xử lý |
|---|---|---|
| 200 OK | success: true |
Yêu cầu kiểm tra hoặc truy xuất thông tin thành công. |
| 400 Bad Request | invalid_target |
Mục tiêu không hợp lệ, không phân giải được DNS hoặc vi phạm chính sách địa chỉ IP công cộng (SSRF loopback/private). |
| 400 Bad Request | port_blocked |
Cổng nằm trong danh sách cấm của hệ thống (VD: 25, 445). Khách cần liên hệ admin hoặc sử dụng Admin API. |
| 401 Unauthorized | unauthorized |
Chưa xác thực quyền quản trị. Thiếu hoặc sai header X-Admin-Key / phiên session hết hạn. |
| 403 Forbidden | csrf_invalid |
Mã xác thực CSRF không hợp lệ (áp dụng khi gọi từ trình duyệt mà không dùng API Key). |
| 429 Too Many Requests | rate_limited |
Vượt quá giới hạn tần suất yêu cầu (Mặc định 15 req/phút mỗi IP hoặc giới hạn đồng thời Concurrency). Hãy đợi trước khi thử lại. |
| 500 Internal Error | internal_error |
Lỗi nội bộ hệ thống trong quá trình khởi tạo socket mạng. |
Khi nhận được tên miền (VD: example.com), máy chủ giải quyết toàn bộ bản ghi DNS A và AAAA. Nếu bất kỳ địa chỉ nào trả về là IP nội bộ, loopback (127.0.0.1), cloud metadata (169.254.169.254), CGNAT hay dải mạng riêng tư (RFC 1918), yêu cầu lập tức bị hủy bỏ và trả về 400 Bad Request. Kết nối socket được tạo trực tiếp tới IP đã kiểm duyệt để chống triệt để kỹ thuật tấn công DNS Rebinding.
Hệ thống áp dụng thuật toán Sliding Window và Concurrency Slots (khóa tệp nguyên tử flock không phong tỏa) để đảm bảo không bị cạn kiệt tài nguyên mạng (file descriptors). Khách thông thường được cấp tối đa 15 yêu cầu / 60 giây và tối đa 5 kết nối đồng thời.