安装指南

安装方法

选择最适合您需求的安装方法：

Docker (推荐)
源码安装

无论是开发环境还是生产环境，Docker 部署都是推荐的方法。

第 1 步：安装 Docker

macOS
Linux
Windows

brew install --cask docker

从应用程序文件夹启动 Docker Desktop。

安装 Docker Engine 和 Docker Compose：

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 将您的用户添加到 docker 组
sudo usermod -aG docker $USER

# 安装 Docker Compose 插件
sudo apt-get install docker-compose-plugin

注销并重新登录以使组更改生效。

第 2 步：安装 Git LFS

用于拉取 fhir_concept_graph.bin 等二进制资产。

# macOS
brew install git-lfs

# Linux
sudo apt install git-lfs

git lfs install

第 3 步：克隆仓库

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

第 4 步：一键部署

./deploy.sh

deploy.sh 会自动完成：

生成 .env（含 ENV=localdb 和新鲜的 CONFIG_ENCRYPTION_KEY）
创建默认 config.localdb.yaml
构建 Docker 镜像
启动 Postgres、Redis 和 Mirobody 后端

等到后端日志出现 Uvicorn running on http://0.0.0.0:18080 即可。

第 5 步：填写至少一个 LLM API Key

打开 config.localdb.yaml，至少填一个：

# DeepAgent（默认）必需
OPENROUTER_API_KEY: 'sk-or-...'

# 可选替代项
OPENAI_API_KEY: 'sk-...'
GOOGLE_API_KEY: '...'
ANTHROPIC_API_KEY: 'sk-ant-...'

所有敏感字段在首次加载时会用 .env 里的 CONFIG_ENCRYPTION_KEY 自动加密。

从源码构建并运行，适用于开发和自定义。

第 1 步：克隆与设置

Mirobody 需要 Python 3.10+ 与 Node.js 18+（图表渲染器是 JS 实现）。

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

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip

第 2 步：安装系统依赖

macOS
Linux (Ubuntu/Debian)

xcode-select --install
brew install gcc gfortran fftw hdf5 openblas lapack

sudo apt install -y g++ gfortran build-essential \
  libfftw3-dev libhdf5-dev libblas-dev liblapack-dev

第 3 步：安装 Python 依赖

pip install -e .

# 可选额外依赖
# pip install -e ".[cn]"    # 国内可选：阿里 OSS、火山、Dashscope
# pip install -e ".[fin]"   # 金融数据：yfinance
# pip install -e ".[test]"  # 测试套件

Mirobody 也已发布到 PyPI，可以用 pip install mirobody 做非可编辑安装。

第 4 步：安装 Node.js 依赖

npm install --omit=dev

第 5 步：拉起依赖服务

通过仓库自带的 compose 文件启动 PostgreSQL 与 Redis：

docker compose up -d pg redis

第 6 步：配置

echo "ENV=localdb" > .env
echo "CONFIG_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

在 config.localdb.yaml 中至少填一个 API 密钥（必要时调整数据库/Redis）：

# DeepAgent（默认）必需
OPENROUTER_API_KEY: 'sk-or-...'

# 可选替代项
OPENAI_API_KEY: ''
GOOGLE_API_KEY: ''
ANTHROPIC_API_KEY: ''

# ============ 数据库（默认值与上面 compose 一致） ============
PG_HOST: 'localhost'
PG_PORT: 5432
PG_USER: 'mirobody'
PG_PASSWORD: ''
PG_DBNAME: 'mirobody'

# ============ Redis ============
REDIS_HOST: 'localhost'
REDIS_PORT: 6379
REDIS_DB: 0
REDIS_PASSWORD: ''

第 7 步：运行

python -m main

服务器应在 http://localhost:18080 启动。如果是在 WSL 下运行，可通过 Windows 访问 http://localhost:18080。

验证安装

安装完成后，验证一切运行正常：

检查服务健康状况

curl http://localhost:18080/health

预期响应：

{
  "status": "healthy",
  "version": "1.0.1",
  "services": {
    "database": "connected",
    "redis": "connected"
  }
}

列出可用提供商

curl http://localhost:18080/api/v1/pulse/providers

应返回可用健康提供商的列表。

检查日志

查看应用程序日志以确保没有错误：

# Docker 部署
docker-compose logs -f backend

# 直接安装
# 日志将显示在您运行 main.py 的终端中

安装后设置

配置数据提供商 (Providers)

要启用健康设备集成，您需要从每个提供商处获取 OAuth 凭据。有关获取和设置以下提供商的 OAuth 凭据的详细说明，请参阅配置指南：

Garmin Connect
Whoop
自定义提供商

设置 AI 对话与 Agent

要启用 AI 功能，请在 config.localdb.yaml 中添加至少一个 API 密钥：

# ============ LLM API 密钥 (至少需要一个) ============
GOOGLE_API_KEY: ''      # 用于 Gemini 模型
OPENAI_API_KEY: ''      # 用于 GPT 模型
OPENROUTER_API_KEY: ''  # 用于 Claude、DeepSeek 等模型

# ============ Agent 配置 ============
MCP_TOOL_DIRS:
  - mirobody/pub/tools
  - mirobody/pub/tools_health

MCP_RESOURCE_DIRS:
  - mirobody/pub/resources

AGENT_DIRS:
  - mirobody/pub/agents

Mirobody 包含两种 Agent 类型：

DeepAgent (基于 LangChain): 最适合复杂任务、文件操作、多步骤规划
BaselineAgent (原生 Gemini): 最适合简单对话、轻量级 MCP 集成

有关配置详情，请参阅工具概览。

配置数据库加密

对于生产环境，请设置安全的加密密钥：

DATABASE_DECRYPTION_KEY: '您的_32_位加密密钥'
JWT_KEY: '您的_安全_JWT_密钥'

在生产环境中使用强随机生成的密钥。切勿将这些密钥提交到版本控制系统中。

设置云存储 (可选)

配置兼容 S3 的存储用于数据备份：

S3_KEY: '您的访问密钥'
S3_TOKEN: '您的私钥'
S3_REGION: 'us-east-1'
S3_BUCKET: '您的存储桶名称'

目录结构

安装后，您的目录结构将如下所示：

mirobody/
├── mirobody/                 # 核心引擎包
│   ├── chat/                # 会话、历史、流式、记忆
│   ├── mcp/                 # MCP JSON-RPC 2.0 服务器（本地 + HTTP 远程）
│   ├── pulse/               # 数据管线（Pulse）
│   │   ├── theta/          # 可穿戴：Garmin / Whoop / Oura / Renpho / Vital ...
│   │   ├── apple/          # Apple Health + CDA 病历
│   │   ├── core/           # FHIR 映射、指标注册表、单位、聚合
│   │   └── file_parser/    # PDF / Excel / CSV / 音频 / 图像 / 基因
│   ├── pub/                 # 内置 Agent 与工具
│   │   ├── agents/         # DeepAgent / MixAgent / BaselineAgent
│   │   ├── tools/          # 内置 MCP 工具（文件操作、图表、execute）
│   │   └── resources/      # MCP 资源
│   ├── indicator/          # 400+ 指标，LOINC/SNOMED CT/RxNorm 搜索
│   ├── server/             # Starlette ASGI、JWT 中间件、限流
│   ├── user/               # JWT、OAuth、WebAuthn/FIDO2、邮件验证
│   └── utils/              # 配置、LLM 客户端、Embedding、DB、存储
│
├── tools/                   # ★ 拖入式 Python 工具 → 自动注册为 MCP 工具
├── skills/                  # ★ Claude Agent Skills（SKILL.md + metadata.json）
├── agents/                  # ★ 自定义 Agent 实现
├── providers/               # ★ 自定义数据 Provider
├── prompts/                 # Jinja2 prompt 模板
├── resources/               # 通过 MCP 暴露的静态资源（HTML、JSON）
│
├── database/                # SQL schema 与迁移
├── tests/                   # 集成测试（pytest）
├── compose.yaml             # Docker Compose 配置
├── config.yaml              # 基础配置（不要直接改，复制成 env 配置）
├── config.localdb.yaml      # 你的环境配置（ENV=localdb）
├── .env                     # ENV + CONFIG_ENCRYPTION_KEY
├── main.py                  # 应用入口
├── pyproject.toml           # Python 包元数据
├── package.json             # Node.js 依赖（图表渲染器）
├── deploy.sh                # Docker 一键部署
└── README.md                # 项目说明

带 ★ 的目录是官方推荐的扩展点 —— 文件丢进去就会自动发现。完整生命周期参见工具概览。

安装问题排查

Docker 安装失败

问题: Docker 命令因权限错误而失败。解决方案:

# Linux: 将用户添加到 docker 组
sudo usermod -aG docker $USER

# 注销并重新登录
newgrp docker

端口冲突

问题: 端口 18080 已被占用。解决方案: 在 config.localdb.yaml 中更改端口：

HTTP_PORT: 18081  # 使用任何可用端口

数据库连接失败

问题: 无法连接到 PostgreSQL。解决方案:

验证 PostgreSQL 正在运行：
```
docker-compose ps postgres
```

检查 config.localdb.yaml 中的连接设置：

PG_HOST: db  # Docker 环境使用 'db'，本地安装使用 'localhost'
PG_PORT: 5432
PG_USER: holistic_user
PG_DBNAME: holistic_db

检查数据库日志：
```
docker-compose logs postgres
```

Python 版本不匹配

问题: Python 3.12 不可用。解决方案:

macOS
Linux
Windows

brew install python@3.12

# Ubuntu/Debian
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.12

从 python.org 下载或使用 pyenv:

pyenv install 3.12
pyenv global 3.12

模块导入错误

问题: 运行应用程序时出现 ModuleNotFoundError。解决方案:

# 确保安装了所有依赖项
pip install -r requirements.txt

# 以开发模式安装
pip install -e .

卸载

Docker
源码安装

删除所有容器、卷和镜像：

# 停止并删除容器
docker-compose down

# 删除卷 (警告: 这将删除所有数据)
docker-compose down -v

# 删除镜像
docker-compose down --rmi all

# 停用虚拟环境
deactivate

# 删除项目目录
cd ..
rm -rf mirobody

下一步

配置指南

配置 OAuth 提供商并自定义设置

快速开始

按照快速开始指南测试您的安装

核心概念

了解 Mirobody 的工作原理

开发环境

搭建您的开发环境

快速开始

核心概念

使用 Providers

Providers 示例

Tools 与 MCP

安装方法

第 1 步：安装 Docker

第 2 步：安装 Git LFS

第 3 步：克隆仓库

第 4 步：一键部署

第 5 步：填写至少一个 LLM API Key

第 1 步：克隆与设置

第 2 步：安装系统依赖

第 3 步：安装 Python 依赖

第 4 步：安装 Node.js 依赖

第 5 步：拉起依赖服务

第 6 步：配置

第 7 步：运行

验证安装

安装后设置

目录结构

安装问题排查

卸载

下一步

配置指南

快速开始

核心概念

开发环境

快速开始

核心概念

使用 Providers

Providers 示例

Tools 与 MCP

Documentation Index

​安装方法

​第 1 步：安装 Docker

​第 2 步：安装 Git LFS

​第 3 步：克隆仓库

​第 4 步：一键部署

​第 5 步：填写至少一个 LLM API Key

​第 1 步：克隆与设置

​第 2 步：安装系统依赖

​第 3 步：安装 Python 依赖

​第 4 步：安装 Node.js 依赖

​第 5 步：拉起依赖服务

​第 6 步：配置

​第 7 步：运行

​验证安装

​安装后设置

​目录结构

​安装问题排查

​卸载

​下一步

配置指南

快速开始

核心概念

开发环境

安装方法

第 1 步：安装 Docker

第 2 步：安装 Git LFS

第 3 步：克隆仓库

第 4 步：一键部署

第 5 步：填写至少一个 LLM API Key

第 1 步：克隆与设置

第 2 步：安装系统依赖

第 3 步：安装 Python 依赖

第 4 步：安装 Node.js 依赖

第 5 步：拉起依赖服务

第 6 步：配置

第 7 步：运行

验证安装

安装后设置

目录结构

安装问题排查

卸载

下一步