2.6 Web 端

本篇重点：本篇讲怎么用 Web 回测工作台，在浏览器（包括手机）里导入策略、改参数、跑回测、看报告。

1 开始之前

• 数据：Web 回测只读 DuckDB 本地数据库，用的是「设置 → 数据设置」里的数据目录。桌面版的「回测数据源」如果设成了 miniQMT，网页回测会在开始前被拦下，提示「网页回测仅支持 DuckDB 数据源」。
• 系统设置：网页回测沿用桌面版的设置，比如「停止后直接退出」、回测前数据检查、成交量限制、性能和内存档位。要改这些，在桌面版的设置里改。
• 策略：准备好 .kh 配置和它引用的 .py，例如自带的案例。

2 打开工作台

2.1 从桌面版打开

主界面工具栏右侧的地球图标，鼠标移上去提示「打开网页回测工作台」。点一下，软件会在后台启动 Web 服务（最多等 30 秒），然后用浏览器打开 http://127.0.0.1:8766/。

• 桌面版当前加载了 .kh 配置的话，会自动把它导入成网页里的一个项目。
• 服务已经在运行时，再点地球图标直接复用，不会重复启动。
• 关掉桌面版主界面后，Web 服务继续运行。
• macOS 上请先在终端运行 kh web，再点地球图标；服务没运行时直接点，可能提示缺少命令行组件。
• 从这里启动的服务固定是 127.0.0.1:8766，只有本机能访问；要改端口或给手机访问，用下面的 kh web。

2.2 用命令打开

kh web

默认监听 127.0.0.1:8766 并自动打开浏览器，终端显示「看海量化 Web 已启动: http://127.0.0.1:8766/」。常用参数：

• kh web 策略.kh：启动时把这个配置导入成项目，打开后自动选中。
• --port 8800：换端口。端口被占用时会报错退出。
• --host 0.0.0.0：让局域网里的其他设备访问，见第 8 节。
• --no-open：不自动打开浏览器。

用命令启动的服务在终端里前台运行，按 Ctrl+C 停止。Linux 没有图形界面，只能用这种方式。

3 界面一览

左侧导航有四个页面，底部显示服务连接状态和版本号：

4 导入策略项目

点右上角「导入」（手机上在「策略项目 → 导入项目」）。

4.1 本机文件

在运行服务的这台电脑上用浏览器打开时，有「本机文件」页签：

• 「选择一个 .kh 配置文件」：弹出 Windows 文件选择框，默认在策略目录。macOS 和 Linux 不支持这个按钮，请用手动输入。
• 手动输入完整路径：填 .kh 或 .py 的完整路径。只给 .py 时用默认参数。

导入时会把 .kh、它引用的策略 .py、策略里 import 的本地模块，以及配置引用的股票列表文件一起复制进 Web 工作区。原文件不会被修改，之后改了原文件需要重新导入。

4.2 远程上传

用手机或其他电脑访问时只能上传文件。可以多选文件，也可以保留目录结构选择整个策略文件夹。规则：

• 一次只能有一个 .kh，并且要同时选上它引用的 .py。没有 .kh 时：只选一个 .py，文件名不限；选多个 .py，需要有且只有一个 main.py 或 strategy.py（都没有时，需要根目录下有且只有一个 .py）。
• 允许 .kh .py .csv .json .txt .yaml .yml .toml .pkl .pickle .joblib .npy .npz .onnx .bin .model；单个文件不超过 20 MB，合计不超过 50 MB。

4.3 项目存在哪里

每个项目一个目录，在 ~\.khquant\web\projects\（macOS 在 ~/Library/Application Support/khQuant/web/projects/），和桌面版的策略目录分开。网页「设置与状态」里那行「共享策略目录」：没设置桌面版策略目录时，显示的就是这个网页项目目录；设置了的话，这一行显示的是桌面版策略目录，网页项目仍保存在上面的项目目录里。网页里不能删除或重命名项目；同一个 .kh 导入多次会生成多张卡片。

5 设置回测参数

改动后约 0.85 秒自动保存为草稿，顶栏显示「草稿已保存」。

• 基础设置：开始日期、结束日期、初始资金、基准合约。
• 触发器：逐 Tick、每 1 分钟、每 5 分钟、每日、自定义时间。选「每日」时有「日内触发上限」（1～100，见 1.8、3.2）；选「自定义时间」时填开始、结束和间隔后点「按范围生成」，也可以在文本框里一行写一个时间。
• 交易成本：佣金比例、最低佣金、印花税率、流量费、滑点方式。
• 盘前盘后回调：开关和时间，默认 08:30:00、15:30:00。
• 行情数据：K 线周期、复权方式、最小交易量和数据字段。周期和触发方式对不上时会显示黄色提示。
• 股票池：文本框一行一个代码；点常用池按钮会合并加入并去重，本机缺少某个股票池文件时按钮显示「缺失」；也可以导入 CSV/TXT（代码在第一列）。

「保存版本」会把当前参数存成一个正式的 .kh 文件，放在项目目录的 configs\ 下。网页里不能回到某个旧版本；需要时，用桌面版「加载配置」或 kh run 打开这个文件。

页面最下方的「策略源码」可以展开查看，只读。

6 运行回测

点「运行回测」。开始前会做一次预检，最多 3 分钟：

• 通过：直接开始。
• 警告：浏览器弹出确认框，问是否仍然继续。常见原因：周期和触发方式不一致、部分股票数据不完整、规模太大跳过了前置扫描。
• 阻断：页面顶部显示红色错误，不会开始。常见原因：桌面版回测数据源不是 DuckDB、数据目录不存在、缺少基准数据、所有股票都没有数据。

运行中右栏显示状态、进度、运行标识、进程号和实时日志（最后 120 行），大约每 1.2 秒刷新。按钮变成「停止回测」。

• 网页端同一时间只能跑一个回测。
• 关掉或刷新网页不会中断回测，重新打开页面会接着显示进度。
• 停止后的行为跟随桌面版「停止后直接退出」设置：开着时立即结束；关着时会先等几秒，让回测自己收尾后再结束。

7 看结果和报告

回测结束后，右栏的「本次回测结果」卡片显示总收益、年化收益、最大回撤和期末资产，点卡片在新标签页打开 HTML 报告。如果有行情因为数据库被占用而跳过，卡片上会多一行黄色提示。

「历史结果」页列出所有回测，桌面版、命令行和网页跑的都在这里，「来源」一列区分。每页 100 条，下方「继续加载后续结果」；搜索框只在已加载的条目里搜。结果可以删除，删除后无法恢复。

报告页顶部有「回测结果 / 策略源码 / 策略配置」三个页签，回测结果里依次是关键指标、净值与回撤曲线、日收益分布、月度收益、交易记录和个股分析。结果目录里还没有报告时，打开时会现场生成。报告的读法见 1.10。

8 用手机访问

页面会自适应手机屏幕：侧栏变成抽屉，底部出现「工作台 / 策略项目 / 历史结果 / 设置与状态」四个入口。手机要连到电脑上的服务，有两种办法：

8.1 同一个局域网

kh web --host 0.0.0.0

这时会自动生成一个访问密钥，终端打印两条带 access_key 的链接：一条给本机，一条是「局域网安全访问: http://192.168.x.x:8766/?access_key=…」。把局域网那条发到手机上打开即可，第一次打开后密钥存在浏览器里，12 小时内不用再带。这种模式下本机浏览器也要用带密钥的链接。Windows 防火墙弹窗时请允许专用网络访问。

8.2 临时外网访问

手机不在同一个网络时，在电脑浏览器里打开「设置与状态」，点「开启临时外网访问」。软件会通过 Cloudflare Quick Tunnel 拿到一个临时的 https 地址，状态变成「临时访问中」后，页面显示访问链接、「复制访问链接」「打开验证」和二维码，用手机扫码即可。

• 新地址可能要约 1 分钟才能访问，打不开时稍等再试。
• 只能在运行服务的这台电脑上开启或关闭。每次开启都是新地址、新密钥；点「关闭临时访问」或退出 Web 服务后，链接立即失效。
• Windows 和 macOS 安装版已内置所需的 cloudflared 组件。Linux 或源码运行要自己从 Cloudflare 官方安装，并放进 PATH（或设置环境变量 KHQUANT_CLOUDFLARED_PATH）；没装时按钮是灰的，提示「当前安装缺少临时访问组件」。
• 这是实验性功能，能否连通取决于网络环境。

8.3 远程访问能做什么

通过局域网或临时链接访问时，可以跑回测、停止、看报告、删除结果、上传项目；看不到本机的路径（显示为「仅服务器本机可见」），不能按路径导入，也不能开关临时访问。报告里包含策略源码和配置，分享链接时请注意。

9 固定域名（进阶）

想长期用自己的域名访问，可以在前面放一个反向代理（如 Nginx）转发到 127.0.0.1:8766。要点：

• 反向代理要把原始 Host 传给后端，并把域名加进环境变量 KHQUANT_WEB_ALLOWED_HOSTS（逗号分隔），否则会被拒绝。支持子路径部署。
• 以 127.0.0.1 监听时网页本身不要求密钥，未开启临时外网访问时，经反向代理过来的公网请求也不需要任何密钥。一定要在反向代理层加自己的登录认证，或者另设 KHQUANT_WEB_ACCESS_KEY 加一道密钥。

10 和桌面版共用什么

常见问题

问：点地球图标提示端口 8766 已被其他程序占用？
答：有别的程序占着 8766。关掉它，或者用 kh web --port 8800 换个端口启动。启动失败的详细日志在 ~\.khquant\web\logs\web_service.log。

问：工具栏上没有地球图标？
答：当前安装的版本不含 Web 模块。请从 内测版下载页下载完整安装包。

问：预检提示「网页回测仅支持 DuckDB 数据源」？
答：到桌面版「设置 → 数据设置」把回测数据源改回「DuckDB本地数据库」。

问：怎么关掉 Web 服务？
答：用命令启动的，在终端按 Ctrl+C。用地球图标启动的，界面上没有关闭按钮，可以在任务管理器里结束对应的 kh.exe 进程，或者重启电脑。

问：「开启临时外网访问」按钮是灰的？
答：这个按钮只出现在运行服务的电脑本机上；灰色表示缺少临时访问组件 cloudflared（页面会提示「当前安装缺少临时访问组件」，Linux 和源码运行要自己装）。从别的电脑或手机访问时不会显示这个按钮，只会看到「正在通过临时安全链接访问」的提示，见附录 B 第 7 节。

问：手机打不开临时链接？
答：新地址可能要约 1 分钟生效，稍等再试；仍不行就关闭后重新开启，换一个地址。

问：Mac 上点「选择一个 .kh 配置文件」报错？
答：这个按钮只支持 Windows，在 Mac 上请手动输入完整路径。

本篇基于 V3.4.1.10 编写。