2.5 Linux

本篇重点：本篇讲在没有图形界面的 Linux 上用 pipx 或 Docker 安装 V3，并用 kh 命令和 Web 工作台完成全部回测流程。

1 三个平台对照

2 用 pipx 安装

2.1 准备

• 推荐 Ubuntu 22.04 或 24.04，x86_64，Python 3.10～3.12（3.13 装不上）。
• Linux 版和 Windows、macOS 版放在同一个地方：登录官网后在 内测版下载页 的「Linux CLI」一栏，下载 wheel（khquant-版本号-py3-none-any.whl）和「SHA256校验」（SHA256SUMS-版本号.txt）两个文件，传到 Linux 机器的同一个目录里（比如用 scp）。

2.2 安装

sudo apt update
sudo apt install -y pipx
pipx ensurepath
cd 放安装文件的目录
sed 's/\r$//' SHA256SUMS-3.4.1.10.txt | sha256sum -c --ignore-missing
pipx install ./khquant-3.4.1.10-py3-none-any.whl
exec "$SHELL" -l
kh version

• 以上以 3.4.1.10 为例，文件名以内测版下载页实际版本为准。下面是在一台全新的 Ubuntu 22.04 上逐条执行的实拍（实拍时是 3.4.1.9，截图里的文件名版本号不同，步骤完全一样）。
• sha256sum 一行校验下载的文件是否完整，应显示 khquant-3.4.1.10-py3-none-any.whl: OK。前面的 sed 是把校验文件里 Windows 格式的换行去掉，否则会提示 no file was verified。
• 漏了 pipx ensurepath 或没重新打开终端，会提示 kh: command not found（kh 装在 ~/.local/bin）。

实拍：逐条执行

① 两个文件放在同一个目录（这里是 ~/khdl）：

② sudo apt install -y pipx 装好 pipx 后，运行 pipx ensurepath，它会把 ~/.local/bin 加进 PATH，并提示要重新打开终端才生效：

③ 校验文件，看到 OK 就说明下载完整：

④ pipx install 安装。因为当前终端还没重新加载，这里会出现一段「~/.local/bin is not on your PATH」的提示，属于正常现象，接着运行 exec "$SHELL" -l（或关掉终端重开）即可：

⑤ kh version 能打印版本号，安装就完成了：

2.3 初始化和第一次回测

kh doctor
kh init
kh data download --source tx --stocks 000001.SZ --period 1d --start 20240101 --adj front
kh run "【1-MA策略案例】双均线精简_使用khMA函数.kh" --report --no-open
kh result show

• Linux 上的 kh init 没有选择回测数据源那一步，一路回车即可：数据目录 ~/khquant/data，策略目录 ~/khquant/strategies（自带示例会复制进去）。
• 没运行 kh init 之前，大部分命令只会提示「尚未初始化」。
• kh doctor 在 Linux 上一定会有一条「历史行情导入源 miniqmt 未就绪」的警告，可以忽略。
• 用 tx 下载要加 --adj front，否则示例策略拿不到前复权价，回测会一笔交易都没有。其他数据源见 2.3；miniQMT 的数据可以通过 HTTP 桥接从 Windows 电脑取，见 2.3 第 4 节。
• 命令行的完整用法和用 AI 做研究见 2.2。

实拍：初始化到出结果

① 还没 kh init 时运行 kh doctor，依赖都显示 OK，另有 5 条警告：schedule 未安装（只影响定时补数据，见第 3 节）、miniqmt 未就绪（Linux 上必然出现）、数据目录和策略目录未配置（kh init 后消失）、Tushare 未配置（可选）：

② kh init 一路回车用默认值，最后打印配置摘要，已复制 25 个示例文件到策略目录（13 个案例的 .py 和 .kh 等）：

③ 用 tx 下载 000001.SZ 的前复权日线。示例策略的基准是沪深 300，软件会顺带把 000300.SH 的日线也下载下来，所以会看到两条「保存」：

④ 运行示例策略，终端先滚动输出运行日志，最后给出回测结果和 HTML 报告的位置（区间取策略文件里的 2025-01-01 ～ 2025-07-03）：

⑤ kh result show 查看最近一次回测的绩效指标：

Linux 上没有浏览器时，把报告目录里的 report.html 拷到本机打开，或者用第 4 节的 Web 工作台查看。

2.4 目录

Linux 版默认按北京时间（Asia/Shanghai）判断交易日和时间，和服务器自己的时区无关；需要时可用环境变量 KHQUANT_MARKET_TZ 改动（见附录 A）。

3 定时补数据

wheel 默认不带定时需要的 schedule 库，先装上：

pipx inject khquant schedule
kh data sync --source tx --schedule 16:30

这条命令会在前台一直运行，适合放在 tmux 或 screen 里。也可以改用 cron 每天跑一次（不需要 schedule 库）：

30 16 * * 1-5 $HOME/.local/bin/kh data sync --source tx >> $HOME/kh_sync.log 2>&1

注意 cron 是按服务器的系统时区触发的。很多云服务器是 UTC，北京时间 16:30 要写成 UTC 08:30（30 8 * * 1-5）。sync 的规则和局限见 2.3 第 10 节。

4 Web 回测工作台

• 本机：kh web --no-open，然后在本机浏览器打开 http://127.0.0.1:8766/（服务器上通常配合 SSH 端口转发使用）。8766 被占用时会提示「端口 8766 已被其他程序占用」，加 --port 换一个端口，比如 kh web --no-open --port 8799。
• 局域网：kh web --host 0.0.0.0 --no-open，用终端打印的带访问密钥的链接打开。
• 临时外网访问：先从 Cloudflare 官方安装 cloudflared 并放进 PATH（或设置 KHQUANT_CLOUDFLARED_PATH）。
• 长期用域名访问：保持监听 127.0.0.1，前面放 Nginx 或 Caddy 配 HTTPS 和登录认证，并把域名加进 KHQUANT_WEB_ALLOWED_HOSTS，见 2.6 第 9 节。

想让 Web 服务开机自动运行，可以交给 systemd 管理。下面是一个参考写法（非官方，用户名和路径按实际修改）：

[Unit]
Description=khQuant Web
After=network-online.target

[Service]
User=你的用户名
ExecStart=/home/你的用户名/.local/bin/kh web --no-open
Restart=on-failure

[Install]
WantedBy=multi-user.target

5 Docker

不想动服务器的 Python 环境，可以用内测版下载页上的 Docker 镜像（khquant-docker-版本号.tar.gz，同样可以用 SHA256 文件校验）。镜像只支持 x86_64（linux/amd64），ARM 服务器不能用。

gunzip -c khquant-docker-3.4.1.10.tar.gz | docker load
docker run --rm -it \
  -v "$HOME/khquant-docker/.khquant:/root/.khquant" \
  -v "$HOME/khquant-docker/khquant:/root/khquant" \
  -v "$PWD:/work" \
  khquant:3.4.1.10 doctor

• 镜像的入口就是 kh，khquant:3.4.1.10 后面直接写子命令，比如 init、data download …、run …。
• 设置、数据和结果都必须通过 -v 挂载到容器外，否则容器删掉就没了。上面的例子给 Docker 单独用了一套目录，不要和本机 pipx 安装的 khQuant 共用 ~/.khquant，两边的数据路径会互相覆盖。
• 跑 Web：docker run --rm -it -p 8766:8766 -v …（同上） khquant:3.4.1.10 web --host 0.0.0.0 --port 8766 --no-open。容器里必须用 --host 0.0.0.0。
• 镜像里不含 cloudflared 和 schedule 库，容器以 root 运行，挂载目录里生成的文件属于 root。

6 从 Windows 搬到 Linux

1. 在 Windows 上关掉 khQuant（包括定时补充、数据管理窗口），避免拷到写了一半的数据。
2. 把整个 DuckDB 数据目录拷过去，放在任意位置，然后运行 kh config set duckdb_data_path 新的目录。拷完可以用 kh data stats 核对。
3. 策略的 .kh 和 .py 放在同一个文件夹里一起拷。.kh 里记的 Windows 路径失效时，软件会自动用同一文件夹里的同名策略。

7 升级和卸载

• 升级：下载新版 wheel，运行 pipx install --force ./khquant-新版本-py3-none-any.whl。pipx upgrade 对这种安装方式无效。重装后之前 inject 的 schedule 需要重新 inject。
• Docker 升级：load 新版本镜像，运行时换成新的标签。
• 卸载：pipx uninstall khquant；Docker 镜像用 docker rmi khquant:版本号 删除。~/.khquant 和 ~/khquant 里的设置、数据、结果不会删，不需要时手动删除。

常见问题

问：Linux 上提示 kh: command not found？
答：运行 pipx ensurepath，然后重新打开终端（或 exec "$SHELL" -l）。

问：大部分命令都提示「尚未初始化」？
答：先运行一次 kh init。

问：示例策略回测完一笔交易都没有？
答：用 tx 下载时没加 --adj front。加上重新下载即可。

问：pipx upgrade khquant 没反应？
答：本地 wheel 安装的不能这样升级，用 pipx install --force 装新版 wheel。

问：kh data sync --schedule 报需要 schedule 库？
答：运行 pipx inject khquant schedule。

本篇基于 V3.4.1.10 编写，在 Ubuntu 22.04 上实测；Docker 部分按发行说明编写。