README.md

---

title: Stock Data API
sdk: docker
app_port: 7860
pinned: false
---


# 股票数据 API 服务

这个目录是从现有板块轮动、短线交易、龙头股分析技能中抽出来的统一数据服务骨架。

它适合部署到 Hugging Face Docker Space，对外提供统一 HTTP API，并用外部数据库缓存 AKShare、东方财富、同花顺、财联社等在线数据源返回的数据。

## 本地启动

```powershell

cd D:\Andy\coding\gupiao_data\stock_data_api_service

python -m uvicorn app.main:app --host 127.0.0.1 --port 7860

```

打开：

- `http://127.0.0.1:7860/health`
- `http://127.0.0.1:7860/docs`
- `http://127.0.0.1:7860/api/v1/catalog`

## Hugging Face 部署

1. 创建一个新的 Hugging Face Space。
2. SDK 选择 `Docker`。
3. 把本目录内容作为 Space 根目录提交。
4. 配置 Secrets：

| Secret | 说明 |
|---|---|
| `DATABASE_URL` | 外部 MySQL 连接串，例如 `mysql+pymysql://user:password@host:3306/dbname?charset=utf8mb4` |
| `DATABASE_SSL` | 可选，云 MySQL 要求 SSL 时设为 `true` |
| `STOCK_DATA_API_KEY` | 可选。配置后请求必须带 `X-API-Key` 或 `Authorization: Bearer ...` |
| `CACHE_ENABLED` | 可选，默认 `true` |
| `CACHE_TABLE_NAME` | 可选，默认 `api_cache`；复用已有数据库时建议改成独立表名 |
| `SOURCE_TIMEOUT_SECONDS` | 可选，默认 `15` |
| `SOURCE_RETRY_ATTEMPTS` | 可选，默认 `1`；关键接口可在代码中单独设为 `2` |
| `SOURCE_RETRY_BACKOFF_SECONDS` | 可选，默认 `0.5` |
| `SUPPRESS_SOURCE_OUTPUT` | 可选，默认 `true`，压制 AKShare 进度条等控制台输出 |

Hugging Face Docker Space 默认服务端口用 `7860`，本 Dockerfile 已经按这个端口启动。

## 主要接口

所有业务接口默认在 `/api/v1` 下：

| 接口 | 说明 | 默认缓存 |
|---|---|---|
| `GET /stocks/{code}/quote` | 个股最新行情 | 5 分钟 |
| `GET /stocks/{code}/daily?days=60` | 个股日 K | 200 天 |
| `GET /stocks/{code}/technical?days=120&history_days=10` | 技术指标 | 6 小时 |
| `GET /stocks/{code}/chip` | 筹码分布（精算版 CYQ，换手率衰减模型） | 1 天 |
| `GET /stocks/{code}/chip-simple?lookback_days=60` | 筹码估算（简化版，成交量加权） | 1 天 |
| `GET /stocks/{code}/fund-flow?days=10` | 个股资金流 | 1 小时 |
| `GET /stocks/{code}/margin?days=30` | 个股融资融券 | 4 小时 |
| `GET /stocks/{code}/shareholders?limit=12` | 股东户数历史 | 12 小时 |
| `GET /stocks/{code}/shareholder-top` | 前十大股东 | 12 小时 |
| `GET /fund-flow/rank?indicator=5日` | 个股资金排名 | 30 分钟 |
| `GET /market/limit-up` | 涨停池 | 10 分钟 |
| `GET /market/limit-down` | 跌停池 | 10 分钟 |
| `GET /market/breadth` | 市场宽度 | 30 分钟 |
| `GET /market/temperature` | 市场温度 | 15 分钟 |
| `GET /market/margin?limit=50` | 全市场融资融券汇总 | 4 小时 |
| `GET /market/northbound?days=30` | 北向资金历史日线 | 1 小时 |
| `GET /market/northbound/realtime` | 北向资金实时分钟 | 2 分钟 |
| `GET /market/northbound/holdings?stock_code=600519` | 北向资金持股明细 | 30 分钟 |
| `GET /market/shenwan-industry?limit=31` | 申万一级行业（含PE/PB分位） | 15 分钟 |
| `GET /market/fund-holdings?date=20260331` | 基金重仓股 | 4 小时 |
| `GET /market/fund-structure` | 基金持仓结构 | 12 小时 |
| `GET /boards/concepts/flow` | 概念板块资金 | 30 分钟 |
| `GET /boards/industries/flow` | 行业板块资金 | 30 分钟 |
| `GET /news/global` | 全市场财经新闻 | 1 小时 |
| `GET /stocks/{code}/news` | 个股新闻 | 1 小时 |
| `GET /stocks/{code}/notices` | 个股公告 | 6 小时 |
| `GET /stocks/{code}/financial?kind=abstract` | 财务摘要 / 指标 / 预告 / 快报 | 2 天 |
| `GET /stocks/{code}/income?kind=ytd` | 利润表（年初至今 / 单季） | 2 天 |
| `GET /stocks/{code}/balancesheet?limit=10` | 资产负债表（总资产、负债、权益等） | 2 天 |
| `GET /stocks/{code}/cashflow?kind=ytd` | 现金流量表（年初至今 / 单季） | 2 天 |
| `GET /stocks/{code}/dividends?kind=main` | 分红与配股方案 | 2 天 |
| `GET /stocks/{code}/equity-history` | 股本变动历史 | 2 天 |
| `GET /stocks/{code}/freeholders` | 十大流通股东 | 2 天 |
| `GET /stocks/{code}/daily-basic?days=30` | 每日基础指标（PE、PB、PS、市值、换手率） | 6 小时 |
| `GET /etfs/premium?sort=abs` | ETF 折溢价率列表 | 30 分钟 |
| `GET /etfs/{code}/premium` | 单只 ETF 折溢价率 | 5 分钟 |
| `GET /hk/stocks/{code}/short-selling` | 港股沽空记录（日度序列） | 6 小时 |
| `GET /market/trade-calendar` | A 股交易日历 | 1 天 |
| `GET /macro/china/{indicator}` | 中国宏观数据 | 2 天 |
| `GET /macro/chinabond/yield-curve` | 中债国债收益率曲线 | 1 天 |
| `GET /us/indices` | 美股三大指数（道指/纳指/标普） | 2 分钟 |
| `GET /us/sectors` | 美股行业/主题 ETF 映射（A 股映射） | 15 分钟 |
| `GET /us/market-summary` | 隔夜美股盘面摘要（策略语气+指引） | 5 分钟 |
| `GET /us/stocks/{symbol}/quote` | 美股个股报价（AAPL、^DJI 等） | 2 分钟 |
| `GET /us/stocks/{symbol}/daily` | 美股个股日 K | 6 小时 |
| `GET /social/x/timeline` | X/Twitter 关注账号时间线 | 5 分钟 |
| `POST /search` | LLM 金融搜索（Grok/OpenAI 兼容） | 1 小时 |
| `GET /search?q=...` | LLM 金融搜索（简易 GET） | 1 小时 |
| `POST /ai-search-hub/search` | 多平台 AI 聚合搜索 | 30 分钟 |
| `GET /ai-search-hub/search?q=...` | 多平台 AI 聚合搜索（简易 GET） | 30 分钟 |
| `GET /ai-search-hub/sites` | 查看可用搜索平台 | — |

股票类 `code` 支持 `600519`、`600519.SH`、`sh600519`、`000001.SZ` 等格式。ETF / 基金代码不要走 `/stocks/...`，应使用 `/etfs/...` 或 `/funds/...`；否则会返回 `400 invalid_symbol`。

## 返回格式

```json

{

  "ok": true,

  "data": {},

  "meta": {

    "endpoint": "stock_quote",

    "source": "akshare.stock_zh_a_spot_em",

    "generated_at": "2026-06-06T09:20:00+00:00",

    "cache": {

      "hit": false,

      "stale": false,

      "key": "stock_quote:...",

      "ttl_seconds": 300

    },

    "attempts": []

  }

}

```

如果实时数据源全部失败，但数据库里有过期缓存，会返回 `cache.stale=true`。这能让上层应用选择“展示旧数据并提示”或“直接失败”。

## 已纳入的数据来源

| 数据类型 | 主来源 | 备用来源 |
|---|---|---|
| 个股实时行情 | `sina.hq.realtime` | `eastmoney.push2.stock.quote` / `tencent.qt.quote` / `akshare.stock_zh_a_spot_em` / `stock_zh_a_hist` / `stock_zh_a_daily` / `yahoo.chart.quote` |
| 个股历史 K 线 | `yahoo.chart.daily` / `eastmoney.push2his.stock_kline` | `tencent.ifzq.fqkline` / `stock_zh_a_hist.eastmoney` / `stock_zh_a_daily.sina` / `baostock.query_history_k_data_plus` |
| 个股资金流 | `stock_individual_fund_flow` | `eastmoney.push2his.stock_fflow` |
| 个股资金排名 | `eastmoney.push2delay.stock_fund_flow_rank` | `eastmoney.push2.stock_fund_flow_rank` / `stock_individual_fund_flow_rank` / `stock_main_fund_flow` / `ths.stock_fund_flow_individual` |
| 涨跌停池 | `stock_zt_pool_em` / `stock_zt_pool_dtgc_em` | `ths.limit_up_pool.direct` / 过期缓存兜底 |
| 概念板块 | `eastmoney.push2delay.board_flow.concept` | `eastmoney.push2.board_flow.concept` / `stock_fund_flow_concept` / `stock_board_concept_name_em` |
| 行业板块 | `eastmoney.push2delay.board_flow.industry` | `eastmoney.push2.board_flow.industry` / `stock_fund_flow_industry` / `stock_board_industry_name_em` |
| Legacy 板块龙头/埋伏/频率文本 | `eastmoney.push2delay.board_flow.combined.legacy` | `eastmoney.push2delay.board_flow.concept/industry` / `stock_fund_flow_concept` / `stock_fund_flow_industry` |
| 市场宽度 | `stock_board_industry_summary_ths` | `stock_zh_a_spot_em` |
| 新闻 | `stock_info_global_cls` / `stock_news_em` | `stock_info_global_em` / `stock_info_global_sina` / `stock_info_global_futu` / `stock_info_global_ths` / 过期缓存兜底 |
| 公告 | `stock_notice_report` | 过期缓存兜底 |
| 财务 | `stock_financial_abstract_ths` / `stock_financial_analysis_indicator` / `stock_financial_analysis_indicator_em` / `stock_yjyg_em` / `stock_yjkb_em` | `eastmoney.f10.*` / 过期缓存兜底 |
| F10 细分表 | `eastmoney.f10.income/cashflow/balance/dividend/equity/freeholders` | `akshare.stock_balance_sheet_by_report_em` / `akshare.stock_main_stock_holder` |
| 宏观 | Jin10 中国宏观直连 / AKShare 中国宏观系列接口 | `chinabond.government_bond.history_query` / 过期缓存兜底 |
| ETF 折溢价率 | `eastmoney.push2delay.etf_premium` | `eastmoney.push2.etf_premium` / `akshare.fund_etf_spot_em` |
| 港股沽空记录 | `eastmoney.hk.sellshort.html` | 过期缓存兜底 |
| 融资融券 | `eastmoney.push2his.stock_rrg` | `akshare.stock_margin_detail_sse` / `akshare.stock_margin_detail_szse` |
| 北向资金 | `akshare.stock_hsgt_hist_em` | `eastmoney.push2his.kamt_kline` |
| 股东户数 | `akshare.stock_zh_a_gdhs_detail_em` | `eastmoney.datacenter.freeholdersnum` |
| 前十大股东 | `akshare.stock_main_stock_holder` | `eastmoney.f10.freeholders` |
| A 股交易日历 | `akshare.tool_trade_date_hist_sina` | 过期缓存兜底 |
| 申万行业 | `eastmoney.push2.sw_industry` | `akshare.index_realtime_sw` |
| 基金重仓股 | `akshare.fund_report_stock_cninfo` | `eastmoney.datacenter.rpt_fund_main_position` |
| 基金持仓结构 | `akshare.fund_hold_structure_em` | `scrapling.eastmoney.fund_structure` |

## AI-Search-Hub 多平台搜索

集成 [AI-Search-Hub](https://github.com/minsight-ai-info/AI-Search-Hub)，可同时查询多个 AI 平台获取不同数据生态的搜索结果：

| 平台 | 数据生态 |
|---|---|
| Gemini | Google Search、全球网页 |
| Grok | X/Twitter 实时搜索、社交趋势 |
| 豆包 | 抖音、头条、中文热点 |
| 元宝 | 微信公众号、微信生态 |
| LongCat | 中文知识、本地生活、大众点评 |
| 通义千问 | 中文网页搜索、淘宝数据 |
| MiniMax | 中文问答、B站 |
| Kimi | 长文档、研究资料 |

### 前置条件

1. 克隆 AI-Search-Hub 仓库：
   ```bash

   git clone https://github.com/minsight-ai-info/AI-Search-Hub ~/AI-Search-Hub

   cd ~/AI-Search-Hub && pip install -r requirements.txt

   ```
2. 安装 Playwright 浏览器驱动：`playwright install chromium`
3. 在目标 AI 平台提前登录（首次使用需要手动登录保存 Cookie）

### 环境变量

| 变量 | 说明 | 默认值 |
|---|---|---|
| `AI_SEARCH_HUB_REPO_PATH` | AI-Search-Hub 仓库路径 | 自动检测 `~/AI-Search-Hub` |
| `AI_SEARCH_HUB_TIMEOUT` | 单平台超时秒数 | `120` |
| `AI_SEARCH_HUB_DEFAULT_SITES` | 默认搜索平台（逗号分隔） | `gemini,grok,doubao` |
| `AI_SEARCH_HUB_HEADLESS` | 是否无头模式运行 | `false` |
| `AI_SEARCH_HUB_MAX_CONCURRENT` | 最大并发平台数 | `3` |

### 调用示例

```bash

# 查询所有默认平台

curl -X POST http://127.0.0.1:7860/api/v1/ai-search-hub/search \

  -H "Content-Type: application/json" \

  -d '{"query": "贵州茅台最近有什么重大新闻", "sites": ["grok", "doubao", "yuanbao"]}'



# GET 方式

curl "http://127.0.0.1:7860/api/v1/ai-search-hub/search?q=A股市场情绪分析&sites=grok,gemini"



# 查看可用平台

curl http://127.0.0.1:7860/api/v1/ai-search-hub/sites

```

## 免费 MySQL 建议

Hugging Face 免费 Space 会睡眠，本地文件缓存不可靠，建议使用外部 MySQL。可以用支持公网连接的免费或低价云 MySQL / PlanetScale 兼容 MySQL 服务 / Aiven MySQL 试用实例等。

数据库只需要一个表 `api_cache`，服务启动时会自动创建。MySQL 用户需要 `CREATE TABLE`、`SELECT`、`INSERT`、`DELETE` 权限。

## 后续迁移技能

原技能脚本已经接入远程优先模式：

- 设置 `STOCK_DATA_API_BASE_URL` 后，脚本优先请求本服务。
- 远程失败、超时或结构异常时，自动回退本地 AKShare。
- 未设置 `STOCK_DATA_API_BASE_URL` 时，保持原本本地行为。

详细说明见 [原技能远程优先接入说明](docs/原技能远程优先接入说明.md)。

<!-- rebuild 2026-06-20 16:27:31 -->

## 美股与 X/Twitter 数据（参考 niuone 项目补充）

参考开源项目 [kunkundi/niuone](https://github.com/kunkundi/niuone) 的数据覆盖，新增了美股行情/盘面摘要与 X 关注列表时间线两组能力。这些接口复用了本项目已有的多源轮换（`run_sources`）+ 缓存架构。

### 美股数据

| 接口 | 说明 | 数据源顺序（自动轮换） |
|---|---|---|
| `GET /us/indices` | 道指/纳指/标普三大指数 | `tencent.qt.us_indices` → `sina.hq.us_indices` → `yahoo.chart.us_indices` |
| `GET /us/sectors` | 美股行业/主题 ETF（半导体、软件、军工、生物科技等，含 A 股映射） | `yahoo.chart.us_sector_etfs` |
| `GET /us/market-summary` | 隔夜美股盘面摘要：风险语气（进攻/平衡/中性/谨慎/防守）+ 指数/板块映射 + 今日指引 | 组合 `us_indices` + `us_sectors` |
| `GET /us/stocks/{symbol}/quote` | 美股个股/指数报价（如 `AAPL`、`^DJI`、`TSLA`） | `yahoo.chart.us_quote` → `sina.hq.us_quote` |
| `GET /us/stocks/{symbol}/daily` | 美股日 K | `yahoo.chart.us_daily` |

> 美股与 A 股是两套独立符号体系：`/stocks/...` 走 A 股（需 `.SH`/`.SZ`），`/us/stocks/...` 走美股（Yahoo/腾讯/新浪代码）。

### X / Twitter 时间线

`GET /social/x/timeline?accounts=elonmusk,OpenAI&limit=5`

- 参数 `accounts`：X 账号，逗号分隔（可带或不带 `@`）。
- 参数 `limit`：每个账号最多抓取条数（1-10）。
- 参数 `hydrate`：是否用帖子链接补充正文/媒体直链，默认 `true`。
- 数据源顺序：`openai_compatible.x_watchlist`（复用 `/search` 的 Grok/OpenAI 兼容模型，实时检索 X）→ `x.com.html.timeline`（模型未配置时，直接抓取 X 公开 HTML 兜底，能拿到帖子 ID 与页面标题，但正文受反爬限制）。
- 模型检索需要配置 `SEARCH_API_BASE_URL` + `SEARCH_API_KEY`（与 `/search` 共用）；未配置时自动降级到 HTML 兜底。

```bash

# 美股三大指数

curl "http://127.0.0.1:7860/api/v1/us/indices?limit=3"



# 隔夜美股盘面摘要

curl "http://127.0.0.1:7860/api/v1/us/market-summary"



# 美股个股报价

curl "http://127.0.0.1:7860/api/v1/us/stocks/AAPL/quote"



# X 关注账号时间线

curl "http://127.0.0.1:7860/api/v1/social/x/timeline?accounts=elonmusk&limit=3"

```

## 免费 MySQL 建议

Hugging Face 免费 Space 会睡眠，本地文件缓存不可靠，建议使用外部 MySQL。可以用支持公网连接的免费或低价云 MySQL / PlanetScale 兼容 MySQL 服务 / Aiven MySQL 试用实例等。

数据库只需要一个表 `api_cache`，服务启动时会自动创建。MySQL 用户需要 `CREATE TABLE`、`SELECT`、`INSERT`、`DELETE` 权限。

## 后续迁移技能

原技能脚本已经接入远程优先模式：

- 设置 `STOCK_DATA_API_BASE_URL` 后，脚本优先请求本服务。
- 远程失败、超时或结构异常时，自动回退本地 AKShare。
- 未设置 `STOCK_DATA_API_BASE_URL` 时，保持原本本地行为。

详细说明见 [原技能远程优先接入说明](docs/原技能远程优先接入说明.md)。

<!-- rebuild 2026-06-20 16:27:31 -->