Linux部署教程 - khQuant看海量化回测平台

适用版本：KhQuant V3.4.0。推荐 Ubuntu 22.04 / 24.04 x86_64，Python 3.10、3.11 或 3.12。

Linux 版适合无桌面的服务器、Docker、批量回测和远程 Web 控制。它与 Windows/macOS 使用同一套回测核心，正式包含 kh CLI 与完整 Web 回测工作台；不包含 PyQt 桌面 GUI、miniQMT/xtdata 和 Windows 实盘交易。

一、先了解 Linux 版能做什么

能力	Linux V3.4.0
DuckDB 数据与回测	支持
BaoStock / Tushare / HTTP 桥接下载	支持
`kh` 命令行	支持
`kh web` 网页回测工作台	支持
HTML 回测报告	支持
PyQt 桌面 GUI	不支持
miniQMT / xtquant / Windows 实盘	不支持

Web 与普通 kh run 调用同一套回测核心，不是另一套引擎。策略文件、.kh 配置、DuckDB 数据和结果协议可以跨平台迁移。

二、pipx 安装

先安装基础工具：

sudo apt update
sudo apt install -y git gh pipx
pipx ensurepath
gh auth login

下载 V3.4.0 Release 并校验：

gh release download v3.4.0 --repo khscience/CSkhQuant
sha256sum -c checksums.txt --ignore-missing
pipx install ./khquant-3.4.0-py3-none-any.whl
exec "$SHELL" -l

完成后执行：

kh version
kh doctor
kh init

也可以在仓库根目录运行：

./scripts/install.sh 3.4.0

安装脚本会校验 Release SHA256，并在升级旧 pipx 环境前迁移旧位置中的回测结果。

三、用户数据目录

内容	默认位置
全局设置	`~/.khquant/settings.json`
DuckDB 数据	`~/khquant/data`
策略	`~/khquant/strategies`
回测结果	`~/khquant/backtest_results`
Parquet 缓存	`${XDG_CACHE_HOME:-~/.cache}/khquant/parquet_cache_pack`

设置文件使用 0600 权限，设置目录使用 0700 权限。Tushare Token 由用户自行配置，不会预置到 wheel、Docker 镜像或 Release 日志中。

四、运行第一次回测

kh data stats
kh strategy list
kh run ~/khquant/strategies/策略配置.kh --report --no-open
kh result show

HTML 报告可以离线生成；部分交互图表资源从公共 CDN 加载，完全离线浏览时可能无法显示交互图表。

五、启动 Web 工作台

服务器本机启动：

kh web --no-open

默认只监听 127.0.0.1:8766。如果要从同一局域网中的电脑或手机访问：

kh web --host 0.0.0.0 --port 8766 --no-open

非回环监听会自动生成随机访问密钥，终端会打印带密钥的网址。不要绕过密钥，也不要把网址和密钥写入公开文档或日志。

临时外网访问

工作台的一键临时访问使用 Cloudflare Quick Tunnel，能够生成临时 HTTPS 地址，不要求公网 IP，也不需要设置路由器端口映射。源码/wheel 不内置第三方 cloudflared，需要提前安装并放入 PATH，或者设置：

export KHQUANT_CLOUDFLARED_PATH=/path/to/cloudflared

临时隧道适合偶尔从手机控制，关闭后网址和访问密钥立即失效，不适合作为固定站点。

自有域名长期部署

服务器长期运行时，建议仍让 KhQuant 监听 127.0.0.1，再用 Nginx 或 Caddy 提供 HTTPS、自有域名和额外认证。不要把无认证的 0.0.0.0:8766 直接暴露到公网。

六、Docker

V3.4.0 的 Docker 发行物当前为 linux/amd64：

gunzip -c khquant-docker-3.4.0.tar.gz | docker load

docker run --rm -it \
  -v "$HOME/.khquant:/root/.khquant" \
  -v "$HOME/khquant:/root/khquant" \
  -v "$PWD:/work" \
  khquant:3.4.0 doctor

数据、策略、设置和回测结果必须挂载到容器外，避免删除容器后丢失。

运行 Web 时映射端口：

docker run --rm -it -p 8766:8766 \
  -v "$HOME/.khquant:/root/.khquant" \
  -v "$HOME/khquant:/root/khquant" \
  khquant:3.4.0 web --host 0.0.0.0 --port 8766 --no-open

七、平台兼容说明

A 股时间统一按 Asia/Shanghai 解释，不受服务器默认 UTC 时区影响。
数据目录优先使用规范的 SH/SZ/BJ，也能读取历史复制数据中的 sh/sz/bj。
Linux wheel 和 Docker 都注册 kh web 并携带生产前端资源。
kh gui 和 kh bridge serve 在 Linux 会给出明确的平台不支持提示，不会尝试加载 Windows/macOS 组件。
并发运行时每次回测使用独立临时配置；不要手工删除其他任务正在使用的运行文件。

八、排错顺序

kh version：确认实际运行的是 V3.4.0。
kh doctor：检查 Python、依赖、目录和数据源。
kh web --no-open：观察终端是否打印实际监听地址和访问密钥。
端口冲突时先用系统工具查出占用进程；已有 KhQuant Web 服务应优先复用，不要重复启动。
Web 页面能打开但回测失败时，查看实时日志、运行事件和结果目录；不要把“没有有效时间点”或 DuckDB 锁跳过当作成功。

完整网页操作请继续阅读 Web 回测工作台使用教程；命令参数以 kh --help、kh web --help 以及当前 Release 文档为准。