> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirobody.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 安装指南
> 在各平台上从源码构建 Mirobody 的 C++ 内核，或用 Docker 运行。
Mirobody 是单个 **C++11** 内核，用 **CMake** 构建（Windows 上加 vcpkg）。同一份源码能产出多种工件：独立的 `mirobody` 二进制、一个共享库（`libmirobody`）、一个 Python wheel、一个 Android `.so`，以及一个 iOS 静态库 / xcframework。本页讲如何逐个构建。
Mirobody 是一个从源码构建的原生二进制：运行 `./build.sh`（Windows 用 `build.cmd`），或使用 Docker。
## 独立二进制（桌面 / 服务器）
### 1. 克隆
```bash theme={null}
git clone https://github.com/thetahealth/mirobody.git
cd mirobody
```
### 2. 安装原生依赖
这里 vcpkg 仅用于 Windows —— Linux 和 macOS 用系统包管理器，CMake 的 `find_package` 会直接找到这些库。下面是**核心**依赖（始终需要）。桌面默认后端是 PostgreSQL，所以也装上 `libpq`。
```bash theme={null}
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
```
```bash theme={null}
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
```
```bash theme={null}
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. 构建
```bash theme={null}
./build.sh # 主机架构 + POSTGRESQL -> build/mirobody
```
后端是一个命令行 token（不是环境变量），可与 `clean` 以任意顺序传入：
```bash theme={null}
./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[_]` 目录，因此多个可以共存。
或者直接调用 CMake：
```bash theme={null}
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. 克隆
```cmd theme={null}
git clone https://github.com/thetahealth/mirobody.git
cd mirobody
```
### 3. 构建
vcpkg 会自动从 [`vcpkg.json`](https://github.com/thetahealth/mirobody/blob/main/vcpkg.json) 拉取原生依赖 —— 无需手动安装。
```cmd theme={null}
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。
### 运行
```bash theme={null}
./mirobody # 默认读取 ./config.yml
./mirobody --config /path/to/config.yml
./mirobody --help
```
先把 `config.example.yml` 复制成 `config.yml` 并设置一个 LLM 密钥 —— 参见 [快速开始](/zh/quickstart) 和 [配置](/zh/configuration)。服务器在 `HTTP_HOST:HTTP_PORT`（默认 `0.0.0.0:8080`）上提供 HTTP + WebSocket（以及从 `res/htdoc` 提供的 Web 客户端）。
## Docker
仓库自带一个多阶段 `Dockerfile`：阶段 1 从 Ubuntu 系统包集合编译出 `mirobody` 可执行文件；阶段 2 是一个精简的运行时镜像，只带二进制所链接的共享库。
```bash theme={null}
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 部署](/zh/deployment/docker)。
## 其他构建产物
同一棵源码树除了独立二进制外，还能构建多个可嵌入的工件。
构建 C-ABI 共享库（`mirobody.dll` / `libmirobody.so` / `.dylib`），任何带 C FFI 的语言都能加载：
```bash theme={null}
./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/` 下。
`mirobody._mirobody` 是一个 CPython 扩展（一个包装 `mirobody::Server` 的 pybind11 模块），由 scikit-build-core 打包成 `.whl` —— 你**从源码构建它**：
```bash theme={null}
./build-python.sh # Linux / macOS （Windows 上是 build-python.cmd）
```
然后在进程内驱动这个内嵌服务器：
```python theme={null}
import mirobody
with mirobody.Server(listen_port=8080, openai_api_key="sk-...") as srv:
print("listening on", srv.listen_port())
```
细节见仓库中的 `python/README.md`。
`android/` 下的 Android 工程通过 `externalNativeBuild` 拉取同一份 `CMakeLists.txt`，把 `mirobody` 目标构建为共享库（`libmirobody.so`），由宿主应用经 JNI 加载。原生依赖来自 `android/prebuilt//` 下的预构建 sysroot（目前为 `arm64-v8a`）。
```bash theme={null}
cd android
./gradlew assembleRelease
```
iOS 目标构建 `libmirobody.a`，暴露 `src/mirobody.h` 中的 C API；Swift/Objective-C 宿主链接它并调用 `mirobody_start` / `mirobody_stop`。原生依赖来自 `ios/prebuilt/-/` 下的预构建 sysroot。
```bash theme={null}
# 设备切片
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/` 经 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 是内置的（无需库）。参见 [文件处理](/zh/concepts/file-processing)。
## 数据库后端
二进制里只会链接**一个** 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/` 再重新构建即可 —— 它们是编译进程序的，而非从运行时插件目录加载。
## 验证安装
```bash theme={null}
curl http://localhost:8080/api/health
```
返回 `ok`。
```bash theme={null}
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 `。
## 故障排查
代码需要 libwebsockets ≥ 4.1。Ubuntu 24.04 自带 4.3；更老的发行版（以及 Debian bookworm）可能太旧 —— 安装一个更新的构建，或用 Docker 镜像（它基于 Ubuntu 24.04）。
重新核对上面对应平台的依赖列表。如果某个库装在非标准前缀下，用 `-DCMAKE_PREFIX_PATH=` 把 CMake 指向它。
修改 `config.yml` 里的 `HTTP_PORT`（默认 `8080`），然后重启。
桌面构建链接的是 PostgreSQL —— 设置 `config.yml` 里的 `PG_*` 键，或用 `./build.sh sqlite` 重新构建，得到一个无需外部数据库的自包含 SQLite 后端。
## 下一步
在 `config.yml` 里配置 Provider、数据库、存储和鉴权
从克隆到运行二进制的最短路径
理解 Mirobody 如何工作
搭建带测试的开发构建