Linux部署教程

适用版本：v3.3.1 及以上

目标：在 Linux 服务器、Docker 容器或 WSL2 中完整部署 khQuant CLI，并与 Windows GUI 端共用同一份策略代码、同一份 .kh 配置文件。

本文是官网正式教程，配套阅读：khQuant CLI 命令行工具完整指南。

---

目录

• 一、为什么要在 Linux 上部署 khQuant
• 二、Linux 端能力矩阵
• 三、环境准备
• 四、GitHub 私有库认证（关键一步）
• 五、方式 A：pipx 安装（推荐）
• 六、方式 B：Docker 部署
• 七、首次使用三连：init → data → run
• 八、升级与卸载
• 九、故障排查 FAQ
• 十、附录：命令速查与资源

---

一、为什么要在 Linux 上部署 khQuant

khQuant 的图形界面 (GUI) 版本一直是 Windows 端的主力交付形态。v3.3.1 起新增的 Linux CLI 部署，并非替代 Windows 版，而是把 khQuant 的应用边界向以下场景扩展：

场景	Linux 部署的价值
云服务器跑批	Linux 云主机便宜、稳定、不弹更新窗口；适合长时间挂机做参数寻优
Docker / 容器化	镜像分发、严格隔离、一份镜像多机部署，CI/CD 友好
接入第三方量化基础设施	多数 Linux 部署的开源量化工具（数据服务、调度框架等）可同环境部署、互相调用
Mac / Linux 主力开发者	通过 SSH 远程操作云上 khQuant，本地可使用任意操作系统

✅ Windows 端的所有用户体验保持不变，本文不影响 Windows 用户的使用方式。

---

二、Linux 端能力矩阵

2.1 整体差异

维度	Windows GUI 版	Linux CLI 版
图形界面 (PyQt5)	✅ 完整 GUI	❌ 不支持，仅命令行
内嵌 VSCode 调试	✅ 支持	❌ 使用本机任意编辑器
xtdata 数据源	✅ 支持	❌ 不支持（xtdata 仅 Windows 可用）
BaoStock 数据源	✅ 支持	✅ 推荐使用
Tushare 数据源	✅ 支持	✅ 支持
本地 DuckDB 数据	✅ 支持	✅ 支持（可从 Windows 同步）
回测、参数寻优	✅ 支持	✅ 支持
HTML 回测报告	✅ 自动浏览器打开	✅ 输出文件，需 scp/静态服务查看

2.2 一句话总结

在 Linux 端，除了无法使用 xtdata 数据源、没有 GUI 之外，其余功能通过 CLI 模式使用起来与 Windows 端没有区别。 两端共用同一份 .kh 配置文件无缝切换，策略代码不需要修改。

---

三、环境准备

以下命令以 Ubuntu 22.04 LTS 为例。其他主流发行版（Debian、CentOS / RHEL、Fedora、Arch）将 apt 替换为对应包管理器即可。

3.1 Python 3.10+

python3 --version
# 若版本 < 3.10 或未安装：
sudo apt update
sudo apt install -y python3 python3-pip

3.2 pipx（强烈推荐用于安装 kh 命令）

pipx 会为每个 Python 应用建立独立虚拟环境，与系统 Python 完全隔离，安装、升级、卸载都很干净：

sudo apt install -y pipx
pipx ensurepath        # 关键：把 ~/.local/bin 加入 PATH
source ~/.bashrc       # 立即生效（zsh 用户改为 source ~/.zshrc）

⚠️ pipx ensurepath 是新装 pipx 用户最容易漏的一步。漏掉它会出现 kh: command not found，因为 ~/.local/bin 还没加入 PATH。

3.3 git + GitHub CLI（私有库下载必备）

由于 khscience/CSkhQuant 是私有仓库，下载 release 资产前必须完成 GitHub 认证。最方便的工具是官方 gh CLI。注意 gh auth login 内部会调用 git 配置凭据，必须先安装 git：

# 1. git（gh 登录的隐藏前置依赖）
sudo apt install -y git
# CentOS/RHEL/Fedora:  sudo dnf install -y git
# Arch:                sudo pacman -S --noconfirm git
git --version

# 2. gh CLI
sudo apt install -y gh
gh --version

若 apt 里找不到 gh，参考 cli.github.com 添加 GitHub 官方源后再装。

3.4 Docker（可选，仅方式 B 需要）

sudo apt install -y docker.io
sudo usermod -aG docker $USER     # 把当前用户加进 docker 组（避免每次 sudo）
newgrp docker                     # 立即生效（或重新登录）
docker run --rm hello-world       # 验证

---

四、GitHub 私有库认证（关键一步）

这一节面向 v3.3 内测群的朋友：你们都已经被拉进项目的 GitHub 私有库 khscience/CSkhQuant，所有下载和安装步骤都依赖一次性的 GitHub 认证。

4.1 为什么直接下载会 404？

如果直接执行：

pipx install https://github.com/khscience/CSkhQuant/releases/download/v3.3.1/khquant-3.3.1-py3-none-any.whl

通常会得到：

ERROR: HTTP error 404 while getting ...

这不是文件丢失，而是 GitHub 对未认证请求私有库资源的安全行为：统一返回 404 Not Found 而不是 401 Unauthorized，避免暴露仓库的存在性。所有下载操作之前，本机必须先认证 GitHub。

4.2 方式一：gh auth login（最简单，强烈推荐）

适合：本机或可访问浏览器的任意设备（手机、另一台电脑均可）。

gh auth login

按以下提示一路选：

? What account do you want to log into?              GitHub.com
? What is your preferred protocol for Git operations? HTTPS
? Authenticate Git with your GitHub credentials?     Yes
? How would you like to authenticate?                Login with a web browser

终端会打印一个 8 位 one-time code（形如 XXXX-XXXX），并提示打开 github.com/login/device。关键点：

• 如果当前机器有浏览器，直接在本机浏览器登录；
• 如果是纯命令行的云服务器（SSH 登录），可在任意设备（手机 / 另一台电脑）打开 github.com/login/device，输入 code 完成授权。

授权完成后，终端会显示类似：

✓ Configured git protocol
! Authentication credentials saved in plain text
✓ Logged in as khscience
! You were already logged in to this account

只要看到 ✓ Logged in as <你的账号>，就说明认证成功。一次配好，后续所有 gh 命令、git clone 私有库都不需要再输密码。

4.3 方式二：Personal Access Token (PAT)

适合：CI/CD、Docker 容器内、纯 headless 服务器、需精确控制权限范围。

Step 1：生成 token

打开 github.com/settings/tokens → 点击 Generate new token (classic)：

字段	推荐值
Note	khquant-linux-deploy
Expiration	90 days（可按需调整）
Select scopes	必须勾选 repo（私有库读取权限）

点击 Generate token，复制生成的 ghp_xxxxxxxxxxxxxxxxxxxx 字符串 —— 该字符串只显示一次，请妥善保存。

Step 2：让本机使用此 token

# 临时使用（仅当前 shell）
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# 永久使用（写入 ~/.bashrc）
echo 'export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx' >> ~/.bashrc
chmod 600 ~/.bashrc
source ~/.bashrc

gh 命令会自动读取 GITHUB_TOKEN 环境变量。

4.4 方式三：SSH 密钥（仅适合 git clone 源码）

如果计划直接克隆源码（参考 5.4 小节），SSH 密钥最稳定：

ssh-keygen -t ed25519 -C "your-email@example.com"
cat ~/.ssh/id_ed25519.pub                    # 复制公钥
# 到 https://github.com/settings/keys 添加 SSH key
ssh -T git@github.com                        # 验证："successfully authenticated" 即可

4.5 验证认证状态

gh auth status

期望输出：

github.com
  ✓ Logged in to github.com account your-username
  - Active account: true
  - Token scopes: 'repo', 'read:org', ...

只要看到 ✓ Logged in，认证就 OK 了。

---

五、方式 A：pipx 安装（推荐）

适用场景：个人开发机、单台云主机、不需要严格容器隔离。

5.1 下载 release 资产

gh release download v3.3.1 --repo khscience/CSkhQuant
ls -lh

预期输出：

khquant-3.3.1-py3-none-any.whl       420K
khquant-3.3.1.tar.gz                 480K
khquant-docker-3.3.1.tar.gz          254M
checksums.txt                        284B

5.2 安装 wheel

# 若 3.2 节已跑过 pipx ensurepath，可跳过这一步
pipx ensurepath

pipx install ./khquant-3.3.1-py3-none-any.whl

# 让 PATH 立即在当前终端生效（三选一）：
exec $SHELL -l         # ① 推荐：重启当前 shell 并加载配置
# source ~/.bashrc     # ② bash 用户手动 source
# （或直接关闭终端重开） ③ 最稳，无需任何命令

pipx 会自动建立独立虚拟环境，安装所有依赖（pandas、numpy、duckdb、baostock、tushare 等），并把 kh 命令链接到 ~/.local/bin/。

5.3 验证

kh version              # 查看版本，应输出 3.3.1
kh --help               # 查看子命令一览
kh doctor               # 体检：Python 版本、依赖、配置、目录

kh doctor 第一次运行可能有几个红/黄警告（如”未配置数据目录”），属正常现象 —— 下一节 kh init 会处理掉大部分。

5.4 备选：从源码安装

适合需要修改源码、参与开发的同学：

gh repo clone khscience/CSkhQuant
cd CSkhQuant
pipx install .
kh version

---

六、方式 B：Docker 部署

适用场景：多机部署、CI/CD、需要严格环境隔离、不愿污染宿主机。

6.1 加载镜像

gh release download v3.3.1 --repo khscience/CSkhQuant -p 'khquant-docker-*.tar.gz'
docker load -i khquant-docker-3.3.1.tar.gz
docker images | grep khquant         # 验证：能看到 khquant:3.3.1

镜像基于 python:3.11-slim，包含全部 Python 依赖：未压缩约 980 MB，压缩后约 254 MB。

6.2 验证

docker run --rm khquant:3.3.1 version

6.3 持久化运行（推荐）

容器是无状态的，配置和数据必须挂卷出来才不会随容器销毁。两个推荐挂载点：

容器内路径	宿主机映射	用途
/root/.khquant	~/.khquant	配置文件（settings.json、tushare token）
/root/khquant	~/khquant	数据 / 策略 / 回测结果（DuckDB、.kh、报告）

# 首次初始化
docker run -it --rm \
  -v ~/khquant:/root/khquant \
  -v ~/.khquant:/root/.khquant \
  khquant:3.3.1 init

# 跑回测
docker run -it --rm \
  -v ~/khquant:/root/khquant \
  -v ~/.khquant:/root/.khquant \
  khquant:3.3.1 run rsi.kh --report

6.4 用 alias 简化命令（推荐）

每次都打长命令太累，写进 ~/.bashrc：

alias kh='docker run -it --rm -v ~/khquant:/root/khquant -v ~/.khquant:/root/.khquant khquant:3.3.1'

之后用法和 pipx 安装完全一致：kh init、kh run xxx.kh。

6.5 用 docker compose 管理（团队 / 多服务推荐）

为多人共享或长期维护，可写一个 docker-compose.yml：

# docker-compose.yml
services:
  khquant:
    image: khquant:3.3.1
    volumes:
      - ./khquant:/root/khquant
      - ./.khquant:/root/.khquant
    stdin_open: true
    tty: true

使用：

docker compose run --rm khquant init
docker compose run --rm khquant run rsi.kh --report

---

七、首次使用三连：init → data → run

无论使用 pipx 还是 Docker，跑通第一个回测的流程都是固定三步。

7.1 kh init —— 5 步交互式向导

kh init

依次回答 5 个问题（全部直接回车走默认值即可）：

步骤	问题	默认值	说明
1	选择数据源	baostock	免费、无需 token，推荐首次使用
2	数据目录	~/khquant/data	自动建好 SH/SZ/BJ 三个市场子目录
3	策略目录	~/khquant/strategies	自动同步内置示例策略（ma、rsi 等）
4	回测结果目录	~/khquant/backtest_results	单次回测一份子目录
5	日志目录	~/khquant/logs	含运行日志、错误日志

💡 v3.3.1 改进：以前要等到第一次 kh run 时框架才会发现数据目录不存在，然后误 fallback 到 xtdata（在 Linux 上必然失败）。新版在 init 时就把目录建好，杜绝这个坑。

7.2 kh data download —— 准备历史数据

Linux 上没有 xtdata，第一步必须用 BaoStock 或 Tushare 把数据下载到本地 DuckDB：

# 最快验证：平安银行近一年日线
kh data download --source baostock --stocks 000001.SZ --period 1d --start 20240101

# 一次下载沪深 300 日线全量（耗时几分钟）
kh data download --source baostock --pool hs300 --period 1d --start 20240101

# 只增量更新已有股票池
kh data download --source baostock --pool hs300 --period 1d --update

下载完成后查看：

kh data list                    # 列出所有已入库股票
kh data info 000001.SZ          # 查看某只股票的数据范围

完整参数列表参见 官网 CLI 指南 · kh data 章节。

7.3 kh run —— 跑通第一个回测

环境就绪后，第一个回测怎么跑、报告怎么看，请跟随官网 CLI 指南的「5 分钟上手流程」操作：

👉 khQuant CLI 完整指南 · § 5 分钟上手流程

涵盖内置示例策略选择、所需数据准备、kh run 参数、--report 在无 GUI 环境下的查看方式等全部细节，Windows 与 Linux 通用。

关于 HTML 报告在无 GUI 环境下的查看

服务器一般没有浏览器，两种推荐方案：

# 方案 A：scp 拉回本地用浏览器打开
scp user@server:~/khquant/backtest_results/xxx/report.html .

# 方案 B：在服务器起一个临时静态 HTTP 服务
cd ~/khquant/backtest_results
python3 -m http.server 8080
# 然后本机浏览器访问 http://your-server:8080

跑通后整个流程从 kh init 到第一份报告生成，5 分钟以内可走完。

---

八、升级与卸载

8.1 升级到新版本

# pipx 用户
gh release download vX.Y.Z --repo khscience/CSkhQuant
pipx install --force ./khquant-X.Y.Z-py3-none-any.whl
exec $SHELL -l                 # 让 PATH 更新

# Docker 用户
gh release download vX.Y.Z --repo khscience/CSkhQuant -p 'khquant-docker-*.tar.gz'
docker load -i khquant-docker-X.Y.Z.tar.gz
# 修改 alias 或 docker-compose.yml 里的版本号即可

pipx install --force 会保留虚拟环境，仅替换包内容；~/khquant 与 ~/.khquant 下的数据、配置、策略不受影响。

8.2 完整卸载

# pipx
pipx uninstall khquant
rm -rf ~/khquant ~/.khquant     # 数据和配置（按需，谨慎执行）

# Docker
docker rmi khquant:3.3.1
rm -rf ~/khquant ~/.khquant     # 同上

---

九、故障排查 FAQ

Q1：pipx install 成功了，但 kh: command not found

原因：~/.local/bin 还没加进 PATH。

修复：

pipx ensurepath
source ~/.bashrc       # zsh 用户改 ~/.zshrc
kh version             # 验证

或直接关闭终端重开。

Q2：pipx install <release-url> 报 404

原因：私有库未认证，GitHub 对未认证请求返回 404 而非 401。

修复：回到 第四章 完成 gh auth login，然后用 gh release download 拿 wheel 文件，不要直接用 URL 安装。

Q3：kh doctor 显示 “xtdata 不可用”

这是 Linux 上的正常现象，不是 bug。Linux 上 xtdata 永远不可用，只要确认 .kh 配置和 kh data download 都使用 baostock / tushare / 本地 DuckDB 即可。

Q4：kh run xxx.kh 提示 “配置文件不存在”

先确认策略目录是否包含该文件：

kh strategy list

如果列表中存在该文件，说明 v3.3.1 的路径解析正常工作。如果不存在，可能是 kh init 时选错策略目录，重新执行 kh init 即可。

v3.3.1 改进：kh run xxx.kh 不再要求 cd 到策略目录，会自动按以下顺序查找：① 当前目录 ② 配置的策略目录 ③ 自动补 .kh 后缀。Windows / Linux 行为完全一致。

Q5：Docker 镜像太大（~980 MB），想瘦身

khquant-docker-3.3.1.tar.gz 已压缩到 254 MB，docker load 后展开 ~980 MB —— 这是因为 pandas、numpy、scipy、matplotlib、duckdb 这些科学计算库本身体积较大。

如果不需要 HTML 报告（matplotlib），可在容器内执行：

docker run -it --name khquant-slim khquant:3.3.1 bash
# 在容器内：
pip uninstall -y matplotlib
exit
docker commit khquant-slim khquant:3.3.1-slim
docker rm khquant-slim

Q6：gh auth login 走到一半报错 “git not found”

原因：gh auth login 内部会调用 git 配置凭据，必须先安装 git。

修复：

sudo apt install -y git       # 或 dnf / pacman
gh auth login                 # 重试

Q7：gh release download 提示 404

原因：token 缺少 repo scope，无法读取私有库 release 资产。

诊断：

gh auth status                # 查看 Token scopes 是否含 'repo'

修复：

gh auth refresh -h github.com -s repo
gh release download v3.3.1 --repo khscience/CSkhQuant

Q8：中文文件名（如 【1-MA策略案例】双均线.kh）能跑吗？

可以。Linux 与 Docker 下中文文件名合法、能正常加载。如果终端没装中文字体（纯命令行 SSH），输出可能显示乱码 —— 那是显示问题，不影响实际执行。

---

十、附录：命令速查与资源

10.1 安装 / 升级速查

# 一次性配置
sudo apt install -y git gh pipx
pipx ensurepath
gh auth login

# 首次安装 v3.3.1
gh release download v3.3.1 --repo khscience/CSkhQuant
pipx install ./khquant-3.3.1-py3-none-any.whl
exec $SHELL -l

# 升级
gh release download vX.Y.Z --repo khscience/CSkhQuant
pipx install --force ./khquant-X.Y.Z-py3-none-any.whl

# 卸载
pipx uninstall khquant

10.2 日常使用速查

kh version                      # 查版本
kh doctor                       # 体检
kh init                         # 初始化配置
kh data download --source baostock --stocks 000001.SZ --period 1d --start 20240101
kh data list                    # 已入库股票列表
kh data info 000001.SZ          # 单只股票数据范围
kh strategy list                # 策略列表
kh run rsi.kh --report          # 跑回测 + HTML 报告
kh result list                  # 历史回测结果

10.3 文件 / 目录速查

路径	作用
~/.khquant/settings.json	全局配置（数据源、目录、token）
~/khquant/data/{SH,SZ,BJ}/	DuckDB 数据库（每只股票一个 .db）
~/khquant/strategies/	策略文件（.py + .kh）
~/khquant/backtest_results/	回测结果（按运行时间命名子目录）
~/khquant/logs/	运行日志
~/.local/bin/kh	pipx 安装的 kh 命令（绝对路径）

10.4 相关链接

• khQuant 官网首页
• CLI 命令行工具完整指南 ← 命令参数与示例最全
• 策略框架介绍
• 策略工具箱 khQTTools
• GitHub Release v3.3.1（内测）
• 微信公众号：看海的城堡

---

版本：本文基于 khQuant v3.3.1
最后更新：2026-04-29