momentry_core/docs/INSTALL_REDIS.md

Redis 安裝指南 (本地部署)

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

---

版本歷史

版本	日期	目的	操作人	工具/模型
V1.0	2026-03-15	創建文件	Warren	OpenCode / MiniMax M2.5
V1.1	2026-03-21	更新 rust redis crate 版本至 0.32.7	OpenCode	-
V1.2	2026-03-21	添加 Redis 用戶配置說明	OpenCode	-

---

概述

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

---

當前狀態

項目	狀態
Redis	✅ 已安裝 v8.4.0
數據目錄	/opt/homebrew/var/db/redis/
日誌目錄	/Users/accusys/momentry/log/
Plist	/Library/LaunchDaemons/com.momentry.redis.plist

---

安裝步驟

Step 1: 安裝 Redis (使用 brew)

# 安裝 Redis
brew install redis

驗證:

redis-server --version
# Redis server v8.4.0

---

Step 2: 建立目錄結構

# 建立數據目錄
mkdir -p /Users/accusys/momentry/var/redis

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

# 建立日誌目錄
mkdir -p /Users/accusys/momentry/log

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

# 設定權限
chown -R accusys:staff /Users/accusys/momentry/var/redis
chown -R accusys:staff /Users/accusys/momentry/etc/redis
chown -R accusys:staff /Users/accusys/momentry/log

---

Step 3: 使用 plist 開機自動啟動

# 複製 plist 到 LaunchDaemons 目錄
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.redis.plist /Library/LaunchDaemons/

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

---

卸載步驟

重要: 路徑說明

路徑	類型	說明
/Users/accusys/momentry/var/redis/	數據	不要刪除 - 數據目錄
/Users/accusys/momentry/etc/redis/	配置	不要刪除 - 配置目錄
/Users/accusys/momentry/log/	日誌	不要刪除 - 日誌目錄
/opt/homebrew/opt/redis/	安裝	刪除 - Redis 安裝目錄

Step 1: 停止 Redis

# 找到 Redis 進程
ps aux | grep redis | grep -v grep

# 停止 Redis
redis-cli -a accusys SHUTDOWN
# 或
pkill redis-server

# 確認停止
ps aux | grep redis | grep -v grep || echo "Redis 已停止"

---

Step 2: 卸載 Redis

# 卸載 Redis
brew uninstall redis

# 移除 plist
sudo launchctl unload /Library/LaunchDaemons/com.momentry.redis.plist
sudo rm /Library/LaunchDaemons/com.momentry.redis.plist

---

Step 3: 刪除專屬檔案

# 刪除數據目錄 (可選)
rm -rf /Users/accusys/momentry/var/redis

# 刪除配置目錄 (可選)
rm -rf /Users/accusys/momentry/etc/redis

# 刪除日誌 (可選)
rm -f /Users/accusys/momentry/log/redis.log
rm -f /Users/accusys/momentry/log/redis.error.log

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

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

---

Step 4: 卸載後檢查清單

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

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

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

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

# 4. brew 安裝
echo "4. brew 安裝:"
brew list redis > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

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

# 6. 數據目錄 (可選刪除)
echo "6. 數據目錄:"
[ -d "/Users/accusys/momentry/var/redis" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"

# 7. 日誌目錄 (可選刪除)
echo "7. 日誌目錄:"
[ -d "/Users/accusys/momentry/log" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"

預期結果:

=== Redis 卸載後檢查 ===
1. Redis 進程:
   ✓ 已停止
2. Port 6379:
   ✓ 已釋放
3. redis-server 命令:
   ✓ 已移除
4. brew 安裝:
   ✓ 已移除
5. launchctl 服務:
   ✓ 已移除
6. 數據目錄:
   ✓ 保留 (或 ✗ 已刪除)
7. 日誌目錄:
   ✓ 保留 (或 ✗ 已刪除)

---

監控配置

添加到監控配置

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

service:
  services:
    - name: "redis"
      type: "tcp"
      port: 6379
      host: "localhost"
      timeout: 5
      enabled: true

添加健康檢查函數

在 monitor/service/health_check.sh 中添加：

check_redis() {
    local start=$(date +%s%N)
    if redis-cli -a accusys ping > /dev/null 2>&1; then
        local end=$(date +%s%N)
        local ms=$(( (end - start) / 1000000 ))
        echo -e "${GREEN}✓${NC} Redis (6379) - ${ms}ms"
        record_service "redis" "up" "$ms" ""
        return 0
    else
        echo -e "${RED}✗${NC} Redis (6379) - Down"
        record_service "redis" "down" "0" "Connection failed"
        return 1
    fi
}

# 1. 檢查進程
ps aux | grep redis | grep -v grep

# 2. 檢查 Port
lsof -i :6379

# 3. 測試連線 (無認證)
redis-cli -a accusys PING

# 4. 測試連線 (有認證)
redis-cli -a accusys -e "PING"

# 5. 查看所有 keys
redis-cli -a accusys KEYS '*'

# 6. 查看 info
redis-cli -a accusys INFO

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

---

連線資訊

項目	值
Host	localhost
Port	6379
Password	accusys

---

環境變數

在 .env 中:

REDIS_URL=redis://:accusys@localhost:6379

---

遠端訪問

• Redis 綁定到 0.0.0.0 (所有網路介面)
• 本地網路其他機器可透過 IP 訪問
• 密碼認證: accusys

---

故障排除

Redis 無法啟動

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

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

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

Port 被佔用

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

# 終止佔用程序
kill <PID>

需要重新載入 plist

# 卸載舊服務 (如果存在)
sudo launchctl unload /Library/LaunchDaemons/com.momentry.redis.plist 2>/dev/null

# 載入新服務
sudo launchctl load /Library/LaunchDaemons/com.momentry.redis.plist

---

檔案位置

類型	路徑	說明
安裝	/opt/homebrew/opt/redis/	Redis 安裝目錄
執行檔	/opt/homebrew/opt/redis/bin/redis-server	Redis 執行檔
數據目錄	/Users/accusys/momentry/var/redis/	數據儲存
配置目錄	/Users/accusys/momentry/etc/redis/	配置儲存
日誌	/Users/accusys/momentry/log/redis.log	執行日誌
錯誤日誌	/Users/accusys/momentry/log/redis.error.log	錯誤日誌
plist	/Library/LaunchDaemons/com.momentry.redis.plist	開機啟動
備份	/Users/accusys/momentry/var/redis_backup_latest.rdb	數據備份

---

備份與恢復

備份

# 觸發保存並備份
redis-cli -a accusys SAVE
cp /opt/homebrew/var/db/redis/dump.rdb /Users/accusys/momentry/var/redis_backup_latest.rdb

恢復

# 停止 Redis
redis-cli -a accusys SHUTDOWN

# 複製備份文件覆蓋
cp /Users/accusys/momentry/var/redis_backup_latest.rdb /Users/accusys/momentry/var/redis/dump.rdb

# 啟動 Redis
sudo launchctl load /Library/LaunchDaemons/com.momentry.redis.plist

---

版本資訊

項目	值
Redis Server	8.4.0
Rust redis crate	0.32.7
Port	6379
Password	accusys
數據目錄	/Users/accusys/momentry/var/redis/
日誌目錄	/Users/accusys/momentry/log/

---

Rust redis crate 版本

Cargo.toml 中的 redis 依賴：

redis = { version = "0.32", features = ["tokio-comp"] }

版本歷史

版本	日期	變更
0.25.4	-	原始版本（有未來相容性警告）
0.32.7	2026-03-21	升級 - 修復 Rust 2024 never type 回退問題

升級說明

升級到 0.32.x 的優點：

• 修復 Rust 2024 edition 未來相容性問題
• API 完全向後相容
• 無需修改現有程式碼

---

Redis 用戶配置說明

當前狀態

項目	狀態
用戶類型	僅有 default 用戶
自訂用戶	❌ 未配置
ACL 持久化	❌ 未配置

Redis ACL 狀態

# 查看 ACL
redis-cli -a accusys ACL LIST

# 輸出:
# user default on sanitize-payload #hash ~* &* +@all

連線格式說明

格式	狀態	說明
redis://:accusys@localhost:6379	✅ 正確	使用默認用戶 + 密碼
redis://accusys:accusys@localhost:6379	❌ 失敗	用戶 accusys 不存在

為何用戶名不可用

1. Redis 啟動方式：使用 --requirepass 參數，僅設定默認用戶密碼
2. 無 ACL 配置文件：未指定 --aclfile 參數
3. 動態建立用戶：手動建立的用戶不會持久化（重啟後消失）

解決方案

方案 A：使用默認用戶（現行）

REDIS_URL=redis://:accusys@localhost:6379

適用於：單一應用、簡單部署

方案 B：建立 ACL 配置文件

# 1. 建立 ACL 文件
cat > /Users/accusys/momentry/etc/redis/users.acl << 'EOF'
user default on sanitize-payload ~* &* +@all >accusys
user accusys on sanitize-payload ~* &* +@all >accusys
EOF

# 2. 修改 plist (添加 --aclfile 參數)
# --aclfile /Users/accusys/momentry/etc/redis/users.acl

# 3. 重啟 Redis
sudo launchctl unload /Library/LaunchDaemons/com.momentry.redis.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.redis.plist

適用於：多應用、需要用戶隔離

參考

• 問題追蹤：docs/PENDING_ISSUES.md 問題 #5
• 測試結果：2026-03-21 Redis 認證測試