安装指南

安装方法

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

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 clone https://github.com/thetahealth/mirobody-health.git
cd mirobody-health

第 3 步：配置环境

创建配置文件：

cp .env.example .env
cp config.yaml config.localdb.yaml

编辑 .env 设置您的环境：

ENV=localdb

在 config.localdb.yaml 中添加至少一个 LLM 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

第 4 步：部署

./run.sh

部署脚本将构建并启动所有必需的服务。

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

第 1 步：克隆与设置

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

# 创建虚拟环境
python3.12 -m venv venv
source venv/bin/activate

第 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 mirobody -r requirements.txt

第 4 步：安装 Node.js 依赖

npm install @antv/gpt-vis-ssr ws

第 5 步：设置外部服务

启动 PostgreSQL 和 Redis（为简单起见使用 Docker）：

docker-compose up -d postgres redis

第 6 步：配置

cp .env.example .env
cp config.yaml config.localdb.yaml

编辑 .env：

ENV=localdb

在 config.localdb.yaml 中添加至少一个 API 密钥和数据库设置：

# ============ LLM API 密钥 (至少需要一个) ============
GOOGLE_API_KEY: ''
OPENAI_API_KEY: ''
OPENROUTER_API_KEY: ''

# ============ 数据库配置 ============
PG_HOST: 'localhost'
PG_PORT: 5432
PG_USER: ''
PG_PASSWORD: ''
PG_DBNAME: ''
PG_SCHEMA: ''

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

第 7 步：运行

python main.py

服务器应在 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 Health 包含两种 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-health/
├── mirobody/                  # 主应用程序包
│   ├── chat/                 # 聊天和 Agent 服务
│   ├── mcp/                  # MCP 协议实现
│   ├── pulse/                # 健康数据提供商
│   │   ├── theta/           # OAuth 提供商 (Garmin, Whoop 等)
│   │   ├── apple/           # Apple 健康平台
│   │   ├── core/            # 核心健康数据服务
│   │   └── file_parser/     # 文件处理程序
│   ├── pub/                  # 公共工具和 Agent
│   │   ├── tools/           # 通用 MCP 工具
│   │   ├── tools_health/    # 健康专用 MCP 工具
│   │   ├── resources/       # MCP 资源
│   │   └── agents/          # Agent 实现
│   ├── server/               # HTTP 服务器
│   ├── user/                 # 用户身份验证
│   └── utils/                # 实用程序
├── database/                  # 数据库模式和迁移
│   └── resource/             # SQL 初始化文件
├── image/                     # Logo 和品牌资产
├── compose.yaml              # Docker Compose 配置
├── config.yaml               # 基础配置 (不可更改)
├── config.localdb.yaml       # 您的环境配置
├── .env                      # 环境变量
├── main.py                   # 应用程序入口
├── requirements.txt          # Python 依赖
├── package.json              # Node.js 依赖
├── run.sh                    # 部署脚本
└── 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-health

下一步

配置指南

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

快速开始

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

核心概念

了解 Mirobody Health 的工作原理

开发环境

搭建您的开发环境

快速开始

核心概念

使用 Providers

Providers 示例

Tools 与 MCP

安装方法

第 1 步：安装 Docker

第 2 步：克隆仓库

第 3 步：配置环境

第 4 步：部署

第 1 步：克隆与设置

第 2 步：安装系统依赖

第 3 步：安装 Python 依赖

第 4 步：安装 Node.js 依赖

第 5 步：设置外部服务

第 6 步：配置

第 7 步：运行

验证安装

安装后设置

目录结构

安装问题排查

卸载

下一步

配置指南

快速开始

核心概念

开发环境

快速开始

核心概念

使用 Providers

Providers 示例

Tools 与 MCP

​安装方法

​第 1 步：安装 Docker

​第 2 步：克隆仓库

​第 3 步：配置环境

​第 4 步：部署

​第 1 步：克隆与设置

​第 2 步：安装系统依赖

​第 3 步：安装 Python 依赖

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

​第 5 步：设置外部服务

​第 6 步：配置

​第 7 步：运行

​验证安装

​安装后设置

​目录结构

​安装问题排查

​卸载

​下一步

配置指南

快速开始

核心概念

开发环境

安装方法

第 1 步：安装 Docker

第 2 步：克隆仓库

第 3 步：配置环境

第 4 步：部署

第 1 步：克隆与设置

第 2 步：安装系统依赖

第 3 步：安装 Python 依赖

第 4 步：安装 Node.js 依赖

第 5 步：设置外部服务

第 6 步：配置

第 7 步：运行

验证安装

安装后设置

目录结构

安装问题排查

卸载

下一步