docs: 准备 v0.1.0 发布文档

发布文档: 1. RELEASE_PREPARATION.md - 发布准备清单 - 发布内容清单 - 系统要求 - 构建步骤 - 发布检查清单 - 安装包制作 2. INSTALLATION_GUIDE.md - 详细安装指南 - 系统要求 - 快速安装步骤 - 详细安装流程 - 高级配置 - 故障排除 - m4promini 测试步骤 3. QUICK_REFERENCE.md - 快速参考卡片 - 一键安装命令 - 系统要求表格 - 关键路径 - 常用命令 - 故障排除 4. README.md - 项目主文档 - 项目简介 - 快速开始 - 功能特性 - 架构设计 - API 文档 - 版本历史目标: - 安装到任何需要的系统 - 测试系统: m4promini - 交给 admin team 做成安装包文档特点: - 一键安装脚本 - 详细步骤说明 - 故障排除指南 - 快速参考卡片
2026-10-12 15:14:07 +08:00
parent be3cef2e0d
commit 12943a3f07
4 changed files with 1885 additions and 162 deletions
--- a/INSTALLATION_GUIDE.md
+++ b/INSTALLATION_GUIDE.md
@@ -0,0 +1,749 @@
+# 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  
+**安装方式**: 一键安装脚本