momentry_core/docs/INSTALL_MONGODB.md

MongoDB 安裝指南 (本地部署)

項目	內容
建立者	Warren
建立時間	2026-03-15
文件版本	V1.0

---

版本歷史

版本	日期	目的	操作人	工具/模型
V1.0	2026-03-15	創建文件	Warren	OpenCode / MiniMax M2.5

---

概述

本文檔說明如何在 macOS 上安裝 MongoDB Community Edition，配置為本地部署，支援遠端訪問。

---

當前狀態

項目	狀態
MongoDB (mongodb-community)	✅ 已安裝 v8.2.6
數據目錄	/opt/homebrew/var/mongodb
日誌目錄	/Users/accusys/momentry/log

---

安裝步驟

Step 1: 安裝 MongoDB Community

# 安裝 MongoDB Community
brew tap mongodb/brew
brew install mongodb-community

驗證:

mongod --version
# db version v8.x.x
mongosh --version
# 2.7.x
sudo launchctl list | grep mongo
# 確認 MongoDB 服務已載入

---

Step 2: 數據目錄 (已存在 - 共用)

數據目錄使用 homebrew 預設位置:

• 數據目錄: /opt/homebrew/var/mongodb
• 配置目錄: /opt/homebrew/etc/mongod.conf
• 日誌目錄: /Users/accusys/momentry/log

建立配置目錄和日誌文件:

# 建立配置目錄
mkdir -p /Users/accusys/momentry/etc/mongodb

# 建立日誌文件
touch /Users/accusys/momentry/log/mongodb.log
touch /Users/accusys/momentry/log/mongodb.error.log

# 確認權限:
ls -la /Users/accusys/momentry/
chown -R accusys:staff /Users/accusys/momentry

---

Step 3: 使用 LaunchAgent 啟動 (開機自動)

# 複製 plist 到 LaunchDaemons 目錄 (開機自動需要 root 權限)
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.mongodb.plist \
    /Library/LaunchDaemons/

# 載入並啟動
sudo launchctl load /Library/LaunchDaemons/com.momentry.mongodb.plist

# 驗證
launchctl list | grep mongodb
pgrep -a mongod

---

Step 4: 建立資料庫用戶

mongosh --eval '
use admin
db.createUser({
  user: "accusys",
  pwd: "Test3200Test3200",
  roles: [
    { role: "readWrite", db: "momentry" },
    { role: "dbAdmin", db: "momentry" }
  ]
})

---

### Step 4: 驗證安裝

```bash
# 檢查進程
pgrep -a mongod

# 檢查端口
lsof -i :27017

# 測試連線
mongosh --eval "db.adminCommand('ping')"

# 檢查 LaunchAgent
launchctl list | grep mongodb

---

監控配置

添加到監控配置

在 monitor/config/monitor_config.yaml 中添加：

database:
  mongodb:
    enabled: true
    host: "localhost"
    port: 27017
    user: "accusys"
    database: "momentry"

---

卸載步驟

重要: 路徑說明

路徑	類型	說明
/Users/accusys/momentry/	共用	不要刪除 - 多個系統共用
/Users/accusys/momentry/var	共用	不要刪除 - 數據目錄
/Users/accusys/momentry/etc/mongodb/	配置	不要刪除 - MongoDB 配置
/Users/accusys/momentry/log	共用	不要刪除 - 日誌目錄
~/.mongosh_history	專屬	可選刪除 - Mongo Shell 歷史

Step 1: 停止 MongoDB

# 找到 MongoDB 進程
ps aux | grep mongod | grep -v grep

# 停止 MongoDB
pkill mongod
# 或
kill <PID>

# 確認停止
ps aux | grep mongod | grep -v grep || echo "MongoDB 已停止"

---

Step 2: 卸載 MongoDB

# 完全卸載 (保留數據)
brew uninstall mongodb-community

---

Step 3: 刪除專屬檔案

# 刪除 MongoDB 專屬配置 (如果有)
rm -f ~/.mongosh_history

# 刪除臨時文件 (可選)
rm -rf /tmp/mongodb-*

注意: 不要刪除以下共用目錄:

# 這些是共用的，不要刪除!
# /Users/accusys/momentry/var
# /Users/accusys/momentry/log

---

Step 4: 卸載後檢查清單

echo "=== MongoDB 卸載後檢查 ==="

# 1. 檢查 MongoDB 進程
echo "1. MongoDB 進程:"
ps aux | grep mongod | grep -v grep && echo "   ✗ 仍在運行" || echo "   ✓ 已停止"

# 2. 檢查 Port 27017
echo "2. Port 27017:"
lsof -i :27017 > /dev/null 2>&1 && echo "   ✗ 仍被佔用" || echo "   ✓ 已釋放"

# 3. 檢查 mongod 命令
echo "3. mongod 命令:"
which mongod > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 4. 檢查 launchctl
echo "4. launchctl 服務:"
sudo launchctl list | grep mongo > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 5. 檢查 Homebrew
echo "5. Homebrew 移除:"
brew list mongo > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 6. 檢查數據目錄 (應該存在)
echo "6. 數據目錄:"
[ -d "/Users/accusys/momentry/var" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"

# 7. 檢查日誌目錄 (應該存在)
echo "7. 日誌目錄:"
[ -d "/Users/accusys/momentry/log" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"

預期結果:

=== MongoDB 卸載後檢查 ===
1. MongoDB 進程:
   ✓ 已停止
2. Port 27017:
   ✓ 已釋放
3. mongod 命令:
   ✓ 已移除
4. launchctl 服務:
   ✓ 已移除
5. Homebrew 移除:
   ✓ 已移除
6. 數據目錄:
   ✓ 保留
7. 日誌目錄:
   ✓ 保留

---

手動檢查命令

# 1. 檢查 Process 是否運行
ps aux | grep mongo | grep -v grep

# 2. 檢查 Port 27017
lsof -i :27017

# 3. 測試連線 (無認證)
mongosh --eval "db.adminCommand('ping')"

# 4. 測試連線 (有認證)
mongosh "mongodb://accusys:Test3200Test3200@localhost:27017/admin" --eval "db.adminCommand('ping')"

# 5. 查看所有資料庫
mongosh "mongodb://accusys:Test3200Test3200@localhost:27017/admin" --quiet --eval "db.adminCommand({listDatabases:1}).databases"

# 6. 查看用戶
mongosh "mongodb://accusys:Test3200Test3200@localhost:27017/admin" --quiet --eval "db.getUser('accusys')"

# 7. 查看日誌
tail -20 /Users/accusys/momentry/log/mongodb.log
tail -20 /Users/accusys/momentry/log/mongodb.error.log

---

管理命令

啟動/停止

# 使用 LaunchAgent (開機自動 - LaunchDaemons 目錄)
sudo launchctl load /Library/LaunchDaemons/com.momentry.mongodb.plist    # 啟動
sudo launchctl unload /Library/LaunchDaemons/com.momentry.mongodb.plist  # 停止

# 手動啟動 (僅除錯用)
nohup /opt/homebrew/bin/mongod \
    --dbpath /Users/accusys/momentry/var \
    --logpath /Users/accusys/momentry/log/mongodb.log \
    --port 27017 \
    --bind_ip 0.0.0.0 \
    > /Users/accusys/momentry/log/mongodb.log 2>&1 &

# 強制停止
pkill mongod

---

連線字串

# 無認證 (本地)
mongodb://localhost:27017

# 有認證 (admin 資料庫)
mongodb://accusys:Test3200Test3200@localhost:27017/admin

# 有認證 (momentry 資料庫)
mongodb://accusys:Test3200Test3200@localhost:27017/momentry?authSource=admin

---

環境變數

在 .env 中:

MONGODB_URL=mongodb://accusys:Test3200Test3200@localhost:27017/admin
MONGODB_DATABASE=momentry

---

遠端訪問

• MongoDB 綁定到 0.0.0.0 (所有網路介面)
• 本地網路其他機器可透過 IP 訪問
• 建議設定防火牆規則限制訪問 IP

---

故障排除

MongoDB 無法啟動

# 檢查日誌
tail -f /Users/accusys/momentry/log/mongodb.log

# 檢查目錄權限
ls -la /Users/accusys/momentry/

# 重新設定權限
chown -R $(whoami):staff /Users/accusys/momentry

Port 被佔用

# 檢查哪個程序佔用 port 27017
lsof -i :27017

# 終止佔用程序
kill <PID>

---

檔案位置

類型	路徑	說明
數據目錄	/Users/accusys/momentry/var	共用 - 不要刪除
日誌目錄	/Users/accusys/momentry/log	共用 - 不要刪除
mongod	/opt/homebrew/bin/mongod	安裝後存在
Homebrew	/opt/homebrew/Cellar/mongodb-community/	卸載時刪除
Homebrew	/opt/homebrew/Cellar/mongodb-database-tools/	卸載時刪除
Homebrew	/opt/homebrew/Cellar/mongosh/	卸載時刪除
配置檔	/opt/homebrew/etc/mongod.conf	卸載時刪除

---

版本資訊

• 用戶: accusys
• 密碼: Test3200Test3200
• 數據目錄: /Users/accusys/momentry/var (共用 - 不要刪除!)
• 日誌目錄: /Users/accusys/momentry/log (共用 - 不要刪除!)