momentry_core/docs/PENDING_ISSUES.md

待解決問題追蹤

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

---

版本歷史

版本	日期	目的	操作人	工具/模型
V1.0	2026-03-17	創建文件	Warren	OpenCode / MiniMax M2.5
V1.1	2026-03-21	更新問題狀態	OpenCode	-
V1.2	2026-03-21	添加備份機制優化待辦	OpenCode	-
V1.3	2026-03-21	完成清理硬編碼密碼	OpenCode	-
V1.4	2026-03-21	完成 OpenCode n8n MCP 整合	OpenCode	-
V1.5	2026-03-21	完成 API Key Management 核心模組	OpenCode	-
V1.6	2026-03-23	添加 Momentry Core API launchd 待辦	OpenCode	-
V1.7	2026-03-23	完成 Momentry Core API launchd 設定	OpenCode	-
V1.8	2026-03-24	完成服務統一遷移，所有服務使用自定義 plist	OpenCode	big-pickle
V1.9	2026-03-24	建立統一會員系統實作計畫	OpenCode	big-pickle
V2.0	2026-03-24	建立 Job Worker 實作計畫	OpenCode	big-pickle

---

問題 #1: sqlx async INSERT 不會實際寫入數據庫

問題描述

使用 sqlx async 執行 INSERT 時，報告成功（rows_affected=1），但數據沒有實際寫入數據庫。

嘗試過的解決方案

#	嘗試方法	結果
1	使用 execute()	報告成功但未寫入
2	使用 fetch()	同樣問題
3	使用交易	同樣問題
4	使用連接池 acquire()	同樣問題
5	每個操作創建新連接池	同樣問題
6	使用 std::process::Command 同步調用 psql	同樣問題
7	使用 tokio::task::spawn_blocking	同樣問題

觀察到的現象

• 直接用 psql 命令行可以成功寫入
• 用另一個 PostgreSQL client 可以成功寫入
• sqlx 查詢 COUNT(*) 可以正確讀取數據
• 但 sqlx INSERT 報告成功卻不寫入

懷疑方向

• sqlx 連接池與 PostgreSQL 的某種交互問題
• Rust async runtime 與 PostgreSQL client 的問題
• postgresql.conf 配置問題

臨時解決方案

• Qdrant 向量存儲正常工作（不受影響）
• 存儲狀態追蹤功能正常運作

負責人

建立日期

2026-03-17

備註

影響 store_vector 函數，PVector 存儲無法正常工作，但 QVector 正常運作

2026-03-21 調查結果

測試結果

• 直接 psql INSERT: ✅ 成功
• 資料寫入驗證: ✅ 成功

發現的問題

store_vector 函數 (postgres_db.rs:819-860) 存在以下問題：

// 問題 1: 錯誤被靜默忽略
match join_result {
    Ok((cid, Ok(output))) => {
        if !output.status.success() {
            let err = String::from_utf8_lossy(&output.stderr);
            tracing::error!("psql error for {}: {}", cid, err);
            // 沒有返回錯誤！只是記錄日誌
        }
    }
    // ...
}
Ok(())  // 即使失敗也返回 Ok

建議修復

1. 讓 store_vector 返回實際結果
2. 在失敗時返回 Err
3. 添加單元測試驗證

下一步

• 修復 store_vector 錯誤處理
• 添加單元測試
• 重現並確認問題根因

2026-03-21 修復完成

已修復 store_vector 函數的錯誤處理：

// 修復前：錯誤被靜默忽略
match join_result {
    Ok((cid, Ok(output))) => {
        if !output.status.success() {
            tracing::error!("...");  // 只記錄，不返回錯誤
        }
    }
}
Ok(())  // 即使失敗也返回 Ok

// 修復後：正確傳播錯誤
let (cid, output) = result;
let output = output.map_err(|e| anyhow::anyhow!(...))?;
if !output.status.success() {
    anyhow::bail!("psql INSERT failed...");
}

---

問題 #2: TUI 與 stdout 輸出混合

問題描述

Python processors 的 progress 輸出蓋過 TUI，導致使用者無法清楚看到處理進度。

解決方案

使用 TUI 渲染到 stderr → 使用 Redis Pub/Sub 作為消息總線

當前狀態

子項目	狀態
RedisPublisher Python 端	✅ 已實作
Rust Redis 客戶端	✅ 已實作 (redis_client.rs)
Rust 訂閱更新 TUI	✅ 已實作 (main.rs)
中斷後繼續/重做	🔜 待實作

負責人

建立日期

2026-03-17

更新日期

2026-03-21

參考文檔

• docs/MOMENTRY_CORE_REDIS_KEYS.md
• scripts/redis_publisher.py
• src/core/db/redis_client.rs

---

問題 #3: Redis Message Bus 尚未實作

問題描述

根據設計規範，需要使用 Redis 作為監控和狀態管理系統。

當前狀態

實作項目	狀態	說明
Redis 客戶端 (Hash)	✅	redis_client.rs
Redis 客戶端 (Pub/Sub)	✅	redis_client.rs::subscribe_progress()
Python RedisPublisher	✅	scripts/redis_publisher.py
Rust 訂閱頻道	✅	main.rs 中的 redis 訂閱邏輯
監控腳本	✅	monitor/service/health_check.sh

負責人

建立日期

2026-03-17

更新日期

2026-03-21

優先級

高 → 中 - 核心功能已完成

參考文檔

• docs/MOMENTRY_CORE_REDIS_KEYS.md
• docs/MOMENTRY_CORE_MONITORING.md

---

架構優化待評估

詳細內容請參考 ARCHITECTURE_EVALUATION.md

項目	複雜度	優先級
PostgreSQL → Redis 故障轉移	中	待評估
連接池監控	低	待評估
Processor 重試機制	中	待評估
PyO3 整合	高	低
HTTP 健康端點	低	✅ 已完成
Commit Message Lint	低	✅ 已完成

---

備份機制優化 (2026-03-21)

問題分析

問題	嚴重性	說明
溫冷分層未啟用	中	weekly/monthly/archive 目錄為空
清理策略未執行	高	每日備份保留過多，空間浪費
無異地備份	高	無遠程備份（雲端/另一設備）
備份驗證未自動化	中	只檢查文件存在，沒驗證可恢復性
Gitea 大文件	中	每次備份 1GB，頻率過高
密碼硬編碼	高	腳本中有多處明文密碼

待辦事項

#	任務	優先級	狀態
1	啟用溫冷分層 (backup_monitor.sh tier)	高	待辦
2	啟用清理策略 (backup_monitor.sh cleanup)	高	待辦
3	添加備份驗證腳本	高	待辦
4	優化 Gitea 備份頻率 (改為週備份)	中	待辦
5	創建外部備份腳本 (rsync/雲端)	高	待辦
6	清理腳本中的硬編碼密碼	高	✅ 已完成

推薦備份策略

層級	保留時間	頻率	目標
Hot	7 天	每日	本地 SSD
Warm	30 天	每週	本地 HDD
Cold	90 天	每月	外部存儲
Archive	1 年	每季	離線/雲端

建議的 Crontab

# 每日備份 (排除 Gitea)
0 3 * * 1-6 /Users/accusys/momentry/scripts/backup_all.sh all_except_gitea

# 每週完整備份 (含 Gitea)
0 3 * * 0 /Users/accusys/momentry/scripts/backup_all.sh all

# 每週溫冷分層
0 4 * * 0 /Users/accusys/momentry_core_0.1/monitor/storage/backup_monitor.sh tier

# 每週清理
0 5 * * 0 /Users/accusys/momentry_core_0.1/monitor/storage/backup_monitor.sh cleanup

# 每月驗證
0 6 1 * * /Users/accusys/momentry/scripts/verify_backup.sh

負責人

參考文件

• /Users/accusys/momentry/scripts/backup_all.sh
• /Users/accusys/momentry_core_0.1/monitor/storage/backup_monitor.sh
• /Users/accusys/momentry/backup/

---

OpenCode n8n MCP 整合 (2026-03-21)

完成狀態

項目	狀態	說明
n8n REST API 啟用	✅	N8N_PUBLIC_API_ENABLED=true
API Key 生成	✅	Settings → API
MCP Server 安裝	✅	@nextoolsolutions/mcp-n8n
OpenCode 設定	✅	~/.config/opencode/opencode.json
43 工具可用	✅	workflows, executions, datatables, tags 等

設定檔案

~/.config/opencode/opencode.json:

{
  "mcp": {
    "gitea": {
      "type": "local",
      "enabled": true,
      "command": [
        "/opt/homebrew/bin/gitea-mcp-server",
        "-token", "<GITEA_TOKEN>",
        "-host", "http://localhost:3000"
      ]
    },
    "n8n": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mcp-n8n"],
      "environment": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "<N8N_API_KEY>"
      }
    }
  }
}

重要提醒

1. API Key 安全: 避免提交到 Git
2. n8n 需通過反向代理: localhost:5678 無法直接訪問 API，需通過 Caddy
3. 重啟生效: 修改 opencode.json 後需重啟 OpenCode

參考文件

• docs/OPENCODE_GUIDE.md - MCP 設定章節
• docs/INSTALL_N8N.md - n8n 安裝指南

---

n8n API 備份腳本 (2026-03-21)

腳本位置

腳本	說明	依賴
monitor/workflow/backup_n8n_api.py	REST API 備份	requests
monitor/workflow/backup_n8n_mcp.py	MCP 備份（開發中）	mcp SDK

使用方式

# 備份所有 workflows
N8N_API_KEY="..." python3.11 backup_n8n_api.py

# 只顯示變更（不備份）
N8N_API_KEY="..." python3.11 backup_n8n_api.py --diff

# 差異備份（只備份變更的 workflows）
N8N_API_KEY="..." python3.11 backup_n8n_api.py --incremental

# 列出可用備份
python3.11 backup_n8n_api.py --list

# 驗證最新備份
python3.11 backup_n8n_api.py --verify

# 顯示備份統計
python3.11 backup_n8n_api.py --stats

# 只備份啟用的 workflows
N8N_API_KEY="..." python3.11 backup_n8n_api.py --active-only

# 備份失敗的執行記錄
N8N_API_KEY="..." python3.11 backup_n8n_api.py --failed-only

功能

• REST API 備份
• 變更偵測
• SHA256 校驗
• 備份版本化
• 差異備份（--incremental）
• 備份驗證（--verify）
• 備份統計（--stats）
• 失敗執行記錄備份（--failed-only）
• 選擇性備份（按 Tags）

備份位置

/Users/accusys/momentry/backup/n8n_workflows/api/
├── 20260321_122059/
│   ├── workflows.json         # 21 workflows
│   ├── workflows.json.sha256  # SHA256 校驗
│   ├── tags.json             # Tags（若有）
│   └── manifest.json         # 元數據
└── ...

Crontab 建議

# 每日備份（下午 3 點）
0 15 * * * N8N_API_KEY="..." /opt/homebrew/bin/python3.11 /Users/accusys/momentry_core_0.1/monitor/workflow/backup_n8n_api.py >> /Users/accusys/momentry/log/monitor/workflow_backup_api.log 2>&1

---

API Key Management System (2026-03-21)

設計目標

為 Momentry Core 實現完整的 API Key 管理系統，包括：

• API Key 生成（安全隨機）
• Key 哈希（SHA256）
• 異常檢測
• 強制輪換機制
• 審計日誌

模組架構

src/core/api_key/
├── mod.rs         # 模組導出
├── models.rs      # 數據模型和類型
├── service.rs    # 核心服務邏輯
├── anomaly.rs    # 異常檢測
└── rotation.rs   # 輪換管理

Key 類型

類型	前綴	默認 TTL	寬限期
System	msys_	365 天	72 小時
User	muser_	90 天	24 小時
Service	msvc_	180 天	48 小時
Integration	mint_	30 天	24 小時
Emergency	memg_	1 天	0 小時

Key 格式

{prefix}{uuid}_{timestamp}_{random}
例如: muser_a1b2c3d4e5f6_1710998400_abc12345

異常檢測閾值

指標	閾值
每分鐘請求數	1000
每小時請求數	10000
錯誤率	50%
每小時唯一 IP 數	5
鎖定閾值	3 次觸發

實現狀態

組件	狀態	說明
數據模型	✅ 完成	models.rs
Key 生成/哈希	✅ 完成	service.rs
異常檢測	✅ 完成	anomaly.rs
輪換機制	✅ 完成	rotation.rs
CLI 命令	✅ 完成	main.rs
數據庫集成	✅ 完成	postgres_db.rs
Redis 告警	✅ 完成	redis_client.rs
數據庫遷移	✅ 完成	migrations/001_api_key_management.sql
單元測試	✅ 完成	55 個測試通過

CLI 命令

# 創建 API Key
momentry api-key create <name> --key-type service --ttl 90

# 列出所有 Keys
momentry api-key list

# 驗證 Key
momentry api-key validate --key <key>

# 撤銷 Key
momentry api-key revoke --key <key>

# 請求輪換
momentry api-key rotate --key <key>

# 顯示統計
momentry api-key stats

參考文件

• src/core/api_key/ - API Key 模組
• docs/API_KEY_MANAGEMENT.md - 設計文檔
• migrations/001_api_key_management.sql - 數據庫遷移

---

問題 #5: Redis 用戶名問題 (2026-03-21)

問題描述

Redis 僅有 default 用戶，無 accusys 用戶。.env 檔案使用 redis://accusys:accusys@localhost:6379 格式會導致認證失敗。

測試結果

URL 格式	結果
redis://accusys:accusys@localhost:6379	❌ AUTH failed
redis://:accusys@localhost:6379	✅ PONG

Redis ACL 狀態

user default on sanitize-payload #1bd51c... ~* &* +@all
requirepass: accusys

根本原因

1. Redis 啟動時僅設定 --requirepass accusys
2. 未建立自訂用戶 accusys
3. ACL 變更不會持久化（無 config file）

已執行修復

項目	修改
.env	redis://accusys:accusys@localhost:6379 → redis://:accusys@localhost:6379

待解決問題

1. ACL 持久化：Redis 啟動後手動建立的用戶不會保留（重啟後消失）
2. 需配置 ACL 文件：建議建立 users.acl 並在 plist 中指定

建議解決方案

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

# .env
REDIS_URL=redis://:accusys@localhost:6379

優點：簡單，無需修改 Redis 配置 缺點：所有應用共享默認用戶

方案 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

優點：支持多用戶，ACL 持久化 缺點：需修改 plist 並重啟

影響範圍

• src/core/config.rs - REDIS_URL 讀取
• src/core/db/redis_client.rs - Redis 連線
• momentry api-key 命令 - 異常告警

狀態

• 已確認問題存在
• 已修改 .env 使用默認用戶
• 待決定是否實施 ACL 方案

---

問題 #6: Momentry Core API 未開機自動啟動 (2026-03-23)

問題描述

Momentry Core API 服務 (momentry server --port 3002) 未設定 launchd，導致：

1. 系統重啟後 API 服務不會自動啟動
2. api.momentry.ddns.net 返回 502 Bad Gateway
3. n8n workflow 呼叫 API 時失敗

發現過程

1. n8n workflow 呼叫 https://api.momentry.ddns.net/api/v1/n8n/search 返回 502
2. 檢查發現 port 3002 無服務運行
3. Caddy 配置正向確，但後端服務未啟動
4. 手動啟動服務後 API 正常運作

配置需求

項目	值
服務名稱	com.momentry.api
二進位檔	/Users/accusys/momentry_core_0.1/target/release/momentry
命令	server --port 3002
Port	3002
環境變數	DATABASE_URL, REDIS_URL 等

待辦事項

• 建立 docs/INSTALL_MOMENTRY_API.md 安裝文件
• 建立 /Library/LaunchDaemons/com.momentry.api.plist
• 設定環境變數 (DATABASE_URL, REDIS_URL 等)
• 測試 launchctl load/unload
• 驗證開機自動啟動 (launchd 載入成功)

完成日期

2026-03-23

參考文件

• /Library/LaunchDaemons/com.momentry.n8n.main.plist - n8n plist 範例
• docs/INSTALL_N8N.md - plist 配置說明

---

服務統一遷移 (2026-03-24)

問題描述

Reboot 後發現 n8n workflow 數量從 42 變成 41，確認是 PostgreSQL 資料庫問題。經過調查發現：

1. 兩組不同的 PostgreSQL 資料目錄：

   • Homebrew plist: /opt/homebrew/var/postgresql@18 (有最新資料)
   • Custom plist: /Users/accusys/momentry/var/postgresql (可能是舊資料)

2. Reboot 時 custom plist 搶先啟動，使用了錯誤的資料目錄

解決方案

1. 統一使用 custom plist：

   • 刪除 homebrew plist (~/Library/LaunchAgents/homebrew.mxcl.postgresql@18.plist)
   • Custom plist 使用 /Users/accusys/momentry/var/postgresql 作為資料目錄
   • 將所有 14 個服務的 plist 註冊到 launchd

2. 所有已遷移的服務：

服務	Plist	資料目錄
PostgreSQL	✅	/Users/accusys/momentry/var/postgresql
MariaDB	✅	/Users/accusys/momentry/var/mariadb
MongoDB	✅	/opt/homebrew/var/mongodb
Redis	✅	-
Ollama	✅	-
Qdrant	✅	-
n8n Main	✅	-
n8n Worker	✅	-
Caddy	✅	-
SFTPGo	✅	-
Gitea	✅	-
Gitea MCP	✅	-
PHP	✅	-
Momentry API	✅	-
RustDesk HBBR	✅	-
RustDesk HBBS	✅	-

還發現的 Homebrew 服務 (未遷移)

服務	建議
homebrew.mxcl.grafana	⚠️ 考慮遷移
homebrew.mxcl.prometheus	⚠️ 考慮遷移
homebrew.mxcl.openwebui	⚠️ 考慮遷移
homebrew.mxcl.kafka	⚠️ 考慮遷移
homebrew.mxcl.seaweedfs	⚠️ 考慮遷移
homebrew.mxcl.netdata	⚠️ 考慮遷移
homebrew.mxcl.ddclient	⚠️ 動態 DNS
homebrew.mxcl.shadowsocks-rust	⚠️ VPN

預防措施

1. 確保統一資料目錄：所有服務只使用一個資料目錄
2. Reboot 測試：遷移完成後需進行 Reboot 測試
3. 文件同步：plist 檔案同步到 repo

完成日期

2026-03-24

參考文件

• docs/SERVICES.md - 服務管理文檔
• docs/SERVICE_ADDITION_GUIDE.md - 服務添加規範
• momentry_runtime/plist/ - plist 檔案存放位置

---

Job Worker 實作 (2026-03-24)

目標

實作輪詢式 Job Worker，實現檔案註冊後自動觸發處理：

1. 輪詢機制：Worker 定期輪詢 jobs 佇列
2. 並行處理：最多 2 個 processor 同時執行
3. 失敗容忍：任一模組獨立，失敗可接續

設計決策

項目	決策	理由
觸發方式	輪詢（Job Worker）	暫無可靠 API 觸發
並行處理	最多 2 個	可根據 CPU/GPU 調整
失敗處理	獨立模組，部分完成可接續	任何模組失敗都產出狀態
Worker 啟動	獨立進程	隔離、易管理
並行上限	環境變數 + 預設值	靈活調整
狀態同步	PostgreSQL + Redis	可靠 + 即時

環境變數

變數	預設值	說明
MOMENTRY_MAX_CONCURRENT	2	最大並行 processor 數
MOMENTRY_POLL_INTERVAL	5	輪詢間隔（秒）
MOMENTRY_WORKER_ENABLED	true	是否啟用 worker

實作計畫

詳細內容請參考 JOB_WORKER_IMPLEMENTATION_PLAN.md

Phase 規劃

Phase	任務	預估工時
1	資料庫遷移	2h
2	Worker 框架	4h
3	Register API 整合	2h
4	Processor 執行	4h
5	進度追蹤	2h
6	API 端點	3h
7	CLI 命令	2h
8	測試	4h

總預估: ~23h

實作結構

src/
├── worker/
│   ├── mod.rs           # Worker 模組導出
│   ├── config.rs        # Worker 配置
│   ├── worker.rs        # Worker 主邏輯
│   ├── processor.rs     # Processor 執行器
│   ├── queue.rs        # Job 佇列管理
│   └── progress.rs      # 進度追蹤
├── api/
│   └── server.rs        # 更新 Register API
└── main.rs              # 新增 worker 命令

狀態

• 系統分析完成
• 實作計畫文件建立
• Phase 1: 資料庫遷移
• Phase 2: Worker 框架
• Phase 3: Register API 整合
• Phase 4: Processor 執行
• Phase 5-8: 依序實作

參考文件

• docs/JOB_WORKER_IMPLEMENTATION_PLAN.md - 完整實作計畫
• docs/PROCESSING_PIPELINE.md - 處理流程
• docs/MOMENTRY_CORE_REDIS_KEYS.md - Redis Key 設計

---

統一會員系統 + 影片歸屬追蹤 (2026-03-24)

目標

建立統一的會員系統：

1. WordPress 作為唯一登入入口
2. 每個影片關聯到 user_id（追蹤歸屬）
3. Per-user 配額管理
4. API 端點啟用認證

實作計畫

詳細內容請參考 USER_MANAGEMENT_PLAN.md

Phase 規劃

Phase	任務	複雜度	優先級	預估工時
1	WordPress Application Passwords 測試	低	P0	1.5h
2	資料庫遷移 (users 表)	中	P0	3h
3	API auth middleware	中	P0	4h
4	Register API 更新	低	P0	2h
5	Admin users API	中	P1	4h
6	n8n workflow	中	P1	6h
7	配額管理	中	P2	4h
8	測試驗證	中	P2	4h

總預估: ~28.5h

待確認事項

• WordPress 用戶建立方式（手動/Elementor表單）
• API Key 格式確認
• SFTPGo 整合方式
• 配額管理策略
• 用戶刪除同步流程

狀態

• 系統分析完成
• 實作計畫文件建立
• Phase 1: WordPress 認證測試
• Phase 2: 資料庫遷移
• Phase 3-8: 依序實作

參考文件

• docs/USER_MANAGEMENT_PLAN.md - 完整實作計畫
• docs/API_KEY_MANAGEMENT.md - API Key 管理
• docs/SFTPGO_DEMO_USER.md - SFTPGo 用戶設定