Cleo项目自托管部署指南：从零开始搭建你的AI助手

前言

Cleo是一款功能强大的AI助手系统，支持自托管部署，让用户能够在私有环境中运行AI服务。本文将详细介绍如何在本地环境中部署Cleo，包括Docker和Pip两种安装方式，以及后续的配置和使用方法。

为什么选择自托管Cleo？

自托管Cleo具有以下显著优势：

1. 数据隐私保护：所有数据都保留在您的私有网络中，甚至可以完全离线运行
2. 高度可定制：从AI模型选择到功能配置，您可以根据需求自由调整
3. 性能优化：可以根据硬件条件优化运行效率，特别是GPU加速

部署准备

在开始部署前，请确保您的系统满足以下基本要求：

• 操作系统：支持macOS、Windows(WSL2)和Linux
• 内存：至少8GB，推荐16GB以上
• 存储空间：至少5GB可用空间
• 网络：基础部署不需要互联网连接(离线模型)

部署方式选择

Cleo提供两种主要部署方式：

1. Docker部署（推荐）

Docker方式适合大多数用户，提供隔离的环境和简化的依赖管理。

系统特定准备

macOS用户：

• 安装Docker Desktop或通过Homebrew安装：

  brew install --cask docker
  brew install docker-compose
  

Windows用户：

1. 安装WSL2（Windows Subsystem for Linux 2）

   wsl --install
   

2. 安装Docker Desktop并启用WSL2后端

Linux用户：

• 通过系统包管理器安装Docker Engine和Docker Compose

部署步骤

1. 创建配置目录并下载docker-compose文件：

   mkdir ~/.cleo && cd ~/.cleo
   wget [Cleo的docker-compose.yml文件地址]
   

2. 配置环境变量：

   • 必须设置：CLEO_ADMIN_PASSWORD、CLEO_DJANGO_SECRET_KEY
   • 可选设置：商业AI模型的API密钥(OpenAI/Anthropic/Gemini)
   • 离线模型：配置OPENAI_BASE_URL指向本地Ollama等服务

3. 启动服务：

   docker-compose up
   

2. Pip直接安装

适合需要深度定制或资源受限的环境。

安装命令

根据不同系统和硬件配置，安装命令有所区别：

macOS(M1/M2芯片)：

CMAKE_ARGS="-DGGML_METAL=on" python -m pip install 'cleo[local]'

Windows(CUDA GPU)：

$env:CMAKE_ARGS = "-DGGML_CUDA=on"
py -m pip install 'cleo[local]'

Linux(AMD GPU)：

CMAKE_ARGS="-DGGML_HIPBLAS=on" FORCE_CMAKE=1 python -m pip install 'cleo[local]'

首次运行

启动服务：

USE_EMBEDDED_DB="true" cleo --anonymous-mode

首次运行会引导您：

1. 创建管理员账户
2. 配置聊天模型
3. 完成基础设置

模型配置指南

Cleo支持多种AI模型，包括商业API和本地离线模型。

商业API模型配置

1. OpenAI：

   • 需要API密钥
   • 支持自定义API端点(兼容Ollama等)
   • 示例模型：gpt-4o

2. Anthropic Claude：

   • 需要API密钥
   • 示例模型：claude-3-5-sonnet

3. Google Gemini：

   • 需要API密钥
   • 示例模型：gemini-2.0-flash

离线模型配置

1. 从模型仓库选择GGUF格式的模型
2. 在管理界面添加模型信息
3. 首次使用时自动下载模型文件
4. 支持GPU加速(需相应硬件)

客户端连接

部署完成后，可以通过以下方式访问：

1. Web界面：http://localhost:42110
2. 桌面客户端：提供更好的系统集成
3. Obsidian/Emacs插件：与常用工具深度集成

常见问题解决

1. 管理员面板访问问题：

   • 确保使用localhost而非127.0.0.1
   • 检查CSRF和域名设置

2. 模型加载缓慢：

   • 首次使用离线模型需要下载，请耐心等待
   • 确保硬件满足模型要求

3. GPU加速不工作：

   • 检查驱动安装
   • 验证部署时的GPU参数设置

进阶配置建议

1. 自动启动：配置系统服务实现开机自启
2. 远程访问：通过反向代理安全暴露服务
3. 知识同步：连接Notion或本地文档库
4. 多模型管理：配置默认模型和专用模型

结语

通过本文的指导，您应该已经成功在本地环境部署了Cleo AI助手系统。自托管方式为您提供了完全控制权和数据隐私保障，同时也带来了灵活的定制可能性。根据您的具体需求，可以进一步探索Cleo的高级功能和集成选项，打造专属的AI助手体验。