# Momentry Studio v0.1.0 - Admin Team 部署指南

**发布日期：** 2026-10-08  
**构建版本：** 8e71996  
**目标环境：** 生产环境

---

## 📦 发布包信息

**文件名：** `momentry-studio-v0.1.0-macos-aarch64.tar.gz`  
**文件大小：** 37MB  
**SHA256：** 
```
154ef0e02a6199278ea6bc6a5073d11c631527f2825ba78ceeafcb5f486cf969
```

---

## 🔐 验证发布包

```bash
# 下载发布包后验证校验和
shasum -a 256 -c momentry-studio-v0.1.0-macos-aarch64.tar.gz.sha256
```

---

## 📋 部署前检查清单

### 1. 系统要求
- [ ] macOS 12.0+ (Monterey 或更高版本)
- [ ] Apple Silicon (M1/M2/M3)
- [ ] 4GB RAM minimum (推荐 8GB)
- [ ] 1GB 可用磁盘空间

### 2. 依赖服务
- [ ] PostgreSQL 14+ 已安装并运行
- [ ] Qdrant 1.7+ 已安装并运行
- [ ] MarkBase Core API 2.3+ 已配置
- [ ] MarkBase Engine 1.0+ 已配置

### 3. 网络配置
- [ ] 端口 3002 可用（Core API）
- [ ] 端口 8888 可用（Proxy）
- [ ] 端口 5432 可用（PostgreSQL）
- [ ] 端口 6333 可用（Qdrant）

---

## 🚀 部署步骤

### 步骤 1: 准备发布包

```bash
# 1. 解压发布包
tar -xzf momentry-studio-v0.1.0-macos-aarch64.tar.gz

# 2. 验证内容
ls -l
# 应该看到：
# - Momentry Studio.app
# - Momentry Studio_0.1.0_aarch64.dmg
# - momentry-core
# - momentry-proxy
# - install.sh
# - README.md
# - RELEASE_NOTES.md
# - VERSION.json
```

### 步骤 2: 部署 Studio App

**选项 A: 使用 DMG（推荐）**
```bash
# 打开 DMG 文件
open "Momentry Studio_0.1.0_aarch64.dmg"

# 在 Finder 中拖拽到 Applications
# 或使用命令行：
cp -r "/Volumes/Momentry Studio/Momentry Studio.app" /Applications/
```

**选项 B: 使用 .app**
```bash
# 直接复制到 Applications
cp -r "Momentry Studio.app" /Applications/

# 如果需要，授权运行
xattr -d com.apple.quarantine "/Applications/Momentry Studio.app"
```

**选项 C: 使用安装脚本**
```bash
# 运行安装脚本
./install.sh
```

### 步骤 3: 部署 Backend Services

**安装 binaries：**
```bash
# 复制到系统 bin 目录
sudo cp momentry-core /usr/local/bin/
sudo cp momentry-proxy /usr/local/bin/

# 设置权限
sudo chmod +x /usr/local/bin/momentry-core
sudo chmod +x /usr/local/bin/momentry-proxy
```

### 步骤 4: 配置服务

**创建配置文件：**
```bash
# 创建配置目录
mkdir -p /opt/momentry/config

# 创建配置文件
cat > /opt/momentry/config/momentry.toml << 'TOML'
[server]
host = "0.0.0.0"
port = 3002

[database]
url = "postgres://momentry:password@localhost:5432/momentry"

[face_settings]
min_confidence = 0.5
min_bbox_size = 80
TOML
```

**设置环境变量：**
```bash
# 在 ~/.zshrc 或 ~/.bash_profile 中添加
export MOMENTRY_API_KEY="your_production_api_key"
export MOMENTRY_DATA_DIR="/opt/momentry/data"
export MOMENTRY_CONFIG="/opt/momentry/config/momentry.toml"
```

### 步骤 5: 启动服务

**手动启动：**
```bash
# 1. 启动 Core API
momentry-core server --config /opt/momentry/config/momentry.toml

# 2. 在另一个终端启动 Studio
open "/Applications/Momentry Studio.app"
```

**创建 launchd 服务（可选）：**
```bash
# 创建 Core API 服务
sudo cat > /Library/LaunchDaemons/com.momentry.core.plist << 'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.momentry.core</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/momentry-core</string>
        <string>server</string>
        <string>--config</string>
        <string>/opt/momentry/config/momentry.toml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
PLIST

# 加载服务
sudo launchctl load /Library/LaunchDaemons/com.momentry.core.plist
```

---

## ✅ 验证部署

### 1. 验证 Core API

```bash
# 检查服务状态
curl http://localhost:3002/api/v1/health

# 预期响应：
# {"status":"ok","version":"1.0.0",...}
```

### 2. 验证 Proxy

```bash
# 检查 proxy 状态
curl http://localhost:8888/health

# 预期响应：
# ok
```

### 3. 验证 Studio App

```bash
# 打开应用
open "/Applications/Momentry Studio.app"

# 检查进程
ps aux | grep "Momentry Studio"
```

### 4. 功能测试

在 Studio 中测试以下功能：

- [ ] 登录功能
- [ ] Library 文件浏览
- [ ] Search 功能
- [ ] People 页面
- [ ] Admin 设置页面
  - [ ] MarkBase Engine 状态显示为 `online`
  - [ ] 批量 Deep Scan 功能
  - [ ] 批量 Unregister 功能

---

## 🔄 更新流程

### 从旧版本升级

```bash
# 1. 停止旧服务
sudo launchctl unload /Library/LaunchDaemons/com.momentry.core.plist 2>/dev/null || true
pkill -f momentry-core
pkill -f "Momentry Studio"

# 2. 备份数据（重要！）
pg_dump momentry > momentry_backup_$(date +%Y%m%d).sql

# 3. 安装新版本
# （按照上面的部署步骤）

# 4. 启动新服务
sudo launchctl load /Library/LaunchDaemons/com.momentry.core.plist
```

---

## 🐛 故障排查

### 问题 1: 应用无法启动

**症状：** 双击 .app 后无反应

**解决方案：**
```bash
# 移除隔离属性
xattr -d com.apple.quarantine "/Applications/Momentry Studio.app"

# 检查控制台日志
log stream --predicate 'process == "momentry-studio"' --level debug
```

### 问题 2: 无法连接到 Core API

**症状：** Studio 显示连接错误

**解决方案：**
```bash
# 检查 Core API 是否运行
ps aux | grep momentry-core

# 检查端口是否监听
lsof -i :3002

# 检查防火墙
# 确保端口 3002 和 8888 已开放
```

### 问题 3: MarkBase Engine 显示 offline

**症状：** Admin 页面显示 MarkBase Engine 为 offline

**解决方案：**
```bash
# 检查 MarkBase Engine 是否运行
curl http://localhost:8080/health

# 如果正常返回 {"status":"ok"}，但 Studio 仍显示 offline
# 确认使用的是最新版本的 Studio（v0.1.0+）
```

---

## 📊 监控和日志

### 日志位置

- **Core API:** `/opt/momentry/logs/core.log`
- **Proxy:** `/opt/momentry/logs/proxy.log`
- **Studio:** `~/Library/Logs/Momentry Studio/`

### 性能监控

```bash
# 检查资源使用
top -pid $(pgrep momentry-core)

# 检查内存使用
ps aux | grep momentry-core | awk '{print $6/1024 "MB"}'
```

---

## 📞 支持联系

**技术支持：**
- Email: tech@momentry.ai
- Slack: #momentry-support

**紧急联系：**
- On-call: +886-xxx-xxx-xxx

**文档：**
- 详细发布说明: RELEASE_NOTES.md
- 用户手册: https://docs.momentry.ai

---

## 📝 部署记录

**部署日期：** _________  
**部署人员：** _________  
**部署环境：** _________  
**验证结果：** [ ] 通过 [ ] 失败  
**备注：** _________

---

**部署完成后，请将此文档归档并通知开发团队。**