OpenViking 源代码编译指南

本文档详细介绍如何从源代码编译 OpenViking，适用于需要修改核心代码或开发新功能的开发者。

环境要求
[1. 安装依赖](#1. 安装依赖)
[2. 从源代码编译](#2. 从源代码编译)
[3. 运行编译后的代码](#3. 运行编译后的代码)
[4. 常见问题及解决方案](#4. 常见问题及解决方案)
[5. 开发工作流](#5. 开发工作流)
[6. 高级编译选项](#6. 高级编译选项)

环境要求

核心依赖

Python: 3.10 或更高版本
Rust: 1.91.1 或更高版本
CMake: 3.12 或更高版本
C++ 编译器: GCC 9+ 或 Clang 11+
操作系统: macOS, Linux (Windows 支持有限)

可选依赖

Maturin: 用于构建 Rust 绑定
uv: 用于更快的 Python 包管理

1. 安装依赖

1.1 安装系统依赖

macOS

bash 复制代码

# 使用 Homebrew 安装依赖
brew install rust cmake

# 安装 Clang (如果未安装)
xcode-select --install

Ubuntu/Debian

bash 复制代码

# 安装依赖
sudo apt update
sudo apt install -y rustc cargo cmake build-essential

CentOS/RHEL

bash 复制代码

# 安装依赖
sudo yum install -y rust cargo cmake gcc-c++

# 或使用 dnf
sudo dnf install -y rust cargo cmake gcc-c++

1.2 安装 Python 依赖

bash 复制代码

# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate  # macOS/Linux
# 或 .venv\Scripts\activate  # Windows

# 安装基础依赖
pip install -e "[build,test,dev]"

# 安装 Maturin (用于 Rust 绑定构建)
pip install maturin

2. 从源代码编译

2.1 检查依赖

bash 复制代码

# 检查所有依赖是否满足
make check-deps

# 预期输出：
# Checking dependencies...
#   [OK] Python 3.10.12
#   [OK] CMake 3.26.4
#   [OK] Rust 1.91.1
#   [OK] Clang 14.0.6

2.2 执行构建

bash 复制代码

# 执行完整构建
make build

# 或直接运行 setup.py
python setup.py build_ext --inplace

2.3 构建过程详解

构建过程会执行以下步骤：

构建 ov CLI (Rust): 编译 Rust 命令行工具
构建 ragfs-python (Rust): 编译 RAGFS Rust 绑定
构建 C++ 扩展: 编译核心向量数据库引擎
安装开发版本: 以可编辑模式安装包

3. 运行编译后的代码

3.1 启动服务器

bash 复制代码

# 激活虚拟环境
source .venv/bin/activate

# 设置配置文件
export OPENVIKING_CONFIG_FILE=/path/to/ov.conf

# 启动服务器
openviking-server

# 或在后台运行
nohup openviking-server > openviking.log 2>&1 &

3.2 启动 Web 控制台

bash 复制代码

# 激活虚拟环境
source .venv/bin/activate

# 启动控制台
python -m openviking.console.bootstrap --openviking-url http://127.0.0.1:1933

# 或在后台运行
nohup python -m openviking.console.bootstrap --openviking-url http://127.0.0.1:1933 > console.log 2>&1 &

3.3 运行 CLI 命令

bash 复制代码

# 激活虚拟环境
source .venv/bin/activate

# 检查服务器状态
ov status

# 添加资源
ov add-resource /path/to/your/project --wait

# 搜索内容
ov find "your query"

4. 常见问题及解决方案

4.1 依赖问题

问题 : ModuleNotFoundError: No module named 'xxx'

解决方案: 安装缺失的依赖

bash 复制代码

pip install [缺失的包名]

4.2 Rust 编译问题

问题 : error: could not compile 'ov_cli'

解决方案:

确保 Rust 版本 >= 1.91.1
清理 Cargo 缓存: cargo clean
更新 Rust: rustup update

4.3 CMake 编译问题

问题 : error: command 'cmake' failed

解决方案:

确保 CMake 版本 >= 3.12
检查 C++ 编译器是否安装
清理构建目录: make clean

4.4 跳过 Rust 组件构建

问题: 只想构建 C++ 扩展，跳过 Rust 组件

解决方案: 使用环境变量跳过 Rust 构建

bash 复制代码

export OV_SKIP_OV_BUILD=1
export OV_SKIP_RAGFS_BUILD=1
python setup.py build_ext --inplace

4.5 构建速度优化

问题: 构建过程太慢

解决方案:

使用并行构建: cmake --build . -j$(nproc)
使用 uv 替代 pip 安装依赖
只构建必要的组件

5. 开发工作流

5.1 修改核心代码

修改 Python 代码 : 直接编辑 openviking/ 目录下的文件
修改 C++ 代码 : 编辑 src/ 目录下的文件，然后重新构建
修改 Rust 代码 : 编辑 crates/ 目录下的文件，然后重新构建

5.2 测试修改

bash 复制代码

# 运行单元测试
pytest tests/

# 运行特定测试
pytest tests/client/test_filesystem.py

# 运行集成测试
pytest tests/integration/

5.3 调试技巧

启用详细日志 : export OPENVIKING_LOG_LEVEL=DEBUG
使用 Python 调试器 : python -m pdb openviking-server
检查构建输出 : 查看 build/ 目录下的构建产物

6. 高级编译选项

6.1 交叉编译

bash 复制代码

# 设置目标架构
export CARGO_BUILD_TARGET=aarch64-apple-darwin

# 执行构建
python setup.py build_ext --inplace

6.2 自定义构建配置

bash 复制代码

# 设置 C 编译器
export CC=/usr/bin/gcc

# 设置 C++ 编译器
export CXX=/usr/bin/g++

# 执行构建
python setup.py build_ext --inplace

6.3 构建 Wheel 包

bash 复制代码

# 构建 Wheel 包
python setup.py bdist_wheel

# 构建的包将位于 dist/ 目录

6.4 清理构建产物

bash 复制代码

# 清理所有构建产物
make clean

# 或手动清理
rm -rf build/ dist/ *.egg-info/ openviking/bin/ openviking/lib/ crates/ov_cli/target/ src/cmake_build/

7. 项目结构参考

源代码目录:
- openviking/ - Python 代码
- src/ - C++ 核心引擎
- crates/ - Rust 组件
  - crates/ov_cli/ - CLI 工具
  - crates/ragfs/ - RAGFS 文件系统
  - crates/ragfs-python/ - Python 绑定
构建配置:
- $Makefile$ (file:///Users/citi/dev/OpenViking/Makefile) - 构建脚本
- $setup.py$ (file:///Users/citi/dev/OpenViking/setup.py) - Python 包配置
- $CMakeLists.txt$ (file:///Users/citi/dev/OpenViking/src/CMakeLists.txt) - C++ 构建配置
配置文件:
- examples/ov.local.conf - 本地开发配置
- examples/ov.conf.example - 配置示例

8. 故障排除

8.1 检查日志

构建日志: 控制台输出
服务器日志 : openviking.log 或控制台输出
Cargo 构建日志 : crates/ov_cli/target/debug/build/

8.2 常见错误代码

错误信息	可能原因	解决方案
`error: command 'cmake' failed`	CMake 未安装或版本过低	安装 CMake >= 3.12
`error: could not compile 'ov_cli'`	Rust 版本过低或依赖问题	更新 Rust 到 >= 1.91.1
`ImportError: ragfs_python native library is not available`	Rust 绑定未构建	安装 Maturin 并重新构建
`SECURITY: server.auth_mode='dev' requires server.host to be localhost`	安全配置问题	修改配置文件，将 host 设置为 127.0.0.1

8.3 性能优化

使用 Release 构建 : cargo build --release
启用编译器优化 : 设置 CMAKE_BUILD_TYPE=Release
使用更快的构建系统 : 考虑使用 ninja 替代 make

文档更新时间 : 2026-04-22
版本: OpenViking 0.3.9