fh_tool-cli 0.2.4__tar.gz → 0.2.5__tar.gz

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fh_tool-cli
-Version: 0.2.4
+Version: 0.2.5
 Summary: 用于本地管理 FiberHome fh_tool 接口的 Python CLI
 Author: Gxxk
 License-Expression: AGPL-3.0-or-later
@@ -82,11 +82,12 @@ fh-tool dev-info --ip 192.168.1.1 --mac AABBCCDDEEFF
 
 ## 常用命令
 
-低风险 probe：
+低风险 probe（输出 `fh_port`/`fh_port_source` 与各候选端口 `fh_ports` 明细，可用于诊断 fh_tool API 所在端口）：
 
 ```bash
 fh-tool probe
 fh-tool probe --json
+fh-tool probe --fh-port 80
 ```
 
 读取设备信息：
@@ -129,6 +130,29 @@ fh-tool telnet enable --confirm
 fh-tool ports --ports 23,80,443,8080
 ```
 
+## fh_tool 端口与型号/固件兼容性
+
+不同型号/固件的 fh_tool 后端监听端口可能不同。大多数固件在 `8080`，但例如 **HG6142A3（固件 V03.00.M0000）** 的 fh_tool API 位于 `http://192.168.1.1:80/fh_tool/api`（80 端口）。
+
+工具默认行为：
+
+1. 先尝试默认端口 `8080`；
+2. 仅当 `8080` TCP 不可达时，自动探测候选端口（当前为 `80`，用 `GetDevInfo` / HTTP surface 验证），并在结果 JSON 的 `fh_port`/`fh_port_source` 字段中说明最终使用的端口和来源（`argument`/`default`/`auto_detected`/`default_unverified`）；
+3. 探测失败时沿用 `8080` 并在错误信息中给出引导。
+
+也可以显式指定端口（跳过探测）：
+
+```bash
+fh-tool dev-info --fh-port 80
+fh-tool call --func GetDevInfo --fh-port 80
+```
+
+已知局限：
+
+- 如果 `8080` 与 `80` 同时 TCP 开放、但 fh_tool API 只在 `80`，TCP 快筛会停留在 `8080` 并以 HTTP/解密错误失败，此时需要 `--fh-port 80` 显式指定；`fh-tool probe --json` 的 `fh_ports` 字段可以诊断这种场景。
+- 设备返回的绝对下载 URL（含端口）按原样使用，不会重写端口。
+- `HTTP 4xx/5xx`、解密失败不会触发端口切换——那说明 8080 上有 HTTP 服务，问题在路径/协议/MAC 而非端口。
+
 ## 本地 VM 测试环境
 
 如果已经在 `/mnt/dev-cold/HG5143F-ONU-vm` 启动本地 userspace VM，可直接用它测试 `cfg_cmd` 和 Web AJAX，不需要碰真实网关：
@@ -358,7 +382,3 @@ fh-tool telnet disable --confirm
 ## License
 
 AGPL-3.0-or-later
-
-## 其它
-
-[认可 LINUX DO](https://linux.do)

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/README.md

@@ -66,11 +66,12 @@ fh-tool dev-info --ip 192.168.1.1 --mac AABBCCDDEEFF
 
 ## 常用命令
 
-低风险 probe：
+低风险 probe（输出 `fh_port`/`fh_port_source` 与各候选端口 `fh_ports` 明细，可用于诊断 fh_tool API 所在端口）：
 
 ```bash
 fh-tool probe
 fh-tool probe --json
+fh-tool probe --fh-port 80
 ```
 
 读取设备信息：
@@ -113,6 +114,29 @@ fh-tool telnet enable --confirm
 fh-tool ports --ports 23,80,443,8080
 ```
 
+## fh_tool 端口与型号/固件兼容性
+
+不同型号/固件的 fh_tool 后端监听端口可能不同。大多数固件在 `8080`，但例如 **HG6142A3（固件 V03.00.M0000）** 的 fh_tool API 位于 `http://192.168.1.1:80/fh_tool/api`（80 端口）。
+
+工具默认行为：
+
+1. 先尝试默认端口 `8080`；
+2. 仅当 `8080` TCP 不可达时，自动探测候选端口（当前为 `80`，用 `GetDevInfo` / HTTP surface 验证），并在结果 JSON 的 `fh_port`/`fh_port_source` 字段中说明最终使用的端口和来源（`argument`/`default`/`auto_detected`/`default_unverified`）；
+3. 探测失败时沿用 `8080` 并在错误信息中给出引导。
+
+也可以显式指定端口（跳过探测）：
+
+```bash
+fh-tool dev-info --fh-port 80
+fh-tool call --func GetDevInfo --fh-port 80
+```
+
+已知局限：
+
+- 如果 `8080` 与 `80` 同时 TCP 开放、但 fh_tool API 只在 `80`，TCP 快筛会停留在 `8080` 并以 HTTP/解密错误失败，此时需要 `--fh-port 80` 显式指定；`fh-tool probe --json` 的 `fh_ports` 字段可以诊断这种场景。
+- 设备返回的绝对下载 URL（含端口）按原样使用，不会重写端口。
+- `HTTP 4xx/5xx`、解密失败不会触发端口切换——那说明 8080 上有 HTTP 服务，问题在路径/协议/MAC 而非端口。
+
 ## 本地 VM 测试环境
 
 如果已经在 `/mnt/dev-cold/HG5143F-ONU-vm` 启动本地 userspace VM，可直接用它测试 `cfg_cmd` 和 Web AJAX，不需要碰真实网关：
@@ -342,7 +366,3 @@ fh-tool telnet disable --confirm
 ## License
 
 AGPL-3.0-or-later
-
-## 其它
-
-[认可 LINUX DO](https://linux.do)

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fh_tool-cli"
-version = "0.2.4"
+version = "0.2.5"
 description = "用于本地管理 FiberHome fh_tool 接口的 Python CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/src/fh_tool_cli/__init__.py

@@ -1,3 +1,3 @@
 """Local CLI for FiberHome fh_tool endpoints."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.5"

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/src/fh_tool_cli/argparse_utils.py

@@ -25,6 +25,16 @@ def parse_ports(value: str) -> list[int]:
     return ports
 
 
+def normalize_port(value: str) -> int:
+    try:
+        port = int(value, 10)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"不符规范的 port: {value}") from exc
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError(f"port 超出范围: {value}")
+    return port
+
+
 def parse_scalar(value: str) -> Any:
     lowered = value.lower()
     if lowered == "true":

fh_tool_cli-0.2.5/src/fh_tool_cli/backends/fh_tool.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import Any
+
+import requests
+
+from ..client import tcp_open
+from ..config_store import format_mac, resolve_ip, resolve_mac
+from ..crypto import decrypt_payload, derive_crypto, encrypt_payload
+from ..errors import FHToolError
+from ..fh_endpoints import (
+    DEFAULT_FH_TOOL_PORT,
+    FALLBACK_FH_TOOL_PORTS,
+    PORT_PROBE_TCP_TIMEOUT,
+    fh_tool_url,
+)
+from ..output import log_event
+
+FH_TOOL_API_PATH = "/fh_tool/api"
+FH_TOOL_UPLOAD_PATH = "/fh_tool/upload"
+TOOL_DOWNLOAD_PATH = "/fh_tool/tool_download"
+SURFACE_PROBE_PATHS = (FH_TOOL_API_PATH, FH_TOOL_UPLOAD_PATH, TOOL_DOWNLOAD_PATH)
+
+
+def fh_tool_call(
+    ip: str,
+    mac: str,
+    payload: dict[str, Any],
+    timeout: float,
+    *,
+    port: int = DEFAULT_FH_TOOL_PORT,
+) -> dict[str, Any]:
+    crypto = derive_crypto(mac)
+    encrypted = encrypt_payload(payload, crypto)
+    url = fh_tool_url(ip, port, FH_TOOL_API_PATH)
+    func = str(payload.get("func", "unknown"))
+    log_event(logging.INFO, "fh_tool.api.request", ip=ip, port=port, path=FH_TOOL_API_PATH, func=func)
+    try:
+        response = requests.post(
+            url,
+            data=encrypted,
+            headers={
+                "Content-Type": "text/plain",
+                "Connection": "close",
+            },
+            timeout=timeout,
+            allow_redirects=False,
+        )
+    except requests.RequestException as exc:
+        log_event(logging.INFO, "fh_tool.api.error", ip=ip, path=FH_TOOL_API_PATH, func=func, error=str(exc))
+        raise FHToolError(f"无法连接 {url}: {exc}") from exc
+
+    if response.status_code != 200:
+        log_event(
+            logging.INFO,
+            "fh_tool.api.http_error",
+            ip=ip,
+            path=FH_TOOL_API_PATH,
+            func=func,
+            status_code=response.status_code,
+        )
+        raise FHToolError(f"{FH_TOOL_API_PATH} 返回 HTTP {response.status_code}")
+
+    try:
+        result = decrypt_payload(response.text, crypto)
+    except Exception as exc:
+        log_event(logging.INFO, "fh_tool.api.decrypt_error", ip=ip, path=FH_TOOL_API_PATH, func=func)
+        raise FHToolError("响应解密失败，MAC 可能不匹配或固件协议不同") from exc
+    log_event(
+        logging.INFO,
+        "fh_tool.api.response",
+        ip=ip,
+        path=FH_TOOL_API_PATH,
+        func=func,
+        status_code=response.status_code,
+        result=result.get("result") if isinstance(result, dict) else None,
+    )
+    return result
+
+
+def api_payload(func: str, params: dict[str, Any] | None = None, index: str = "1") -> dict[str, Any]:
+    payload: dict[str, Any] = {"index": str(index), "func": func}
+    if params:
+        payload.update(params)
+    return payload
+
+
+def verify_fh_tool_port(ip: str, port: int, mac: str, timeout: float) -> bool:
+    try:
+        result = fh_tool_call(ip, mac, api_payload("GetDevInfo"), timeout, port=port)
+    except FHToolError:
+        return False
+    return result.get("result") == 0
+
+
+def _surface_reachable(ip: str, port: int, timeout: float) -> bool:
+    url = fh_tool_url(ip, port, FH_TOOL_API_PATH)
+    try:
+        response = requests.get(url, timeout=timeout, allow_redirects=False)
+    except requests.RequestException:
+        return False
+    log_event(logging.DEBUG, "fh_tool.port.surface", ip=ip, port=port, status_code=response.status_code)
+    return True
+
+
+def resolve_fh_port(
+    args: argparse.Namespace,
+    ip: str,
+    *,
+    mac: str | None = None,
+    timeout: float,
+    candidates: tuple[int, ...] = FALLBACK_FH_TOOL_PORTS,
+) -> tuple[int, str]:
+    """解析 fh_tool 后端端口：显式 --fh-port > 8080 TCP 快筛 > 候选端口探测 > 回退默认。
+
+    仅当 8080 TCP 不可达时才触发候选端口探测；HTTP 4xx/5xx、解密失败不触发切换。
+    """
+    explicit = getattr(args, "fh_port", None)
+    if explicit is not None:
+        log_event(logging.DEBUG, "fh_tool.port.explicit", ip=ip, port=explicit)
+        return explicit, "argument"
+
+    tcp_timeout = min(timeout, PORT_PROBE_TCP_TIMEOUT)
+    if tcp_open(ip, DEFAULT_FH_TOOL_PORT, tcp_timeout):
+        log_event(logging.DEBUG, "fh_tool.port.default_ok", ip=ip, port=DEFAULT_FH_TOOL_PORT)
+        return DEFAULT_FH_TOOL_PORT, "default"
+
+    tried: list[int] = []
+    for port in candidates:
+        if port == DEFAULT_FH_TOOL_PORT:
+            continue
+        tried.append(port)
+        if not tcp_open(ip, port, tcp_timeout):
+            continue
+        verified_by = "surface"
+        if mac:
+            if verify_fh_tool_port(ip, port, mac, timeout):
+                verified_by = "getdevinfo"
+            elif not _surface_reachable(ip, port, timeout):
+                continue
+        log_event(
+            logging.INFO,
+            "fh_tool.port.fallback_selected",
+            ip=ip,
+            port=port,
+            default_port=DEFAULT_FH_TOOL_PORT,
+            verified_by=verified_by,
+        )
+        return port, "auto_detected"
+
+    log_event(
+        logging.INFO,
+        "fh_tool.port.fallback_failed",
+        ip=ip,
+        tried=tried,
+        default_port=DEFAULT_FH_TOOL_PORT,
+    )
+    return DEFAULT_FH_TOOL_PORT, "default_unverified"
+
+
+def _unverified_port_hint(exc: FHToolError) -> FHToolError:
+    candidates = ", ".join(str(port) for port in FALLBACK_FH_TOOL_PORTS)
+    return FHToolError(
+        f"{exc}\n"
+        f"（提示：已自动探测候选端口 {candidates}，未发现 fh_tool 服务。"
+        "可运行 fh-tool probe 查看各端口/路径状态，或用 --fh-port 显式指定端口；"
+        "部分型号/固件（如 HG6142A3 V03.00.M0000）的 fh_tool API 在 80 端口）"
+    )
+
+
+def probe_fh_port_candidates(
+    ip: str,
+    mac: str | None,
+    timeout: float,
+    ports: tuple[int, ...] | None = None,
+) -> dict[str, dict[str, Any]]:
+    """对候选端口逐个报告 tcp/surface/getdevinfo 状态，供 probe 命令诊断端点。"""
+    if ports is None:
+        ports = tuple(dict.fromkeys([DEFAULT_FH_TOOL_PORT, *FALLBACK_FH_TOOL_PORTS]))
+    tcp_timeout = min(timeout, PORT_PROBE_TCP_TIMEOUT)
+    report: dict[str, dict[str, Any]] = {}
+    for port in ports:
+        entry: dict[str, Any] = {
+            "tcp": tcp_open(ip, port, tcp_timeout),
+            "surface": {},
+            "getdevinfo": None,
+        }
+        for path in SURFACE_PROBE_PATHS:
+            url = fh_tool_url(ip, port, path)
+            try:
+                response = requests.get(url, timeout=timeout, allow_redirects=False)
+                entry["surface"][path] = {
+                    "status_code": response.status_code,
+                    "content_type": response.headers.get("Content-Type"),
+                }
+            except requests.RequestException as exc:
+                entry["surface"][path] = {"error": str(exc)}
+        if mac and entry["tcp"]:
+            try:
+                dev_info = fh_tool_call(ip, mac, api_payload("GetDevInfo"), timeout, port=port)
+                entry["getdevinfo"] = {
+                    "ok": dev_info.get("result") == 0,
+                    "response": dev_info,
+                }
+            except FHToolError as exc:
+                entry["getdevinfo"] = {"ok": False, "error": str(exc)}
+        report[str(port)] = entry
+    return report
+
+
+def call_method(args: argparse.Namespace, func: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    ip, ip_source = resolve_ip(args)
+    mac, mac_source = resolve_mac(args, ip, required=True)
+    assert mac is not None
+    port, port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
+    try:
+        response = fh_tool_call(ip, mac, api_payload(func, params), args.timeout, port=port)
+    except FHToolError as exc:
+        if port_source == "default_unverified":
+            raise _unverified_port_hint(exc) from exc
+        raise
+    return {
+        "ip": ip,
+        "ip_source": ip_source,
+        "mac": format_mac(mac),
+        "mac_source": mac_source,
+        "fh_port": port,
+        "fh_port_source": port_source,
+        "request": api_payload(func, params),
+        "response": response,
+    }
+
+
+def response_download_url(response: dict[str, Any]) -> str:
+    url = response.get("Dowloadurl") or response.get("Downloadurl") or response.get("downloadurl")
+    if not isinstance(url, str) or not url:
+        raise FHToolError(f"响应中没有 Dowloadurl: {response}")
+    return url

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/src/fh_tool_cli/cli.py

@@ -21,9 +21,13 @@ from .argparse_utils import parse_json_object, parse_kv, parse_ports
 from .backends.fh_tool import (
     FH_TOOL_API_PATH,
     FH_TOOL_UPLOAD_PATH,
+    TOOL_DOWNLOAD_PATH,
     api_payload,
     call_method,
     fh_tool_call,
+    fh_tool_url,
+    probe_fh_port_candidates,
+    resolve_fh_port,
     response_download_url,
 )
 from .backup import (
@@ -184,6 +188,7 @@ def command_probe(args: argparse.Namespace) -> dict[str, Any]:
     ip, ip_source = resolve_ip(args)
     mac, mac_source = resolve_mac(args, ip, required=False, allow_prompt=False)
     ports = parse_ports(args.ports)
+    fh_port, fh_port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
 
     result: dict[str, Any] = {
         "mode": "probe",
@@ -191,13 +196,16 @@ def command_probe(args: argparse.Namespace) -> dict[str, Any]:
         "ip_source": ip_source,
         "mac": format_mac(mac) if mac else None,
         "mac_source": mac_source,
+        "fh_port": fh_port,
+        "fh_port_source": fh_port_source,
         "tcp": {str(port): tcp_open(ip, port, args.timeout) for port in ports},
         "surface": {},
         "fh_tool_probe": None,
+        "fh_ports": probe_fh_port_candidates(ip, mac, args.timeout),
     }
 
-    for path in [FH_TOOL_API_PATH, FH_TOOL_UPLOAD_PATH, "/fh_tool/tool_download"]:
-        url = f"http://{ip}:8080{path}"
+    for path in [FH_TOOL_API_PATH, FH_TOOL_UPLOAD_PATH, TOOL_DOWNLOAD_PATH]:
+        url = fh_tool_url(ip, fh_port, path)
         try:
             response = requests.get(url, timeout=args.timeout, allow_redirects=False)
             result["surface"][path] = {
@@ -214,6 +222,7 @@ def command_probe(args: argparse.Namespace) -> dict[str, Any]:
                 mac,
                 api_payload("GetDevInfo"),
                 args.timeout,
+                port=fh_port,
             )
             result["fh_tool_probe"] = {
                 "func": "GetDevInfo",
@@ -810,6 +819,7 @@ def command_log_download(args: argparse.Namespace) -> dict[str, Any]:
             url_value,
             Path(args.output).expanduser(),
             args.timeout,
+            port=result["fh_port"],
         )
     return result
 
@@ -851,7 +861,7 @@ def command_download_file(args: argparse.Namespace) -> dict[str, Any]:
         output = Path(args.output).expanduser()
     else:
         output = Path.cwd() / Path(url_value.split("?", 1)[0]).name
-    result["download"] = download_to_file(result["ip"], url_value, output, args.timeout)
+    result["download"] = download_to_file(result["ip"], url_value, output, args.timeout, port=result["fh_port"])
     return result
 
 
@@ -983,14 +993,19 @@ def command_raw_call(args: argparse.Namespace) -> dict[str, Any]:
 
 def command_download_url(args: argparse.Namespace) -> dict[str, Any]:
     ip, ip_source = resolve_ip(args)
+    mac, _mac_source = resolve_mac(args, ip, required=False, allow_prompt=False)
+    fh_port, fh_port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
     return {
         "ip": ip,
         "ip_source": ip_source,
+        "fh_port": fh_port,
+        "fh_port_source": fh_port_source,
         "download": download_to_file(
             ip,
             args.url,
             Path(args.output).expanduser(),
             args.timeout,
+            port=fh_port,
         ),
     }
 
@@ -998,6 +1013,8 @@ def command_download_url(args: argparse.Namespace) -> dict[str, Any]:
 def command_upload(args: argparse.Namespace) -> dict[str, Any]:
     dry_run = not is_confirmed(args)
     ip, ip_source = resolve_ip(args)
+    mac, _mac_source = resolve_mac(args, ip, required=False, allow_prompt=False)
+    fh_port, fh_port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
     file_path = Path(args.file).expanduser()
     result = upload_file(
         ip=ip,
@@ -1005,9 +1022,12 @@ def command_upload(args: argparse.Namespace) -> dict[str, Any]:
         file_path=file_path,
         sessionid=args.sessionid,
         timeout=args.timeout,
+        port=fh_port,
         dry_run=dry_run,
     )
     result["ip_source"] = ip_source
+    result["fh_port"] = fh_port
+    result["fh_port_source"] = fh_port_source
     if dry_run:
         _attach_dry_run_notice(result)
     return result

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/src/fh_tool_cli/client.py

@@ -9,6 +9,7 @@ from urllib.parse import urljoin
 import requests
 
 from .errors import FHToolError
+from .fh_endpoints import DEFAULT_FH_TOOL_PORT
 from .output import log_event
 
 
@@ -23,14 +24,21 @@ def tcp_open(ip: str, port: int, timeout: float) -> bool:
         return False
 
 
-def make_download_url(ip: str, value: str) -> str:
+def make_download_url(ip: str, value: str, port: int = DEFAULT_FH_TOOL_PORT) -> str:
     if value.startswith("http://") or value.startswith("https://"):
         return value
-    return urljoin(f"http://{ip}:8080", value)
+    return urljoin(f"http://{ip}:{port}", value)
 
 
-def download_to_file(ip: str, url_value: str, output: Path, timeout: float) -> dict[str, Any]:
-    url = make_download_url(ip, url_value)
+def download_to_file(
+    ip: str,
+    url_value: str,
+    output: Path,
+    timeout: float,
+    *,
+    port: int = DEFAULT_FH_TOOL_PORT,
+) -> dict[str, Any]:
+    url = make_download_url(ip, url_value, port)
     log_event(logging.INFO, "download.start", url=url, output=str(output))
     try:
         response = requests.get(url, timeout=timeout, stream=True)

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/src/fh_tool_cli/commands/web.py

@@ -10,7 +10,7 @@ from typing import Any
 from ..account import WEB_ADMIN_PASSWORD_PATH
 from ..argparse_utils import parse_json_object, parse_kv
 from ..backends.cfg_cmd import CfgCmdBackend
-from ..backends.fh_tool import api_payload, fh_tool_call
+from ..backends.fh_tool import api_payload, fh_tool_call, resolve_fh_port
 from ..backends.local_vm import DEFAULT_VM_ROOT, LocalVmShell
 from ..backends.telnet import TelnetCredentials, TelnetShell
 from ..backends.web_ajax import DEFAULT_AJAX_PATH, DEFAULT_WEB_LOGIN_PORT, WebAjaxClient
@@ -182,7 +182,8 @@ def _web_password_from_admin_account(args: argparse.Namespace) -> str:
     ip, _ip_source = resolve_ip(args)
     mac, _mac_source = resolve_mac(args, ip, required=True, allow_prompt=True)
     assert mac is not None
-    result = fh_tool_call(ip, mac, api_payload("GetAdminAccount"), args.timeout)
+    fh_port, _fh_port_source = resolve_fh_port(args, ip, mac=mac, timeout=args.timeout)
+    result = fh_tool_call(ip, mac, api_payload("GetAdminAccount"), args.timeout, port=fh_port)
     password = _extract_password_from_mapping(result)
     if not password:
         raise FHToolError("GetAdminAccount 响应中没有可用 password 字段")

fh_tool_cli-0.2.5/src/fh_tool_cli/fh_endpoints.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+# fh_tool 后端端点常量与 URL 构造。
+# 独立成模块以避免 client.py 与 backends.fh_tool 之间的循环导入：
+# backends.fh_tool 导入 client.tcp_open，而 client.py 需要这里的默认端口。
+
+DEFAULT_FH_TOOL_PORT = 8080
+# 8080 TCP 不可达时依次尝试的候选端口；HG6142A3 V03.00.M0000 实测 fh_tool API 在 80 端口。
+FALLBACK_FH_TOOL_PORTS = (80,)
+# TCP 探测超时上限（秒），控制候选端口全部不可达时的最坏延迟。
+PORT_PROBE_TCP_TIMEOUT = 2.0
+
+
+def fh_tool_base_url(ip: str, port: int) -> str:
+    return f"http://{ip}:{port}"
+
+
+def fh_tool_url(ip: str, port: int, path: str) -> str:
+    return f"{fh_tool_base_url(ip, port)}{path}"

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/src/fh_tool_cli/parser.py

@@ -6,6 +6,7 @@ from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
 
+from .argparse_utils import normalize_port
 from .backends.local_vm import DEFAULT_VM_ROOT
 from .backup import DEFAULT_DEVICE_RESTORE_CHUNK_SIZE, DEFAULT_DEVICE_RESTORE_TMPDIR
 from .commands.web import register_web_commands
@@ -34,6 +35,12 @@ def add_common_options(parser: argparse.ArgumentParser) -> None:
         default=5.0,
         help="HTTP/TCP timeout 秒数，默认 5",
     )
+    parser.add_argument(
+        "--fh-port",
+        type=normalize_port,
+        default=None,
+        help="fh_tool API 端口；默认先 8080，TCP 不可达时自动探测候选端口（如 80）。显式指定后跳过探测",
+    )
     parser.add_argument(
         "--config",
         default=str(DEFAULT_CONFIG_PATH),

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/src/fh_tool_cli/upload.py

@@ -10,6 +10,7 @@ import requests
 
 from .backends.fh_tool import FH_TOOL_UPLOAD_PATH
 from .errors import CliError
+from .fh_endpoints import DEFAULT_FH_TOOL_PORT
 
 UPLOAD_ACTIONS = {"upgradeimage", "preconfig"}
 REDACTED = "[REDACTED]"
@@ -37,11 +38,12 @@ def upload_file(
     file_path: Path,
     sessionid: str,
     timeout: float,
+    port: int = DEFAULT_FH_TOOL_PORT,
     dry_run: bool = False,
     post: Callable[..., Any] = requests.post,
 ) -> dict[str, Any]:
     file_info = _validate_upload_inputs(action, file_path, sessionid)
-    url = f"http://{ip}:8080{FH_TOOL_UPLOAD_PATH}?action={action}"
+    url = f"http://{ip}:{port}{FH_TOOL_UPLOAD_PATH}?action={action}"
     base = _upload_result_base(
         ip=ip,
         url=url,

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/src/fh_tool_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fh_tool-cli
-Version: 0.2.4
+Version: 0.2.5
 Summary: 用于本地管理 FiberHome fh_tool 接口的 Python CLI
 Author: Gxxk
 License-Expression: AGPL-3.0-or-later
@@ -82,11 +82,12 @@ fh-tool dev-info --ip 192.168.1.1 --mac AABBCCDDEEFF
 
 ## 常用命令
 
-低风险 probe：
+低风险 probe（输出 `fh_port`/`fh_port_source` 与各候选端口 `fh_ports` 明细，可用于诊断 fh_tool API 所在端口）：
 
 ```bash
 fh-tool probe
 fh-tool probe --json
+fh-tool probe --fh-port 80
 ```
 
 读取设备信息：
@@ -129,6 +130,29 @@ fh-tool telnet enable --confirm
 fh-tool ports --ports 23,80,443,8080
 ```
 
+## fh_tool 端口与型号/固件兼容性
+
+不同型号/固件的 fh_tool 后端监听端口可能不同。大多数固件在 `8080`，但例如 **HG6142A3（固件 V03.00.M0000）** 的 fh_tool API 位于 `http://192.168.1.1:80/fh_tool/api`（80 端口）。
+
+工具默认行为：
+
+1. 先尝试默认端口 `8080`；
+2. 仅当 `8080` TCP 不可达时，自动探测候选端口（当前为 `80`，用 `GetDevInfo` / HTTP surface 验证），并在结果 JSON 的 `fh_port`/`fh_port_source` 字段中说明最终使用的端口和来源（`argument`/`default`/`auto_detected`/`default_unverified`）；
+3. 探测失败时沿用 `8080` 并在错误信息中给出引导。
+
+也可以显式指定端口（跳过探测）：
+
+```bash
+fh-tool dev-info --fh-port 80
+fh-tool call --func GetDevInfo --fh-port 80
+```
+
+已知局限：
+
+- 如果 `8080` 与 `80` 同时 TCP 开放、但 fh_tool API 只在 `80`，TCP 快筛会停留在 `8080` 并以 HTTP/解密错误失败，此时需要 `--fh-port 80` 显式指定；`fh-tool probe --json` 的 `fh_ports` 字段可以诊断这种场景。
+- 设备返回的绝对下载 URL（含端口）按原样使用，不会重写端口。
+- `HTTP 4xx/5xx`、解密失败不会触发端口切换——那说明 8080 上有 HTTP 服务，问题在路径/协议/MAC 而非端口。
+
 ## 本地 VM 测试环境
 
 如果已经在 `/mnt/dev-cold/HG5143F-ONU-vm` 启动本地 userspace VM，可直接用它测试 `cfg_cmd` 和 Web AJAX，不需要碰真实网关：
@@ -358,7 +382,3 @@ fh-tool telnet disable --confirm
 ## License
 
 AGPL-3.0-or-later
-
-## 其它
-
-[认可 LINUX DO](https://linux.do)

{fh_tool_cli-0.2.4 → fh_tool_cli-0.2.5}/src/fh_tool_cli.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ src/fh_tool_cli/credentials.py
 src/fh_tool_cli/crypto.py
 src/fh_tool_cli/diagnostics.py
 src/fh_tool_cli/errors.py
+src/fh_tool_cli/fh_endpoints.py
 src/fh_tool_cli/output.py
 src/fh_tool_cli/parser.py
 src/fh_tool_cli/remote.py
@@ -48,6 +49,7 @@ tests/test_config_decrypt.py
 tests/test_credentials.py
 tests/test_diagnostics.py
 tests/test_extracted_helpers.py
+tests/test_fh_port.py
 tests/test_local_vm_integration.py
 tests/test_parser_registration.py
 tests/test_remote.py

fh_tool_cli-0.2.5/tests/test_fh_port.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import argparse
+import contextlib
+import io
+import json
+import unittest
+from unittest.mock import patch
+
+import requests
+
+from fh_tool_cli import cli
+from fh_tool_cli.argparse_utils import normalize_port
+from fh_tool_cli.backends.fh_tool import (
+    api_payload,
+    call_method,
+    fh_tool_call,
+    probe_fh_port_candidates,
+    resolve_fh_port,
+)
+from fh_tool_cli.client import make_download_url
+from fh_tool_cli.crypto import derive_crypto, encrypt_payload
+from fh_tool_cli.errors import FHToolError
+
+TEST_IP = "192.168.1.1"
+TEST_MAC = "AABBCCDDEEFF"
+
+
+class _FakeResponse:
+    def __init__(self, status_code: int = 200, text: str = "", headers: dict[str, str] | None = None):
+        self.status_code = status_code
+        self.text = text
+        self.headers = headers or {}
+
+
+def _encrypted_ok_response(result: int = 0) -> _FakeResponse:
+    crypto = derive_crypto(TEST_MAC)
+    return _FakeResponse(status_code=200, text=encrypt_payload({"result": result}, crypto))
+
+
+def _args(**overrides) -> argparse.Namespace:
+    values: dict = {
+        "ip": TEST_IP,
+        "mac": TEST_MAC,
+        "timeout": 1.0,
+        "fh_port": None,
+        "config": "/nonexistent/fh-tool-test.json",
+        "ask_mac": False,
+        "json": True,
+    }
+    values.update(overrides)
+    return argparse.Namespace(**values)
+
+
+class NormalizePortTests(unittest.TestCase):
+    def test_accepts_valid_port(self) -> None:
+        self.assertEqual(normalize_port("80"), 80)
+        self.assertEqual(normalize_port("65535"), 65535)
+
+    def test_rejects_zero(self) -> None:
+        with self.assertRaises(argparse.ArgumentTypeError):
+            normalize_port("0")
+
+    def test_rejects_out_of_range(self) -> None:
+        with self.assertRaises(argparse.ArgumentTypeError):
+            normalize_port("70000")
+
+    def test_rejects_non_numeric(self) -> None:
+        with self.assertRaises(argparse.ArgumentTypeError):
+            normalize_port("abc")
+
+
+class ResolveFhPortTests(unittest.TestCase):
+    def test_explicit_argument_skips_probing(self) -> None:
+        with patch("fh_tool_cli.backends.fh_tool.tcp_open", side_effect=AssertionError("should not probe")):
+            self.assertEqual(
+                resolve_fh_port(_args(fh_port=80), TEST_IP, mac=TEST_MAC, timeout=1.0),
+                (80, "argument"),
+            )
+
+    def test_default_8080_when_tcp_open(self) -> None:
+        with patch("fh_tool_cli.backends.fh_tool.tcp_open", return_value=True) as tcp_mock:
+            self.assertEqual(
+                resolve_fh_port(_args(), TEST_IP, mac=TEST_MAC, timeout=1.0),
+                (8080, "default"),
+            )
+        tcp_mock.assert_called_once_with(TEST_IP, 8080, 1.0)
+
+    def test_fallback_detected_by_getdevinfo(self) -> None:
+        with (
+            patch("fh_tool_cli.backends.fh_tool.tcp_open", side_effect=[False, True]),
+            patch("fh_tool_cli.backends.fh_tool.verify_fh_tool_port", return_value=True) as verify_mock,
+        ):
+            self.assertEqual(
+                resolve_fh_port(_args(), TEST_IP, mac=TEST_MAC, timeout=1.0),
+                (80, "auto_detected"),
+            )
+        verify_mock.assert_called_once_with(TEST_IP, 80, TEST_MAC, 1.0)
+
+    def test_fallback_detected_by_surface_when_getdevinfo_fails(self) -> None:
+        with (
+            patch("fh_tool_cli.backends.fh_tool.tcp_open", side_effect=[False, True]),
+            patch("fh_tool_cli.backends.fh_tool.verify_fh_tool_port", return_value=False),
+            patch("fh_tool_cli.backends.fh_tool.requests.get", return_value=_FakeResponse(404)),
+        ):
+            self.assertEqual(
+                resolve_fh_port(_args(), TEST_IP, mac=TEST_MAC, timeout=1.0),
+                (80, "auto_detected"),
+            )
+
+    def test_fallback_skips_candidate_when_surface_unreachable(self) -> None:
+        with (
+            patch("fh_tool_cli.backends.fh_tool.tcp_open", side_effect=[False, True]),
+            patch("fh_tool_cli.backends.fh_tool.verify_fh_tool_port", return_value=False),
+            patch(
+                "fh_tool_cli.backends.fh_tool.requests.get",
+                side_effect=requests.ConnectionError("refused"),
+            ),
+        ):
+            self.assertEqual(
+                resolve_fh_port(_args(), TEST_IP, mac=TEST_MAC, timeout=1.0),
+                (8080, "default_unverified"),
+            )
+
+    def test_all_closed_falls_back_to_default_unverified(self) -> None:
+        with patch("fh_tool_cli.backends.fh_tool.tcp_open", return_value=False):
+            self.assertEqual(
+                resolve_fh_port(_args(), TEST_IP, mac=TEST_MAC, timeout=1.0),
+                (8080, "default_unverified"),
+            )
+
+    def test_default_port_candidates_are_skipped(self) -> None:
+        with patch("fh_tool_cli.backends.fh_tool.tcp_open", return_value=False) as tcp_mock:
+            self.assertEqual(
+                resolve_fh_port(_args(), TEST_IP, mac=TEST_MAC, timeout=1.0, candidates=(8080,)),
+                (8080, "default_unverified"),
+            )
+        tcp_mock.assert_called_once_with(TEST_IP, 8080, 1.0)
+
+    def test_missing_fh_port_attr_is_tolerated(self) -> None:
+        with patch("fh_tool_cli.backends.fh_tool.tcp_open", return_value=True):
+            self.assertEqual(
+                resolve_fh_port(argparse.Namespace(ip=TEST_IP), TEST_IP, timeout=1.0),
+                (8080, "default"),
+            )
+
+
+class FhToolCallUrlTests(unittest.TestCase):
+    def test_uses_explicit_port_in_url(self) -> None:
+        with patch("fh_tool_cli.backends.fh_tool.requests.post", return_value=_encrypted_ok_response()) as post_mock:
+            result = fh_tool_call(TEST_IP, TEST_MAC, api_payload("GetDevInfo"), 1.0, port=80)
+        self.assertEqual(result, {"result": 0})
+        self.assertEqual(post_mock.call_args.args[0], "http://192.168.1.1:80/fh_tool/api")
+
+    def test_default_port_is_8080(self) -> None:
+        with patch("fh_tool_cli.backends.fh_tool.requests.post", return_value=_encrypted_ok_response()) as post_mock:
+            fh_tool_call(TEST_IP, TEST_MAC, api_payload("GetDevInfo"), 1.0)
+        self.assertEqual(post_mock.call_args.args[0], "http://192.168.1.1:8080/fh_tool/api")
+
+
+class MakeDownloadUrlTests(unittest.TestCase):
+    def test_default_port(self) -> None:
+        self.assertEqual(make_download_url(TEST_IP, "/fh_tool/tool_download?a=b"), "http://192.168.1.1:8080/fh_tool/tool_download?a=b")
+
+    def test_explicit_port(self) -> None:
+        self.assertEqual(make_download_url(TEST_IP, "/fh_tool/tool_download", port=80), "http://192.168.1.1:80/fh_tool/tool_download")
+
+    def test_absolute_url_is_untouched(self) -> None:
+        self.assertEqual(make_download_url(TEST_IP, "http://example.com/file.bin", port=80), "http://example.com/file.bin")
+
+
+class CallMethodTests(unittest.TestCase):
+    def test_result_contains_default_port_fields(self) -> None:
+        with (
+            patch("fh_tool_cli.backends.fh_tool.tcp_open", return_value=True),
+            patch("fh_tool_cli.backends.fh_tool.requests.post", return_value=_encrypted_ok_response()),
+        ):
+            result = call_method(_args(), "GetDevInfo")
+        self.assertEqual(result["fh_port"], 8080)
+        self.assertEqual(result["fh_port_source"], "default")
+
+    def test_result_uses_explicit_port_end_to_end(self) -> None:
+        with (
+            patch("fh_tool_cli.backends.fh_tool.tcp_open", side_effect=AssertionError("should not probe")),
+            patch("fh_tool_cli.backends.fh_tool.requests.post", return_value=_encrypted_ok_response()) as post_mock,
+        ):
+            result = call_method(_args(fh_port=80), "GetDevInfo")
+        self.assertEqual(result["fh_port"], 80)
+        self.assertEqual(result["fh_port_source"], "argument")
+        self.assertEqual(post_mock.call_args.args[0], "http://192.168.1.1:80/fh_tool/api")
+
+    def test_unverified_port_appends_hint(self) -> None:
+        with (
+            patch("fh_tool_cli.backends.fh_tool.tcp_open", return_value=False),
+            patch(
+                "fh_tool_cli.backends.fh_tool.requests.post",
+                side_effect=requests.ConnectionError("connection refused"),
+            ),
+        ):
+            with self.assertRaises(FHToolError) as ctx:
+                call_method(_args(), "GetDevInfo")
+        message = str(ctx.exception)
+        self.assertIn("--fh-port", message)
+        self.assertIn("fh-tool probe", message)
+        self.assertIn("HG6142A3", message)
+
+    def test_http_error_on_default_port_does_not_append_hint(self) -> None:
+        with (
+            patch("fh_tool_cli.backends.fh_tool.tcp_open", return_value=True),
+            patch("fh_tool_cli.backends.fh_tool.requests.post", return_value=_FakeResponse(500)),
+        ):
+            with self.assertRaises(FHToolError) as ctx:
+                call_method(_args(), "GetDevInfo")
+        self.assertNotIn("--fh-port", str(ctx.exception))
+
+
+class ProbeFhPortCandidatesTests(unittest.TestCase):
+    def test_reports_per_port_surface_without_mac(self) -> None:
+        with (
+            patch("fh_tool_cli.backends.fh_tool.tcp_open", side_effect=[False, True]),
+            patch("fh_tool_cli.backends.fh_tool.requests.get", return_value=_FakeResponse(404, headers={"Content-Type": "text/html"})),
+        ):
+            report = probe_fh_port_candidates(TEST_IP, None, 1.0)
+        self.assertEqual(set(report), {"8080", "80"})
+        self.assertFalse(report["8080"]["tcp"])
+        self.assertTrue(report["80"]["tcp"])
+        self.assertEqual(report["80"]["surface"]["/fh_tool/api"]["status_code"], 404)
+        self.assertIsNone(report["80"]["getdevinfo"])
+
+    def test_getdevinfo_verified_with_mac(self) -> None:
+        with (
+            patch("fh_tool_cli.backends.fh_tool.tcp_open", side_effect=[False, True]),
+            patch("fh_tool_cli.backends.fh_tool.fh_tool_call", return_value={"result": 0}),
+        ):
+            report = probe_fh_port_candidates(TEST_IP, TEST_MAC, 1.0)
+        self.assertTrue(report["80"]["getdevinfo"]["ok"])
+        self.assertTrue(report["8080"]["getdevinfo"] is None)
+
+
+class CliEndToEndTests(unittest.TestCase):
+    def test_call_with_fh_port_80_sends_to_port_80(self) -> None:
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        with (
+            patch("fh_tool_cli.backends.fh_tool.requests.post", return_value=_encrypted_ok_response()) as post_mock,
+            contextlib.redirect_stdout(stdout),
+            contextlib.redirect_stderr(stderr),
+        ):
+            exit_code = cli.main(
+                [
+                    "call",
+                    "--func",
+                    "GetDevInfo",
+                    "--fh-port",
+                    "80",
+                    "--ip",
+                    TEST_IP,
+                    "--mac",
+                    TEST_MAC,
+                    "--timeout",
+                    "1",
+                    "--json",
+                ]
+            )
+        self.assertEqual(exit_code, 0)
+        payload = json.loads(stdout.getvalue())
+        self.assertEqual(payload["fh_port"], 80)
+        self.assertEqual(payload["fh_port_source"], "argument")
+        self.assertTrue(post_mock.call_args.args[0].startswith("http://192.168.1.1:80/"))
+
+
+if __name__ == "__main__":
+    unittest.main()

fh_tool_cli-0.2.4/src/fh_tool_cli/backends/fh_tool.py

@@ -1,98 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import logging
-from typing import Any
-
-import requests
-
-from ..config_store import format_mac, resolve_ip, resolve_mac
-from ..crypto import decrypt_payload, derive_crypto, encrypt_payload
-from ..errors import FHToolError
-from ..output import log_event
-
-FH_TOOL_API_PATH = "/fh_tool/api"
-FH_TOOL_UPLOAD_PATH = "/fh_tool/upload"
-
-
-def fh_tool_call(
-    ip: str,
-    mac: str,
-    payload: dict[str, Any],
-    timeout: float,
-) -> dict[str, Any]:
-    crypto = derive_crypto(mac)
-    encrypted = encrypt_payload(payload, crypto)
-    url = f"http://{ip}:8080{FH_TOOL_API_PATH}"
-    func = str(payload.get("func", "unknown"))
-    log_event(logging.INFO, "fh_tool.api.request", ip=ip, path=FH_TOOL_API_PATH, func=func)
-    try:
-        response = requests.post(
-            url,
-            data=encrypted,
-            headers={
-                "Content-Type": "text/plain",
-                "Connection": "close",
-            },
-            timeout=timeout,
-            allow_redirects=False,
-        )
-    except requests.RequestException as exc:
-        log_event(logging.INFO, "fh_tool.api.error", ip=ip, path=FH_TOOL_API_PATH, func=func, error=str(exc))
-        raise FHToolError(f"无法连接 {url}: {exc}") from exc
-
-    if response.status_code != 200:
-        log_event(
-            logging.INFO,
-            "fh_tool.api.http_error",
-            ip=ip,
-            path=FH_TOOL_API_PATH,
-            func=func,
-            status_code=response.status_code,
-        )
-        raise FHToolError(f"{FH_TOOL_API_PATH} 返回 HTTP {response.status_code}")
-
-    try:
-        result = decrypt_payload(response.text, crypto)
-    except Exception as exc:
-        log_event(logging.INFO, "fh_tool.api.decrypt_error", ip=ip, path=FH_TOOL_API_PATH, func=func)
-        raise FHToolError("响应解密失败，MAC 可能不匹配或固件协议不同") from exc
-    log_event(
-        logging.INFO,
-        "fh_tool.api.response",
-        ip=ip,
-        path=FH_TOOL_API_PATH,
-        func=func,
-        status_code=response.status_code,
-        result=result.get("result") if isinstance(result, dict) else None,
-    )
-    return result
-
-
-def api_payload(func: str, params: dict[str, Any] | None = None, index: str = "1") -> dict[str, Any]:
-    payload: dict[str, Any] = {"index": str(index), "func": func}
-    if params:
-        payload.update(params)
-    return payload
-
-
-def call_method(args: argparse.Namespace, func: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
-    ip, ip_source = resolve_ip(args)
-    mac, mac_source = resolve_mac(args, ip, required=True)
-    assert mac is not None
-    response = fh_tool_call(ip, mac, api_payload(func, params), args.timeout)
-    return {
-        "ip": ip,
-        "ip_source": ip_source,
-        "mac": format_mac(mac),
-        "mac_source": mac_source,
-        "request": api_payload(func, params),
-        "response": response,
-    }
-
-
-def response_download_url(response: dict[str, Any]) -> str:
-    url = response.get("Dowloadurl") or response.get("Downloadurl") or response.get("downloadurl")
-    if not isinstance(url, str) or not url:
-        raise FHToolError(f"响应中没有 Dowloadurl: {response}")
-    return url