概述
由于 miniQMT 与 xtquant 目前仍是 Windows 专属生态，macOS 无法像 Windows 一样直接调用券商终端下载行情。在上一章中我们提到，Mac 用户此前主要靠两种方式取数：① BaoStock / Tushare 等第三方数据源；② 从 Windows 机器拷贝已下载好的 DuckDB 数据库。这两种方式都能用，但不够丝滑——而 miniQMT 数据较全、免费、还能下载 Tick，用不起来实在可惜。
为此，看海量化新增了 miniQMT 桥接模式：让一台 Windows 电脑作为行情服务端，通过局域网把 miniQMT 的行情能力开放给 macOS。Mac 端无需安装 xtquant、无需运行 miniQMT，只要填入服务地址与 API Key，即可远程下载数据并自动写入 Mac 本地 DuckDB。如果手头没有 Windows 实体机，在 macOS 上用虚拟机跑一台 Windows 同样可行。
本章将原理与图形界面、命令行两条操作路径逐步细化，带你从零把桥接链路搭起来并跑通第一笔数据导入。
适用版本：v3.3 系列内测版及以上。桥接模式同时支持 GUI 与 CLI 两种用法。
一、桥接模式的原理与架构
桥接模式的本质，是在 Windows 与 Mac 之间架起一座”数据桥”：
Windows 负责连接 miniQMT，macOS 负责远程取数并落入本地 DuckDB。
Windows 端启动的桥接服务只做行情数据、不含任何交易功能。它以数据专用模式运行，把 miniQMT 的历史行情接口封装成 HTTP API，并显示当前局域网访问地址；Mac 端通过这个地址远程请求数据，最终写入本机 DuckDB，供回测使用。
整条链路：
Windows + miniQMT → 行情桥接服务(HTTP API) → 局域网 → macOS → 本地 DuckDB → 回测
二、准备工作（开始前请逐项确认）
在动手之前，请确认以下五项前置条件，它们是桥接能否跑通的关键：
下载说明：本章涉及两个程序——Windows 端的行情桥接服务端程序与 macOS 端的下载安装程序，两者下载网址相同，均在内测下载页获取：https://khsci.com/khQuant/beta/（仅对内测用户开放）。
- Windows 端已安装看海量化主程序：桥接服务依赖主程序中的 xtquant 能力，不能只装服务端。（从上述下载页获取 Windows 端程序）
- Windows 端已启动并登录 miniQMT：若 miniQMT 未运行，桥接服务虽能启动，但取不到任何行情数据。
- 两端网络互通：最简单的做法是让 Windows 与 Mac 连接同一个局域网（同一路由器/同一 WiFi）。
- Windows 防火墙放行端口：需允许桥接服务端口（默认
8001）被局域网访问，否则 Mac 端会连接失败。 - Mac 端已配置 DuckDB 数据目录：桥接最终是把数据写入本地 DuckDB，需先在 Mac 端「设置」里配置好数据目录（默认
~/Library/Application Support/khQuant/stock_data）。
三、图形界面操作（推荐普通用户）
第一步：在 Windows 端启动行情桥接服务
- 确认 miniQMT 已启动并处于登录状态。
- 打开看海量化提供的「行情桥接服务」程序。它会以数据专用模式启动。
- 按需配置以下参数（一般保持默认即可）：
| 参数 | 默认值 | 说明 |
|---|---|---|
| 监听地址 (host) | 0.0.0.0 |
0.0.0.0 表示允许局域网内其它设备访问 |
| 端口 (port) | 8001 |
如被占用可改为其它端口 |
| API Key | 自定义 | 用于防止局域网内未授权访问，Mac 端需填一致的值 |
| miniQMT 路径 | 留空 | 通常自动识别；特殊环境下可手动指定 userdata_mini 路径 |
- 启动后，界面会显示类似这样的局域网访问地址：
http://192.168.1.10:8001
这个地址（含
http://、IP 与端口）就是 Mac 端后续要填写的「桥接服务地址」。请记下它与你设置的 API Key。
第二步：在 macOS 端通过桥接服务导入数据
- 在 Mac 端打开看海量化的数据管理界面，进入「miniQMT 桥接导入」页面。
- 填写第一步记下的服务地址与 API Key。
- 点击「测试连接」。连接成功后再继续——若失败，请回到第二节核对网络与防火墙。
- 选择导入参数：股票池（预设池或自定义）、周期、复权方式、日期范围。
- 点击导入，等待完成。
导入过程会自动完成三件事，全程无需手动拷贝文件、Mac 也无需安装 xtquant：
- 请求 Windows 服务端调用 miniQMT 下载历史数据；
- 从 Windows 服务端读取 miniQMT 本地缓存；
- 把数据写入 Mac 本地 DuckDB 数据库。
「桥接导入」模块与 Windows 端「从 miniQMT 导入数据」模块功能完全一致：支持增量补充、多种复权方式、预设股票池与自定义股票池，全程傻瓜化操作。
建议：首次使用先用单只股票（如
000001.SZ日线）小批量测试，确认链路正常后再下载大股票池。
四、命令行操作（适合 CLI 用户）
除了图形界面，桥接模式同样接入了看海量化 CLI。命令风格与其它数据源保持一致，只是把 --source 从 xtdata / baostock / tushare 换成 http。
4.1 Windows 端：启动桥接服务
注意：CLI 启动桥接服务同样需要在 Windows 端安装看海量化回测系统主程序，而不仅是服务端程序。
kh bridge serve --host 0.0.0.0 --port 8001 --api-key your-api-key
参数与 GUI 一一对应：--host 监听地址、--port 端口、--api-key 访问密钥；特殊环境可加 --qmt-path 指定 miniQMT 的 userdata_mini 路径。启动后终端会打印局域网访问地址。
可在另一台机器用
kh bridge status --url http://192.168.1.10:8001查询服务状态，确认链路是否就绪。
4.2 macOS 端：配置服务地址并下载
先把桥接服务地址与 API Key 写入本机配置（两项缺一不可，否则 --source http 会报错提示未配置）：
kh config set http_base_url http://192.168.1.10:8001
kh config set http_api_key your-api-key
然后用 http 数据源下载单只股票：
kh data download --source http --stocks 000001.SZ --period 1d --start 20240101 --end 20241231
也可以直接下载预设股票池、并一次指定多个周期：
kh data download --source http --pool hs300 --period 1d,1m --start 20240101
五、桥接模式支持哪些数据
1. 支持的 K 线周期
当前桥接模式主要面向回测行情数据导入，支持以下周期：
| 周期 | 取值 |
|---|---|
| 日线 | 1d |
| 1 分钟 | 1m |
| 5 分钟 | 5m |
| Tick | tick |
2. 支持的复权方式
延续看海量化 DuckDB 的多字段存储设计，可一次勾选多种复权方式，系统会分别取数后合并写入同一份数据表。后续回测时，策略配置选哪种复权，就读取对应字段：
| 复权方式 | 写入字段 |
|---|---|
| 不复权 | open / high / low / close |
| 前复权 | open_front / high_front / low_front / close_front |
| 后复权 | open_back / high_back / low_back / close_back |
| 等比前复权 / 等比后复权 | 对应的 *_ratio 字段 |
六、常见问题与排错
Q：Mac 端「测试连接」失败 / CLI 连不上服务？
A：按顺序排查——① Windows 的 miniQMT 是否已启动并登录；② 两端是否在同一局域网；③ Windows 防火墙是否放行了服务端口（默认 8001）；④ Mac 端填写的地址是否完整（含 http://、正确 IP 与端口）。
Q：连接成功但取不到数据？
A：多半是 Windows 端 miniQMT 未登录或未运行。桥接服务可在 miniQMT 离线时启动，但无法取数。
Q：CLI 提示”桥接服务地址未配置 / API Key 未配置”？
A：--source http 要求先设置好两项配置：kh config set http_base_url <地址> 与 kh config set http_api_key <key>，缺一不可。
Q：API Key 两端不一致会怎样？
A：服务端会拒绝未授权访问。请确保 Mac 端填写的 API Key 与 Windows 服务端设置的完全一致。
Q：导入的数据存在哪里？
A：写入 Mac 本地 DuckDB，路径即「设置」中配置的数据目录（默认 ~/Library/Application Support/khQuant/stock_data）。请在导入前确认已配置。
七、下载与获取
桥接模式随看海量化最新 V3 内测版提供，目前仅对内测用户开放。Windows 端服务端程序与 macOS 端安装包的下载地址见上文第二节「准备工作」。
其它资源：
- 内测下载页（Windows 服务端 + macOS 安装包）：https://khsci.com/khQuant/beta/
- 看海量化官方网站：https://khsci.com/khQuant/
- CLI 命令行工具指南：https://khsci.com/khQuant/cli/
如尚未加入内测，可关注公众号「看海的城堡」，在页面下方点击相关标签了解开通方式。