安装指南 - Mirobody

Mirobody 是单个 C++11 内核，用 CMake 构建（Windows 上加 vcpkg）。同一份源码能产出多种工件：独立的 mirobody 二进制、一个共享库（libmirobody）、一个 Python wheel、一个 Android .so，以及一个 iOS 静态库 / xcframework。本页讲如何逐个构建。

Mirobody 是一个从源码构建的原生二进制：运行 ./build.sh（Windows 用 build.cmd），或使用 Docker。

独立二进制（桌面 / 服务器）

Linux / WSL / macOS
Windows (MSVC + vcpkg)

1. 克隆

git clone https://github.com/thetahealth/mirobody.git
cd mirobody

2. 安装原生依赖

这里 vcpkg 仅用于 Windows —— Linux 和 macOS 用系统包管理器，CMake 的 find_package 会直接找到这些库。下面是核心依赖（始终需要）。桌面默认后端是 PostgreSQL，所以也装上 libpq。

Debian / Ubuntu / WSL
Fedora / RHEL
macOS (Homebrew)

sudo apt install build-essential cmake ninja-build pkg-config \
                 libwebsockets-dev libcurl4-openssl-dev libssl-dev \
                 rapidjson-dev libyaml-cpp-dev libhiredis-dev \
                 libjpeg-dev libpng-dev libtiff-dev libwebp-dev

# 数据库客户端（PostgreSQL 是桌面默认）
sudo apt install libpq-dev

sudo dnf install gcc-c++ cmake ninja-build pkgconf-pkg-config \
                 libwebsockets-devel libcurl-devel openssl-devel \
                 rapidjson-devel yaml-cpp-devel hiredis-devel \
                 libjpeg-turbo-devel libpng-devel libtiff-devel libwebp-devel

# 数据库客户端（PostgreSQL 是桌面默认）
sudo dnf install libpq-devel

brew install cmake ninja pkg-config libwebsockets curl openssl@3 \
             rapidjson yaml-cpp hiredis \
             jpeg-turbo libpng libtiff webp

# 数据库客户端（PostgreSQL 是桌面默认）
brew install libpq

只装与你打算构建的后端相匹配的那一个数据库客户端 —— SQLite、MySQL/MariaDB、DuckDB 客户端仅在你选择这些后端时才需要。参见后端列表。

3. 构建

./build.sh              # 主机架构 + POSTGRESQL  -> build/mirobody

后端是一个命令行 token（不是环境变量），可与 clean 以任意顺序传入：

./build.sh sqlite       # SQLITE                 -> build_sqlite/
./build.sh legacy       # POSTGRESQL_LEGACY      -> build_legacy/
./build.sh legacy clean # 从头重新配置
./build.sh -h           # 完整 token 列表

Token：pg / postgresql、legacy / pg_legacy、mysql、sqlite、duckdb、ck / clickhouse（省略即用 POSTGRESQL 默认）。每个后端构建到各自的 build[_<backend>] 目录，因此多个可以共存。或者直接调用 CMake：

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DMIROBODY_DATABASE_BACKEND=POSTGRESQL
cmake --build build

1. 安装 Visual Studio

安装 Visual Studio 2017 或更新版（Community 即可）。在安装器中，工作负载 下勾选 使用 C++ 的桌面开发，单个组件 下勾选 适用于 Windows 的 C++ CMake 工具 —— 该组件自带 ninja.exe 和一份内置的 vcpkg，正是 build.cmd 所需。无需另外安装 Ninja。

2. 克隆

git clone https://github.com/thetahealth/mirobody.git
cd mirobody

3. 构建

vcpkg 会自动从 vcpkg.json 拉取原生依赖 —— 无需手动安装。

build.cmd              :: 主机架构 + POSTGRESQL   -> build\mirobody.exe
build.cmd sqlite       :: SQLITE                   -> build_sqlite\
build.cmd legacy clean :: 重新配置该目录
build.cmd -h           :: 完整 token 列表

环境变量 VS_DIR、VCPKG_ROOT、NINJA 都是可选的 —— 它们只用于覆盖默认值。vcvarsall.bat 默认指向 VS 内置的 vcpkg。完整的 Windows 步骤见仓库 README。

运行

./mirobody                  # 默认读取 ./config.yml
./mirobody --config /path/to/config.yml
./mirobody --help

先把 config.example.yml 复制成 config.yml 并设置一个 LLM 密钥 —— 参见快速开始和配置。服务器在 HTTP_HOST:HTTP_PORT（默认 0.0.0.0:8080）上提供 HTTP + WebSocket（以及从 res/htdoc 提供的 Web 客户端）。

Docker

仓库自带一个多阶段 Dockerfile：阶段 1 从 Ubuntu 系统包集合编译出 mirobody 可执行文件；阶段 2 是一个精简的运行时镜像，只带二进制所链接的共享库。

git clone https://github.com/thetahealth/mirobody.git
cd mirobody

# 构建（默认 PostgreSQL 后端）
docker build -t mirobody:latest .

# 或换一个 SQL 后端
docker build --build-arg MIROBODY_DATABASE_BACKEND=POSTGRESQL_LEGACY -t mirobody:legacy .

# 运行 —— 镜像把 HTTP_PORT=80 固定好；挂载你自己的 config.yml
docker run -p 80:80 -v $PWD/config.yml:/app/config.yml mirobody:latest

镜像把 config.example.yml 烘焙成优先级最低的默认层；真实设置来自挂载的 config.yml 或环境变量。细节见 Docker 部署。

其他构建产物

同一棵源码树除了独立二进制外，还能构建多个可嵌入的工件。

共享库（libmirobody）—— Java / Go / C# / Node / Rust

构建 C-ABI 共享库（mirobody.dll / libmirobody.so / .dylib），任何带 C FFI 的语言都能加载：

./build-shared.sh          # -> build-shared/libmirobody.*  （Windows 上是 build-shared.cmd）

C API 声明在 src/mirobody.h（mirobody_start / mirobody_stop / mirobody_chat / …）。Go、C#、Node、Rust、Java 的可运行绑定位于 bindings/ 下。

Python wheel —— 从源码构建（非 PyPI）

mirobody._mirobody 是一个 CPython 扩展（一个包装 mirobody::Server 的 pybind11 模块），由 scikit-build-core 打包成 .whl —— 你从源码构建它：

./build-python.sh          # Linux / macOS  （Windows 上是 build-python.cmd）

然后在进程内驱动这个内嵌服务器：

import mirobody
with mirobody.Server(listen_port=8080, openai_api_key="sk-...") as srv:
    print("listening on", srv.listen_port())

细节见仓库中的 python/README.md。

Android —— 经 JNI 的 libmirobody.so

android/ 下的 Android 工程通过 externalNativeBuild 拉取同一份 CMakeLists.txt，把 mirobody 目标构建为共享库（libmirobody.so），由宿主应用经 JNI 加载。原生依赖来自 android/prebuilt/<ABI>/ 下的预构建 sysroot（目前为 arm64-v8a）。

cd android
./gradlew assembleRelease

iOS —— libmirobody.a / mirobody.xcframework

iOS 目标构建 libmirobody.a，暴露 src/mirobody.h 中的 C API；Swift/Objective-C 宿主链接它并调用 mirobody_start / mirobody_stop。原生依赖来自 ios/prebuilt/<sdk>-<arch>/ 下的预构建 sysroot。

# 设备切片
cmake -S . -B build-ios-arm64 -G Xcode \
    -DCMAKE_TOOLCHAIN_FILE=path/to/ios.toolchain.cmake \
    -DPLATFORM=OS64 -DDEPLOYMENT_TARGET=15.0 \
    -DCMAKE_PREFIX_PATH="$(pwd)/ios/prebuilt/iphoneos-arm64"
cmake --build build-ios-arm64 --config Release

用 xcodebuild -create-xcframework 把设备 + 模拟器切片打包成 xcframework。只构建 arm64 切片。

桌面（Electron）与 Qt 客户端

electron/ 经 koffi FFI 在进程内嵌入 libmirobody，并使用自包含的 SQLite 后端（无需外部数据库）—— 先构建共享库和 Web 客户端，再 cd electron && npm install && npm start。qt/ 是一个原生 Qt Quick（QML）客户端，它是纯 HTTP/SSE API 客户端（不嵌入内核），与任意运行中的 mirobody 后端通信。两者都在仓库 README 中有说明。

可选的文档格式库

不装这些内核也能正常构建；对应格式只会在运行时报告”未构建”。用 CMake 标志启用它们：

功能	CMake 标志	说明
`.xlsx` 读取	（自动探测）	经 xlnt。Linux/macOS 上未打包 —— 从源码构建；Windows 上经 vcpkg 必需。
PDF 文本 + 栅格化	`-DMIROBODY_ENABLE_PDF=ON`	经 PDFium —— 下载一个预构建的 no-V8 版本，并把 `-DCMAKE_PREFIX_PATH` 指向它。
扫描版 PDF 的 OCR	`-DMIROBODY_ENABLE_OCR=ON`	经 Tesseract（隐含 PDF）；`apt install tesseract-ocr libtesseract-dev libleptonica-dev tesseract-ocr-eng`。
旧版 `.xls`	`-DMIROBODY_ENABLE_XLS=ON`	经 libxls —— 无包，自行 vendor。

CSV 是内置的（无需库）。参见文件处理。

数据库后端

二进制里只会链接一个 SQL 后端，在构建期经 -DMIROBODY_DATABASE_BACKEND=（或 build.sh 的 token）选定。SQL schema 位于 res/sql/ 下。

后端取值	默认用于	`build.sh` token
`POSTGRESQL`	桌面 / 服务器	`pg` / `postgresql` （默认）
`SQLITE`	移动端 / 自包含	`sqlite`
`POSTGRESQL_LEGACY`	—	`legacy` / `pg_legacy`
`MYSQL`	—	`mysql`
`DUCKDB`	—	`duckdb`
`CLICKHOUSE`	—（目前为占位实现）	`ck` / `clickhouse`

仓库结构

mirobody/
├── src/                    # C++ 内核
│   ├── mirobody.h          # 公开 C ABI（extern "C"）—— 嵌入接口
│   ├── main.cpp            # 独立服务器入口
│   ├── server/             # HTTP + WebSocket 路由（libwebsockets）
│   ├── chat/               # agent：提供商选择、系统提示词、流式返回
│   ├── llm/                # 流式 LLM 客户端（OpenAI、Gemini、MiroThinker；chat / realtime / embeddings）
│   ├── mcp/                # MCP JSON-RPC 端点 + 编译期工具注册表
│   ├── memory/             # 长期记忆（本地 embeddings 或 Mem0 / Zep / EverOS）
│   ├── fhir/               # RESTful FHIR R4 端点 + 单位归一化 + 术语
│   ├── health/             # 健康数据层；vendor/ = 每个数据源一个客户端（platform/ phone/ device/ ehr/）
│   ├── database/           # SQL 后端（Postgres / SQLite / DuckDB / MySQL / ClickHouse）
│   ├── cache/              # 进程内 KV 或 Redis
│   ├── storage/            # S3 / OSS / Azure Blob / 本地文件系统 后端
│   ├── user/               # 邮箱 + 社交登录（含 Tanka 二维码）、令牌签发
│   ├── circle/             # 健康圈：分享关系图
│   ├── jwt/  oauth/         # JWT 签发/校验 + OAuth 2.0 授权服务器
│   ├── config/             # 配置 schema + 加载器（YAML + Fernet）
│   ├── transcode/          # 上传转码器：图像 + 文档（PDF/Excel/CSV）
│   └── platform/           # 日志 + JNI / C-ABI / pybind11 入口
├── res/                    # 由二进制编译/托管的内置资源
│   ├── agents/base.cpp     # 唯一的 agent，编译期自注册
│   ├── mcp_tools/*.cpp     # MCP 工具，编译期自注册
│   ├── mcp_resources/      # MCP 资源
│   ├── sql/                # 各方言 SQL schema（pg、sqlite、mysql…）
│   └── htdoc/              # 构建好的 Web 客户端（HTTP_ROOT）
├── htdoc/                  # Web 客户端源码（webpack -> res/htdoc）
├── cli/                    # 独立的各子系统调试二进制
├── bindings/               # Java / Go / C# / Node / Rust FFI 绑定 + 示例
├── android/  ios/  electron/  qt/  miniapp/   # 宿主应用 / 客户端
├── python/                 # Python 包装包 + wheel README
├── CMakeLists.txt          # 构建定义
├── Dockerfile              # 多阶段服务器镜像
├── build.sh  build.cmd      # 二进制构建包装脚本
├── build-shared.sh  build-python.sh   # 共享库 / Python wheel 包装脚本
├── config.example.yml      # 配置模板 —— 复制成 config.yml
└── README.md

Agent 和 MCP 工具在编译期自注册：把一个 .cpp 丢进 res/agents/ 或 res/mcp_tools/ 再重新构建即可 —— 它们是编译进程序的，而非从运行时插件目录加载。

验证安装

健康检查

curl http://localhost:8080/api/health

返回 ok。

MCP 发现

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

列出内置工具。

日志

二进制默认把日志打到 stdout；在 config.yml 里设置 LOG_DIR 可写入文件。Docker 下用 docker logs <container>。

故障排查

libwebsockets 太旧 / websocket_client.cpp 编译失败

代码需要 libwebsockets ≥ 4.1。Ubuntu 24.04 自带 4.3；更老的发行版（以及 Debian bookworm）可能太旧 —— 安装一个更新的构建，或用 Docker 镜像（它基于 Ubuntu 24.04）。

find_package 找不到某个依赖

重新核对上面对应平台的依赖列表。如果某个库装在非标准前缀下，用 -DCMAKE_PREFIX_PATH=<install-root> 把 CMake 指向它。

端口冲突

修改 config.yml 里的 HTTP_PORT（默认 8080），然后重启。

数据库连接失败

桌面构建链接的是 PostgreSQL —— 设置 config.yml 里的 PG_* 键，或用 ./build.sh sqlite 重新构建，得到一个无需外部数据库的自包含 SQLite 后端。

下一步

配置

在 config.yml 里配置 Provider、数据库、存储和鉴权

快速开始

从克隆到运行二进制的最短路径

架构

理解 Mirobody 如何工作

开发

搭建带测试的开发构建

​独立二进制（桌面 / 服务器）

​1. 克隆

​2. 安装原生依赖

​3. 构建

​1. 安装 Visual Studio

​2. 克隆

​3. 构建

​运行

​Docker

​其他构建产物

​可选的文档格式库

​数据库后端

​仓库结构

​验证安装

​故障排查

​下一步

配置

快速开始

架构

开发

独立二进制（桌面 / 服务器）

1. 克隆

2. 安装原生依赖

3. 构建

1. 安装 Visual Studio

2. 克隆

3. 构建

运行

Docker

其他构建产物

可选的文档格式库

数据库后端

仓库结构

验证安装

故障排查

下一步