momentry_studio/release/ADMIN_DEPLOYMENT_GUIDE.md

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

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

---

📦 发布包信息

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

154ef0e02a6199278ea6bc6a5073d11c631527f2825ba78ceeafcb5f486cf969

---

🔐 验证发布包

# 下载发布包后验证校验和
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: 准备发布包

# 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（推荐）

# 打开 DMG 文件
open "Momentry Studio_0.1.0_aarch64.dmg"

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

选项 B: 使用 .app

# 直接复制到 Applications
cp -r "Momentry Studio.app" /Applications/

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

选项 C: 使用安装脚本

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

步骤 3: 部署 Backend Services

安装 binaries：

# 复制到系统 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: 配置服务

创建配置文件：

# 创建配置目录
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

设置环境变量：

# 在 ~/.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: 启动服务

手动启动：

# 1. 启动 Core API
momentry-core server --config /opt/momentry/config/momentry.toml

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

创建 launchd 服务（可选）：

# 创建 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

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

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

2. 验证 Proxy

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

# 预期响应：
# ok

3. 验证 Studio App

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

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

4. 功能测试

在 Studio 中测试以下功能：

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

---

🔄 更新流程

从旧版本升级

# 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 后无反应

解决方案：

# 移除隔离属性
xattr -d com.apple.quarantine "/Applications/Momentry Studio.app"

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

问题 2: 无法连接到 Core API

症状： Studio 显示连接错误

解决方案：

# 检查 Core API 是否运行
ps aux | grep momentry-core

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

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

问题 3: MarkBase Engine 显示 offline

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

解决方案：

# 检查 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/

性能监控

# 检查资源使用
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

---

📝 部署记录

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

---

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