安装 - Theta Health

安装方式

选择最适合你需求的安装方式：

Docker (Recommended)
From Source

Docker 部署适用于开发与生产环境，也是推荐方式。

Step 1：安装 Docker

macOS
Linux
Windows

brew install --cask docker

从 Applications 文件夹启动 Docker Desktop。

安装 Docker Engine 与 Docker Compose：

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

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt-get install docker-compose-plugin

退出并重新登录使用户组变更生效。

Step 2：克隆仓库

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

Step 3：配置环境

cp .env_example .env
cp config.example.yaml config.yaml

Step 4：部署

./deploy.sh

部署脚本会构建并启动所需的全部服务。

从源码构建运行，适用于开发与深度定制。

Step 1：克隆并初始化

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

# Create virtual environment
python3.12 -m venv venv
source venv/bin/activate

Step 2：安装依赖

pip install -r requirements.txt

Step 3：启动外部服务

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

docker-compose up -d postgres redis

Step 4：配置

cp config.example.yaml config.yaml
# Edit config.yaml with your settings

Step 5：初始化数据库

python -c "from mirobody.utils.db_initializer import initialize_database; import asyncio; asyncio.run(initialize_database())"

Step 6：运行

python main.py

服务应启动于 http://localhost:18080

验证安装

安装完成后，请验证各项功能是否正常：

检查服务健康状态

curl http://localhost:18080/health

期望响应：

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

列出可用 providers

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

应返回可用健康 providers 列表。

查看日志

查看应用日志，确保没有错误：

# Docker deployment
docker-compose logs -f backend

# Direct installation
# 日志会输出在运行 main.py 的终端中

安装后配置

配置数据 Providers

要启用健康设备集成，你需要为每个 provider 准备 OAuth 凭据。获取与配置 OAuth 凭据的详细说明请参见配置指南，包括：

Garmin Connect
Whoop
自定义 providers

启用 AI 对话与文件处理

要启用 AI 功能，请在 config.yaml 中添加 API keys：

# REQUIRED API Keys
OPENROUTER_API_KEY: 'your_openrouter_api_key'  # For AI chat/agents
GOOGLE_API_KEY: 'your_google_api_key'  # For file processing (Gemini)

# Optional
OPENAI_API_KEY: 'your_openai_api_key'

OPENROUTER_API_KEY：AI 对话与 agent 功能必填
GOOGLE_API_KEY：使用 Gemini 处理文件（PDF、图片、医疗记录等）必填
OPENAI_API_KEY：可选，仅用于 OpenAI 相关特性

配置数据库加密

生产环境请设置安全的加密 key：

DATABASE_DECRYPTION_KEY: 'your_32_char_encryption_key'
JWT_KEY: 'your_secure_jwt_secret'

生产环境请使用强度高且随机生成的 key，切勿提交到版本控制系统。

配置云存储（可选）

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

S3_KEY: 'your_access_key'
S3_TOKEN: 'your_secret_key'
S3_REGION: 'us-east-1'
S3_BUCKET: 'your-bucket-name'

目录结构

安装完成后，目录结构大致如下：

mirobody-health/
├── connect/                    # Provider integrations
│   ├── __init__.py
│   └── theta/                 # Theta platform providers
│       ├── mirobody_garmin_connect/
│       └── mirobody_whoop/
├── docker/                     # Docker configuration
│   ├── docker-compose.yaml
│   ├── Dockerfile.backend
│   ├── Dockerfile.base
│   └── Dockerfile.postgres
├── shell/                      # Utility scripts
│   ├── chat_test_commands.sh
│   └── get_tools.sh
├── config.yaml                 # Main configuration
├── .env                       # Environment variables
├── main.py                    # Application entry point
├── requirements.txt           # Python dependencies
├── setup.py                   # Package setup
└── README.md                  # Documentation

安装问题排查

Docker 安装/运行失败

Problem：Docker 命令因权限问题失败。Solution：

# Linux: Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in
newgrp docker

端口冲突

Problem：端口 18080 已被占用。Solution：在 config.yaml 中修改端口：

HTTP_PORT: 18081  # Use any available port

数据库连接失败

Problem：无法连接 PostgreSQL。Solutions：

确认 PostgreSQL 正在运行：
```
docker-compose ps postgres
```

检查 config.yaml 中的连接配置：

PG_HOST: db  # 'db' for Docker, 'localhost' for local install
PG_PORT: 5432
PG_USER: holistic_user
PG_DBNAME: holistic_db

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

Python 版本不匹配

Problem：系统没有 Python 3.12。Solutions：

macOS
Linux
Windows

brew install [email protected]

# 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

模块导入错误

Problem：运行应用时出现 ModuleNotFoundError。Solution：

# Ensure all dependencies are installed
pip install -r requirements.txt

# Install in development mode
pip install -e .

卸载

Docker
Source Installation

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

# Stop and remove containers
docker-compose down

# Remove volumes (WARNING: This deletes all data)
docker-compose down -v

# Remove images
docker-compose down --rmi all

# Deactivate virtual environment
deactivate

# Remove project directory
cd ..
rm -rf mirobody-health

下一步

Configuration

配置 OAuth providers 并自定义系统设置

Quick Start

按照快速开始指南验证安装

Architecture

了解 Mirobody Health 的工作原理

Development

搭建开发环境

快速开始

核心概念

使用 Providers

Providers 示例

Tools 与 MCP

安装

安装方式

Step 1：安装 Docker

Step 2：克隆仓库

Step 3：配置环境

Step 4：部署

Step 1：克隆并初始化

Step 2：安装依赖

Step 3：启动外部服务

Step 4：配置

Step 5：初始化数据库

Step 6：运行

验证安装

安装后配置

目录结构

安装问题排查

卸载

下一步

Configuration

Quick Start

Architecture

Development

快速开始

核心概念

使用 Providers

Providers 示例

Tools 与 MCP

​安装方式

​Step 1：安装 Docker

​Step 2：克隆仓库

​Step 3：配置环境

​Step 4：部署

​Step 1：克隆并初始化

​Step 2：安装依赖

​Step 3：启动外部服务

​Step 4：配置

​Step 5：初始化数据库

​Step 6：运行

​验证安装

​安装后配置

​目录结构

​安装问题排查

​卸载

​下一步

Configuration

Quick Start

Architecture

Development

安装方式

Step 1：安装 Docker

Step 2：克隆仓库

Step 3：配置环境

Step 4：部署

Step 1：克隆并初始化

Step 2：安装依赖

Step 3：启动外部服务

Step 4：配置

Step 5：初始化数据库

Step 6：运行

验证安装

安装后配置

目录结构

安装问题排查

卸载

下一步