fix(data-provider): skip unavailable optional fetchers and back off longbridge reconnects (#1249)

* fix(data-provider): skip unavailable optional fetchers and back off longbridge reconnects

* fix(data-provider): back off unavailable longbridge routes

* fix(data-provider): back off noisy pytdx name lookups

* docs: align PR 1249 changelog and compatibility notes

* fix(config): preserve legacy schedule override precedence

Author: zbl-96

.env.example

@@ -31,6 +31,8 @@ TUSHARE_TOKEN=
 # LONGBRIDGE_ACCESS_TOKEN=
 # static_info 进程内缓存秒数，默认 86400；0=每次请求拉取
 # LONGBRIDGE_STATIC_INFO_TTL_SECONDS=86400
+# 连接关闭类异常后的冷却秒数，默认 15；冷却期内会临时跳过 Longbridge，避免请求级频繁重连
+# LONGBRIDGE_CONNECTION_COOLDOWN_SECONDS=15
 # Longbridge SDK 语言与 REPORT_LANGUAGE（zh/en）一致；SDK 日志写入 LOG_DIR/longbridge_sdk.log
 # 接入点（与 REPORT_LANGUAGE 无关；留空则用下列默认值）：
 # LONGBRIDGE_HTTP_URL=https://openapi.longbridge.com
@@ -564,6 +566,7 @@ SCHEDULE_ENABLED=false
 # 每日执行时间（HH:MM 格式，24小时制）
 SCHEDULE_TIME=18:00
 # 定时模式启动时是否立即执行一次分析（true/false）
+# 若未显式设置，定时模式会沿用 RUN_IMMEDIATELY 的运行时覆盖语义以兼容旧配置
 SCHEDULE_RUN_IMMEDIATELY=true
 # 非定时模式启动时是否立即执行一次分析（true/false）
 RUN_IMMEDIATELY=true

data_provider/base.py

@@ -36,6 +36,7 @@
 logger = logging.getLogger(__name__)
 
 _DEFAULT_STATIC_INFO_TTL = 86400  # 24h
+_DEFAULT_CONNECTION_COOLDOWN_SECONDS = 15
 
 
 def _static_info_ttl_seconds() -> int:
@@ -49,6 +50,17 @@ def _static_info_ttl_seconds() -> int:
         return _DEFAULT_STATIC_INFO_TTL
 
 
+def _connection_cooldown_seconds() -> int:
+    """Cooldown after connection-close errors to avoid reconnect thrashing."""
+    raw = os.getenv("LONGBRIDGE_CONNECTION_COOLDOWN_SECONDS", "").strip()
+    if raw == "":
+        return _DEFAULT_CONNECTION_COOLDOWN_SECONDS
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return _DEFAULT_CONNECTION_COOLDOWN_SECONDS
+
+
 _REGION_URL_MAP: Dict[str, Dict[str, str]] = {
     "cn": {
         "http_url": "https://openapi.longbridge.cn",
@@ -271,6 +283,7 @@ def __init__(self):
         self._config = None
         self._ctx_lock = threading.Lock()
         self._available = None
+        self._cooldown_until = 0.0
         # {symbol: (StaticInfo, timestamp)}
         self._static_cache: Dict[str, Any] = {}
         self._static_cache_lock = threading.Lock()
@@ -285,6 +298,33 @@ def _invalidate_ctx(self):
             self._ctx = None
             self._config = None
 
+    def _mark_connection_cooldown(self, exc: Exception) -> None:
+        cooldown_seconds = _connection_cooldown_seconds()
+        self._invalidate_ctx()
+        if cooldown_seconds <= 0:
+            return
+        self._cooldown_until = time.time() + cooldown_seconds
+        logger.warning(
+            "[Longbridge] 检测到连接异常，进入 %ss 冷却期以避免频繁重连: %s",
+            cooldown_seconds,
+            exc,
+        )
+
+    def is_available_for_request(self, capability: str = "") -> bool:
+        """Report request-time availability including temporary cooldown."""
+        if not self._is_available():
+            return False
+        if self._cooldown_until > time.time():
+            logger.debug(
+                "[Longbridge] %s 冷却中，暂时跳过请求，剩余 %.1fs",
+                capability or "request",
+                self._cooldown_until - time.time(),
+            )
+            return False
+        if self._cooldown_until:
+            self._cooldown_until = 0.0
+        return True
+
     def _is_available(self) -> bool:
         """Check if Longbridge credentials are configured."""
         if self._available is not None:
@@ -417,7 +457,7 @@ def _get_static_info(self, symbol: str) -> Optional[Any]:
         except Exception as e:
             logger.debug(f"[Longbridge] static_info({symbol}) 失败: {e}")
             if self._is_connection_error(e):
-                self._invalidate_ctx()
+                self._mark_connection_cooldown(e)
         return None
 
     # ------------------------------------------------------------------
@@ -499,7 +539,7 @@ def _compute_volume_ratio(self, symbol: str, today_volume: int) -> Optional[floa
 
     def get_realtime_quote(self, stock_code: str) -> Optional[UnifiedRealtimeQuote]:
         """Fetch realtime quote from Longbridge, computing derived fields."""
-        if not self._is_available():
+        if not self.is_available_for_request("realtime_quote"):
             return None
 
         symbol = _to_longbridge_symbol(stock_code)
@@ -519,8 +559,7 @@ def get_realtime_quote(self, stock_code: str) -> Optional[UnifiedRealtimeQuote]:
         except Exception as e:
             logger.info(f"[Longbridge] quote({symbol}) 失败: {e}")
             if self._is_connection_error(e):
-                logger.warning("[Longbridge] 检测到连接已断开，将在下次调用时重建连接")
-                self._invalidate_ctx()
+                self._mark_connection_cooldown(e)
             return None
 
         price = safe_float(getattr(q, "last_done", None))
@@ -627,6 +666,9 @@ def _fetch_raw_data(
         self, stock_code: str, start_date: str, end_date: str
     ) -> pd.DataFrame:
         """Fetch historical candlesticks from Longbridge."""
+        if not self.is_available_for_request("daily_data"):
+            raise RuntimeError("Longbridge temporarily unavailable for daily_data")
+
         symbol = _to_longbridge_symbol(stock_code)
         if symbol is None:
             raise ValueError(f"Cannot convert {stock_code} to Longbridge symbol")
@@ -650,8 +692,7 @@ def _fetch_raw_data(
             )
         except Exception as e:
             if self._is_connection_error(e):
-                logger.warning("[Longbridge] 检测到连接已断开，将在下次调用时重建连接")
-                self._invalidate_ctx()
+                self._mark_connection_cooldown(e)
             raise
 
         if not candles:

data_provider/longbridge_fetcher.py

@@ -16,6 +16,7 @@
 
 import logging
 import re
+import time
 from contextlib import contextmanager
 from typing import Optional, Generator, List, Tuple
 
@@ -28,11 +29,20 @@
     before_sleep_log,
 )
 
-from .base import BaseFetcher, DataFetchError, STANDARD_COLUMNS, is_bse_code, _is_hk_market
+from .base import (
+    BaseFetcher,
+    DataFetchError,
+    DataSourceUnavailableError,
+    STANDARD_COLUMNS,
+    is_bse_code,
+    _is_hk_market,
+)
 import os
 
 logger = logging.getLogger(__name__)
 
+_PYTDX_CONNECTION_COOLDOWN_SECONDS = 15.0
+
 
 def _parse_hosts_from_env() -> Optional[List[Tuple[str, int]]]:
     """
@@ -139,6 +149,23 @@ def __init__(self, hosts: Optional[List[Tuple[str, int]]] = None):
         self._current_host_idx = 0
         self._stock_list_cache = None  # 股票列表缓存
         self._stock_name_cache = {}    # 股票名称缓存 {code: name}
+        self._unavailable_until = 0.0
+        self._last_unavailable_reason = ""
+
+    def _is_in_connection_cooldown(self) -> bool:
+        return time.time() < self._unavailable_until
+
+    def _mark_connection_cooldown(self, reason: str) -> None:
+        self._unavailable_until = time.time() + _PYTDX_CONNECTION_COOLDOWN_SECONDS
+        self._last_unavailable_reason = str(reason or "").strip()
+        logger.info(
+            "Pytdx 连接失败，进入冷却 %.0fs: %s",
+            _PYTDX_CONNECTION_COOLDOWN_SECONDS,
+            self._last_unavailable_reason or "unknown",
+        )
+
+    def is_available_for_request(self, capability: str = "") -> bool:
+        return not self._is_in_connection_cooldown()
 
     def _get_pytdx(self):
         """
@@ -167,6 +194,11 @@ def _pytdx_session(self) -> Generator:
             with self._pytdx_session() as api:
                 # 在这里执行数据查询
         """
+        if self._is_in_connection_cooldown():
+            raise DataSourceUnavailableError(
+                f"Pytdx temporarily unavailable: {self._last_unavailable_reason or 'connection cooldown'}"
+            )
+
         TdxHq_API = self._get_pytdx()
         if TdxHq_API is None:
             raise DataFetchError("pytdx 库未安装")
@@ -191,6 +223,7 @@ def _pytdx_session(self) -> Generator:
                     continue
 
             if not connected:
+                self._mark_connection_cooldown("Pytdx 无法连接任何服务器")
                 raise DataFetchError("Pytdx 无法连接任何服务器")
 
             yield api
@@ -400,7 +433,7 @@ def get_stock_name(self, stock_code: str) -> Optional[str]:
                     return name
 
         except Exception as e:
-            logger.warning(f"Pytdx 获取股票名称失败 {stock_code}: {e}")
+            logger.debug(f"Pytdx 获取股票名称失败 {stock_code}: {e}")
 
         return None
 

data_provider/pytdx_fetcher.py

@@ -11,6 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 <!-- 新条目格式：- [类型] 描述（类型取值：新功能/改进/修复/文档/测试/chore）-->
 <!-- 每条独立一行追加到本段末尾，无需分类标题，合并时冲突最小 -->
+- [修复] 未配置 Tushare / Longbridge 凭据时不再实例化对应可选 fetcher，避免缺失凭据的数据源进入候选集。
+- [修复] Longbridge 遇到连接关闭类异常后会进入冷却期，并在美股/港股实时与日线请求中临时跳过该数据源，避免请求级频繁重连。
+- [修复] Pytdx 股票名称查询在全部服务器不可达时会短暂冷却，并在冷却期内跳过重复探测，减少无效拨号与告警噪音。
+- [修复] 调度模式未显式设置 `SCHEDULE_RUN_IMMEDIATELY` 时，会继续继承 `RUN_IMMEDIATELY` 的运行时覆盖语义，避免被持久化 `.env` 别名反向覆盖。
+- [文档] 补充 Longbridge 冷却开关与调度启动兼容语义说明。
 
 - [新功能] Web 系统设置页开放 `.env` 配置备份导入/导出，复用键级覆盖、配置版本冲突保护和重载链路；Web 端在 `ADMIN_AUTH_ENABLED=false` 时该入口为禁用状态。
 - [chore] 精简仓库根目录：将文档图片资源迁入 `docs/assets/`，将东方财富请求补丁迁入 `src/patches/`，并下移 CI 专用依赖文件与技能适配服务。

docs/CHANGELOG.md

@@ -145,6 +145,7 @@ daily_stock_analysis/
 | `LONGBRIDGE_APP_SECRET` | Longbridge App Secret | 可选 |
 | `LONGBRIDGE_ACCESS_TOKEN` | Longbridge Access Token | 可选 |
 | `LONGBRIDGE_STATIC_INFO_TTL_SECONDS` | 长桥 `static_info` 进程内缓存秒数（默认 86400，0=不缓存） | 可选 |
+| `LONGBRIDGE_CONNECTION_COOLDOWN_SECONDS` | 长桥连接关闭类异常后的冷却秒数（默认 15；冷却期内临时跳过 Longbridge，避免频繁重连） | 可选 |
 | `LONGBRIDGE_HTTP_URL` | HTTP 接口地址（默认 `https://openapi.longbridge.com`） | 可选 |
 | `LONGBRIDGE_QUOTE_WS_URL` | 行情 WebSocket 地址（默认 `wss://openapi-quote.longbridge.com/v2`） | 可选 |
 | `LONGBRIDGE_TRADE_WS_URL` | 交易 WebSocket 地址（默认 `wss://openapi-trade.longbridge.com/v2`） | 可选 |
@@ -156,6 +157,8 @@ daily_stock_analysis/
 
 > **GitHub Actions：** 仓库自带 `daily_analysis.yml` 已把上表中的 `LONGBRIDGE_*` 映射到任务环境。若未在 **Settings → Secrets and variables → Actions** 中配置 `LONGBRIDGE_APP_KEY`、`LONGBRIDGE_APP_SECRET`、`LONGBRIDGE_ACCESS_TOKEN`，CI 内不会调用长桥（日志中一般看不到 `[Longbridge]` 相关行情行）。可选接入点变量（如 `LONGBRIDGE_REGION`）可放在 **Variables** 或 **Secrets**。
 
+> **Longbridge 运行时行为：** 未配置凭据时不会实例化 Longbridge 这个可选 fetcher；若运行时遇到 `client is closed`、`context closed`、`connection closed` 等连接关闭类异常，会进入冷却期（默认 15 秒，可用 `LONGBRIDGE_CONNECTION_COOLDOWN_SECONDS` 调整），冷却期内美股/港股的实时与日线请求会自动跳过 Longbridge，退回 YFinance / AkShare 等兜底链路。
+
 > 补充说明
 - TUSHARE_TOKEN，当此参数配置后，但不具备港股日线接口权限时，也会出现港股数据查询不出来或者错误的情况，和老版本提示不支持港股效果相同
 
@@ -306,7 +309,7 @@ daily_stock_analysis/
 | `LONGBRIDGE_APP_KEY` | [Longbridge OpenAPI](https://open.longbridge.com/) App Key；配置后美股/港股的量比、换手率、PE 等 YFinance 缺失字段会自动从长桥补充 | - | 可选 |
 | `LONGBRIDGE_APP_SECRET` | Longbridge App Secret | - | 可选 |
 | `LONGBRIDGE_ACCESS_TOKEN` | Longbridge Access Token | - | 可选 |
-| `LONGBRIDGE_*`（可选） | 见官方 [环境变量](https://open.longbridge.com/zh-CN/docs/getting-started#环境变量)；另有 `LONGBRIDGE_STATIC_INFO_TTL_SECONDS` | - | 可选 |
+| `LONGBRIDGE_*`（可选） | 见官方 [环境变量](https://open.longbridge.com/zh-CN/docs/getting-started#环境变量)；另有 `LONGBRIDGE_STATIC_INFO_TTL_SECONDS` 与 `LONGBRIDGE_CONNECTION_COOLDOWN_SECONDS` | - | 可选 |
 | `ENABLE_REALTIME_QUOTE` | 启用实时行情（关闭后使用历史收盘价分析） | `true` | 可选 |
 | `ENABLE_REALTIME_TECHNICAL_INDICATORS` | 盘中实时技术面：启用时用实时价计算 MA5/MA10/MA20 与多头排列（Issue #234）；关闭则用昨日收盘 | `true` | 可选 |
 | `ENABLE_CHIP_DISTRIBUTION` | 启用筹码分布分析（该接口不稳定，云端部署建议关闭）。GitHub Actions 用户需在 Repository Variables 中设置 `ENABLE_CHIP_DISTRIBUTION=true` 方可启用；workflow 默认关闭。 | `true` | 可选 |
@@ -630,7 +633,8 @@ python main.py --schedule --no-run-immediately
 |--------|------|:-------:|:-----:|
 | `SCHEDULE_ENABLED` | 是否启用定时任务 | `false` | `true` |
 | `SCHEDULE_TIME` | 每日执行时间 (HH:MM) | `18:00` | `09:30` |
-| `SCHEDULE_RUN_IMMEDIATELY` | 启动服务时是否立即运行一次 | `true` | `false` |
+| `SCHEDULE_RUN_IMMEDIATELY` | 定时模式启动时是否立即运行一次；未显式设置时沿用 `RUN_IMMEDIATELY` 的运行时覆盖语义 | `true` | `false` |
+| `RUN_IMMEDIATELY` | 非定时模式启动时是否立即运行一次；同时作为未显式设置 `SCHEDULE_RUN_IMMEDIATELY` 时的 legacy 回退 | `true` | `false` |
 | `TRADING_DAY_CHECK_ENABLED` | 交易日检查：非交易日跳过执行；设为 `false` 可强制执行 | `true` | `false` |
 
 例如在 Docker 中配置：
@@ -640,6 +644,8 @@ python main.py --schedule --no-run-immediately
 docker run -e SCHEDULE_ENABLED=true -e SCHEDULE_RUN_IMMEDIATELY=false ...
 ```
 
+> 兼容说明：如果运行时显式传入 `RUN_IMMEDIATELY`，但没有单独传 `SCHEDULE_RUN_IMMEDIATELY`，内置调度模式会继续继承前者，避免被 `.env` 中持久化的 `SCHEDULE_RUN_IMMEDIATELY` 旧值反向覆盖。
+
 #### 交易日判断（Issue #373）
 
 默认根据自选股市场（A 股 / 港股 / 美股）和 `MARKET_REVIEW_REGION` 判断是否为交易日：
@@ -898,9 +904,11 @@ PUSHOVER_API_TOKEN=your_api_token
 - 美股/港股数据兜底，补充 YFinance 缺失的量比、换手率、PE 等字段
 - 需从 [open.longbridge.com](https://open.longbridge.com/) 注册并获取 App Key / App Secret / Access Token
 - 设置 `LONGBRIDGE_APP_KEY`、`LONGBRIDGE_APP_SECRET`、`LONGBRIDGE_ACCESS_TOKEN`
+- 可选设置 `LONGBRIDGE_CONNECTION_COOLDOWN_SECONDS` 控制连接关闭类异常后的冷却秒数（默认 15）
 - 接入点可配 `LONGBRIDGE_HTTP_URL`、`LONGBRIDGE_QUOTE_WS_URL`、`LONGBRIDGE_TRADE_WS_URL`、`LONGBRIDGE_REGION`
 - 其余可选参数见官方 [环境变量说明](https://open.longbridge.com/zh-CN/docs/getting-started#环境变量)
 - 仅在 YFinance（美股）或 AkShare（港股）返回数据不完整时自动触发，不影响 A 股链路
+- 未配置凭据时不会实例化该可选数据源；若运行时出现连接关闭类异常，会在冷却期内临时跳过 Longbridge，避免请求级频繁重连
 
 ### 东财接口频繁失败时的处理
 

docs/full-guide.md

@@ -315,13 +315,16 @@ For the P0 notification baseline and diagnostics, see [Notification Baseline](no
 | `MARKET_REVIEW_REGION` | Market review region: cn (A-shares), hk (HK stocks), us (US stocks), both (all three markets) | `cn` |
 | `SCHEDULE_ENABLED` | Enable scheduled tasks | `false` |
 | `SCHEDULE_TIME` | Scheduled execution time | `18:00` |
+| `SCHEDULE_RUN_IMMEDIATELY` | Run once immediately when scheduler mode starts; when unset it keeps following the legacy `RUN_IMMEDIATELY` runtime override | `true` |
+| `RUN_IMMEDIATELY` | Run once immediately for non-scheduler startup; also acts as the legacy fallback when `SCHEDULE_RUN_IMMEDIATELY` is unset | `true` |
 | `LOG_DIR` | Log directory | `./logs` |
 
 > Behavior notes:
 > - When `TICKFLOW_API_KEY` is configured, CN market review first tries TickFlow for main indices. Market breadth also tries TickFlow only when the current TickFlow plan supports universe queries.
 > - TickFlow behavior is capability-based rather than just key-based: limited plans can still enhance main CN indices, while plans with `CN_Equity_A` universe query support also enhance market breadth.
 > - The official quickstart documents `quotes.get(universes=["CN_Equity_A"])`, but online smoke tests confirmed two additional real-world constraints: universe access depends on plan permissions, and `quotes.get(symbols=[...])` has a per-request symbol limit.
 > - TickFlow currently returns `change_pct` / `amplitude` as ratio values; this integration normalizes them to the project's percent convention so they match AkShare / Tushare / efinance semantics.
+> - In scheduler mode, if runtime env explicitly sets `RUN_IMMEDIATELY` but does not set `SCHEDULE_RUN_IMMEDIATELY`, the scheduler keeps inheriting the legacy runtime override instead of being pulled back to a persisted `.env` alias value.
 > - CN market review reports now use a post-market workstation layout with fixed market light, market temperature, index detail, sector Top tables, news catalysts, next-session plan, and risk sections. Missing data sources degrade by omitting or simplifying only the affected block.
 > - Per-stock analysis, realtime quote priority, and sector rankings fallback remain unchanged.
 
@@ -779,6 +782,13 @@ System defaults to AkShare (free), also supports other data sources:
 - Supports US/HK stock data
 - US stock historical and real-time data both use YFinance exclusively to avoid technical indicator errors from akshare's US stock adjustment issues
 
+### Longbridge
+- Optional fallback for US/HK stocks, mainly used to supplement fields that YFinance may miss
+- Configure `LONGBRIDGE_APP_KEY`, `LONGBRIDGE_APP_SECRET`, and `LONGBRIDGE_ACCESS_TOKEN`
+- Optional knobs: `LONGBRIDGE_STATIC_INFO_TTL_SECONDS` (default `86400`) and `LONGBRIDGE_CONNECTION_COOLDOWN_SECONDS` (default `15`)
+- If credentials are absent, the optional Longbridge fetcher is not instantiated
+- When runtime errors such as `client is closed`, `context closed`, or `connection closed` occur, Longbridge enters a short cooldown window and US/HK daily or realtime requests automatically fall back to YFinance / AkShare instead of reconnecting on every request
+
 ---
 
 ## Advanced Features
@@ -791,7 +801,7 @@ Use `hk` prefix for HK stock codes:
 STOCK_LIST=600519,hk00700,hk01810
 ```
 
-HK daily history skips efinance, pytdx, baostock, and other built-in providers that do not support HK daily data, avoiding mismatches between HK symbols and non-HK market data. AkShare/Tushare/YFinance/Longbridge continue to provide HK fallback paths.
+HK daily history skips efinance, pytdx, baostock, and other built-in providers that do not support HK daily data, avoiding mismatches between HK symbols and non-HK market data. AkShare/Tushare/YFinance/Longbridge continue to provide HK fallback paths. If Longbridge is inside its connection cooldown window, the route temporarily skips it and continues with the remaining HK-capable fallbacks.
 
 ### Multi-Model Switching