看海量化 Web 回测工作台使用教程 - khQuant看海量化回测平台

适用版本：看海量化 V3.4.0 VIP 专项桌面版，以及后续明确包含 Web 模块的版本。本文以 Windows V3.4.0 为例，讲解如何从桌面主程序打开网页工作台、导入策略、配置参数、运行回测、查看报告，并通过手机临时远程控制。源码部署的安装方式和发行边界与桌面专项版不同，请以对应仓库说明为准。

Web 回测工作台不是一套新的回测引擎。它把看海量化原有的 kh run 回测能力做成了适合电脑、平板和手机使用的网页界面。策略、DuckDB 行情、回测结果仍保存在运行看海量化的主机上，浏览器主要负责配置、控制和查看。

这带来三个直接好处：

电脑上可以使用更清晰的网页布局管理策略、参数和历史结果；
浏览器关闭后，回测任务仍由独立进程继续运行，重新打开页面会恢复状态；
临时外出时，可以在不申请公网 IP、不配置路由器端口的情况下，用手机查看日志、停止任务或启动下一次回测。

图 1 · Web 工作台把本机策略、DuckDB、回测任务和跨设备控制连接在一起

一、开始前需要准备什么

第一次使用前，请逐项确认下面的条件。

1. 安装包含 Web 模块的 V3.4.0 VIP 专项版

看海量化 V3 桌面专项版仅向权益有效的 khQuant VIP 用户提供。已开通 VIP 的用户请登录 V3 专项下载页获取当前安装包：

https://khsci.com/khQuant/beta/

非 VIP 用户不能从该专项页下载 V3 桌面安装包；官网公开下载区继续提供 V2.1 公开版。V3 安装包的真实下载地址只在登录后的 VIP 专项页面显示，不应从其他页面或他人转发的直链获取。

下载 V3 的 VIP 权限，和稍后手机临时访问使用的安全密钥，是两套完全不同的机制：前者决定能否获取桌面安装包，后者只保护用户自己电脑上临时开启的 Web 链接。

如果桌面主程序顶部工具栏没有地球图标，通常说明当前安装包没有包含 Web 工作台，或版本早于 V3.4.0。请先升级，不要单独复制网页文件到旧版本目录。

2. 先在桌面端配置好 DuckDB

Web 工作台当前固定使用桌面端设置中的 DuckDB 数据源，不在网页里切换 miniQMT、BaoStock 或 Tushare。开始前应先在桌面端完成：

设置 DuckDB 数据目录；
下载或导入策略所需的股票、周期、复权和字段；
确认回测日期范围内确实有数据。

网页中的「设置与状态」页面只展示核心环境，不直接修改这些全局设置。需要下载、补充、核验或修复行情时，仍应回到桌面端「数据管理」。

3. 准备策略配置

最推荐的入口是一份已经能在桌面端或 CLI 中运行的 .kh 配置。配置应正确引用策略 .py 文件；如果策略还会导入同一项目中的其他 Python 模块，也应把这些依赖文件保留在策略目录或项目目录中。

建议首次使用先选一只股票和较短日期范围跑通。确认策略、行情与报告链路正常后，再扩大股票池和回测区间。

二、打开 Web 回测工作台

方式一：从桌面主程序打开（推荐）

打开看海量化主程序；
如需把当前策略直接带入网页，可先在桌面端加载对应 .kh 配置；
点击顶部工具栏右侧的地球图标；
等待状态栏提示「网页回测服务已启动并打开」。

鼠标停在地球图标上时，会显示「打开网页回测工作台」。程序默认在本机启动 127.0.0.1:8766，健康检查通过后才会打开浏览器。如果 8766 端口上已经运行的是看海量化 Web，软件会复用现有服务；如果端口属于其他程序，则会明确提示端口被占用，不会重复启动或覆盖未知服务。

图 2 · 主界面顶部右侧的地球图标就是 Web 工作台入口

打开成功后，浏览器地址通常是：

http://127.0.0.1:8766/

关闭桌面主窗口不会自动结束已经独立启动的 Web 服务，关闭浏览器也不会停止正在执行的回测。

方式二：使用已安装的 `kh` 命令（可选）

熟悉命令行的用户可以运行：

kh web

希望启动时直接导入一份配置，可以运行：

kh web "D:\策略研究\我的策略.kh"

常用可选参数：

kh web --port 8766 --no-open

--port：指定端口，默认是 8766；
--no-open：只启动服务，不自动打开浏览器；
--host 0.0.0.0：允许局域网设备访问，启动终端会生成带访问密钥的安全链接。

习惯图形界面的 VIP 用户不需要命令行。手机外网访问也不必使用 --host 0.0.0.0，直接使用第九节的一键临时访问即可。

三、先认识四个页面

进入工作台后，电脑端左侧和手机端底部都有四个导航入口。

页面	主要用途
回测工作台	修改本次回测参数、运行/停止任务、查看实时日志和最近结果
策略项目	查看已经导入的项目，切换策略和配置版本
历史结果	搜索、打开或删除已有回测结果
设置与状态	查看版本、DuckDB、性能设置，开启临时外网访问

图 3 · 电脑端工作台：左侧配置参数，右侧控制任务与查看结果

桌面端侧栏底部显示「本机服务已连接」时，表示浏览器与本机服务通信正常。短时断网或页面切到后台后，界面会自动重连；本机回测进程不会因为网页暂时离线而停止。

四、导入策略项目

点击右上角「导入」，或在「策略项目」页面点击「导入项目」，会看到两种导入方式。

1. 本机文件：适合在运行看海量化的电脑上操作

选择「本机文件」后，可以直接点击「选择一个 .kh 配置文件」，也可以手动输入完整路径。

图 4 · 本机导入会读取 .kh，并自动复制它引用的策略与本地 Python 依赖

本机导入的实际行为如下：

.kh 中的相对策略路径按 .kh 所在目录解析；
自动收集入口策略实际导入的本地 Python 模块和包；
如果策略位于 strategy、strategies 或 src 子目录，会同时检查上一级项目目录中的公共模块；
如果配置引用股票清单文件，会把识别出的股票写入项目草稿，并复制清单文件；
所有文件复制到看海量化 Web 工作区，原始 .kh 和 .py 不会被修改。

因此，本机导入特别适合包含 precision_contract.py、公共基准策略或自定义模块的多文件策略。若导入后仍出现 No module named ...，通常表示该模块不在入口策略可解析的项目目录中，或使用了动态导入。此时应把缺少的依赖整理到策略项目目录，再重新导入。

2. 远程上传：适合手机或另一台电脑

通过手机、临时隧穿或其他电脑访问时，浏览器无权直接读取服务器硬盘，因此页面只显示「远程上传」。请同时选择：

一份入口 .kh；
.kh 引用的策略 .py；
策略依赖的其他 .py、模型或配置资源；
配置引用的 CSV/TXT 股票清单（如有）。

如果文件较多，推荐使用「选择整个策略文件夹」，这样可以保留目录结构。一次上传只能有一个 .kh 入口；没有 .kh 时，多文件项目应把唯一入口命名为 main.py 或 strategy.py。

当前上传限制为：单文件不超过 20 MB，项目文件总计不超过 50 MB。支持常见的 .kh、.py、CSV/JSON/TXT/YAML/TOML、Pickle、NumPy、ONNX 和模型资源文件；可执行程序和任意未知文件不会进入工作区。

3. 在策略项目中切换

导入完成后，项目会显示在「策略项目」页面。点击任意卡片即可回到工作台并载入该项目的草稿配置。

图 5 · 每个项目保存自己的策略副本、参数草稿和正式配置版本

项目名称相同不等于同一个项目。多次导入同一 .kh 可能形成多张项目卡片，正式使用前可按策略和时间确认当前选择。

五、配置回测参数

网页参数会直接映射到同一套 CLI 回测配置，不会偷偷转换为另一种计算口径。修改后约 0.85 秒自动保存草稿，顶部会从「正在保存草稿」恢复为「草稿已保存」。

1. 基础设置

填写以下四项：

开始日期 / 结束日期：决定回测区间；
初始资金：必须大于 0；
基准合约：例如 000300.SH；
最小交易量：A 股股票通常为 100，具体以标的规则为准。

2. 触发器

支持逐 Tick、每 1 分钟、每 5 分钟、每日和自定义时间。

使用日线策略时，通常选择「每日」；
使用 1 分钟或 5 分钟数据时，触发方式一般与 K 线周期保持一致；
使用「自定义时间」时，可以设置开始时间、结束时间和间隔，点击「按范围生成」；
自动生成只保留 A 股交易时段 09:30–11:30 和 13:00–15:00，间隔范围为 3–3600 秒。

如果数据周期与触发方式不一致，页面会给出黄色提醒，运行前的预检也会要求确认。

3. 交易成本

网页可以设置：

佣金比例；
最低佣金；
印花税率；
流量费（元/笔）；
按成交金额比例或按最小变动价位计算的滑点。

比例使用小数保存，例如 0.001 表示 0.1%。界面中的「滑点比例（%）」按百分数显示，填写 0.1 才表示 0.1%，请不要把 0.001 和 0.1% 混淆。

4. 盘前盘后回调

策略实现了 khPreMarket 或 khPostMarket 时，可开启对应回调并设置时间。只有开关开启后，CLI 才会执行相应回调。没有实现这些函数的普通策略保持关闭即可。

5. 行情周期、复权和字段

网页端可选 Tick、1 分钟、5 分钟和日线，支持不复权、前复权、后复权、等比前复权和等比后复权。下方字段勾选决定框架初始化时从 DuckDB 加载哪些行情字段。

图 6 · 行情口径和股票池必须与本机 DuckDB 中的实际数据对应

策略调用 khPrice、khIndex、khHistory 或自定义字段时，要确保相应字段已写入 DuckDB，并在配置中勾选。网页只负责读取，不会在运行前替用户自动下载缺失行情。

6. 股票池

可以采用三种方法：

直接在文本框中输入，一行一个，也支持空格或逗号分隔；
点击上证 50、沪深 300、中证 500、沪深 A 股、ETF、T0 ETF、自选清单等常用池；
导入 CSV 或 TXT 文件。

点击常用股票池是「合并加入」，不会覆盖已经手动输入的代码，重复代码会自动去重。CSV/TXT 要把股票代码放在第一列，支持 UTF-8 和 GBK，文件不超过 5 MB。

7. 草稿、正式版本和源码预览

普通参数修改自动保存为草稿；
点击「保存版本」，可以给当前参数起名并生成一份带时间戳的正式 .kh 配置；
页面底部「策略源码」仅用于核对入口文件和代码，不提供在线编辑。

图 7 · 源码面板用于确认导入内容，修改策略仍应使用桌面编辑器或本机 IDE

六、运行回测与查看实时状态

当前界面只保留一个「运行回测」按钮。点击后会按下面的顺序执行：

等待当前草稿保存完成；
生成本次运行专用配置；
调用 CLI 执行最长 180 秒的同步预检；
预检通过后启动独立 kh run 子进程；
持续读取进度、阶段和日志；
完成后生成统一 HTML 报告。

图 8 · 预检会在正式运行前检查配置、策略初始化和数据条件

预检结果分为三类：

通过：直接启动回测；
警告：弹出原因，由用户决定是否继续；
阻断：不启动任务，并显示需要修复的问题。

刚启动时，进度环可能显示「启动中」，这是 CLI 初始化、加载策略和准备数据的阶段。只要实时日志还在更新，就不代表卡死。页面会每约 1.2 秒同步状态，网络异常时会自动退避重连。

图 9 · 运行区会显示状态、进度、进程、启动时间和最近 120 行日志

重要的运行规则

Web 工作台同一时间只运行一个任务；
关闭或刷新网页不会停止任务；
重新打开页面会从服务端恢复进度和日志；
点击「停止回测」会先写入停止请求，再按桌面端「停止后直接退出」设置决定是否快速结束进程；
页面连接超时后会主动查询服务端状态，避免出现实际已经运行、页面却仍显示失败的“幽灵回测”。

Web 端不会阻止用户同时在桌面端或手工 CLI 启动另一场回测。多个只读回测主要会增加 CPU、内存和磁盘压力；如果数据下载、导入或修复任务正在写入同一批 DuckDB 文件，才更容易触发数据库占用重试或跳过告警。正式长测时，建议避免无必要并发，并把写库任务与回测错开。

七、查看最近结果、历史结果和完整报告

回测完成后，右侧「本次回测结果」会显示总收益、年化收益、最大回撤和期末资产。点击卡片即可打开完整 HTML 报告。

「历史结果」页面会统一列出网页端、桌面端和 CLI 生成的完整回测结果，而不是只显示网页任务。可以按策略名或结果目录搜索，点击柱状图按钮打开报告。

图 10 · 历史结果统一展示不同入口生成的回测记录

历史结果默认先加载 100 条，结果较多时可点击「继续加载后续结果」。垃圾桶按钮会永久删除该结果目录，页面会再次确认；删除后无法从工作台恢复，请先确认结果已经备份或确实不再需要。

完整报告包括：

总收益、年化收益、最大回撤、夏普比率；
初始/最终资产、基准收益、胜率、盈亏比等关键指标；
净值、基准、持仓、回撤、日盈亏和策略成交图；
日收益分布和月度收益；
交易记录、日收益和个股分析；
策略源码与本次策略配置。

图 11 · RSI 示例策略的完整报告长图，指标、曲线和成交记录均在同一页面

报告中的高收益不等于策略可直接实盘。仍需检查数据完整性、手续费、滑点、停牌、涨跌停、成交量限制和样本外表现。

八、在手机或平板上使用

网页会根据屏幕宽度自动切换为移动端布局。手机底部保留「工作台、策略项目、历史结果、设置与状态」四个入口，核心功能不会因为屏幕变小而被移除。

图 12 · 手机端可查看状态、结果和参数，也可以启动或停止回测

图 13 · 设置与状态页面在手机窄屏下仍保留完整环境信息

手机端适合：

查看回测是否仍在运行；
阅读实时日志和失败原因；
调整少量参数后重新运行；
停止耗时异常的任务；
打开最近结果和完整报告。

大量编辑股票池或逐项核对复杂参数时，电脑端仍然更高效。

九、无需公网 IP 的一键临时外网访问

当手机不在同一局域网时，可以使用内置的 Cloudflare Quick Tunnel。它不需要申请公网 IP、不需要进入路由器做端口映射，也不要求用户购买域名。

1. 在主机本机开启

必须在运行看海量化的电脑上操作：

打开 Web 工作台；
进入「设置与状态」；
在「临时外网访问」卡片点击「开启临时外网访问」；
等待状态变为「临时访问中」；
用手机扫描二维码，或复制完整安全链接发送到自己的可信设备。

图 14 · 临时访问只能在服务器本机开启和关闭

开启后会显示临时公网地址、复制按钮、验证按钮和二维码。教程截图已经对网址和二维码做了遮挡；用户自己的实际页面会显示可用内容。

图 15 · 公网地址和二维码包含访问凭证，不要发布到群聊、论坛或公开网页

2. 为什么临时访问不要求再次登录网站账号

临时链接包含本次隧穿会话专用的访问密钥。手机第一次打开完整链接后，浏览器会保存安全 Cookie，并自动从地址栏移除密钥；控制操作还必须携带当前服务生成的控制令牌，并通过同源检查。

它不是“打开一次就作废”的单次密钥：只要本次临时隧穿仍在运行，完整链接就可能被重复打开或转发。因此，已安装软件的用户临时连接自己的主机时，不需要再次输入 khQuant 网站账号和密码，但仍要把完整链接当作密码保管，并遵守三条安全规则：

只把完整链接或二维码发送给可信设备；
用完立即点击「关闭临时访问」；
不要把 8766 端口直接暴露到公网。

关闭后，临时地址和访问密钥立即失效。下次重新开启会生成新的地址和密钥。

3. 远程页面为什么看不到本机完整路径

远程访问时，DuckDB 路径和策略目录会被隐藏，实时日志中的本机路径也会脱敏。远程浏览器不能调用服务器的原生文件选择器，所以导入策略必须使用「远程上传」。这是权限边界，不是功能故障。

4. 临时访问的边界

主机必须开机；
看海量化 Web 服务必须保持运行；
Quick Tunnel 依赖主机当前网络和 Cloudflare 服务；
临时网址不保证长期不变；
该功能适合偶尔外出查看和控制，不等同于正式生产服务器。

如果页面提示「当前安装缺少临时访问组件」，VIP 用户请从 V3 专项下载页重新安装包含 cloudflared 的 V3.4.0 专项版，不要从未知网站单独下载替换文件。

十、局域网与固定域名部署（进阶）

1. 同一局域网访问

需要让同一 Wi-Fi 下的手机或平板长期访问时，可用：

kh web --host 0.0.0.0 --port 8766

终端会打印包含访问密钥的局域网链接。Windows 防火墙需要允许该端口的局域网访问。不要把终端中的完整安全链接发给不可信设备。

2. 自己有服务器和域名

Web 模式适合部署在持续运行的 Windows 主机（包括 Windows Server）上。如果已经有域名，可以使用 Nginx、Caddy 等反向代理，把固定域名转发到 127.0.0.1:8766，并配置 HTTPS、独立身份认证和访问日志。

图 16 · 固定域名适合长期服务器部署，但需要自行维护 HTTPS、认证和更新

当前软件提供的是一键临时隧穿，不会自动替用户配置固定域名。使用自定义域名时，还必须把域名加入 Web 服务允许列表；否则后端会返回「无效的访问主机」。例如在同一个 PowerShell 窗口中启动：

$env:KHQUANT_WEB_ALLOWED_HOSTS="quant.example.com"
kh web --host 127.0.0.1 --port 8766 --no-open

多个域名可用英文逗号分隔。环境变量必须由实际启动 Web 服务的进程继承；如果改用桌面地球图标启动，应先配置用户环境变量并完整重启桌面程序。

固定域名场景不会自动获得 Quick Tunnel 的会话密钥保护，因此反向代理层的独立登录或零信任访问控制是必需项，不是可选优化。正式公网部署前，应具备基本的服务器运维能力，并注意：

后端仍只监听本机地址，由反向代理对外提供 HTTPS；
必须启用独立登录或零信任访问控制；
限制上传体积和访问来源；
及时安装安全更新；
不在公开页面暴露策略源码、日志或回测文件。

十一、常见问题与排查顺序

1. 点击地球图标后提示 8766 端口被占用

软件会先判断端口上的服务是不是看海量化 Web。若不是，就会停止启动并提示冲突。请先确认占用程序，或使用其他端口；不要直接强制结束不认识的系统进程。

Windows 可在 PowerShell 中查看：

Get-NetTCPConnection -LocalPort 8766 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

再用任务管理器按 PID 确认程序。桌面启动失败时，错误框会给出 Web 服务启动日志路径；默认日志位于用户目录下的 .khquant/web/logs/web_service.log。

2. 一直显示「启动中」

先看实时日志是否继续增加。全 A 股、大量分钟数据、复杂策略初始化或首次构建缓存都可能在 0% 阶段停留较久。

按顺序检查：

实时日志最后一行是什么；
是否出现策略导入失败或 No module named ...；
DuckDB 路径和回测日期是否正确；
是否缺少策略需要的历史预热数据；
页面刷新后，状态是否仍能恢复。

如果 CLI 进程已经退出，却没有完整结果元数据和 summary.csv，系统会标记为「失败」，不会把半成品目录误报为成功。

3. 导入后提示缺少 Python 模块

本机导入会分析普通 import 和 from ... import ...，但动态拼接模块名、运行时修改 sys.path 或依赖项目目录外文件时，可能无法自动收集。

处理方法：

把入口策略和本地依赖放到同一项目目录；
保留原来的包目录结构和 __init__.py；
确认 .kh 中的 strategy_file 能从配置位置解析；
重新导入项目；
远程上传时，同时选择所有依赖或整个文件夹。

4. 页面提示数据周期与触发方式不一致

这是预警，不是页面错误。日线数据通常对应「每日」，1 分钟对应「每 1 分钟」，5 分钟对应「每 5 分钟」。确实需要不同口径时，可以在理解策略执行频率的前提下确认继续。

5. 实时日志提示 DuckDB 被占用或数据为空

Web 端不会替用户强制关闭数据库。请回到桌面端数据管理查看数据库占用诊断，关闭正在写入同一数据库的下载、导入或核验任务，再重新运行。

如果只是某些股票在某个时间点没有数据，要区分停牌、上市时间不足、历史预热不足和真实数据缺口。不能仅因为回测完成就假定数据完整。

6. 手机打开临时地址失败

检查：

主机是否仍开机；
Web 服务和临时访问状态是否仍为运行中；
是否使用了包含访问密钥的完整链接；
手机网络是否能访问 Cloudflare；
旧链接是否已经因关闭或重开隧穿而失效。

7. 历史结果里找不到本次报告

只有完成标记和 summary.csv 都齐全的结果才进入完成列表。被停止、失败或只有半成品目录的任务不会伪装成成功结果。请先查看任务状态和实时日志。

十二、推荐的日常使用流程

为了减少配置错误和无效长测，建议按下面的固定顺序操作：

在桌面端补齐并核验 DuckDB 数据；
用桌面端或 CLI 跑通单只股票、短时间范围；
从地球图标打开 Web 工作台；
导入 .kh，确认策略源码和依赖正确；
核对日期、资金、触发器、交易成本、行情口径和股票池；
等待顶部显示「草稿已保存」；
点击一次「运行回测」，根据预检结果处理；
运行中重点看阶段、实时日志和异常告警；
完成后打开完整报告，不只看总收益；
外出前再按需开启临时访问，用完立即关闭。

Web 工作台的价值不是把本地量化变成云端黑箱，而是在保留本地策略、本地数据和同一回测引擎的前提下，让配置、运行、报告和跨设备控制更顺手。