feat: backup architecture docs, source code, and scripts
This commit is contained in:
Warren
@@ -0,0 +1,501 @@
|
||||
---
|
||||
document_type: "installation_guide"
|
||||
service: "REDIS"
|
||||
title: "Redis 安裝指南 (本地部署)"
|
||||
date: "2026-03-15"
|
||||
version: "V1.0"
|
||||
status: "active"
|
||||
owner: "Warren"
|
||||
created_by: "Warren"
|
||||
tags:
|
||||
- "redis"
|
||||
- "cache"
|
||||
- "key-value"
|
||||
- "macos"
|
||||
ai_query_hints:
|
||||
- "如何安裝 Redis 快取伺服器？"
|
||||
- "Redis 連線資訊為何？"
|
||||
- "如何配置 Redis 持久化？"
|
||||
---
|
||||
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 安裝 Redis
|
||||
brew install redis
|
||||
```
|
||||
|
||||
**驗證**:
|
||||
```bash
|
||||
redis-server --version
|
||||
# Redis server v8.4.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: 建立目錄結構
|
||||
|
||||
```bash
|
||||
# 建立數據目錄
|
||||
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 開機自動啟動
|
||||
|
||||
```bash
|
||||
# 複製 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
|
||||
|
||||
```bash
|
||||
# 找到 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
|
||||
|
||||
```bash
|
||||
# 卸載 Redis
|
||||
brew uninstall redis
|
||||
|
||||
# 移除 plist
|
||||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.redis.plist
|
||||
sudo rm /Library/LaunchDaemons/com.momentry.redis.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: 刪除專屬檔案
|
||||
|
||||
```bash
|
||||
# 刪除數據目錄 (可選)
|
||||
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
|
||||
```
|
||||
|
||||
**注意: 不要刪除以下共用目錄**:
|
||||
```bash
|
||||
# 這些是共用的，不要刪除!
|
||||
# /Users/accusys/momentry/var
|
||||
# /Users/accusys/momentry/etc
|
||||
# /Users/accusys/momentry/log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: 卸載後檢查清單
|
||||
|
||||
```bash
|
||||
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` 中添加：
|
||||
|
||||
```yaml
|
||||
service:
|
||||
services:
|
||||
- name: "redis"
|
||||
type: "tcp"
|
||||
port: 6379
|
||||
host: "localhost"
|
||||
timeout: 5
|
||||
enabled: true
|
||||
```
|
||||
|
||||
### 添加健康檢查函數
|
||||
|
||||
在 `monitor/service/health_check.sh` 中添加：
|
||||
|
||||
```bash
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
# 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` 中:
|
||||
|
||||
```env
|
||||
REDIS_URL=redis://:accusys@localhost:6379
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 遠端訪問
|
||||
|
||||
- Redis 綁定到 `0.0.0.0` (所有網路介面)
|
||||
- 本地網路其他機器可透過 IP 訪問
|
||||
- 密碼認證: `accusys`
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
### Redis 無法啟動
|
||||
|
||||
```bash
|
||||
# 檢查日誌
|
||||
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 被佔用
|
||||
|
||||
```bash
|
||||
# 檢查哪個程序佔用 port 6379
|
||||
lsof -i :6379
|
||||
|
||||
# 終止佔用程序
|
||||
kill <PID>
|
||||
```
|
||||
|
||||
### 需要重新載入 plist
|
||||
|
||||
```bash
|
||||
# 卸載舊服務 (如果存在)
|
||||
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` | 數據備份 |
|
||||
|
||||
---
|
||||
|
||||
## 備份與恢復
|
||||
|
||||
### 備份
|
||||
|
||||
```bash
|
||||
# 觸發保存並備份
|
||||
redis-cli -a accusys SAVE
|
||||
cp /opt/homebrew/var/db/redis/dump.rdb /Users/accusys/momentry/var/redis_backup_latest.rdb
|
||||
```
|
||||
|
||||
### 恢復
|
||||
|
||||
```bash
|
||||
# 停止 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 依賴：
|
||||
|
||||
```toml
|
||||
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 狀態
|
||||
|
||||
```bash
|
||||
# 查看 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：使用默認用戶（現行）
|
||||
|
||||
```env
|
||||
REDIS_URL=redis://:accusys@localhost:6379
|
||||
```
|
||||
|
||||
**適用於**：單一應用、簡單部署
|
||||
|
||||
#### 方案 B：建立 ACL 配置文件
|
||||
|
||||
```bash
|
||||
# 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_v1.0/REFERENCE/PENDING_ISSUES.md` 問題 #5
|
||||
- 測試結果：2026-03-21 Redis 認證測試
|
||||
Reference in New Issue
Block a user