Your Memory 项目本地开发环境搭建指南

项目概述

Your Memory 是一个基于人工智能的记忆辅助系统，能够帮助用户存储、组织和检索各类记忆信息。该系统采用了现代化的技术栈，包括 PostgreSQL 数据库、Qdrant 向量搜索引擎以及 OpenAI 的 NLP 能力。

开发环境选择

Your Memory 提供了三种开发环境配置方案：

1. 全本地 Docker 环境：使用 Docker 容器运行 PostgreSQL 和 Qdrant
2. 混合云环境：使用 Supabase 云数据库和 Qdrant Cloud 向量存储
3. 生产环境：部署在 Render 云平台

对于大多数开发者，我们推荐使用全本地 Docker 环境进行开发，因为它提供了最完整的隔离性和一致性。

全本地 Docker 环境搭建

准备工作

在开始之前，请确保你的开发机满足以下要求：

• Docker 20.10+ 和 Docker Compose 1.29+
• Python 3.8 或更高版本
• Node.js 14.x 或更高版本
• npm 或 pnpm 包管理器
• OpenAI API 密钥（用于 AI 功能）

详细安装步骤

第一步：运行修复脚本

项目提供了一个修复脚本，用于创建必要的配置文件和目录结构：

./fix-local-setup.sh

这个脚本会自动创建 .env.template 文件和其他必要的目录。

第二步：配置环境变量

编辑生成的 .env 文件，添加你的 OpenAI API 密钥：

OPENAI_API_KEY=你的OpenAI_API密钥

第三步：启动 Docker 容器

使用以下命令启动所有必要的服务容器：

./setup-local-dev.sh --fresh

--fresh 参数会确保所有容器从干净的状态启动。

第四步：初始化数据库

容器启动后，需要初始化数据库结构：

./init-local-database.sh

这个脚本会创建所有必要的数据库表、索引和初始数据。

第五步：完成设置

运行完整的设置脚本：

./setup-local-dev.sh

第六步：启动服务

现在可以启动 API 和 UI 服务了：

# 在第一个终端启动API服务
./start-api.sh

# 在第二个终端启动UI服务
./start-ui.sh

第七步：访问服务

服务启动后，可以通过以下地址访问：

• API 服务：http://localhost:8765
• 用户界面：http://localhost:3000
• PostgreSQL 数据库：localhost:5432
  • 用户名：jean_memory
  • 密码：memory_password
• Qdrant 管理界面：http://localhost:6334

第八步：验证安装

建议运行测试脚本来验证所有组件是否正常工作：

./test-complete-local-setup.py

混合云环境搭建

如果你希望使用云服务进行开发，可以按照以下步骤配置混合云环境。

准备工作

• 有效的 Supabase 账户和项目
• Qdrant Cloud 账户
• Python 3.8+
• Node.js 14+

配置步骤

1. 从模板创建环境文件：

cp .env.template .env

2. 编辑 .env 文件，添加你的云服务凭证：

SUPABASE_URL=你的Supabase项目URL
SUPABASE_ANON_KEY=你的Supabase匿名密钥
SUPABASE_SERVICE_KEY=你的Supabase服务密钥
QDRANT_HOST=你的Qdrant Cloud主机地址
QDRANT_API_KEY=你的Qdrant API密钥
OPENAI_API_KEY=你的OpenAI API密钥

3. 运行混合环境设置脚本：

./setup-hybrid.sh

4. 启动服务：

# 使用统一管理脚本启动所有服务
./jean-memory.sh start

# 或者手动启动
./jean-memory.sh start-api  # API服务
./jean-memory.sh start-ui   # UI服务

统一管理脚本

项目提供了一个方便的脚本 jean-memory.sh 来管理整个开发环境：

# 设置新环境
./jean-memory.sh setup

# 测试连接
./jean-memory.sh test-connection

# 安装依赖
./jean-memory.sh setup-deps

# 启动所有服务
./jean-memory.sh start

# 检查服务状态
./jean-memory.sh status

# 停止所有服务
./jean-memory.sh stop

常见问题排查

Docker 相关问题

• 容器无法启动：检查 5432、6333、6334 端口是否被占用
• 数据库连接失败：等待 PostgreSQL 完全启动后再运行迁移脚本

认证问题

• 401 未授权错误：确保 API 的 .env 文件中设置了 USER_ID=default_user
• 前端认证错误：检查 UI 的 .env.local 文件中设置了 NEXT_PUBLIC_USER_ID=default_user

数据库问题

• 迁移失败：尝试重新运行 ./init-local-database.sh
• Qdrant 错误：检查 Qdrant 容器是否正常运行

常用命令

# 查看Docker容器状态
docker ps

# 查看Docker日志
docker-compose logs -f

# 完全重置环境
./setup-local-dev.sh --fresh

# 清理Docker卷
docker-compose down -v

# 查看API日志
tail -f openmemory/api/logs/*.log

系统架构说明

1. 本地认证绕过：当设置 USER_ID 环境变量时，系统会绕过 Supabase 认证
2. 数据库灵活性：支持本地 PostgreSQL 和 Supabase 云数据库
3. 向量存储：支持本地 Qdrant 和 Qdrant Cloud
4. 环境隔离：API 和 UI 有各自的环境配置文件

数据库结构

系统使用以下主要数据表：

• users：用户数据
• apps：用户应用
• memories：核心记忆存储
• categories：记忆分类
• documents：文档存储
• document_chunks：文档分块（用于处理）
• access_controls：权限设置
• archive_policies：归档策略
• memory_status_history：状态变更记录
• memory_access_logs：访问记录

开发建议

1. 使用本地认证：开发时设置 USER_ID=default_user 可以简化认证流程
2. 监控服务状态：定期检查 Docker 容器和服务的运行状态
3. 利用测试脚本：项目提供了多个测试脚本，可以帮助验证环境配置
4. 关注日志：API 和前端服务都会生成详细的日志文件

通过本指南，你应该能够顺利搭建 Your Memory 项目的本地开发环境。如果在过程中遇到任何问题，可以参考项目的文档或寻求社区支持。