momentry_studio/INSTALLATION_GUIDE.md

Momentry Studio v0.1.0 安装指南

版本: v0.1.0
目标: 安装并运行 Momentry Studio
适用系统: macOS / Linux
测试系统: m4promini

---

📋 系统要求

必需软件

软件	版本	用途	安装命令
Node.js	v18+	前端运行	brew install node@18
Rust	1.77.2+	后端编译	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
npm	v9+	包管理	随 Node.js 安装
PostgreSQL	12+	核心数据库	brew install postgresql@14
Qdrant	1.7+	向量搜索	brew install qdrant 或 Docker
MongoDB	5+	文档存储	brew install mongodb-community

系统资源

• CPU: 4 核心或更高
• 内存: 8GB 或更高
• 存储: 100GB 或更高

---

🚀 快速安装 (推荐)

步骤 1: 下载发布包

# 从 Git 仓库克隆
cd ~
git clone <repo_url> momentry_studio
cd momentry_studio

# 或下载压缩包
curl -LO <release_url>/momentry_studio_v0.1.0.tar.gz
tar -xzf momentry_studio_v0.1.0.tar.gz
cd momentry_studio

---

步骤 2: 运行一键安装脚本

# 给脚本执行权限
chmod +x scripts/*.sh

# 运行安装脚本
./scripts/install.sh

安装脚本会自动:

• ✅ 检测用户主目录
• ✅ 安装 Node.js 依赖
• ✅ 构建前端
• ✅ 构建 Rust 后端
• ✅ 创建数据目录
• ✅ 生成随机密码
• ✅ 创建启动脚本
• ✅ 初始化数据库

安装输出:

================================================================================
                    Momentry Studio v0.1.0 安装
================================================================================

步骤 1/6: 环境检查...
✅ Node.js: v18.x
✅ Rust: 1.77.2
✅ npm: 9.x

步骤 2/6: 设置环境变量...
✅ 用户主目录: /Users/nextorageai
✅ 项目根目录: /Users/nextorageai/momentry_studio

步骤 3/6: 创建数据目录...
✅ 已创建数据目录

步骤 4/6: 安装依赖并构建...
✅ 构建完成

步骤 5/6: 初始化默认用户...
========================================
Default user password: demo_a1b2c3d4
Please save this password securely!
========================================

步骤 6/6: 创建启动脚本...
✅ 启动脚本已创建

================================================================================
                    安装完成
================================================================================

下一步:
1. 启动必需服务:
   - PostgreSQL
   - Qdrant
   - MongoDB

2. 配置环境变量:
   vim .env

3. 启动应用:
   ./start.sh

================================================================================

---

步骤 3: 启动必需服务

# PostgreSQL
pg_ctl start -D /usr/local/var/postgres
createdb momentry
psql -d momentry -c "CREATE EXTENSION IF NOT EXISTS vector;"

# MongoDB
mongod --config /usr/local/etc/mongod.conf --fork

# Qdrant
qdrant &
# 或使用 Docker
docker run -d -p 6333:6333 qdrant/qdrant

---

步骤 4: 启动应用

# 启动 Momentry Studio
./start.sh

# 访问应用
# 浏览器打开: http://localhost:5173
# 或使用 Tauri 桌面应用: open "release/Momentry Studio.app"

---

🔧 详细安装步骤

1. 环境准备

1.1 安装 Node.js

macOS:

# 使用 Homebrew
brew install node@18

# 验证
node --version  # v18.x
npm --version   # 9.x

Linux (Ubuntu):

# 使用 NodeSource
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version  # v18.x
npm --version   # 9.x

---

1.2 安装 Rust

所有平台:

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 加载环境
source $HOME/.cargo/env

# 验证
rustc --version  # 1.77.2+
cargo --version

---

1.3 安装 PostgreSQL

macOS:

# 安装
brew install postgresql@14

# 启动服务
pg_ctl start -D /usr/local/var/postgres

# 创建数据库
createdb momentry

# 安装 pgvector 扩展
psql -d momentry -c "CREATE EXTENSION IF NOT EXISTS vector;"

Linux (Ubuntu):

# 安装
sudo apt-get install -y postgresql postgresql-contrib

# 启动服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

# 创建数据库
sudo -u postgres createdb momentry

# 安装 pgvector
sudo apt-get install -y postgresql-14-pgvector
sudo -u postgres psql -d momentry -c "CREATE EXTENSION IF NOT EXISTS vector;"

---

1.4 安装 Qdrant

macOS (Homebrew):

brew install qdrant
qdrant &

Docker (推荐):

docker run -d -p 6333:6333 qdrant/qdrant

Linux:

# 下载二进制
wget https://github.com/qdrant/qdrant/releases/download/v1.7.0/qdrant-x86_64-unknown-linux-gnu.tar.gz
tar -xzf qdrant-x86_64-unknown-linux-gnu.tar.gz
./qdrant &

---

1.5 安装 MongoDB

macOS:

brew tap mongodb/brew
brew install mongodb-community

# 启动
mongod --config /usr/local/etc/mongod.conf --fork

Linux (Ubuntu):

# 导入公钥
wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -

# 添加源
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

# 安装
sudo apt-get update
sudo apt-get install -y mongodb-org

# 启动
sudo systemctl start mongod
sudo systemctl enable mongod

---

2. 代码部署

2.1 获取代码

从 Git 克隆:

cd ~
git clone <repo_url> momentry_studio
cd momentry_studio

从压缩包:

cd ~
curl -LO <release_url>/momentry_studio_v0.1.0.tar.gz
tar -xzf momentry_studio_v0.1.0.tar.gz
cd momentry_studio

---

2.2 配置环境

自动配置:

./scripts/generate_config.sh

手动配置:

# 复制模板
cp .env.template .env
cp config/admin_config.json.template config/admin_config.json

# 编辑配置
vim .env

必需配置:

# .env 文件
MOMENTRY_API_KEY=your_api_key_here
MOMENTRY_DEFAULT_PASSWORD=demo_a1b2c3d4

# PostgreSQL
DATABASE_URL=postgres://$(whoami)@localhost:5432/momentry

# Qdrant
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your_qdrant_key

# MongoDB
MONGODB_URL=mongodb://localhost:27017
MONGODB_DATABASE=momentry

---

2.3 安装依赖

# Node.js 依赖
npm install

# Rust 依赖 (自动)
cd src-tauri
cargo fetch
cd ..

---

2.4 构建应用

开发构建:

# 构建前端
npm run build

# 构建 Rust
cd src-tauri
cargo build --release
cd ..

生产构建 (Tauri 应用):

cargo tauri build

---

3. 数据库初始化

3.1 初始化三层架构

# 运行初始化脚本
./scripts/init_three_layer_db.sh

# 检查结果
./scripts/check_three_layer.sh

输出:

✅ Admin Layer: 存在
✅ Group Layer: 2 个群组
✅ User Layer: 1 个用户

---

3.2 创建默认用户

# 查看用户列表
./src-tauri/target/release/user_tool list

# 修改密码
./src-tauri/target/release/user_tool set-password demo new_password

---

4. 启动应用

4.1 启动后端服务

# 确保 Momentry Core API 运行
cd ~/momentry_core
./start.sh

# 确保 MarkBase API 运行
cd ~/markbase/markbase-core
./start.sh

---

4.2 启动 Studio

开发模式:

# 使用安装脚本生成的启动脚本
./start.sh

# 或手动启动
npm run dev

生产模式:

# 启动代理
./src-tauri/target/release/momentry-proxy &

# 启动前端
npm run preview

Tauri 桌面应用:

# macOS
open "release/Momentry Studio.app"

# 或直接运行
./src-tauri/target/release/momentry-studio

---

5. 验证安装

5.1 检查服务

# 检查数据库
./scripts/check_db_dependencies.sh

# 检查三层架构
./scripts/check_three_layer.sh

# 检查用户隔离
./scripts/check_user_isolation.sh

---

5.2 测试功能

访问应用:

http://localhost:5173

登录:

• 用户名: demo
• 密码: 查看安装输出或 .env 文件

测试功能:

• 视频搜索
• 人脸识别
• 文件管理
• 搜索历史
• 书签功能

---

🔧 高级配置

1. 自定义路径

通过环境变量:

export MOMENTRY_CORE_ROOT=/custom/path/momentry_core
export MARKBASE_ROOT=/custom/path/markbase
export STORAGE_ROOT=/custom/path/storage

在 .env 文件中:

MOMENTRY_CORE_ROOT=/custom/path/momentry_core
MARKBASE_ROOT=/custom/path/markbase
STORAGE_ROOT=/custom/path/storage

---

2. 多用户配置

创建新用户:

./src-tauri/target/release/user_tool create user1 password123

创建群组:

# 参考 docs/MARKBASE_THREE_LAYER_ARCHITECTURE.md

---

3. 权限配置

参考: docs/MARKBASE_THREE_LAYER_ARCHITECTURE.md

---

❓ 故障排除

问题 1: PostgreSQL 连接失败

检查:

# 服务是否运行
pg_isready

# 数据库是否存在
psql -l | grep momentry

# 权限是否正确
psql -d momentry

解决:

# 创建数据库
createdb momentry

# 授予权限
psql -d momentry -c "GRANT ALL PRIVILEGES ON DATABASE momentry TO $(whoami);"

---

问题 2: Qdrant 未运行

检查:

curl http://localhost:6333/health

解决:

# 启动 Qdrant
qdrant &

# 或使用 Docker
docker run -d -p 6333:6333 qdrant/qdrant

---

问题 3: MongoDB 连接失败

检查:

mongosh --eval "db.runCommand({ping:1})"

解决:

# 启动 MongoDB
mongod --config /usr/local/etc/mongod.conf --fork

# 或使用 systemctl
sudo systemctl start mongod

---

问题 4: 编译失败

检查:

# Node.js 版本
node --version  # 需要 v18+

# Rust 版本
rustc --version  # 需要 1.77.2+

# 依赖安装
npm install
cargo fetch

解决:

# 清理并重新构建
cargo clean
npm run build
cargo build --release

---

问题 5: 忘记密码

解决:

# 查看密码
cat .env | grep MOMENTRY_DEFAULT_PASSWORD

# 或重置密码
./src-tauri/target/release/user_tool set-password demo new_password

---

📊 安装后检查清单

服务检查

• PostgreSQL 运行中 (localhost:5432)
• Qdrant 运行中 (localhost:6333)
• MongoDB 运行中 (localhost:27017)
• Momentry Core API 运行中 (localhost:3002)
• MarkBase API 运行中 (localhost:11438)

---

数据库检查

• PostgreSQL momentry 数据库存在
• pgvector 扩展已安装
• SQLite 数据库已初始化
• Admin 数据库存在
• Group 数据库存在
• User 数据库存在

---

应用检查

• 前端可访问 (localhost:5173)
• 代理服务运行 (localhost:8888)
• 可以登录
• 功能测试通过

---

📞 获取帮助

文档

• docs/DEPLOYMENT_CHECKLIST.md - 部署检查清单
• docs/DATABASE_DEPENDENCIES.md - 数据库依赖
• docs/DEFAULT_PASSWORD_SYSTEM.md - 密码系统

脚本

• scripts/install.sh - 一键安装
• scripts/check_*.sh - 各种检查脚本

支持

• Issues: <repo_url>/issues
• Email: support@momentry.ai

---

🎯 m4promini 测试步骤

1. 环境准备

# 登录到 m4promini
ssh nextorageai@m4promini

# 检查系统
uname -a
sw_vers  # macOS

---

2. 安装依赖

# 检查现有版本
node --version
rustc --version

# 如果未安装，运行:
./scripts/install.sh

---

3. 部署应用

# 克隆代码
cd ~
git clone <repo_url> momentry_studio
cd momentry_studio

# 运行安装
./scripts/install.sh

---

4. 验证功能

# 启动服务
./start.sh

# 测试访问
curl http://localhost:5173
curl http://localhost:8888/api/v1/search-history

# 浏览器测试
# 打开: http://m4promini.local:5173

---

准备状态: ✅ 文档和脚本已准备
测试环境: m4promini
安装方式: 一键安装脚本