docs: 准备 v0.1.0 发布文档
发布文档: 1. RELEASE_PREPARATION.md - 发布准备清单 - 发布内容清单 - 系统要求 - 构建步骤 - 发布检查清单 - 安装包制作 2. INSTALLATION_GUIDE.md - 详细安装指南 - 系统要求 - 快速安装步骤 - 详细安装流程 - 高级配置 - 故障排除 - m4promini 测试步骤 3. QUICK_REFERENCE.md - 快速参考卡片 - 一键安装命令 - 系统要求表格 - 关键路径 - 常用命令 - 故障排除 4. README.md - 项目主文档 - 项目简介 - 快速开始 - 功能特性 - 架构设计 - API 文档 - 版本历史 目标: - 安装到任何需要的系统 - 测试系统: m4promini - 交给 admin team 做成安装包 文档特点: - 一键安装脚本 - 详细步骤说明 - 故障排除指南 - 快速参考卡片
This commit is contained in:
327
QUICK_REFERENCE.md
Normal file
327
QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# Momentry Studio v0.1.0 快速参考卡片
|
||||
|
||||
**版本**: v0.1.0
|
||||
**日期**: 2026-10-12
|
||||
|
||||
---
|
||||
|
||||
## 🚀 一键安装
|
||||
|
||||
```bash
|
||||
# 1. 克隆代码
|
||||
git clone <repo_url> momentry_studio && cd momentry_studio
|
||||
|
||||
# 2. 运行安装
|
||||
./scripts/install.sh
|
||||
|
||||
# 3. 启动服务
|
||||
./start.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 系统要求
|
||||
|
||||
| 软件 | 版本 | 安装命令 |
|
||||
|-----|------|---------|
|
||||
| Node.js | v18+ | `brew install node@18` |
|
||||
| Rust | 1.77.2+ | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
|
||||
| PostgreSQL | 12+ | `brew install postgresql@14` |
|
||||
| Qdrant | 1.7+ | `docker run -d -p 6333:6333 qdrant/qdrant` |
|
||||
| MongoDB | 5+ | `brew install mongodb-community` |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 必需服务启动
|
||||
|
||||
```bash
|
||||
# PostgreSQL
|
||||
pg_ctl start -D /usr/local/var/postgres
|
||||
createdb momentry
|
||||
psql -d momentry -c "CREATE EXTENSION IF NOT EXISTS vector;"
|
||||
|
||||
# Qdrant
|
||||
qdrant &
|
||||
|
||||
# MongoDB
|
||||
mongod --config /usr/local/etc/mongod.conf --fork
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 关键路径
|
||||
|
||||
```
|
||||
~/momentry_studio/ # 项目根目录
|
||||
├── .env # 环境变量配置
|
||||
├── start.sh # 启动脚本
|
||||
├── data/ # 数据目录
|
||||
│ ├── admin/admin.sqlite # Admin 数据库
|
||||
│ ├── groups/group_*.sqlite # Group 数据库
|
||||
│ └── users/*.sqlite # User 数据库
|
||||
├── src-tauri/target/release/ # 编译产物
|
||||
│ ├── momentry-studio # 主程序
|
||||
│ ├── momentry-proxy # 代理服务
|
||||
│ └── user_tool # 用户管理工具
|
||||
└── release/ # 发布包
|
||||
└── "Momentry Studio.app" # macOS 应用
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔑 默认账号
|
||||
|
||||
**管理员**:
|
||||
- 用户名: `admin`
|
||||
- 密码: `admin123`
|
||||
|
||||
**普通用户**:
|
||||
- 用户名: `demo`
|
||||
- 密码: 查看 `.env` 文件或安装输出
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 用户管理工具
|
||||
|
||||
```bash
|
||||
# 列出用户
|
||||
./src-tauri/target/release/user_tool list
|
||||
|
||||
# 创建用户
|
||||
./src-tauri/target/release/user_tool create <username> <password>
|
||||
|
||||
# 修改密码
|
||||
./src-tauri/target/release/user_tool set-password <username> <password>
|
||||
|
||||
# 删除用户
|
||||
./src-tauri/target/release/user_tool delete <username>
|
||||
|
||||
# 初始化 demo 用户
|
||||
./src-tauri/target/release/user_tool init-demo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 检查命令
|
||||
|
||||
```bash
|
||||
# 数据库依赖检查
|
||||
./scripts/check_db_dependencies.sh
|
||||
|
||||
# 三层架构检查
|
||||
./scripts/check_three_layer.sh
|
||||
|
||||
# 用户隔离检查
|
||||
./scripts/check_user_isolation.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 访问地址
|
||||
|
||||
| 服务 | 地址 | 用途 |
|
||||
|-----|------|------|
|
||||
| **前端** | `http://localhost:5173` | Web 界面 |
|
||||
| **代理** | `http://localhost:8888` | API 代理 |
|
||||
| **Core API** | `http://localhost:3002` | Momentry Core |
|
||||
| **MarkBase API** | `http://localhost:11438` | 文件管理 |
|
||||
| **PostgreSQL** | `localhost:5432` | 核心数据库 |
|
||||
| **Qdrant** | `http://localhost:6333` | 向量搜索 |
|
||||
| **MongoDB** | `localhost:27017` | 文档存储 |
|
||||
|
||||
---
|
||||
|
||||
## 📝 环境变量
|
||||
|
||||
```bash
|
||||
# .env 文件
|
||||
|
||||
# API Keys
|
||||
MOMENTRY_API_KEY=your_api_key_here
|
||||
|
||||
# 默认用户密码
|
||||
MOMENTRY_DEFAULT_PASSWORD=demo_a1b2c3d4
|
||||
|
||||
# SMB 配置 (可选)
|
||||
SMB_USER=demo
|
||||
SMB_PASSWORD=${MOMENTRY_DEFAULT_PASSWORD}
|
||||
|
||||
# 数据库连接
|
||||
DATABASE_URL=postgres://$(whoami)@localhost:5432/momentry
|
||||
QDRANT_URL=http://localhost:6333
|
||||
MONGODB_URL=mongodb://localhost:27017
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 常用命令
|
||||
|
||||
### 启动
|
||||
|
||||
```bash
|
||||
# 启动所有服务
|
||||
./start.sh
|
||||
|
||||
# 或手动启动
|
||||
npm run dev # 前端
|
||||
./src-tauri/target/release/momentry-proxy & # 代理
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 停止
|
||||
|
||||
```bash
|
||||
# 停止服务
|
||||
pkill -f momentry-proxy
|
||||
pkill -f vite
|
||||
|
||||
# 停止数据库
|
||||
pg_ctl stop -D /usr/local/var/postgres
|
||||
mongod --shutdown
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 重启
|
||||
|
||||
```bash
|
||||
# 重启应用
|
||||
pkill -f momentry-proxy && ./start.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 日志
|
||||
|
||||
```bash
|
||||
# 查看日志
|
||||
tail -f /tmp/momentry_*.log
|
||||
tail -f logs/studio.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 故障排除
|
||||
|
||||
### 服务未运行
|
||||
|
||||
```bash
|
||||
# PostgreSQL
|
||||
pg_ctl start -D /usr/local/var/postgres
|
||||
|
||||
# Qdrant
|
||||
qdrant &
|
||||
|
||||
# MongoDB
|
||||
mongod --config /usr/local/etc/mongod.conf --fork
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 端口被占用
|
||||
|
||||
```bash
|
||||
# 查看端口占用
|
||||
lsof -i :5173
|
||||
lsof -i :8888
|
||||
lsof -i :3002
|
||||
lsof -i :11438
|
||||
|
||||
# 终止进程
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 数据库连接失败
|
||||
|
||||
```bash
|
||||
# PostgreSQL
|
||||
psql -l | grep momentry
|
||||
|
||||
# Qdrant
|
||||
curl http://localhost:6333/health
|
||||
|
||||
# MongoDB
|
||||
mongosh --eval "db.runCommand({ping:1})"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 文档位置
|
||||
|
||||
| 文档 | 位置 | 用途 |
|
||||
|-----|------|------|
|
||||
| **部署检查清单** | `DEPLOYMENT_CHECKLIST.md` | 部署前检查 |
|
||||
| **安装指南** | `INSTALLATION_GUIDE.md` | 详细安装步骤 |
|
||||
| **数据库依赖** | `docs/DATABASE_DEPENDENCIES.md` | 数据库架构 |
|
||||
| **三层架构** | `docs/MARKBASE_THREE_LAYER_ARCHITECTURE.md` | 架构设计 |
|
||||
| **密码系统** | `docs/DEFAULT_PASSWORD_SYSTEM.md` | 密码管理 |
|
||||
| **文件存储** | `docs/CLIENTVIEW_STORAGE_ARCHITECTURE.md` | 存储架构 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 m4promini 测试
|
||||
|
||||
```bash
|
||||
# 1. SSH 登录
|
||||
ssh nextorageai@m4promini
|
||||
|
||||
# 2. 克隆代码
|
||||
git clone <repo_url> ~/momentry_studio
|
||||
cd ~/momentry_studio
|
||||
|
||||
# 3. 一键安装
|
||||
./scripts/install.sh
|
||||
|
||||
# 4. 启动服务
|
||||
./start.sh
|
||||
|
||||
# 5. 验证
|
||||
curl http://localhost:5173
|
||||
curl http://localhost:8888/api/v1/search-history
|
||||
|
||||
# 6. 浏览器测试
|
||||
# 访问: http://m4promini.local:5173
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要提示
|
||||
|
||||
### 已知问题
|
||||
|
||||
1. **用户数据库隔离**: 当前硬编码 `demo.sqlite`
|
||||
- 文档: `docs/USER_DATABASE_ISOLATION_FIX.md`
|
||||
- 影响: 所有用户共享同一数据库
|
||||
- 修复: v0.2.0
|
||||
|
||||
2. **遗留依赖**: sqlx (PostgreSQL) 未使用
|
||||
- 文档: `docs/DATABASE_OPTIMIZATION.md`
|
||||
- 影响: 编译时间增加
|
||||
- 修复: v0.2.0
|
||||
|
||||
---
|
||||
|
||||
### 安全建议
|
||||
|
||||
- ✅ 修改默认密码
|
||||
- ✅ 设置 .env 文件权限为 600
|
||||
- ✅ 定期备份数据库
|
||||
- ✅ 启用审计日志
|
||||
|
||||
---
|
||||
|
||||
## 📞 获取帮助
|
||||
|
||||
**文档**: `docs/` 目录
|
||||
**脚本**: `scripts/` 目录
|
||||
**Issues**: <repo_url>/issues
|
||||
**Email**: support@momentry.ai
|
||||
|
||||
---
|
||||
|
||||
**版本**: v0.1.0
|
||||
**状态**: ✅ 准备就绪
|
||||
**测试**: m4promini
|
||||
Reference in New Issue
Block a user