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: 下载发布包

```bash
# 从 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: 运行一键安装脚本

```bash
# 给脚本执行权限
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: 启动必需服务

```bash
# 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: 启动应用

```bash
# 启动 Momentry Studio
./start.sh

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

---

## 🔧 详细安装步骤

### 1. 环境准备

#### 1.1 安装 Node.js

**macOS**:
```bash
# 使用 Homebrew
brew install node@18

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

**Linux (Ubuntu)**:
```bash
# 使用 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

**所有平台**:
```bash
# 安装 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**:
```bash
# 安装
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)**:
```bash
# 安装
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)**:
```bash
brew install qdrant
qdrant &
```

**Docker (推荐)**:
```bash
docker run -d -p 6333:6333 qdrant/qdrant
```

**Linux**:
```bash
# 下载二进制
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**:
```bash
brew tap mongodb/brew
brew install mongodb-community

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

**Linux (Ubuntu)**:
```bash
# 导入公钥
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 克隆**:
```bash
cd ~
git clone <repo_url> momentry_studio
cd momentry_studio
```

**从压缩包**:
```bash
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 配置环境

**自动配置**:
```bash
./scripts/generate_config.sh
```

**手动配置**:
```bash
# 复制模板
cp .env.template .env
cp config/admin_config.json.template config/admin_config.json

# 编辑配置
vim .env
```

**必需配置**:
```bash
# .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 安装依赖

```bash
# Node.js 依赖
npm install

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

---

#### 2.4 构建应用

**开发构建**:
```bash
# 构建前端
npm run build

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

**生产构建 (Tauri 应用)**:
```bash
cargo tauri build
```

---

### 3. 数据库初始化

#### 3.1 初始化三层架构

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

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

**输出**:
```
✅ Admin Layer: 存在
✅ Group Layer: 2 个群组
✅ User Layer: 1 个用户
```

---

#### 3.2 创建默认用户

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

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

---

### 4. 启动应用

#### 4.1 启动后端服务

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

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

---

#### 4.2 启动 Studio

**开发模式**:
```bash
# 使用安装脚本生成的启动脚本
./start.sh

# 或手动启动
npm run dev
```

**生产模式**:
```bash
# 启动代理
./src-tauri/target/release/momentry-proxy &

# 启动前端
npm run preview
```

**Tauri 桌面应用**:
```bash
# macOS
open "release/Momentry Studio.app"

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

---

### 5. 验证安装

#### 5.1 检查服务

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

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

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

---

#### 5.2 测试功能

**访问应用**:
```
http://localhost:5173
```

**登录**:
- 用户名: `demo`
- 密码: 查看安装输出或 `.env` 文件

**测试功能**:
- [ ] 视频搜索
- [ ] 人脸识别
- [ ] 文件管理
- [ ] 搜索历史
- [ ] 书签功能

---

## 🔧 高级配置

### 1. 自定义路径

**通过环境变量**:
```bash
export MOMENTRY_CORE_ROOT=/custom/path/momentry_core
export MARKBASE_ROOT=/custom/path/markbase
export STORAGE_ROOT=/custom/path/storage
```

**在 .env 文件中**:
```bash
MOMENTRY_CORE_ROOT=/custom/path/momentry_core
MARKBASE_ROOT=/custom/path/markbase
STORAGE_ROOT=/custom/path/storage
```

---

### 2. 多用户配置

**创建新用户**:
```bash
./src-tauri/target/release/user_tool create user1 password123
```

**创建群组**:
```bash
# 参考 docs/MARKBASE_THREE_LAYER_ARCHITECTURE.md
```

---

### 3. 权限配置

**参考**: `docs/MARKBASE_THREE_LAYER_ARCHITECTURE.md`

---

## ❓ 故障排除

### 问题 1: PostgreSQL 连接失败

**检查**:
```bash
# 服务是否运行
pg_isready

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

# 权限是否正确
psql -d momentry
```

**解决**:
```bash
# 创建数据库
createdb momentry

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

---

### 问题 2: Qdrant 未运行

**检查**:
```bash
curl http://localhost:6333/health
```

**解决**:
```bash
# 启动 Qdrant
qdrant &

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

---

### 问题 3: MongoDB 连接失败

**检查**:
```bash
mongosh --eval "db.runCommand({ping:1})"
```

**解决**:
```bash
# 启动 MongoDB
mongod --config /usr/local/etc/mongod.conf --fork

# 或使用 systemctl
sudo systemctl start mongod
```

---

### 问题 4: 编译失败

**检查**:
```bash
# Node.js 版本
node --version  # 需要 v18+

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

# 依赖安装
npm install
cargo fetch
```

**解决**:
```bash
# 清理并重新构建
cargo clean
npm run build
cargo build --release
```

---

### 问题 5: 忘记密码

**解决**:
```bash
# 查看密码
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. 环境准备

```bash
# 登录到 m4promini
ssh nextorageai@m4promini

# 检查系统
uname -a
sw_vers  # macOS
```

---

### 2. 安装依赖

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

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

---

### 3. 部署应用

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

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

---

### 4. 验证功能

```bash
# 启动服务
./start.sh

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

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

---

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