admin/momentry_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

cleanup: remove dead code and duplicate docs

Browse Source 
- Remove session-ses_2f27.md (161KB raw session log)
- Remove 49 ROOT_* duplicate files across REFERENCE/
- Remove 14 duplicate files between REFERENCE/ root and history/
- Remove asr_legacy.rs (dead code, replaced by asr.rs)
- Remove src/core/worker/ (duplicate JobWorker)
- Remove src/core/layers/ (empty directory)
- Remove 4 .bak files in src/
- Remove 7 dead private methods in worker/processor.rs
- Remove backup directory from git tracking
This commit is contained in:
Warren
2026-05-04 01:31:21 +08:00
parent ee81e343ce
commit e75c4d6f07
3270 changed files with 35190 additions and 53367 deletions
Download Patch File Download Diff File Expand all files Collapse all files

198
docs_v1.0/OPERATIONS/ARCHITECTURE_REVIEW_REPORT.md
View File

@@ -1,198 +0,0 @@
# 架構文件審查報告 (Architecture Review Report)
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-25 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 全面審查 docs_v1.0 架構文件的一致性与完整性 | OpenCode | OpenCode |
---
## 1. 審查範圍
| 文件 | 狀態 | 評分 |
|------|------|------|
| `IMPLEMENTATION/FILE_IDENTITY_API_DESIGN.md` | 核心設計 | 7/10 |
| `ARCHITECTURE/RESOURCE_MANAGEMENT/UNIFIED_RESOURCE_REGISTRY.md` | 資源管理 | 8/10 |
| `PROCESSORS/_CORE/PROCESSOR_RESUME_STRATEGY.md` | 續傳機制 | 9/10 |
| `AI_AGENTS/CORE/AGENT_SPEC.md` | Agent 規範 | 8/10 |
| `STANDARDS/DOCS_STANDARD.md` | 文檔規範 | 9/10 |
---
## 2. 發現的問題與建議
### 2.1 高優先級 (High) — 架構矛盾
#### 🚨 H1: `faces` 表與 `file_identities` 表的關係不清
**問題**:
* `FILE_IDENTITY_API_DESIGN.md` 同時定義了 `faces` 表和 `file_identities` 表。
* `faces` 表有 `identity_id` (表示 Face 可直接歸屬 Identity)。
* `file_identities` 表也有身份關聯資訊。
* **兩者的職責重疊**，開發者會困惑該寫入哪張表。
**建議**:
* **方案 A**: 移除 `faces` 表，將 Face 視為 `pre_chunk` 的一種類型，Face 與 Identity 的關聯僅通過 `file_identities` 管理。
* **方案 B**: 保留 `faces` 表，但明確定義其為「Face 檢測原始數據表」，`file_identities` 僅作為「Face 與 Identity 的多對多關聯橋接表」。
* **推薦方案 A**：符合「Frame = Pre-chunk」的設計理念，減少冗餘。
#### 🚨 H2: 缺少 `pre_chunks` 表的 Schema 定義
**問題**:
* `FILE_IDENTITY_API_DESIGN.md` 中**未定義** `pre_chunks` 表結構。
* 但 `PROCESSOR_RESUME_STRATEGY.md` 明確指出 Processor 應產出 `pre_chunks`。
* 實作時將無參考標準。
**建議**:
* 在設計文件中補充 `pre_chunks` 表定義，至少包含：
```sql
pre_chunks (
pre_chunk_id UUID PK,
file_id UUID FK → files,
processor_type VARCHAR(20), -- 'yolo', 'face', 'asr'...
frame_index BIGINT, -- 幀索引 (或語句索引)
timestamp FLOAT, -- 時間位置
data JSONB, -- 處理器原始輸出
created_at TIMESTAMPTZ
)
```
#### 🚨 H3: Candidate 與 Face 的關係未明確定義
**問題**:
* 設計說「Candidate 是未被確認歸屬 Identity 的 face」。
* 但資料庫中沒有 `candidates` 表。
* Candidate 是邏輯狀態還是物理表？
**建議**:
* **方案 A (推薦)**: Candidate 不需要獨立表。`faces.identity_id IS NULL` 即代表該 Face 是 Candidate。
* 在 API 設計中明確說明：`GET /people/candidates` = `SELECT * FROM faces WHERE identity_id IS NULL`。
---
### 2.2 中優先級 (Medium) — 設計缺失
#### ⚠️ M1: 缺少 Chunk 聚合規則的輸入輸出定義
**問題**:
* Rule 1/2/3 如何讀取 `pre_chunks` 並產出 `chunks`？
* 沒有明確的數據流說明。
**建議**:
* 補充 `CHUNKING` 目錄下的規則文件，定義每個 Rule 的：
* **Input**: 從哪些 `pre_chunks` 讀取？
* **Logic**: 聚合邏輯是什麼？
* **Output**: 產出什麼樣的 `chunk`？
#### ⚠️ M2: Resource Registry 與現有 Job Worker 的整合
**問題**:
* `UNIFIED_RESOURCE_REGISTRY.md` 定義了統一的資源註冊機制。
* 但現有的 `src/worker/job_worker.rs` 是硬編碼調度 (`ProcessorType::all()`)。
* 如何過渡？
**建議**:
* 定義過渡路徑：
1. **Phase 1**: Worker 仍使用硬編碼，但 Processor 啟動時額外註冊到 Registry（僅用於監控）。
2. **Phase 2**: Worker 改為從 Registry 動態發現資源。
#### ⚠️ M3: 檔案類型限制與欄位設計
**問題**:
* `files` 表定義了 `file_type` (video, pdf...) 但現階段僅處理 Video。
* `pre_chunks` 和 `chunks` 表若設計時未考慮擴充性，未來加 PDF 時需大改。
**建議**:
* 在 `pre_chunks` 表加入 `coordinate_type` 欄位：
* Video: 使用 `frame_index` (幀號)
* Text: 使用 `page_number` + `paragraph_index`
* 確保 Schema 可容納未來的檔案類型。
---
### 2.3 低優先級 (Low) — 文檔一致性
#### ℹ️ L1: 術語不一致
| 文件 | 使用的術語 | 建議統一為 |
|------|-----------|-----------|
| `FILE_IDENTITY_API_DESIGN.md` | `file_id` | `file_id` |
| `PROCESSOR_RESUME_STRATEGY.md` | `file_uuid` | `file_id` |
| 現有程式碼 | `uuid` | `file_id` |
**建議**: 全文統一使用 `file_id` 或 `file_uuid`，避免混用。
#### ℹ️ L2: API Response 格式微調
`FILE_IDENTITY_API_DESIGN.md` 定義了 `candidates` 為回應中的 key，但規範說 List 應使用 `data`。
**建議**: 統一使用 `data` 作為 List 回應的 key，或明確列出例外情況。
#### ℹ️ L3: 缺少錯誤碼定義
API 設計中定義了 `{"ok": false, "error": "..."}` 但未列出標準錯誤碼。
**建議**: 新增 `ERROR_CODES.md`，定義如 `E001_FILE_NOT_FOUND` 等標準錯誤。
---
## 3. 架構完整性檢查清單
| 項目 | 狀態 | 說明 |
|------|------|------|
| File 管理 | ✅ | Schema 完整 |
| Identity 管理 | ✅ | Schema 完整 |
| Face/Candidate 管理 | ⚠️ | 缺少明確的 Candidates 查詢邏輯定義 |
| Pre-chunk 定義 | ❌ | **缺少 Schema** (高優先級) |
| Chunk 聚合規則 | ⚠️ | 有目錄但缺少詳細規則文件 |
| Processor 續傳 | ✅ | 設計完整 |
| Resource Registry | ✅ | 設計完整 |
| AI Agent 規範 | ✅ | 設計完整 |
| API 錯誤處理 | ⚠️ | 缺少標準錯誤碼 |
| 遷移策略 | ❌ | **缺少從舊系統到新系統的遷移指南** |
---
## 4. 建議的行動計畫
### Phase 0: 文檔修正 (立即)
* [ ] 在 `FILE_IDENTITY_API_DESIGN.md` 中補充 `pre_chunks` 表 Schema (解決 H2)
* [ ] 明確定義 `faces` vs `file_identities` 的職責分工 (解決 H1)
* [ ] 統一術語 (`file_id` vs `file_uuid`) (解決 L1)
### Phase 1: 補充缺失文檔
* [ ] 撰寫 `CHUNKING/RULES/RULE_SPEC.md` (解決 M1)
* [ ] 撰寫 `MIGRATION_GUIDE.md` (從舊系統過渡)
* [ ] 撰寫 `API_ERROR_CODES.md` (解決 L3)
### Phase 2: 架構對齊
* [ ] 確認 Resource Registry 與現有 Job Worker 的整合路徑 (解決 M2)
---
## 5. 總結
目前的架構設計在**核心概念** (File + Identity + Pre-chunk + Chunk) 上是正確的，方向明確。
主要缺失在於：
1. **`pre_chunks` 表未定義** (最關鍵，影響實作)
2. **Face/Candidate 的關係需要更清晰的表述**
3. **缺少舊系統遷移策略**
建議在進入 Implementation Phase 前，先完成 Phase 0 的文檔修正。
---
## 版本資訊
* 版本: V1.0
* 審查日期: 2026-04-25
* 審查者: OpenCode

468
docs_v1.0/OPERATIONS/BACKUP_VERSIONING.md
View File

@@ -1,468 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "Momentry 備份版本管理規範"
date: "2026-03-25"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "momentry"
- "備份版本管理規範"
ai_query_hints:
- "查詢 Momentry 備份版本管理規範 的內容"
- "Momentry 備份版本管理規範 的主要目的是什麼？"
- "如何操作或實施 Momentry 備份版本管理規範？"
---
# Momentry 備份版本管理規範
| 項目 | 內容 |
|------|------|
| 建立者 | Warren / OpenCode |
| 建立時間 | 2026-03-25 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 |
|------|------|------|--------|
| V1.0 | 2026-03-25 | 建立備份版本管理規範 | OpenCode |
---
## 1. 概述
本文檔定義 Momentry 系統的備份版本管理規範，確保新舊架構之間的回滾相容性。
### 1.1 版本定義
| 版本 | 日期 | 說明 |
|------|------|------|
| v1 | 2026-03-18 | 初始備份架構（不包含新架構組件）|
| v2 | 2026-03-25 | 新架構備份（包含 monitor_jobs, processor_results, Output 目錄）|
### 1.2 備份版本格式
| 版本 | 檔案命名格式 |
|------|-------------|
| v1 | `{service}_{type}_{YYYYMMDD}_{HHMMSS}.{ext}` |
| v2 | `{service}_{type}_v2_{YYYYMMDD}_{HHMMSS}.{ext}` |
### 1.3 各版本涵蓋範圍
| 組件 | v1 | v2 |
|------|-----|-----|
| PostgreSQL (videos, chunks) | ✅ | ✅ |
| PostgreSQL (monitor_jobs) | ❌ | ✅ |
| PostgreSQL (processor_results) | ❌ | ✅ |
| Redis | ✅ | ✅ |
| MongoDB Cache | ⚠️ | ⚠️ |
| Output (probe.json) | ❌ | ✅ |
> ⚠️ MongoDB 備份目前存在路徑問題，正在修復中
---
## 2. 備份版本識別
### 2.1 檔名識別
```bash
# 識別版本
detect_version() {
local backup_file=$1
if echo "$backup_file" | grep -q "_v2_"; then
echo "v2"
else
echo "v1"
fi
}
# 使用範例
detect_version "postgresql_db_momentry_v2_20260325_030000.sql.gz"
# 輸出: v2
detect_version "postgresql_db_momentry_20260324_030000.sql.gz"
# 輸出: v1
```
### 2.2 內容識別
```bash
# 檢查是否為 v2 備份
is_v2_backup() {
local backup_file=$1
gzip -dc "$backup_file" 2>/dev/null | grep -q "monitor_jobs" && echo "yes" || echo "no"
}
# 檢查是否包含 processor_results
has_processor_results() {
local backup_file=$1
gzip -dc "$backup_file" 2>/dev/null | grep -q "processor_results" && echo "yes" || echo "no"
}
```
### 2.3 檔案大小比較
| 版本 | PostgreSQL 備份大小 | 說明 |
|------|---------------------|------|
| v1 | ~18-19 MB | 基本資料表 |
| v2 | >19 MB | 包含新表格和索引 |
---
## 3. 回滾策略
### 3.1 回滾流程圖
```
┌─────────────────────────────────────────┐
│ 選擇還原目標 │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 選擇備份版本 │
│ ┌───────────┐ ┌───────────┐ │
│ │ v1 備份 │ │ v2 備份 │ │
│ └───────────┘ └───────────┘ │
└─────────────────────────────────────────┘
│
┌─────────┴─────────┐
▼ ▼
┌──────────┐ ┌──────────┐
│ v1 回滾 │ │ v2 回滾 │
└──────────┘ └──────────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ 基本資料庫 │ │ 完整還原 │
└──────────┘ └──────────┘
```
### 3.2 回滾矩陣
| 還原目標 | v1 備份 | v2 備份 |
|----------|---------|---------|
| 基本資料庫 | ✅ | ✅ |
| + monitor_jobs | ❌ | ✅ |
| + processor_results | ❌ | ✅ |
| + Output 檔案 | ❌ | ✅ |
| + MongoDB Cache | ⚠️ | ⚠️ |
### 3.3 回滾相容性說明
#### v1 → v2（支援）
- v1 備份可以還原到 v2 架構
- 新架構組件會從空白狀態開始
- 不會造成資料損壞
#### v2 → v1（⚠️ 警告）
```
⚠️ v2 回滾到 v1 可能導致資料丟失
影響範圍：
- monitor_jobs 資料會消失
- processor_results 資料會消失
- Output 檔案參照可能失效
建議：
1. 在還原前建立 v2 快照
2. 或使用隔離還原（staging restore）
```
---
## 4. 還原腳本保護機制
### 4.1 還原前檢查
```bash
# 還原前檢查版本相容性
pre_restore_check() {
local backup_file=$1
local version=$(detect_version "$backup_file")
local current_db_version=$(check_current_db_version)
echo "備份版本: $version"
echo "目前版本: $current_db_version"
# v2 → v1: 警告但允許（使用者需確認）
if [ "$version" = "v1" ] && [ "$current_db_version" = "v2" ]; then
echo "⚠️ 警告：即將回滾到 v1"
echo "影響：monitor_jobs 和 processor_results 資料將被清除"
read -p "確認繼續？(y/N): " confirm
[ "$confirm" != "y" ] && exit 1
fi
# v1 → v2: 直接允許
if [ "$version" = "v1" ] && [ "$current_db_version" = "v2" ]; then
echo "ℹ️ 提示：新架構組件將重新初始化"
fi
# v2 → v2: 直接允許
# v1 → v1: 直接允許
}
```
### 4.2 隔離還原（Staging Restore）
```bash
# 只還原到暫存資料庫，不影響生產
restore_to_staging() {
local backup_file=$1
local version=$(detect_version "$backup_file")
echo "執行隔離還原..."
echo "版本: $version"
# 建立暫存資料庫
PGPASSWORD="$PG_PASSWORD" psql -U "$PG_USER" -d postgres << EOF
DROP DATABASE IF EXISTS momentry_staging;
CREATE DATABASE momentry_staging;
EOF
# 還原到暫存資料庫
PGPASSWORD="$PG_PASSWORD" pg_restore -U "$PG_USER" -d "momentry_staging" \
--no-owner --no-acl "$backup_file"
echo "✅ 還原完成：momentry_staging"
echo "驗證命令：psql -U accusys -d momentry_staging -c '\\dt'"
}
```
### 4.3 版本驗證命令
```bash
# 識別所有備份版本
ls /Users/accusys/momentry/backup/daily/postgresql/*.sql.gz | \
xargs -I {} sh -c 'echo "{}: $(detect_version {})"'
# 驗證 v2 備份內容
verify_v2_backup() {
local backup_file=$1
echo "驗證備份: $backup_file"
# 檢查 monitor_jobs
if gzip -dc "$backup_file" | grep -q "monitor_jobs"; then
echo "✅ 包含 monitor_jobs"
else
echo "❌ 缺少 monitor_jobs"
return 1
fi
# 檢查 processor_results
if gzip -dc "$backup_file" | grep -q "processor_results"; then
echo "✅ 包含 processor_results"
else
echo "❌ 缺少 processor_results"
return 1
fi
echo "✅ v2 備份驗證通過"
}
```
---
## 5. 版本遷移
### 5.1 v1 → v2 遷移步驟
| 步驟 | 說明 | 驗證 |
|------|------|------|
| 1 | 確認所有 v1 備份已完成 | `ls *.sql.gz \| grep -v v2` |
| 2 | 修改 `backup_all.sh` 加入 v2 標記 | 確認 TIMESTAMP 包含 `v2_` |
| 3 | 修正 MongoDB 路徑 | 確認指向正確目錄 |
| 4 | 新增 Output 目錄備份 | 確認 probe.json 被備份 |
| 5 | 執行測試備份 | 驗證命名格式正確 |
| 6 | 驗證 v2 備份完整性 | `verify_v2_backup` |
| 7 | 正式啟用 v2 備份 | 確認 crontab 使用新版 |
### 5.2 遷移驗證清單
```bash
#!/bin/bash
# verify_v2_migration.sh
echo "=== v2 遷移驗證 ==="
# 1. 檢查備份腳本
echo "1. 檢查備份腳本..."
if grep -q "v2_" /Users/accusys/momentry/scripts/backup_all.sh; then
echo " ✅ 版本標記已啟用"
else
echo " ❌ 版本標記未啟用"
fi
# 2. 檢查 MongoDB 路徑
echo "2. 檢查 MongoDB 路徑..."
if grep -q "/opt/homebrew/var/mongodb" /Users/accusys/momentry/scripts/backup_all.sh; then
echo " ✅ MongoDB 路徑已修正"
else
echo " ❌ MongoDB 路徑未修正"
fi
# 3. 檢查 Output 目錄備份
echo "3. 檢查 Output 目錄備份..."
if grep -q "momentry_output" /Users/accusys/momentry/scripts/backup_all.sh; then
echo " ✅ Output 目錄備份已啟用"
else
echo " ❌ Output 目錄備份未啟用"
fi
# 4. 檢查最新備份
echo "4. 檢查最新備份..."
latest_backup=$(ls -t /Users/accusys/momentry/backup/daily/postgresql/*.sql.gz 2>/dev/null | head -1)
if [ -n "$latest_backup" ]; then
version=$(detect_version "$latest_backup")
echo " 最新備份: $(basename $latest_backup)"
echo " 版本: $version"
if [ "$version" = "v2" ]; then
verify_v2_backup "$latest_backup"
fi
fi
echo "=== 驗證完成 ==="
```
---
## 6. 疑難排解
### 6.1 常見問題
| 問題 | 原因 | 解決方案 |
|------|------|----------|
| 無法識別版本 | 檔名被修改 | 使用內容分析 `gzip -dc \| grep "monitor_jobs"` |
| v2 備份還原失敗 | 磁碟空間不足 | 清理空間後重試 |
| v1 還原覆蓋 v2 | 操作失誤 | 使用隔離還原保護生產資料 |
| MongoDB 備份為空 | 路徑錯誤 | 修正為 `/opt/homebrew/var/mongodb` |
### 6.2 緊急回滾流程
```bash
#!/bin/bash
# emergency_restore.sh
set -e
BACKUP_FILE=$1
VERSION=$2
echo "=== 緊急回滾 ==="
echo "備份檔案: $BACKUP_FILE"
echo "目標版本: $VERSION"
# 1. 建立當前狀態快照
echo "1. 建立當前狀態快照..."
NOW=$(date +%Y%m%d_%H%M%S)
pg_dump -U accusys -d momentry | gzip > "/tmp/momentry_emergency_$NOW.sql.gz"
echo " 快照: /tmp/momentry_emergency_$NOW.sql.gz"
# 2. 執行還原
echo "2. 執行還原..."
gunzip -c "$BACKUP_FILE" | psql -U accusys -d momentry
# 3. 驗證
echo "3. 驗證還原..."
psql -U accusys -d momentry -c "SELECT COUNT(*) FROM monitor_jobs;"
echo "=== 回滾完成 ==="
```
---
## 7. 備份清單（v2）
### 7.1 每日備份（v2 格式）
| 服務 | 備份項目 | 檔案命名 | 說明 |
|------|----------|----------|------|
| PostgreSQL | momentry | `postgresql_db_momentry_v2_{date}_{time}.sql.gz` | 完整資料庫 |
| PostgreSQL | video_register | `postgresql_db_video_register_v2_{date}_{time}.sql.gz` | 影片註冊資料 |
| Redis | RDB | `redis_rdb_v2_{date}_{time}.rdb` | Redis 快照 |
| MongoDB | 資料 | `mongodb_data_v2_{date}_{time}.tar.gz` | MongoDB 資料 |
| n8n | 資料+DB | `n8n_{date}_{time}.tar.gz`, `n8n_db_{date}_{time}.sql.gz` | n8n 完整 |
| SFTPGo | 配置+DB | `sftpgo_{date}_{time}.tar.gz`, `sftpgo_db_{date}_{time}.sql.gz` | SFTPGo |
| Gitea | 資料 | `gitea_{date}_{time}.tar.gz` | Gitea |
| Output | 檔案 | `momentry_output_v2_{date}_{time}.tar.gz` | probe.json 等 |
### 7.2 備份保留策略
| 類型 | 保留期限 | 位置 |
|------|----------|------|
| 每日備份 | 7 天 | `backup/daily/` |
| 每週備份 | 4 週 | `backup/weekly/` |
| 每月備份 | 12 個月 | `backup/monthly/` |
| 歸檔 | 1 年+ | `backup/archive/` |
---
## 8. 相關文件
| 文件 | 說明 |
|------|------|
| [SERVICES.md](./SERVICES.md) | 服務說明 |
| [MOMENTRY_CORE_MONITORING.md](./MOMENTRY_CORE_MONITORING.md) | 監控規範 |
| `/Users/accusys/momentry/scripts/backup_all.sh` | 備份腳本 |
| `/Users/accusys/momentry/scripts/restore_all.sh` | 還原腳本 |
| `/Users/accusys/momentry_core_0.1/monitor/storage/backup_monitor.sh` | 備份監控 |
---
## 附錄 A：v2 備份完整性檢查清單
```bash
#!/bin/bash
# check_v2_integrity.sh
BACKUP_DIR="/Users/accusys/momentry/backup/daily"
echo "=== v2 備份完整性檢查 ==="
# 檢查 PostgreSQL
echo "1. PostgreSQL..."
pg_backup=$(ls -t "$BACKUP_DIR/postgresql"/postgresql_db_momentry_v2_*.sql.gz 2>/dev/null | head -1)
if [ -n "$pg_backup" ]; then
echo " 備份: $(basename $pg_backup)"
verify_v2_backup "$pg_backup"
else
echo " ❌ 未找到 v2 備份"
fi
# 檢查 Output
echo "2. Output 目錄..."
output_backup=$(ls -t "$BACKUP_DIR/momentry"/momentry_output_v2_*.tar.gz 2>/dev/null | head -1)
if [ -n "$output_backup" ]; then
echo " 備份: $(basename $output_backup)"
echo " ✅ Output 備份已存在"
else
echo " ❌ 未找到 Output 備份"
fi
# 檢查 MongoDB
echo "3. MongoDB..."
mongo_backup=$(ls -t "$BACKUP_DIR/mongodb"/mongodb_data_v2_*.tar.gz 2>/dev/null | head -1)
if [ -n "$mongo_backup" ]; then
size=$(stat -f%z "$mongo_backup" 2>/dev/null || stat -c%s "$mongo_backup" 2>/dev/null)
echo " 備份: $(basename $mongo_backup)"
echo " 大小: $size bytes"
if [ "$size" -gt 1000 ]; then
echo " ✅ MongoDB 備份有效"
else
echo " ⚠️ MongoDB 備份可能為空"
fi
else
echo " ❌ 未找到 MongoDB 備份"
fi
echo "=== 檢查完成 ==="
```

540
docs_v1.0/OPERATIONS/DEVELOPMENT_LOG.md
View File

@@ -1,540 +0,0 @@
# Momentry Core 開發日誌
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
---
> **文檔維護開始**：2026-03-18
> **⚠️ 補充說明**：事後補記（2026-03-18 以前），僅供參考。未來紀錄將即時記錄，參考價值較高。
---
## 開發工具
### Coding LLM 模型
| 階段 | 工具 | 模型 | ID | 說明 |
|------|------|------|-----|------|
| **初期** | Claude CLI | - | - | 初始專案架構建立 |
| **中期** | OpenCode | big-pickle | opencode/big-pickle | 主要開發協作者 |
**切換記錄**：
- 初期使用 Claude CLI 建立專案基本架構
- 中期切換至 OpenCode (big-pickle) 進行主要功能開發
---
## 2026-03-17
### ML 模型選用
| Processor | 模型 | 版本/大小 | 說明 |
|----------|------|-----------|------|
| **ASR** | WhisperX (faster-whisper) | base, int8 | 語音識別 + 對話分段 |
| **CUT** | PySceneDetect | 0.6.7.1 | ContentDetector 場景檢測 |
| **YOLO** | YOLOv8n | yolov8n.pt (6.2MB) | 物體檢測（nano 版本最快） |
| **OCR** | EasyOCR | 1.7.2 | 文字識別 |
| **Face** | OpenCV Haar Cascade | built-in | 人臉檢測（無需額外下載） |
| **Pose** | YOLOv8n-Pose | yolov8n-pose.pt (6.5MB) | 姿態估計（nano 版本） |
**模型下載**：
- YOLOv8n: `yolov8n.pt` (6.2MB)
- YOLOv8n-Pose: `yolov8n-pose.pt` (6.5MB)
**Python 依賴**：
```
torch==2.8.0
whisperx==3.8.2
ultralytics==8.4.23
scenedetect==0.6.7.1
easyocr==1.7.2
opencv-python==4.13.0.92
```
---
### ASR 實作完成
- 完成 Python ML processor scripts（使用本地模型）
- `asrx_processor.py` - whisperx for speaker diarization
- `cut_processor.py` - PySceneDetect for scene detection
- `yolo_processor.py` - YOLOv8 for object detection
- `ocr_processor.py` - EasyOCR for text recognition
- `face_processor.py` - OpenCV Haar Cascade for face detection
- `pose_processor.py` - YOLOv8 Pose for pose estimation
- 更新 `requirements.txt` with all dependencies
- 安裝完成：torch 2.8.0, whisperx 3.8.2, ultralytics 8.4.23, scenedetect 0.6.7.1, easyocr 1.7.2, opencv-python 4.13.0.92
- 下載模型：YOLOv8n.pt (6.2MB), YOLOv8n-Pose.pt (6.5MB)
### Async Streaming 實作
- 更新 Rust processor modules 使用 async streaming 進行 real-time progress
- `src/core/processor/asr.rs`
- `src/core/processor/cut.rs`
- `src/core/processor/yolo.rs`
- `src/core/processor/ocr.rs`
- `src/core/processor/face.rs`
- `src/core/processor/pose.rs`
### 測試結果
- 測試影片：BigBuckBunny_320x180.mp4
- ASR: 4 segments
- CUT: 134 scenes
- YOLO: 14315 frames（每幀處理耗時）
- OCR: 40 frames with text
- Face: 44 frames with faces
- Pose: Timeout
---
### Warning 清理
修復 clippy warnings：
- 移除未使用的 imports (HashMap in mongodb_db.rs, postgres_db.rs)
- 新增 `#[allow(dead_code)]` 標註未使用變數
- 新增 `Default` implementation for MongoDb, QdrantDb
- 將 `probe` module 重新命名為 `ffprobe`
- 新增 `player` feature in Cargo.toml
- 修復 `format_in_format_args` 警告
---
### TUI Progress Window 實作
建立新的 UI module：
- 建立 `src/ui/mod.rs`
- 建立 `src/ui/progress/mod.rs`
實作功能：
- ProcessorProgress 結構（追蹤每個 processor 狀態）
- ProgressState 結構（管理所有 processors）
- ProgressUi 結構（ratatui TUI 渲染）
- 整合到 `src/main.rs` 的 process 命令
TUI 顯示：
```
┌ Processing: BigBuckBunny_320x180.mp4 ────────────────────────────────────────┐
│ ASR [████████████] 100% (4 segs) │
│ CUT [████████████] 100% (134 scenes) │
│ ASRX [████████████] 100% (0 segs) │
│ YOLO [██░░░░░░░░░░░] 30% (4200/14315) ETA 2:30 │
│ OCR [---------] 0% │
│ Face [---------] 0% │
│ Pose [---------] 0% │
└──────────────────────────────────────────────────────────────────────────────┘
```
---
### 輸出位置討論
討論 stdout vs stderr vs TUI 的輸出配置：
- 最終結果 → stdout
- Python progress → 需改用 Redis Pub/Sub
- TUI Progress → stderr (ratatui)
---
## 2026-03-18
### Redis Message Bus 設計
討論使用 Redis 作為消息總線，分離 Python 輸出與 Rust TUI 顯示。
設計重點：
1. 頻道命名：`momentry:progress:{uuid}`
2. 本地 Redis：`localhost:6379`
3. 失敗策略：完全失效（因 stdout 問題未解決）
### UUID 使用時機分析
分析 Redis Key 上使用 UUID 的時機：
**全局 Keys（無 UUID）**：
- health, stats, jobs 管理
**Per-Video Keys（UUID 必要）**：
- job:{uuid}, progress:{uuid}, metrics:{uuid}
**Per-Processor Keys（UUID + Processor 必要）**：
- job:{uuid}:processor:{name}
### 備份系統整合
參考 `docs/SERVICE_ADDITION_GUIDE.md` 設計規範，規劃 OutputDir 模組：
1. **環境變數**：
- `MOMENTRY_OUTPUT_DIR` - JSON 輸出目錄
- `MOMENTRY_BACKUP_DIR` - 備份目錄（預設：`/Users/accusys/momentry/backup/momentry`）
- `MOMENTRY_BACKUP_ENABLED` - 啟用備份
2. **命名格式**：
- 備份格式：`momentry_data_{YYYYMMDD}_{HHMMSS}_{uuid}.{ext}`
- 校驗和：`{filename}.sha256`
3. **CLI 命令**：
- `cargo run -- backup list` - 列出備份
- `cargo run -- backup cleanup` - 清理舊備份
- `cargo run -- backup verify` - 驗證備份
---
### 監控系統整合
討論將 momentry_core 納入監控系統：
1. **Layer 2: Service 監控**
- 新增 momentry_core CLI 檢查
2. **Layer 7: Backup 監控**
- 新增 momentry 備份配置
3. **Redis 監控**
- 健康檢查
- Job 狀態監控
- 即時進度監控
---
## 實作完成項目
### 程式碼變更
| 日期 | 檔案 | 變更 |
|------|------|------|
| 2026-03-17 | `src/core/processor/*.rs` | Async streaming 更新 |
| 2026-03-17 | `src/ui/mod.rs` | 新增 UI module |
| 2026-03-17 | `src/ui/progress/mod.rs` | 新增 Progress TUI |
| 2026-03-17 | `src/main.rs` | 整合 Progress UI |
| 2026-03-18 | `src/core/storage/output_dir.rs` | 新增 OutputDir 模組 |
| 2026-03-18 | `src/core/storage/mod.rs` | 新增 output_dir export |
| 2026-03-18 | `src/core/db/redis_client.rs` | 新增 Redis 客戶端（Hash + Pub/Sub） |
| 2026-03-18 | `src/core/db/mod.rs` | 新增 redis_client export |
### 新增檔案
| 日期 | 檔案 | 說明 |
|------|------|------|
| 2026-03-18 | `docs/MOMENTRY_CORE_REDIS_KEYS.md` | Redis Key 設計規範 |
| 2026-03-18 | `docs/MOMENTRY_CORE_MONITORING.md` | 監控規範（暫定） |
| 2026-03-18 | `scripts/redis_publisher.py` | Redis 訊息發布模組 |
### 更新檔案
| 日期 | 檔案 | 說明 |
|------|------|------|
| 2026-03-17 | `Cargo.toml` | 新增 player feature |
| 2026-03-17 | `src/lib.rs` | 新增 ui module exports |
| 2026-03-18 | `docs/PENDING_ISSUES.md` | 新增問題 #2, #3 |
| 2026-03-18 | `src/core/storage/output_dir.rs` | 預設改為 `./output` |
| 2026-03-18 | `scripts/yolo_processor.py` | 新增 --uuid 參數 + Redis |
| 2026-03-18 | `scripts/cut_processor.py` | 新增 Redis |
| 2026-03-18 | `scripts/ocr_processor.py` | 新增 Redis |
| 2026-03-18 | `scripts/face_processor.py` | 新增 --uuid 參數 + Redis |
| 2026-03-18 | `scripts/pose_processor.py` | 新增 --uuid 參數 + Redis |
| 2026-03-18 | `scripts/asr_processor.py` | 新增 --uuid 參數 + Redis |
| 2026-03-18 | `scripts/asrx_processor.py` | 新增 --uuid 參數 + Redis |
| 2026-03-18 | `requirements.txt` | 新增 redis>=5.0.0 |
| 2026-03-18 | `src/core/processor/yolo.rs` | 新增 uuid 參數 |
| 2026-03-18 | `src/core/processor/cut.rs` | 新增 uuid 參數 |
| 2026-03-18 | `src/core/processor/ocr.rs` | 新增 uuid 參數 |
| 2026-03-18 | `src/core/processor/face.rs` | 新增 uuid 參數 |
| 2026-03-18 | `src/core/processor/pose.rs` | 新增 uuid 參數 |
| 2026-03-18 | `src/core/processor/asr.rs` | 新增 uuid 參數 |
| 2026-03-18 | `src/core/processor/asrx.rs` | 新增 uuid 參數 |
| 2026-03-18 | `src/main.rs` | 更新所有 processor 調用傳入 uuid |
| 2026-03-18 | `Cargo.toml` | 新增 futures-util 依賴 |
| 2026-03-18 | `src/core/db/redis_client.rs` | 新增 subscribe_and_callback 方法，密碼認證 |
| 2026-03-18 | `src/ui/progress/mod.rs` | 新增 update_from_redis 方法 |
| 2026-03-18 | `scripts/redis_publisher.py` | 新增密碼認證支援 |
| 2026-03-18 | 測試 | Redis Pub/Sub 成功運作 |
---
## 待解決問題
### 問題 #1: sqlx async INSERT 不會實際寫入數據庫
- 狀態：待解決
- 影響：`store_vector` 函數，PVector 存儲
### 問題 #2: TUI 與 stdout 輸出混合
- 狀態：已解決
- 解決方案：使用 Redis Message Bus
- 進度：
- ✅ Redis 客戶端 (`src/core/db/redis_client.rs`)
- ✅ Python redis_publisher.py
- ✅ 所有 Python processors 更新完成
- ✅ 所有 Rust processor 函數更新完成
- ✅ main.rs 調用更新完成
- ✅ Rust TUI Redis 訂閱已完成
### 問題 #3: Redis Message Bus 尚未實作
- 狀態：已解決
- 詳細設計：參考 `docs/MOMENTRY_CORE_REDIS_KEYS.md`
- 進度：Python 端 + Rust 端均已完成
---
## 環境變數
```bash
# 輸出目錄
MOMENTRY_OUTPUT_DIR=./output # 預設
# 備份
MOMENTRY_BACKUP_ENABLED=false # 預設
MOMENTRY_BACKUP_DIR=/Users/accusys/momentry/backup/momentry
# Redis（未來實作）
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=accusys
```
---
## 數據庫
- PostgreSQL: `postgres://accusys@localhost:5432/momentry`
- Redis: `localhost:6379`（待實作）
- Qdrant: `localhost:6333`
---
## 指令範例
```bash
# 註冊視頻
cargo run -- register /path/to/video.mp4
# 處理視頻
cargo run -- process <uuid>
# 列出備份
cargo run -- backup list
# 清理備份
cargo run -- backup cleanup
# 驗證備份
cargo run -- backup verify
# 查看狀態
cargo run -- status
# API Server
cargo run -- server --host 0.0.0.0 --port 3000
```
---
## 2026-03-18 (進行中)
### Redis Message Bus 實作
**問題**：TUI 與 Python stdout 輸出混合，導致 TUI 顯示混亂
**解決方案**：使用 Redis Pub/Sub 作為訊息匯流排
**實作內容**：
| 元件 | 檔案 | 狀態 |
|------|------|------|
| Redis 客戶端 | `src/core/db/redis_client.rs` | ✅ |
| Progress 訂閱 | `src/main.rs` | ✅ |
| UI 更新 | `src/ui/progress/mod.rs` | ✅ |
| Python Publisher | `scripts/redis_publisher.py` | ✅ |
| Python Processors | 7 個 `scripts/*_processor.py` | ✅ |
| Rust 函數 | `src/core/processor/*.rs` | ✅ |
**流程**：
```
Python Processor ──(Redis Pub)──> Redis ──(Subscribe)──> Rust TUI
```
**測試結果**：
- Redis 連線 ✅
- 密碼認證 ✅
- 即時進度發布 ✅
- TUI 即時更新 ✅
**新增依賴**：
- `futures-util = "0.3"` (Cargo.toml)
- `redis >= 5.0.0` (requirements.txt)
---
## 2026-03-18 (HTTP API)
### HTTP API 實作
**問題**：TUI 運作正常但使用者偏好 HTTP API 來查詢進度
**解決方案**：建立 HTTP 端點 + Redis Hash 儲存
**實作內容**：
| 元件 | 檔案 | 變更 |
|------|------|------|
| HTTP 端點 | `src/api/server.rs` | 新增 `/api/v1/progress/:uuid` |
| Redis Hash 查詢 | `src/core/db/redis_client.rs` | 新增 `get_processor_status` 方法 |
| Progress 儲存 | `src/main.rs` | 新增 Redis HSET 儲存進度 |
**API 端點**：
```
GET /api/v1/progress/:uuid
Response:
{
"uuid": "5dea6618a606e7c7",
"processors": [
{"name": "asr", "status": "complete", "current": 0, "total": 0, "message": "7 segments"},
{"name": "cut", "status": "complete", "current": 134, "total": 134, "message": "134 scenes"},
{"name": "yolo", "status": "complete", "current": 14300, "total": 14315, "message": "..."},
...
]
}
```
**流程**：
```
Python Processor ──(Redis Pub)──> Redis ──(Subscribe)──> Rust TUI
└──(HSET)──> Redis Hash
│
HTTP Client ──(GET /progress/:uuid)──> Rust API ─(HGETALL)──> Redis Hash
```
**測試結果**：
- ✅ 編譯成功
- ✅ API 伺服器啟動 (port 3002)
- ✅ 即時進度查詢
- ✅ 完整流程測試 (BigBuckBunny_320x180.mp4)
**除錯記錄**：
1. 語法錯誤：main.rs 有重複程式碼區塊 (lines 297-322)，已移除
2. DB 連線池：從 5 增加到 10 個連線
3. PostgreSQL 狀態：處理 shutdown 狀態，殺掉 stale 連線
**新增變更**：
- `src/api/server.rs` - 新增進度端點
- `src/core/db/redis_client.rs` - 新增 `get_processor_status` 方法
- `src/core/db/postgres_db.rs` - 連線池 5→10
- `src/main.rs` - Redis Hash 儲存 + 語法修復
**使用方式**：
```bash
# 啟動 API 伺服器
cargo run --bin momentry -- server --host 127.0.0.1 --port 3002
# 註冊影片
cargo run --bin momentry -- register ~/test_video/BigBuckBunny_320x180.mp4
# 處理影片
cargo run --bin momentry -- process <uuid>
# 查詢進度
curl http://127.0.0.1:3002/api/v1/progress/<uuid>
```
---
## 2026-03-18 (Dashboard)
### Web Dashboard 實作
**目標**：建立 Web 介面監控 momentry_core 處理進度
**技術選擇**：Static HTML + JavaScript (非 WASM)
**實作內容**：
| 元件 | 檔案 | 說明 |
|------|------|------|
| Dashboard | `momentry_dashboard/dist/index.html` | 靜態 HTML 頁面 |
| API 代理 | Caddyfile port 3200 | 反向代理到 API server |
**功能**：
- 影片列表顯示
- 即時進度條 (每 5 秒自動刷新)
- 搜尋功能
- 處理器狀態 (ASR/CUT/YOLO/OCR/Face/Pose)
**訪問**：
- Dashboard: http://localhost:3200
- API: http://localhost:3200/api/v1/*
---
## 發生問題記錄
### HTTP API 問題
1. **語法錯誤** (main.rs)
- 位置：lines 297-322
- 原因：重複的程式碼區塊
- 解決：移除重複區塊
2. **DB 連線池耗盡**
- 原因：預設 5 個連線不足
- 解決：增加到 10 個連線
3. **PostgreSQL shutdown 狀態**
- 原因：共享記憶體未釋放
- 解決：殺掉 stale 連線
### WASM Dashboard 問題
1. **Yew 版本問題**
- 嘗試：yew 0.21 → 0.23
- 問題：feature 名稱變更 (`web-sys` → `web_sys` → `csr`)
- 解決：放棄 WASM，改用靜態 HTML
2. **編譯錯誤**
- `wasm32-unknown-unknown` target 未安裝
- 解決：`rustup target add wasm32-unknown-unknown`
3. **Yew 0.23 API 變更**
- Properties 需要 PartialEq derive
- 多處 API 語法變更
- 放棄 WASM 方案
### Gitea Push 問題
1. **Remote URL 錯誤**
- 原因：使用 localhost:3000 而非 gitea.momentry.ddns.net
- 解決：建立新 repo `momentry_core_0_1`
2. **認證問題**
- SSH key 未授權
- 密碼認證成功推送
### Caddy 設定問題
1. **API 代理順序**
- 問題：try_files 在 reverse_proxy 之前導致 API 回傳 HTML
- 解決：使用 `handle` 區塊明確定義順序
```caddyfile
:3200 {
handle /api/* {
reverse_proxy localhost:3002
}
handle {
root * /Users/accusys/momentry_dashboard/dist
try_files {path} /index.html
file_server
}
}
```
---
## 未來工作
- [ ] 修復 WASM Dashboard (Yew 0.23 相容性)
- [ ] 新增影片播放器整合
- [ ] WebSocket 實時推送
- [ ] 移動端響應式設計

474
docs_v1.0/OPERATIONS/DOCS_STANDARD.md
View File

@@ -1,474 +0,0 @@
# 文件創建規範
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件規範 | Warren | OpenCode / MiniMax M2.5 |
---
本文檔定義 Momentry Core 專案中文件的命名規範、格式標準和結構要求。
---
## 1. 檔案命名規範
### 命名模式
所有文件必須使用以下命名模式：
| 文件類型 | 模式 | 範例 |
|----------|------|------|
| 安裝指南 | `INSTALL_<NAME>.md` | `INSTALL_POSTGRESQL.md` |
| 開發指南 | `DEVELOP_<NAME>.md` | `DEVELOP_API.md` |
| API 參考 | `API_REFERENCE.md` | `API_REFERENCE.md` |
| 規格文件 | `<NAME>_SPEC.md` | `CHUNK_SPEC.md` |
| 設計文件 | `<NAME>_DESIGN.md` | `CHUNK_DESIGN.md` |
| 服務總覽 | `SERVICES.md` | `SERVICES.md` |
| 其他文件 | `<NAME>.md` | `README.md` |
### 命名規則
- 使用 **大駝峰** (PascalCase) 命名法
- 服務名稱使用 **全大寫** (e.g., `POSTGRESQL`, `SFTPGO`)
- 英文優先，縮寫保持大寫
- 使用底線 `_` 作為單詞分隔符
- 副檔名統一使用 `.md` (Markdown)
### 禁止事項
- 不允許使用中文檔名
- 不允許空格
- 不允許混合大小寫 (如 `Install_PostgreSQL.md`)
---
## 2. 文件結構模板
### 安裝指南結構
```markdown
# <服務名稱> 安裝指南 (部署類型)
## 概述
本文檔說明如何...
---
## 當前狀態
| 項目 | 狀態 |
|------|------|
| <服務名> | ✅ 已安裝 v<版本號> |
| Port | <端口號> |
| ... | ... |
---
## 安裝步驟
### Step 1: <步驟名稱>
<說明內容>
```bash
# 代碼範例
command --option value
```
### Step 2: <步驟名稱>
...
---
## 卸載步驟
### Step 1: <步驟名稱>
...
---
## 故障排除
### <問題名稱>
<解決方案>
---
## 檔案位置
| 類型 | 路徑 | 說明 |
|------|------|------|
| 安裝 | /path/to/install | 說明 |
...
---
## 常用指令
```bash
# 驗證
command verify
# 查看版本
command --version
```
---
## 版本資訊
- 版本: <版本號>
- 安裝日期: <日期>
```
---
### 規格文件結構
```markdown
# <名稱> 規格文件
## 概述
<簡短描述>
---
## 詳細規格
### 1. <功能模組>
#### 欄位定義
| 欄位 | 類型 | 必填 | 說明 |
|------|------|------|------|
| field1 | string | Yes | 說明 |
#### 資料結構
```json
{
"example": "data"
}
```
---
## 限制條件
- <限制1>
- <限制2>
---
## 相關文件
- `RELATED_FILE.md` - 相關說明
```
---
## 3. 格式標準
### Markdown 格式
| 項目 | 標準 |
|------|------|
| 標題層級 | H1 (`#`) → H2 (`##`) → H3 (`###`) |
| 水平線 | 使用 `---` 分隔主要章節 |
| 程式碼區塊 | 使用三個反引號 ``` 並標註語言 |
| 表格 | 使用 `|` 和 `-` 對齊 |
| 強調 | 使用 `**粗體**` 和 `*斜體*` |
### 程式碼區塊語言標註
```bash
# Bash
```bash
command
```
```json
# JSON
```json
{"key": "value"}
```
```rust
# Rust
```rust
fn main() {}
```
```yaml
# YAML
key: value
```
### 表格格式
```markdown
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
```
### 列表格式
- 使用 `-` 作為無序列表標記
- 使用數字 `1.` 作為有序列表標記
- 縮進使用 2 個空格
---
## 4. 語言規範
### 標題語言
| 區域 | 語言 |
|------|------|
| 主要內容 | 繁體中文 |
| 技術術語 | 英文保留 |
| 命令和代碼 | 英文 |
| 文件標題 | 繁體中文 |
### 常用術語對照
| 英文 | 中文 |
|------|------|
| Install | 安裝 |
| Configure/Config | 配置/設定 |
| Uninstall | 卸載 |
| Troubleshooting | 故障排除 |
| Status | 狀態 |
| Documentation | 文件 |
| Guide | 指南 |
| Overview | 概述 |
| Specification | 規格 |
| Current Status | 當前狀態 |
| Default | 預設 |
| Required | 必填 |
| Optional | 選填 |
| Example | 範例 |
### 標點符號
- 中文內容使用全形標點：`，`、`。`、`：`、`（`、`）`
- 英文/程式內容使用半形標點：`:`、`(`、`)`
- 命令行使用 `` `command` `` 格式
---
## 5. 內容要求
### 必需章節
每份文件必須包含：
1. **標題** - 文件名稱
2. **概述** - 檔案用途說明
3. **版本/狀態資訊** - 當前狀態
4. **檔案位置** - 重要路徑列表
5. **常用指令** - 基本操作命令
### 版本資訊格式
每份文件頂部必須包含以下資訊：
```markdown
| 項目 | 內容 |
|------|------|
| 建立者 | <姓名> |
| 建立時間 | <YYYY-MM-DD> |
| 文件版本 | V1.0 |
```
版本歷史表：
```markdown
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
```
---
### 版本資訊章節格式
```markdown
---
## 版本資訊
- 版本: <版本號>
- 安裝日期: <YYYY-MM-DD>
- 文件更新: <YYYY-MM-DD>
```
### 狀態標記
| 狀態 | 標記 |
|------|------|
| 已安裝 | ✅ 已安裝 v<x.x.x> |
| 未安裝 | ❌ 未安裝 |
| 可選 | ⚙️ 可選 |
| 進行中 | 🔄 進行中 |
---
## 6. 示例文件
### 正確範例
```markdown
# PostgreSQL 安裝指南 (本地部署)
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
---
## 概述
本文檔說明如何在 macOS 上安裝 PostgreSQL...
---
## 當前狀態
| 項目 | 狀態 |
|------|------|
| PostgreSQL | ✅ 已安裝 v16.2 |
| Port | 5432 |
---
## 安裝步驟
### Step 1: 安裝 PostgreSQL
```bash
brew install postgresql@16
```
### Step 2: 啟動服務
```bash
brew services start postgresql@16
```
---
## 檔案位置
| 類型 | 路徑 |
|------|------|
| 配置文件 | /path/to/config |
| 數據目錄 | /path/to/data |
---
## 版本資訊
- 版本: 16.2
- 安裝日期: 2026-03-01
```
### 錯誤範例
```
❌ PostgreSQL安裝.md # 中文檔名
❌ install-postgresql.md # 全部小寫
❌ Install PostgreSQL.md # 空格
❌ postgresql_install.md # 非標準命名
```
---
## 7. 文件審查清單
創建新文件時，請確認：
- [ ] 檔案命名符合 `INSTALL_*.md` 或其他標準模式
- [ ] 文件包含頂部資訊表（建立者、建立時間、版本）
- [ ] 文件包含版本歷史表
- [ ] 文件包含概述章節
- [ ] 文件包含當前狀態/版本資訊
- [ ] 文件包含檔案位置章節
- [ ] 文件包含常用指令章節
- [ ] 使用統一的 Markdown 格式
- [ ] 使用繁體中文作為主要語言
- [ ] 程式碼區塊標註語言類型
- [ ] 表格格式正確
- [ ] 章節使用 `---` 分隔
### 頂部資訊表範本
```markdown
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V1.0 |
```
### 版本歷史表範本
```markdown
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
```
---
## 8. 更新現有文件
當更新現有文件時：
1. 更新 **版本資訊** 中的日期
2. 如有必要，更新版本號
3. 記錄重大變更於 `CHANGELOG.md` 或 `DEVELOPMENT_LOG.md`
---
## 附錄：文件類型參考
| 前綴 | 用途 | 位置 |
|------|------|------|
| `INSTALL_` | 服務安裝指南 | `/docs/` |
| `DEVELOP_` | 開發指南 | `/docs/` |
| `*_SPEC.md` | 規格定義 | `/docs/` |
| `*_DESIGN.md` | 設計文件 | `/docs/` |
| `API_REFERENCE.md` | API 參考文件 | `/docs/` |
| `README.md` | 專案總覽 | `/` |
| `AGENTS.md` | AI 代理指令 | `/` |
| `CHANGELOG.md` | 變更日誌 | `/` |

266
docs_v1.0/OPERATIONS/DOCUMENT_AUDIT_REPORT.md
View File

@@ -1,266 +0,0 @@
# docs_v1.0 文件規範分析報告
---
document_type: "analysis_report"
service: "MOMENTRY_CORE"
title: "docs_v1.0 文件規範分析報告"
date: "2026-04-25"
status: "active"
current_state: "draft"
owner: "Warren"
created_by: "OpenCode"
created_at: "2026-04-25"
version: "V1.0"
tags:
- "documentation"
- "ai-agent"
- "analysis"
- "docs_v1.0"
ai_query_hints:
- "docs_v1.0 文件規範有哪些缺失？"
- "如何改進文件的 AI Agent 友好性？"
- "哪些文件需要補充 YAML Frontmatter？"
---
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-25 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 創建 docs_v1.0 文件規範分析報告 | OpenCode | OpenCode |
---
## 概述
本文檔對 `docs_v1.0` 目錄下所有文件進行全面掃描與分析，識別出 AI Agent 友好性方面的缺失，並提出具體的改進建議。
---
## 1. 文件總覽統計
| 項目 | 數量 |
|------|------|
| Markdown 文件總數 | 165 |
| 已有 YAML Frontmatter | 157 (95.2%) |
| 缺少 YAML Frontmatter | 8 (4.8%) |
| AI-optimized 模板 | 6 (位於 templates/ 目錄) |
### 目錄分佈
| 目錄 | 文件數 | 說明 |
|------|--------|------|
| ARCHITECTURE/ | 61 | 架構設計文件 |
| IMPLEMENTATION/ | 37 | 實作與安裝指南 |
| OPERATIONS/ | 25 | 運維紀錄 (含 maintenance_records/) |
| REFERENCE/ | 26 | 參考文件 |
| TESTING/ | 10 | 測試相關文件 |
| STANDARDS/ | 2 | 規範文件 |
| 根目錄 | 4 | 其他文件 |
---
## 2. 缺失分析
### 2.1 缺少 YAML Frontmatter 的文件 (8 個)
| 文件路徑 | 類型 | 建議動作 |
|----------|------|----------|
| `ARCHITECTURE/API_KEY_ARCHITECTURE.md` | 架構設計 | 補充 YAML Frontmatter |
| `ARCHITECTURE/N8N_WORKFLOW_VIDEO_RAG_MCP.md` | 架構設計 | 補充 YAML Frontmatter |
| `IMPLEMENTATION/PLACES365_INSTALLATION.md` | 安裝指南 | 補充 YAML Frontmatter |
| `IMPLEMENTATION/PLACES365_MODEL_GUIDE.md` | 使用指南 | 補充 YAML Frontmatter |
| `IMPLEMENTATION/YOLO_RESUME_INTEGRATION.md` | 整合指南 | 補充 YAML Frontmatter |
| `REFERENCE/AI_DRIVEN_PROCESSOR_CONTRACT.md` | 參考文件 | 補充 YAML Frontmatter |
| `REFERENCE/AI_PROCESSOR_COMPLIANCE_CHECKLIST.md` | 檢查清單 | 補充 YAML Frontmatter |
| `REFERENCE/AI_PROCESSOR_MODULE_REVISION_RECORDS.md` | 修訂紀錄 | 補充 YAML Frontmatter |
### 2.2 現有 YAML Frontmatter 的品質問題
經抽查現有文件，發現以下問題：
| 問題 | 影響 | 建議 |
|------|------|------|
| 缺少 `tags` 欄位 | AI 無法進行分類檢索 | 補上相關標籤 |
| 缺少 `ai_query_hints` 欄位 | RAG 檢索命中率低 | 補上查詢提示 |
| 缺少 `service` 欄位 | 無法按服務篩選文件 | 補上服務名稱 |
| `document_type` 未標準化 | 類型不一致影響查詢 | 統一使用標準值 |
| Markdown 表格與 YAML 不同步 | 數據不一致 | 建立同步機制 |
---
## 3. 規範符合度評估
### 3.1 DOCS_STANDARD.md 規範檢查
| 規範項目 | 符合度 | 說明 |
|----------|--------|------|
| 檔案命名規範 | ✅ 95% | 大部分符合 PascalCase 和全大寫服務名 |
| 版本歷史表 | ✅ 90% | 大部分文件包含 |
| 概述章節 | ✅ 95% | 大部分文件包含 |
| YAML Frontmatter | ❌ 0% | 規範中**原本未定義** (已於本次更新補齊) |
| AI 查詢提示 | ❌ 0% | 規範中**原本未定義** (已於本次更新補齊) |
### 3.2 AI Agent 友好性評分
| 維度 | 分數 (0-100) | 說明 |
|------|-------------|------|
| 結構化元數據 | 40 | 大部分有 Markdown 表格，但缺少標準化 YAML |
| 查詢提示 | 0 | 幾乎所有文件缺少 `ai_query_hints` |
| 標籤系統 | 0 | 幾乎所有文件缺少 `tags` |
| 文件類型標記 | 0 | 缺少 `document_type` 欄位 |
| 總體評分 | **15/100** | 需大幅改進以符合 AI Agent 標準 |
---
## 4. 改進建議
### 4.1 立即執行 (高優先級)
#### 4.1.1 補充 8 個缺失文件的 YAML Frontmatter
為以下 8 個文件加入標準 YAML Frontmatter：
- `ARCHITECTURE/API_KEY_ARCHITECTURE.md`
- `ARCHITECTURE/N8N_WORKFLOW_VIDEO_RAG_MCP.md`
- `IMPLEMENTATION/PLACES365_INSTALLATION.md`
- `IMPLEMENTATION/PLACES365_MODEL_GUIDE.md`
- `IMPLEMENTATION/YOLO_RESUME_INTEGRATION.md`
- `REFERENCE/AI_DRIVEN_PROCESSOR_CONTRACT.md`
- `REFERENCE/AI_PROCESSOR_COMPLIANCE_CHECKLIST.md`
- `REFERENCE/AI_PROCESSOR_MODULE_REVISION_RECORDS.md`
#### 4.1.2 更新 DOCS_STANDARD.md (已完成)
已加入「第 10 章：AI Agent 友好規範」，定義：
- YAML Frontmatter 格式
- 標準化字段 (document_type, service, tags, ai_query_hints)
- 雙重格式設計要求
- 數據同步要求
### 4.2 短期執行 (中優先級)
#### 4.2.1 為所有 INSTALL_* 文件補充 YAML Frontmatter
`IMPLEMENTATION/` 下共有 16 個 `INSTALL_*.md` 文件，建議批次補充：
- `INSTALL_CADDY.md`
- `INSTALL_GITEA.md`
- `INSTALL_GITEA_MCP.md`
- `INSTALL_MARIADB.md`
- `INSTALL_MOMENTRY_API.md`
- `INSTALL_MONGODB.md`
- `INSTALL_N8N.md`
- `INSTALL_OLLAMA.md`
- `INSTALL_PHP.md`
- `INSTALL_POSTGRESQL.md`
- `INSTALL_QDRANT.md`
- `INSTALL_REDIS.md`
- `INSTALL_RUSTDESK.md`
- `INSTALL_SFTPGO.md`
- `INSTALL_SYNONYM_FOREST.md`
- `INSTALL_WORDPRESS.md`
#### 4.2.2 建立標準文件模板
在 `docs_v1.0/IMPLEMENTATION/` 下建立：
- `TEMPLATE_INSTALL_GUIDE.md`
- `TEMPLATE_DESIGN_DOC.md`
- `TEMPLATE_SPEC_DOC.md`
### 4.3 長期執行 (低優先級)
#### 4.3.1 批次補齊所有文件的 tags 和 ai_query_hints
針對 165 個文件，批次補充：
- `tags` 欄位 (建議 3-5 個標籤)
- `ai_query_hints` 欄位 (建議 3-5 個查詢提示)
#### 4.3.2 建立文件品質檢查工具
開發自動化腳本檢查：
- YAML Frontmatter 是否存在
- 必要欄位是否填寫
- Markdown 表格與 YAML 是否同步
- 標籤是否合理
---
## 5. 執行計畫
### Phase 1: 補齊缺失文件 (立即)
- [ ] 為 8 個缺失文件補充 YAML Frontmatter
- [ ] 驗證 DOCS_STANDARD.md 更新
### Phase 2: INSTALL 文件批次更新 (短期)
- [ ] 為 16 個 INSTALL_* 文件補充 YAML Frontmatter
- [ ] 建立標準模板文件
### Phase 3: 全面優化 (長期)
- [ ] 為所有 165 個文件補充 tags 和 ai_query_hints
- [ ] 建立文件品質檢查工具
- [ ] 建立定期審查機制
---
## 6. YAML Frontmatter 範例
### INSTALL 指南範例
```yaml
---
document_type: "installation_guide"
service: "POSTGRESQL"
title: "PostgreSQL 安裝指南 (本地部署)"
date: "2026-03-15"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "Warren"
tags:
- "database"
- "macos"
- "postgresql"
- "local-deployment"
ai_query_hints:
- "如何在 macOS 安裝 PostgreSQL？"
- "PostgreSQL 數據目錄路徑在哪裡？"
- "如何卸載 PostgreSQL 並保留數據？"
---
```
### 架構設計範例
```yaml
---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "File / Identity API 架構設計"
date: "2026-04-25"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "api"
- "file"
- "identity"
- "face"
- "candidate"
ai_query_hints:
- "查詢 File/Identity 核心架構設計"
- "查詢 People API 端點定義"
- "查詢 Candidate 狀態轉換流程"
---
```
---
## 版本資訊
- 版本: V1.0
- 分析日期: 2026-04-25
- 文件更新: 2026-04-25

340
docs_v1.0/OPERATIONS/FILE_CHANGE_MANAGEMENT.md
View File

@@ -1,340 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "文件修改管理規範 v1.0"
date: "2026-03-22"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "文件修改管理規範"
ai_query_hints:
- "查詢 文件修改管理規範 v1.0 的內容"
- "文件修改管理規範 v1.0 的主要目的是什麼？"
- "如何操作或實施 文件修改管理規範 v1.0？"
---
# 文件修改管理規範 v1.0
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-22 |
| 文件版本 | V1.0 |
---
## 1. 概述
本文檔定義 Momentry 專案的文件修改流程，確保不同工具/模型對文件的一致性理解，防止誤修改並保留完整的修改紀錄。
### 1.1 適用範圍
- 所有 `.md` 文件（技術文檔、安裝指南、API 文件等）
- 所有 `.rs` 文件（Rust 源代碼）
- 所有 `.sh` 文件（Shell 腳本）
- 所有 `.yaml` / `.yml` 文件（配置文件）
- 所有 `.json` 文件（配置及數據文件）
### 1.2 核心原則
1. **先讀後改**：修改前必須完整閱讀相關文件
2. **預檢清單**：修改前執行預檢查步驟
3. **變更對照**：修改後必須比對差異
4. **驗證確認**：變更後執行驗證測試
5. **完整紀錄**：所有修改必須記錄於版本歷史
---
## 2. 修改前預檢清單
### 2.1 文件閱讀要求
修改文件前，必須完成以下閱讀：
| 步驟 | 項目 | 說明 |
|------|------|------|
| 1 | 閱讀完整文件 | 不可僅閱讀部分章節 |
| 2 | 理解文件用途 | 確認文件的目標讀者 |
| 3 | 確認現有術語 | 使用一致的術語和命名 |
| 4 | 查閱相關文件 | 確認相關聯的文件 |
### 2.2 預檢問題清單
在修改前回答以下問題：
```
□ 1. 此修改是否影響其他文件？
□ 2. 此修改是否與現有規範衝突？
□ 3. 此修改是否需要更新版本歷史？
□ 4. 此修改是否需要新增測試？
□ 5. 此修改是否需要通知相關人員？
□ 6. 此修改是否有破壞性變更（Breaking Change）？
```
### 2.3 預檢命令
修改前執行以下命令確認現有狀態：
```bash
# 1. 確認 git 狀態
git status
# 2. 檢查相關文件的最新版本
git log -3 --oneline <file_path>
# 3. 查看現有版本歷史
cat docs/<file>.md | grep -A 20 "版本歷史"
```
---
## 3. 文件修改流程
### 3.1 標準修改流程
```
┌─────────────────────────────────────────────────────────────┐
│ Step 1: 閱讀 │
│ ├─ 完整閱讀目標文件 │
│ └─ 閱讀相關聯文件 │
├─────────────────────────────────────────────────────────────┤
│ Step 2: 預檢 │
│ ├─ 回答預檢問題清單 │
│ └─ 執行預檢命令 │
├─────────────────────────────────────────────────────────────┤
│ Step 3: 規劃 │
│ ├─ 說明修改內容 │
│ └─ 列出變更差異 │
├─────────────────────────────────────────────────────────────┤
│ Step 4: 修改 │
│ ├─ 執行修改 │
│ └─ 更新版本歷史 │
├─────────────────────────────────────────────────────────────┤
│ Step 5: 驗證 │
│ ├─ 執行 lint/format 檢查 │
│ └─ 執行相關測試 │
├─────────────────────────────────────────────────────────────┤
│ Step 6: 提交 │
│ └─ 撰寫清晰的 commit message │
└─────────────────────────────────────────────────────────────┘
```
### 3.2 預修改彙報格式
在執行修改前，必須先彙報以下內容：
```markdown
## 檔案
`<file_path>`
## 修改原因
<說明修改的目的>
## 變更內容
```diff
- <刪除的內容>
+ <新增的內容>
```
## 版本歷史更新
| 版本 | 日期 | 內容 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| Vx.x | YYYY-MM-DD | <修改說明> | <操作者> | <使用的工具> |
```
### 3.3 版本歷史格式
每個文件頂部必須包含版本歷史表：
```markdown
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-22 | 更新內容 | Warren | OpenCode / big-pickle |
```
---
## 4. 變更對照
### 4.1 diff 對照
修改後必須提供 diff 對照：
```bash
git diff <file_path>
```
### 4.2 變更類型分類
| 類型 | 標記 | 說明 |
|------|------|------|
| 新增 | `+` | 新增內容 |
| 刪除 | `-` | 刪除內容 |
| 修改 | `~` | 修改內容 |
| 移動 | `↕` | 移動位置 |
| 格式 | `@` | 格式變更 |
### 4.3 變更確認清單
```
□ 1. diff 輸出已確認
□ 2. 變更符合預期
□ 3. 無意外變更
□ 4. 版本歷史已更新
□ 5. 其他關聯文件已檢查
```
---
## 5. 驗證流程
### 5.1 自動化驗證
修改後執行以下自動化檢查：
```bash
# Rust 文件
cargo fmt -- --check
cargo clippy --lib
cargo test --lib
# Python 文件
ruff check <files>
ruff format --check <files>
# Markdown 文件
markdownlint <files>
# Shell 文件
shellcheck -S error <files>
```
### 5.2 手動驗證清單
```
□ 1. 文件語法正確
□ 2. 連結有效
□ 3. 格式一致
□ 4. 術語一致
□ 5. 版本歷史完整
□ 6. 變更記錄清晰
```
---
## 6. 提交規範
### 6.1 Commit Message 格式
```
<type>: <subject>
<body>
<footer>
```
### 6.2 Type 類型
| Type | 說明 |
|------|------|
| `feat` | 新功能 |
| `fix` | 錯誤修復 |
| `refactor` | 重構 |
| `docs` | 文檔更新 |
| `style` | 格式變更 |
| `test` | 測試相關 |
| `chore` | 維護工作 |
### 6.3 Commit Message 範例
```bash
# 文檔更新
git commit -m "docs: update INSTALL_MONGODB.md with LaunchAgent instructions
- Add LaunchDaemon plist installation steps
- Update management commands section
- Add version history entry
Closes: #xxx"
# 配置文件更新
git commit -m "fix: remove duplicate mongodb entry in monitor_config.yaml
The backup section had two mongodb entries which caused confusion.
Removed the duplicate config entry at line 408-414."
```
---
## 7. AI 工具修改額外規範
### 7.1 修改前確認
AI 工具修改文件前，必須：
1. **完整閱讀**：閱讀完整文件（不可只讀取部分）
2. **理解語境**：理解文件的用途和目標讀者
3. **查閱相關**：查閱相關聯文件確保一致性
4. **提出計畫**：修改前先提出變更計畫供確認
### 7.2 修改後確認
AI 工具修改文件後，必須：
1. **展示差異**：顯示修改的 diff 內容
2. **說明變更**：解釋每項變更的目的
3. **執行驗證**：執行相關的 lint/test 命令
4. **更新歷史**：更新版本歷史表
### 7.3 禁止事項
AI 工具**禁止**以下行為：
```
□ 未閱讀完整文件即進行修改
□ 未經確認直接執行大規模修改
□ 未提供 diff 即提交變更
□ 未更新版本歷史
□ 未執行驗證即聲稱完成
□ 擅自刪除其他工具/模型添加的內容
□ 無視現有文件規範
```
---
## 8. 審查清單
### 8.1 提交前審查
```
□ 1. 修改內容已完整閱讀
□ 2. 預檢問題清單已回答
□ 3. diff 對照已確認
□ 4. 版本歷史已更新
□ 5. 自動化驗證已通過
□ 6. 手動驗證清單已完成
□ 7. Commit message 符合規範
□ 8. 無敏感資訊泄露
```
### 8.2 Code Review 關注點
- [ ] 修改是否影響現有功能？
- [ ] 修改是否與專案規範一致？
- [ ] 是否有遺漏的關聯修改？
- [ ] 測試是否足夠？
- [ ] 文檔是否同步更新？
---
## 9. 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode / big-pickle |

98
docs_v1.0/OPERATIONS/IMPLEMENTATION_COMPATIBILITY_ANALYSIS.md
View File

@@ -1,98 +0,0 @@
# Implementation Compatibility Analysis Report
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-25 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 分析新架構與現有文件的相容性 | OpenCode | OpenCode |
---
## 概述
本文檔比對了「全新 File/Identity/Candidate 架構」與 `docs_v1.0` 現有文件的相容性，提出過時文件合併、刪除或重構的建議，並分析衝突內容。
---
## 1. 核心架構變更比對
### 1.1 資料庫變更
| 項目 | 舊設計 (Current) | 新設計 (Proposed) | 影響層級 |
|------|------------------|-------------------|----------|
| **主要媒體表** | `videos` (Video 專屬) | `files` (所有檔案: video/pdf/png...) | 高 (核心實體變更) |
| **身份表** | `face_identities` (僅限臉部) | `identities` (全域所有實體) | 高 (擴充型變更) |
| **人物表** | `person_identities` (影片級) | `file_identities` (關聯表) | 高 (結構變更) |
| **檢測表** | `face_detections`, `face_clusters` | `faces`, `candidates` | 中 (重構與合併) |
### 1.2 流程變更
| 項目 | 舊設計 (Current) | 新設計 (Proposed) |
|------|------------------|-------------------|
| **註冊** | `register` API 直接處理 | `probe` Processor 自動判斷與分類 |
| **身份歸屬** | 手動或 TMDB 觸發 | Candidate 狀態轉換與 Agent 建議 |
| **Face 處理** | `face_processor` 獨立運行 | 視為 Resource 指派的一環 |
---
## 2. 衝突文件分析
### 2.1 高衝突文件 (需大幅修改或刪除)
| 文件路徑 | 衝突內容 | 建議動作 | 原因 |
|----------|----------|----------|------|
| **ARCHITECTURE/TMDB_CHARACTER_INTEGRATION.md** | 詳細定義了 `global_person_identities` 和 `person_identities` 結構，與新架構完全不符。 | **刪除** | 新設計已在 `FILE_IDENTITY_API_DESIGN.md` 中定義了全新的 Identity 邏輯，此文檔已失效。 |
| **ARCHITECTURE/SPEAKER_INTEGRATION.md** | 依賴舊版 `global_person_identities` 表結構，提及 `voice_print`。 | **合併** | 將核心概念（聲紋匹配）整合至新的 Design Doc 中，並刪除本文檔。 |
| **ARCHITECTURE/IDENTITY_SYSTEM_DESIGN.md** | 定義了 `face_identities` 為檔案層級定妝表。 | **刪除** | 被 `FILE_IDENTITY_API_DESIGN.md` 取代。 |
### 2.2 中衝突文件 (需重構更新)
| 文件路徑 | 衝突內容 | 建議動作 | 原因 |
|----------|----------|----------|------|
| **ARCHITECTURE/PLAYGROUND_ARCHITECTURE.md** | 描述了 Playground 使用的舊表結構。 | **重構** | 更新為新的 `files`, `faces`, `identities` 結構。 |
| **ARCHITECTURE/chunking/CHUNKING_ENRICHMENT_PIPELINE.md** | 提到 `face_id_01` 查詢 `face_identities`。 | **重構** | 更新查詢邏輯，改為查詢 `identities` 表。 |
### 2.3 低衝突文件 (需更新名詞)
| 文件路徑 | 衝突內容 | 建議動作 | 原因 |
|----------|----------|----------|------|
| **OPERATIONS/PRODUCTION_DEPLOYMENT_GUIDE.md** | 包含 `videos` 表的索引指令和 `video_register` 資料庫備份。 | **更新** | 將 `videos` 改為 `files`，更新備份名稱。 |
| **OPERATIONS/BACKUP_VERSIONING.md** | 提及 `video_register` 資料庫。 | **更新** | 更新為 `files` 表相關的備份策略。 |
---
## 3. 執行建議
### 3.1 立即刪除 (已失效)
以下文件因架構被完全推翻，建議直接刪除：
1. `docs_v1.0/ARCHITECTURE/TMDB_CHARACTER_INTEGRATION.md`
2. `docs_v1.0/ARCHITECTURE/SPEAKER_INTEGRATION.md`
3. `docs_v1.0/ARCHITECTURE/IDENTITY_SYSTEM_DESIGN.md`
### 3.2 建立新文件 (Design Phase 2)
1. 將上述刪除文件中有價值的業務邏輯 (如: 聲紋提取邏輯、TMDB 角色映射邏輯) 遷移至 `FILE_IDENTITY_API_DESIGN.md` 或新的 `PROCESSOR_DESIGN.md`。
### 3.3 批量名詞替換
在 `docs_v1.0` 中執行全局替換 (需謹慎)：
- `person_identities` -> `file_identities` (僅限指代「人物在檔案中的出現」時)
- `face_identities` -> `identities` (僅限指代「全域身份」時)
---
## 4. 結論
目前的文檔庫 (`docs_v1.0`) 中，約有 **10%** 的架構設計文件與新系統不相容。在進入 Implementation 階段前，清理這些「殭屍文件」對於避免 AI Agent 檢索錯誤資訊至關重要。
---
## 版本資訊
- 版本: V1.0
- 分析日期: 2026-04-25
- 文件更新: 2026-04-25

457
docs_v1.0/OPERATIONS/INCIDENT_RESPONSE_PROCEDURE.md
View File

@@ -1,457 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "事件處理流程 (SOP)"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "事件處理流程"
ai_query_hints:
- "查詢 事件處理流程 (SOP) 的內容"
- "事件處理流程 (SOP) 的主要目的是什麼？"
- "如何操作或實施 事件處理流程 (SOP)？"
---
# 事件處理流程 (SOP)
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-03-27 |
| 文件版本 | V1.0 |
| 適用範圍 | Momentry 系統所有服務 |
| 參考文件 | DOCS_STANDARD.md, maintenance_records/README.md |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-27 | 創建事件處理流程 SOP | OpenCode | deepseek-reasoner |
---
## 1. 概述
本文件定義 Momentry 系統的事件處理標準作業程序 (SOP)，涵蓋事件檢測、報告、分類、處理、升級、關閉和歸檔的全生命周期管理。
### 1.1 目標
- 提供統一的事件處理框架
- 明確責任分配和時限要求
- 確保事件得到及時有效的解決
- 建立完整的文件記錄和經驗傳承
### 1.2 適用範圍
本 SOP 適用於所有 Momentry 系統相關的事件，包括但不限於：
- 服務中斷或不可用
- 性能問題（響應時間慢、資源耗盡）
- 安全事件（未授權訪問、數據洩露）
- 數據問題（數據損壞、不一致）
- 配置錯誤
- 用戶報告的問題
---
## 2. 事件嚴重等級定義
### 2.1 等級分類
| 等級 | 代碼 | 影響描述 | 處理時間目標 | 文件要求 | 通知要求 |
|------|------|----------|--------------|----------|----------|
| P0 | 緊急 | 服務完全中斷，影響所有用戶 | 立即處理，1小時內解決 | 必須創建 RCA | 立即通知所有相關人員 |
| P1 | 高 | 主要功能不可用，影響多數用戶 | 2小時內開始處理，4小時內解決 | 建議創建 RCA | 1小時內通知負責人 |
| P2 | 中 | 次要功能問題，影響部分用戶 | 4小時內開始處理，8小時內解決 | 可選創建 RCA | 2小時內通知負責人 |
| P3 | 低 | 輕微問題，不影響核心功能 | 1個工作日內處理 | 事件報告即可 | 工作日內通知 |
| P4 | 資訊 | 諮詢、建議或非緊急問題 | 3個工作日內回應 | 簡單紀錄 | 無需緊急通知 |
### 2.2 等級評估準則
#### P0 緊急事件（符合任一條件）
- 核心服務完全不可用（網站無法訪問、API 完全無響應）
- 數據庫完全無法連接
- 安全事件導致系統被入侵
- 影響所有用戶的關鍵功能故障
#### P1 高級事件（符合任一條件）
- 主要功能模塊不可用（如視頻處理、搜索功能失效）
- 影響超過 50% 用戶的功能問題
- 性能嚴重下降（響應時間 > 10秒）
- 數據丟失或損壞風險
#### P2 中級事件（符合任一條件）
- 次要功能問題（如報告生成、特定查詢失敗）
- 影響部分用戶（< 50%）的功能問題
- 中等性能問題（響應時間 3-10秒）
- 配置錯誤但不影響核心功能
#### P3 低級事件
- 界面顯示問題（錯別字、格式不正確）
- 輕微性能問題（響應時間 1-3秒）
- 功能建議或改進請求
- 不影響功能的日誌警告
#### P4 資訊事件
- 一般諮詢問題
- 功能使用方法詢問
- 非緊急的建議
- 文檔更新請求
---
## 3. 事件處理流程
### 3.1 整體流程圖
```
事件檢測 → 報告與分類 → 等級評估 → 處理 → 關閉 → 歸檔
↓ ↓ ↓ ↓ ↓ ↓
監控警報 創建事件報告 確定等級 實施解決 驗證解決 文件歸檔
用戶報告 指派負責人 設定時限 狀態更新 創建 RCA 經驗總結
```
### 3.2 詳細步驟
#### 步驟 1：事件檢測與報告
**檢測來源**：
1. **監控系統警報**（自動檢測）
2. **用戶報告**（通過支持渠道）
3. **系統日誌分析**（異常錯誤）
4. **例行檢查發現**
**報告要求**：
1. 發現事件後立即報告，不應延遲
2. 提供盡可能詳細的信息：
- 問題現象描述
- 發生時間
- 影響範圍
- 重現步驟（如可重現）
- 相關錯誤訊息或日誌
3. 使用指定渠道報告（團隊溝通工具、郵件等）
#### 步驟 2：創建事件報告文件
**文件創建時限**：
- P0-P1：15分鐘內
- P2-P3：1小時內
- P4：1個工作日內
**創建步驟**：
```bash
# 1. 複製事件模板
cp docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_INCIDENT.md \
docs/maintenance_records/incidents/_active/INCIDENT_<服務>_<問題>_$(date +%Y_%m_%d).md
# 2. 編輯文件內容，填寫基本資訊
# 3. 更新狀態為 ⏳ 待處理
```
**文件填寫要求**：
- 完整填寫頂部資訊表
- 詳細描述問題現象
- 初步評估影響範圍
- 指定負責人（如已知）
#### 步驟 3：等級評估與分類
**評估人員**：
- 初步：事件報告者或值班人員
- 確認：技術負責人或團隊負責人
**評估流程**：
1. 根據「2.2 等級評估準則」確定初步等級
2. 與相關人員確認等級評估
3. 在事件報告中記錄評估結果
4. 根據等級設定處理時限和通知要求
**等級調整**：
- 如發現初始評估不準確，應及時調整等級
- 記錄等級調整的原因和時間
- 通知相關人員等級變更
#### 步驟 4：事件處理
**處理時限要求**：
| 等級 | 開始處理時限 | 解決時限 | 狀態更新頻率 |
|------|--------------|----------|--------------|
| P0 | 立即（5分鐘內） | 1小時 | 每15分鐘 |
| P1 | 2小時內 | 4小時 | 每30分鐘 |
| P2 | 4小時內 | 8小時 | 每2小時 |
| P3 | 1個工作日內 | 2個工作日 | 每日 |
| P4 | 3個工作日內 | 5個工作日 | 每週 |
**處理步驟**：
1. **狀態更新**：將事件狀態改為 🔍 調查中
2. **問題調查**：
- 收集相關日誌和指標
- 分析問題根本原因
- 確認影響範圍
3. **制定方案**：
- 確定解決方案
- 評估方案風險
- 準備實施計劃
4. **方案實施**：
- 將狀態改為 🔧 處理中
- 實施解決方案
- 監控實施效果
5. **驗證修復**：
- 確認問題已解決
- 驗證功能恢復正常
- 檢查無副作用
**溝通要求**：
- 定期更新事件狀態（按上表頻率）
- 重大進展及時通知相關人員
- 記錄所有處理步驟和決策
#### 步驟 5：升級為 RCA 分析
**何時需要 RCA**：
- 所有 P0 事件必須進行 RCA
- P1 事件建議進行 RCA
- 重複發生的 P2-P3 事件
- 有學習價值的任何事件
**RCA 創建時限**：
- P0：事件解決後 24 小時內
- P1：事件解決後 48 小時內
- P2-P3：事件解決後 1 週內
**創建步驟**：
```bash
# 1. 複製 RCA 模板
cp docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_RCA.md \
docs/maintenance_records/rca/_active/RCA_<服務>_<問題>_$(date +%Y_%m_%d).md
# 2. 連結相關事件報告
# 3. 進行深入分析
```
#### 步驟 6：事件關閉
**關閉條件**：
1. 問題已確認解決
2. 功能恢復正常
3. 用戶確認問題解決（如適用）
4. RCA 已完成（如需要）
5. 所有相關文件已更新
**關閉步驟**：
1. **更新狀態**：將事件狀態改為 ✅ 已解決
2. **驗證確認**：
- 負責人確認問題解決
- 相關人員驗證功能正常
3. **移動文件**：
```bash
# 將文件從 _active/ 移動到 _completed/
mv docs/maintenance_records/incidents/_active/INCIDENT_*.md \
docs/maintenance_records/incidents/_completed/
```
4. **通知關閉**：通知相關人員事件已關閉
#### 步驟 7：文件歸檔
**歸檔時機**：
- 事件關閉後保留在 _completed/ 目錄 30 天
- 超過保留期限後歸檔到 _archived/
**歸檔規則**：
| 文件類型 | 完成保留期 | 歸檔保留期 | 總保留期 |
|----------|------------|------------|----------|
| P0 事件 | 30 天 | 11 個月 | 1 年 |
| P1 事件 | 30 天 | 11 個月 | 1 年 |
| P2-P3 事件 | 30 天 | 11 個月 | 1 年 |
| RCA 文件 | 30 天 | 23 個月 | 2 年 |
**歸檔操作**：
```bash
# 每月執行歸檔檢查（可使用自動化腳本）
# 檢查 _completed/ 中的文件是否超過保留期限
# 移動過期文件到 _archived/
```
---
## 4. 角色與責任
### 4.1 事件報告者
- **職責**：發現並報告事件，創建初步事件報告
- **技能要求**：基本的問題描述能力，熟悉報告渠道
- **時限要求**：按等級要求及時報告
### 4.2 值班工程師
- **職責**：接收事件報告，初步評估等級，分配負責人
- **技能要求**：了解系統架構，能夠初步判斷問題嚴重性
- **時限要求**：P0-P1 事件 15 分鐘內響應
### 4.3 技術負責人
- **職責**：確認事件等級，協調處理資源，審核解決方案
- **技能要求**：深入系統知識，問題解決能力，協調能力
- **時限要求**：按等級要求參與處理決策
### 4.4 處理工程師
- **職責**：調查問題原因，實施解決方案，更新狀態
- **技能要求**：相關技術領域專業知識，問題排查能力
- **時限要求**：按等級要求完成處理
### 4.5 驗證人員
- **職責**：驗證問題解決，確認功能恢復，關閉事件
- **技能要求**：測試驗證能力，用戶視角理解
- **時限要求**：解決後 2 小時內完成驗證（P0-P1）
---
## 5. 溝通與通知
### 5.1 通知矩陣
| 事件等級 | 通知對象 | 通知時限 | 通知方式 | 更新頻率 |
|----------|----------|----------|----------|----------|
| P0 | 所有相關人員 | 立即（5分鐘內） | 即時通訊+電話 | 每15分鐘 |
| P1 | 技術團隊+管理層 | 1小時內 | 即時通訊+郵件 | 每30分鐘 |
| P2 | 技術團隊 | 2小時內 | 即時通訊 | 每2小時 |
| P3 | 相關工程師 | 工作日內 | 即時通訊 | 每日 |
| P4 | 無需緊急通知 | 3工作日內 | 任務系統 | 每週 |
### 5.2 狀態更新模板
**調查中更新**：
```
事件：<事件標題>
狀態：🔍 調查中
進度：正在收集日誌/分析原因
預計更新：<時間>
負責人：<姓名>
```
**處理中更新**：
```
事件：<事件標題>
狀態：🔧 處理中
進度：已確定解決方案，正在實施
預計解決時間：<時間>
影響：<當前影響範圍>
```
**已解決更新**：
```
事件：<事件標題>
狀態：✅ 已解決
解決時間：<時間>
解決方案：<簡要描述>
後續行動：<RCA/改進計劃>
```
---
## 6. 工具與自動化
### 6.1 監控系統集成
- **監控配置**：`monitor/config/monitor_config.yaml`
- **警報規則**：根據服務重要性設定閾值
- **自動通知**：配置 n8n/webhook/Email 通知
### 6.2 文件管理自動化
```bash
# 示例：事件報告自動創建腳本
#!/bin/bash
# create_incident_report.sh
TEMPLATE="docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_INCIDENT.md"
DATE=$(date +%Y_%m_%d)
SERVICE=$1
ISSUE=$2
FILENAME="docs/maintenance_records/incidents/_active/INCIDENT_${SERVICE}_${ISSUE}_${DATE}.md"
cp "$TEMPLATE" "$FILENAME"
echo "事件報告已創建：$FILENAME"
```
### 6.3 狀態追蹤
- 使用文件狀態標記（⏳🔍🔧✅📁🗄️）
- 定期檢查 _active/ 目錄中的文件處理進度
- 自動提醒超時事件
### 6.4 AI 優化功能
- **AI 優化模板**: 所有模板包含 YAML frontmatter，支持 AI Agent 高效解析
- **自動化工作流**: 支持狀態變更、文件移動、通知觸發的自動化
- **查詢優化**: 標準化查詢語法，便於 AI Agent 搜索和分析
- **參考指南**: 詳見 `AI_AGENT_DOCUMENTATION_GUIDE.md`
---
## 7. 常見問題處理指南
### 7.1 服務不可用
1. **檢查步驟**：
- 確認服務進程是否運行
- 檢查端口是否監聽
- 查看服務日誌
- 檢查依賴服務狀態
2. **常見原因**：
- 配置錯誤
- 資源不足（內存、CPU）
- 依賴服務故障
- 網絡問題
### 7.2 性能問題
1. **檢查步驟**：
- 檢查系統資源使用率
- 分析應用日誌
- 檢查數據庫性能
- 監控網絡延遲
2. **常見原因**：
- 查詢效率低下
- 緩存失效
- 資源競爭
- 配置不當
### 7.3 數據問題
1. **檢查步驟**：
- 驗證數據完整性
- 檢查數據庫連接
- 審查最近變更
- 備份驗證
2. **常見原因**：
- 遷移腳本錯誤
- 並發操作衝突
- 存儲故障
- 應用邏輯錯誤
---
## 8. 附錄
### 8.1 相關文件
- `docs_v1.0/OPERATIONS/maintenance_records/README.md` - 維護紀錄目錄說明
- `docs_v1.0/STANDARDS/DOCS_STANDARD.md` - 文件創建規範
- `docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_INCIDENT.md` - 事件報告模板
- `docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_RCA.md` - RCA 模板
- `monitor/config/monitor_config.yaml` - 監控配置
### 8.2 參考資源
- 團隊溝通工具頻道
- 監控儀表板連結
- 系統架構文檔
- 緊急聯絡人名單
### 8.3 培訓材料
- 新成員事件處理培訓
- 定期流程復盤會議
- 案例分享會
---
## 9. 簽核
| 角色 | 姓名 | 簽字 | 日期 | 備註 |
|------|------|------|------|------|
| 建立者 | OpenCode | - | 2026-03-27 | 初版創建 |
| 技術審核 | Warren | | | |
| 運維負責人 | Warren | | | |
| 最終批准 | Warren | | | |
> **注意**：本文檔需經技術負責人和運維負責人審核後正式生效。

364
docs_v1.0/OPERATIONS/INTEGRATED_PLAYER_GUIDE.md
View File

@@ -1,364 +0,0 @@
# Integrated Player 使用指南
## 功能
整合播放器可以同時顯示：
- **ASR**: 文字字幕
- **Face**: 人臉檢測框和截圖
- **Self ASRX**: 說話人 ID + 演員名 + 角色名
- **Pose**: 嘴部關鍵點動作
## 編譯
```bash
cargo build --bin integrated_player
```
## 使用方式
### 🎬 自動演示模式（新功能）
最簡單的方式，自動播放所有說話人的片段：
```bash
# 快速演示（推薦）
./run_demo.sh --quick
# 標準演示
./run_demo.sh
# 自定義演示
./target/debug/integrated_player \
--video /tmp/charade_audio.wav \
--asrx /tmp/asrx_charade_optimized.json \
--demo \
--demo-segments-per-speaker 5 \
--demo-speed 1.5
```
**演示參數**：
- `--demo`: 啟用自動演示模式
- `--demo-segments-per-speaker`: 每個說話人演示的片段數（默認 3）
- `--demo-speed`: 演示速度倍數（默認 2.0）
**演示特點**：
- ✅ 自動播放所有說話人
- ✅ 顯示演員名和角色名
- ✅ 可調整播放速度
- ✅ 適合展示和測試
### 基本用法
```bash
./target/debug/integrated_player \
--video /path/to/video.mp4 \
--asr /path/to/asr.json \
--face /path/to/face.json \
--asrx /path/to/asrx.json \
--pose /path/to/pose.json
```
### 短參數
```bash
./target/debug/integrated_player \
-v video.mp4 \
-r asr.json \
-f face.json \
-x asrx.json \
-p pose.json
```
### 自動播放特定說話人
```bash
./target/debug/integrated_player \
--video /tmp/charade_audio.wav \
--asrx /tmp/asrx_charade_optimized.json \
--auto-play-speaker \
--speaker-name SPEAKER_0
```
## 交互命令
進入交互模式後，可以使用以下命令：
- `<時間>`: 跳轉到指定時間（秒）
- 示例: `300.5` 跳轉到 5分30秒
- `s` 或 `show`: 顯示當前時間的整合信息
- 顯示文字、說話人、人臉、嘴部動作
- `l` 或 `list`: 列出所有說話人統計
- 顯示說話人 ID、演員名、角色名、片段數、總時長
- `p <說話人ID>`: 播放該說話人的片段
- 示例: `p SPEAKER_1` 播放 SPEAKER_1 的片段
- `q` 或 `quit` 或 `exit`: 退出播放器
## 數據格式
### ASR 格式
```json
{
"language": "en",
"segments": [
{
"start": 60.0,
"end": 62.0,
"text": "You"
}
]
}
```
### Face 格式
```json
{
"results": {
"detections": [
{
"frame": 554,
"timestamp": 23.08,
"x": 78,
"y": 88,
"width": 74,
"height": 74,
"confidence": 1.0
}
]
}
}
```
### ASRX 格式
```json
{
"segments": [
{
"index": 0,
"start": 1.8,
"end": 2.6,
"duration": 0.8,
"speaker": "SPEAKER_5"
}
],
"speaker_stats": {
"SPEAKER_0": {
"count": 654,
"duration": 1766.5
}
}
}
```
### Pose 格式
```json
{
"frames": [
{
"frame": 12,
"timestamp": 0.545,
"persons": [
{
"keypoints": [
{
"name": "mouth",
"x": 100.5,
"y": 50.2,
"confidence": 0.85
}
],
"bbox": {
"x": 90,
"y": 40,
"width": 20,
"height": 30
}
}
]
}
]
}
```
## 測試案例
### Charade 1963 (114.7 分鐘)
```bash
# 準備數據
export VIDEO=/tmp/charade_audio.wav
export ASRX=/tmp/asrx_charade_optimized.json
export FACE=/tmp/face_long.json
export INTEGRATED=/tmp/charade_integrated.json
# 播放 SPEAKER_0 (Cary Grant)
./target/debug/integrated_player \
--video $VIDEO \
--asrx $ASRX \
--face $FACE \
--auto-play-speaker \
--speaker-name SPEAKER_0
# 交互模式
./target/debug/integrated_player \
--video $VIDEO \
--asrx $ASRX
# 進入後輸入:
# l - 列出說話人
# p SPEAKER_1 - 播放 Audrey Hepburn
# s - 顯示當前片段信息
# q - 退出
```
## 輸出示例
### 說話人統計
```
📊 Speaker Statistics:
────────────────────────────────────────────────────────────────────────────────
Speaker ID Actor Character Segments Duration
────────────────────────────────────────────────────────────────────────────────
SPEAKER_0 Cary Grant Peter Joshua 654 1766.5s
SPEAKER_1 Audrey Hepburn Regina Lampert 403 1121.8s
SPEAKER_2 Walter Matthau Hamilton Bartholomew 49 65.7s
SPEAKER_4 James Coburn Tex Panthollow 3 42.0s
────────────────────────────────────────────────────────────────────────────────
```
### 片段信息
```
================================================================================
⏱ Time: 299.50s - 303.10s
📝 Text: You know, I think I'm beginning to like this painting.
🎤 Speaker: SPEAKER_1 → Audrey Hepburn (Regina Lampert)
👤 Face: bbox=(1250,178) 147x206, confidence=0.88
👄 Mouth landmarks: 3 points
• mouth_left: (100.5, 50.2) conf=0.85
• mouth_right: (110.3, 49.8) conf=0.87
• nose: (105.0, 45.0) conf=0.90
================================================================================
```
## 功能特點
### 1. 自動說話人識別
- 自動檢測影片中的說話人
- 顯示演員名和角色名
- 統計每個說話人的片段數和時長
### 2. 人臉檢測整合
- 顯示人臉位置和大小
- 顯示檢測置信度
- 時間同步顯示
### 3. 嘴部動作追蹤
- 提取嘴部關鍵點
- 顯示嘴部座標和置信度
- 過濾顯示相關關鍵點
### 4. 字幕同步
- 自動載入 ASR 文字
- 時間同步顯示
- 支持多語言
## 技術實現
### 核心組件
1. **IntegratedSegment**: 整合數據結構
- start/end: 時間範圍
- text: ASR 文字
- speaker: 說話人 ID
- face: 人臉檢測信息
- mouth_landmarks: 嘴部關鍵點
2. **IntegratedPlayer**: 播放器核心
- 載入各種數據格式
- 時間同步查詢
- 信息整合顯示
3. **播放控制**:
- ffplay 音頻播放
- 時間跳轉
- 片段播放
## 未來擴展
### 待實現功能
1. **視頻播放**: 整合 SDL2 顯示視頻畫面
2. **字幕疊加**: 在視頻上疊加 ASR 文字
3. **人臉標註**: 在視頻上畫出人臉框
4. **說話人切換**: 自動跳轉到說話人片段
5. **關鍵詞搜索**: 搜索特定文字並跳轉
6. **導出功能**: 導出整合結果為字幕文件
### GUI 擴展
可考慮使用以下框架實現圖形界面：
- **egui**: 即時模式 GUI
- **slint**: 聲明式 UI
- **iced**: Elm 架構 GUI
## 性能優化
### 當前實現
- 使用 HashMap 存儲說話人映射
- 使用迭代器進行時間查詢
- 使用線程進行播放控制
### 優化建議
1. **索引結構**: 為時間查詢建立索引
2. **預加載**: 預先載入下一個片段
3. **快取**: 快取常用片段信息
4. **並行**: 並行載入多個數據源
## 相關文檔
- `FINAL_TEST_REPORT.md`: 測試報告
- `LONG_MOVIE_TEST_SUMMARY.md`: 長影片測試
- `GUI_FACE_PLAYER_USAGE.md`: GUI 播放器使用
## 問題排查
### 常見問題
1. **找不到數據文件**
- 確認文件路徑正確
- 檢查文件格式是否正確
2. **播放失敗**
- 確認 ffplay 已安裝
- 檢查視頻文件是否存在
3. **無法識別說話人**
- 確認 ASRX 數據格式正確
- 檢查 speaker_stats 是否存在
### 調試模式
```bash
RUST_LOG=debug ./target/debug/integrated_player ...
```
---
**創建日期**: 2026-04-02
**版本**: 1.0.0
**作者**: Momentry Team

693
docs_v1.0/OPERATIONS/MOMENTRY_CORE_MONITORING.md
View File

@@ -1,693 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "Momentry Core 監控規範 (暫定)"
date: "2026-03-17"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "momentry"
- "core"
- "監控規範"
ai_query_hints:
- "查詢 Momentry Core 監控規範 (暫定) 的內容"
- "Momentry Core 監控規範 (暫定) 的主要目的是什麼？"
- "如何操作或實施 Momentry Core 監控規範 (暫定)？"
---
# Momentry Core 監控規範 (暫定)
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-17 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-17 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-25 | 新增可配置 Redis Key Prefix 說明 | Warren | OpenCode / GLM-5 |
| V1.2 | 2026-03-25 | 新增 Job Worker 監控、processor_results 表 | Warren | OpenCode / GLM-5 |
---
> **⚠️ 狀態**: 此文檔為暫定版本，momentry_core 仍在開發中，待開發完成後再正式納入監控系統。
---
## 1. 概述
momentry_core 是 Rust 開發的數字資產管理系統，專注於視頻分析和 RAG 功能。
## 2. 監控架構
### Layer 2: Service 監控
| 項目 | 類型 | 檢查方式 | Port | 狀態 |
|------|------|----------|------|------|
| postgresql | TCP | `pg_isready` | 5432 | ✅ 運行中 |
| redis | TCP | `redis-cli ping` | 6379 | ✅ 運行中 |
| n8n | HTTP | `/healthz` | 5678 | ✅ 運行中 |
| sftpgo | HTTP | `/healthz`, `/api/v2/token` | 8080 | ✅ 運行中 |
| qdrant | HTTP | `/collections` | 6333 | ✅ 運行中 |
| momentry_core | CLI | `momentry --version` | - | ⚠️ 待編譯 |
**附屬服務狀態** (非核心但相關):
| gitea | HTTP | `/` | 3000 | ✅ 運行中 |
| ollama | HTTP | `/api/tags` | 11434 | ✅ 運行中 |
| caddy | HTTP | `/` | 80 | ✅ 運行中 |
### Layer 7: Backup 監控
| 項目 | 類型 | 位置 |
|------|------|------|
| momentry | data | `/Users/accusys/momentry/backup/momentry` |
| sftpgo | config + db | `/Users/accusys/momentry/backup/daily/sftpgo/` |
---
## 3. Redis 監控架構
> **⚠️ 注意**: 從 V1.1 開始，所有 Redis Keys 都支援自定義前綴。
> 預設前綴：生產環境為 `momentry:`，開發環境為 `momentry_dev:`
>
> 若使用非預設前綴，請將下方命令中的 `momentry:` 替換為實際前綴。
### 3.1 健康檢查
```bash
# 檢查 Redis 連線
redis-cli -a accusys ping
# 檢查 momentry 健康狀態
redis-cli GET momentry:health:current
```
### 3.2 Job 狀態監控
```bash
# 查看運行中的 Jobs
redis-cli SMEMBERS momentry:jobs:active
# 查看 Job 狀態
redis-cli HGETALL momentry:job:5dea6618a606e7c7
```
### 3.3 即時進度監控
```bash
# 訂閱進度頻道
redis-cli SUBSCRIBE momentry:progress:5dea6618a606e7c7
```
---
## 4. 監控腳本
### 4.1 健康檢查項目細節
基於當前系統狀態，需要監控的核心項目:
#### 4.1.1 資料庫服務檢查
```bash
# PostgreSQL - 檢查伺服器運行與關鍵資料庫
check_postgresql() {
if pg_isready -h localhost -p 5432 > /dev/null 2>&1; then
echo -e "${GREEN}✓${NC} PostgreSQL"
# 檢查關鍵資料庫是否存在
local missing_dbs=()
for db in momentry video_register n8n sftpgo; do
if ! psql -h localhost -U postgres -lqt 2>/dev/null | cut -d\| -f1 | grep -qw "$db"; then
missing_dbs+=("$db")
fi
done
if [ ${#missing_dbs[@]} -gt 0 ]; then
echo -e " ${YELLOW}⚠${NC} 缺失資料庫: ${missing_dbs[*]}"
record_service "postgresql" "warning" "1" "Missing databases: ${missing_dbs[*]}"
else
record_service "postgresql" "up" "1" ""
fi
else
echo -e "${RED}✗${NC} PostgreSQL"
record_service "postgresql" "down" "0" "PostgreSQL not responding"
fi
}
```
#### 4.1.2 Redis 檢查
```bash
check_redis() {
if redis-cli -a "$REDIS_PASSWORD" ping 2>/dev/null | grep -q PONG; then
echo -e "${GREEN}✓${NC} Redis"
record_service "redis" "up" "1" ""
else
echo -e "${RED}✗${NC} Redis"
record_service "redis" "down" "0" "Redis not responding"
fi
}
```
#### 4.1.3 SFTPGo 檢查
```bash
check_sftpgo() {
# 1. 檢查 HTTP API
if curl -s http://localhost:8080/healthz > /dev/null 2>&1; then
# 2. 檢查 API 認證
if TOKEN=$(curl -s -X GET http://localhost:8080/api/v2/token -u "admin:$SFTPGO_ADMIN_PASSWORD" 2>/dev/null | jq -r '.access_token') && [ -n "$TOKEN" ]; then
echo -e "${GREEN}✓${NC} SFTPGo"
record_service "sftpgo" "up" "1" ""
else
echo -e "${YELLOW}⚠${NC} SFTPGo (API認證失敗)"
record_service "sftpgo" "warning" "1" "API authentication failed"
fi
else
echo -e "${RED}✗${NC} SFTPGo"
record_service "sftpgo" "down" "0" "HTTP API not responding"
fi
}
```
#### 4.1.4 n8n 檢查
```bash
check_n8n() {
if curl -s http://localhost:5678/healthz > /dev/null 2>&1; then
echo -e "${GREEN}✓${NC} n8n"
record_service "n8n" "up" "1" ""
else
echo -e "${RED}✗${NC} n8n"
record_service "n8n" "down" "0" "API not responding"
fi
}
```
#### 4.1.5 Qdrant 檢查
```bash
check_qdrant() {
if curl -s http://localhost:6333/collections > /dev/null 2>&1; then
echo -e "${GREEN}✓${NC} Qdrant"
record_service "qdrant" "up" "1" ""
else
echo -e "${RED}✗${NC} Qdrant"
record_service "qdrant" "down" "0" "API not responding"
fi
}
```
#### 4.1.6 Momentry Core 檢查
```bash
check_momentry_core() {
local binary="/Users/accusys/momentry/target/release/momentry"
if [ ! -f "$binary" ]; then
binary="/Users/accusys/momentry/target/debug/momentry"
fi
if [ -f "$binary" ] && $binary --version > /dev/null 2>&1; then
echo -e "${GREEN}✓${NC} Momentry Core"
record_service "momentry_core" "up" "1" ""
else
echo -e "${RED}✗${NC} Momentry Core"
record_service "momentry_core" "down" "0" "Binary not found or not executable"
fi
}
```
### 4.2 檢查腳本範例完整實現
```bash
#!/bin/bash
# monitor/service/health_check.sh
export REDIS_PASSWORD="accusys"
export SFTPGO_ADMIN_PASSWORD="Test3200Test3200"
check_postgresql
check_redis
check_sftpgo
check_n8n
check_qdrant
check_momentry_core
```
### 4.2 Redis Job 監控腳本
**檔案**: `monitor/service/redis_job_monitor.sh`
此腳本專門監控 Redis 中的 Job 狀態與即時進度:
```bash
#!/bin/bash
# Momentry Core Redis Job 監控
REDIS_PASSWORD="${REDIS_PASSWORD:-accusys}"
REDIS_PREFIX="${REDIS_PREFIX:-momentry:}"# 可配置前綴，預設 momentry:
# 檢查 Job 狀態
check_job_status() {
local active_jobs=$(redis-cli -a "$REDIS_PASSWORD" SCARD "${REDIS_PREFIX}jobs:active" 2>/dev/null || echo "0")
local completed_jobs=$(redis-cli -a "$REDIS_PASSWORD" SCARD "${REDIS_PREFIX}jobs:completed" 2>/dev/null || echo "0")
local failed_jobs=$(redis-cli -a "$REDIS_PASSWORD" SCARD "${REDIS_PREFIX}jobs:failed" 2>/dev/null || echo "0")
echo "Momentry Jobs: Active=$active_jobs, Completed=$completed_jobs, Failed=$failed_jobs"
echo "$active_jobs $completed_jobs $failed_jobs"
}
# 檢查特定 Job 進度
check_job_progress() {
local job_uuid=$1
if [ -z "$job_uuid" ]; then
echo "Usage: $0 progress <uuid>"
return 1
fi
local progress=$(redis-cli -a "$REDIS_PASSWORD" HGETALL "${REDIS_PREFIX}job:$job_uuid" 2>/dev/null)
if [ -n "$progress" ]; then
echo "Job $job_uuid progress:"
echo "$progress" | while read -r key value; do
[ -n "$key" ] && echo " $key: $value"
done
else
echo "No progress data for job $job_uuid"
fi
}
# 訂閱即時進度頻道
subscribe_progress() {
local job_uuid=$1
if [ -z "$job_uuid" ]; then
echo "Subscribing to all progress channels..."
redis-cli -a "$REDIS_PASSWORD" PSUBSCRIBE "${REDIS_PREFIX}progress:*" 2>/dev/null
else
echo "Subscribing to job $job_uuid progress..."
redis-cli -a "$REDIS_PASSWORD" SUBSCRIBE "${REDIS_PREFIX}progress:$job_uuid" 2>/dev/null
fi
}
# 列出所有活動 Job
list_active_jobs() {
echo "Active Jobs:"
redis-cli -a "$REDIS_PASSWORD" SMEMBERS "${REDIS_PREFIX}jobs:active" 2>/dev/null | while read -r uuid; do
[ -n "$uuid" ] && echo " - $uuid"
done
}
# 主程序
case "$1" in
status)
check_job_status
;;
progress)
check_job_progress "$2"
;;
subscribe)
subscribe_progress "$2"
;;
list)
list_active_jobs
;;
*)
echo "Usage: $0 {status|progress <uuid>|subscribe [uuid]|list}"
exit 1
;;
esac
```
### 4.3 監控腳本排程
使用 cron 定期執行健康檢查：
```bash
# crontab -e
# 每 5 分鐘執行一次健康檢查
*/5 * * * * /Users/accusys/momentry/scripts/health_check.sh >> /Users/accusys/momentry/log/health_check.log 2>&1
```
### 4.4 監控數據記錄
健康檢查結果應寫入監控數據庫，建議的 `monitor_services` 表結構:
```sql
CREATE TABLE monitor_services (
id SERIAL PRIMARY KEY,
service_name VARCHAR(50) NOT NULL,
status VARCHAR(20) NOT NULL, -- up, down, warning
error_message TEXT,
checked_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_monitor_services_checked ON monitor_services(checked_at);
CREATE INDEX idx_monitor_services_name ON monitor_services(service_name);
```
---
## 5. 配置更新
### 5.1 環境變數
必需監控相關環境變數配置在 `.env` 或系統中：
```bash
# Redis 連接
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=accusys
# Redis Key Prefix (可選，預設: momentry:)
REDIS_PREFIX=momentry:
# SFTPGo 管理員密碼 (用於 API 健康檢查)
SFTPGO_ADMIN_PASSWORD=Test3200Test3200
# Momentry Core 路徑 (可選，如果不在標準位置)
MOMENTRY_BINARY_PATH="/Users/accusys/momentry/target/release/momentry"
```
### 5.2 監控配置範例
**檔案**: `monitor/config/monitor_config.yaml`
```yaml
services:
# Redis - 消息隊列與狀態存儲
- name: "redis"
type: "tcp"
host: "localhost"
port: 6379
timeout: 3
enabled: true
# PostgreSQL - 數據庫
- name: "postgresql"
type: "tcp"
host: "localhost"
port: 5432
timeout: 5
enabled: true
check_sql: "SELECT 1;" # 可選：執行 SQL 驗證
# n8n - 工作流引擎
- name: "n8n"
type: "http"
host: "localhost"
port: 5678
check_url: "http://localhost:5678/healthz"
timeout: 5
enabled: true
# SFTPGo - 文件上傳服務
- name: "sftpgo"
type: "http"
host: "localhost"
port: 8080
check_url: "http://localhost:8080/healthz"
timeout: 5
enabled: true
# 附加認證檢查（每小時一次）
auth_check:
endpoint: "/api/v2/token"
method: "GET"
username: "admin"
password_env: "SFTPGO_ADMIN_PASSWORD"
# Qdrant - 向量數據庫
- name: "qdrant"
type: "http"
host: "localhost"
port: 6333
check_url: "http://localhost:6333/collections"
timeout: 5
enabled: true
# Momentry Core CLI
- name: "momentry_core"
type: "cli"
binary_path: "/Users/accusys/momentry/target/release/momentry"
args: ["--version"]
timeout: 3
enabled: true
```
### 5.3 備份配置更新
統一備份系統 (`backup_all.sh`) 已包含 SFTPGo 備份，無需額外配置。
備份保留策略 (預設):
- **每日備份**: 保留 7 天
- **每週備份**: 保留 4 週
- **每月備份**: 保留 12 個月
備份存儲位置:
- 配置文件: `/Users/accusys/momentry/backup/daily/<service>/`
- 最新備份鏈接: `/Users/accusys/momentry/backup/latest/` (由 backup_monitor.sh 管理)
### 5.4 監控腳本配置
建立符號鏈接到監控腳本目錄:
```bash
ln -sf /Users/accusys/momentry/scripts/backup_all.sh /usr/local/bin/backup_all
ln -sf /Users/accusys/momentry/scripts/health_check.sh /usr/local/bin/health_check
```
這樣可以在任何地方執行:
```bash
health_check
backup_all status
backup_all restore sftpgo 20260321_101928
```
---
## 6. 報警規則
| 層級 | 異常類型 | 等級 | 處理 |
|------|----------|------|------|
| Service | PostgreSQL 未運行 | Critical | 記錄 + 通知 |
| Service | Redis 未運行 | Critical | 記錄 + 通知 |
| Service | n8n API 無回應 | Critical | 記錄 + 通知 |
| Service | SFTPGo API 無回應 | Critical | 記錄 + 通知 |
| Service | Qdrant 未運行 | Critical | 記錄 + 通知 |
| Service | Momentry CLI 缺失 | Critical | 記錄 + 通知 |
| Database | 關鍵資料庫不存在 | Warning | 記錄 |
| Backup | 備份失敗 | Critical | 記錄 |
| Backup | 備份過期 | Warning | 記錄 |
| Job | 處理失敗 | Warning | 記錄 |
| Job | 處理超時 | Warning | 記錄 |
### 6.1 資料庫缺失處理
當檢查到以下資料庫不存在時，應記錄警告:
- `momentry` - Momentry Core 主資料庫
- `video_register` - 視頻註冊資料庫
- `n8n` - n8n 工作流資料庫
- `sftpgo` - SFTPGo 資料庫
**處理程序**:
1. 確認是否為首次安裝（資料庫尚未建立）
2. 檢查備份並執行還原
3. 如果是意外刪除，立即從最新備份恢復
### 6.2 SFTPGo 監控特殊注意
SFTPGo 使用雙重認證檢查:
1. **健康檢查**: `/healthz` (無需認證)
2. **API 可用性**: `/api/v2/token` (需要 Basic Auth)
若 `/healthz` 正常但 `/api/v2/token` 失敗，可能是:
- admin 密碼被重置
- 數據庫連接問題
- API 配置錯誤
應立即檢查:
```bash
tail -20 /Users/accusys/momentry/log/sftpgo.log
tail -20 /Users/accusys/momentry/log/sftpgo.error.log
```
---
## 7. 數據庫記錄
### monitor_jobs 表
```sql
CREATE TABLE monitor_jobs (
id SERIAL PRIMARY KEY,
uuid VARCHAR(16) NOT NULL,
video_path VARCHAR(512),
status VARCHAR(20),
current_processor VARCHAR(20),
progress_total INT,
progress_current INT,
error_count INT DEFAULT 0,
last_error TEXT,
started_at TIMESTAMP,
updated_at TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_monitor_jobs_uuid ON monitor_jobs(uuid);
CREATE INDEX idx_monitor_jobs_status ON monitor_jobs(status);
CREATE INDEX idx_monitor_jobs_created_at ON monitor_jobs(created_at);
```
### processor_results 表
```sql
CREATE TABLE processor_results (
id SERIAL PRIMARY KEY,
job_id INTEGER REFERENCES monitor_jobs(id) ON DELETE CASCADE,
video_id BIGINT REFERENCES videos(id),
processor VARCHAR(20) NOT NULL,
status VARCHAR(20) NOT NULL DEFAULT 'pending',
started_at TIMESTAMP,
completed_at TIMESTAMP,
error_message TEXT,
created_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_processor_results_job ON processor_results(job_id);
CREATE INDEX idx_processor_results_video ON processor_results(video_id);
CREATE INDEX idx_processor_results_status ON processor_results(status);
```
**processor 狀態值**:
- `pending` - 等待處理
- `running` - 處理中
- `completed` - 已完成
- `failed` - 處理失敗
- `skipped` - 跳過（已在其他處理中完成）
---
## 8. 環境變數
```bash
# 輸出目錄
MOMENTRY_OUTPUT_DIR=/path/to/output
# 備份
MOMENTRY_BACKUP_ENABLED=true
MOMENTRY_BACKUP_DIR=/Users/accusys/momentry/backup/momentry
# Redis
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=accusys
```
---
## 9. 待實作項目
| # | 項目 | 狀態 | 更新日期 |
|---|------|------|---------|
| 1 | 實作 Redis Pub/Sub 客戶端 | ✅ 已實作 | 2026-03-21 |
| 2 | 修改 Python processors 使用 Redis | ✅ 已實作 | 2026-03-21 |
| 3 | 設計並實現 health_check.sh | ✅ 已實作 | 2026-03-22 |
| 4 | 創建 monitor_jobs 表 | ✅ 已實作 | 2026-03-21 |
| 5 | SFTPGo 備份與還原流程 | ✅ 已實作 | 2026-03-22 |
| 6 | SFTPGo API 管理工具 | ✅ 已實作 | 2026-03-22 |
| 7 | SFTPGo Hook 自動註冊 | ✅ 已實作 | 2026-03-22 |
| 8 | 文檔化監控規範 | ✅ 已實作 | 2026-03-22 |
| 9 | Job Worker 輪詢機制 | ✅ 已實作 | 2026-03-25 |
| 10 | processor_results 表 | ✅ 已實作 | 2026-03-25 |
| 11 | Probe API 端點 | ✅ 已實作 | 2026-03-25 |
| 12 | 整合測試 | 🔜 待實作 | - |
| 13 | 生產環境部署驗證 | ⏳ 待開始 | - |
### Job Worker 監控 (2026-03-25 新增)
**Worker 服務狀態檢查**:
```bash
# 檢查 Worker 程序
ps aux | grep momentry
# 查看 Worker 日誌
tail -f /Users/accusys/momentry/log/worker.log
```
**monitor_jobs 狀態查詢**:
```bash
# 查看待處理工作
psql -U accusys -d momentry -c "SELECT * FROM monitor_jobs WHERE status = 'pending';"
# 查看執行中工作
psql -U accusys -d momentry -c "SELECT * FROM monitor_jobs WHERE status = 'running';"
# 查看失敗工作
psql -U accusys -d momentry -c "SELECT * FROM monitor_jobs WHERE status = 'failed';"
```
**processor_results 狀態查詢**:
```bash
# 查看特定工作的處理器狀態
psql -U accusys -d momentry -c "
SELECT pr.*, mj.uuid
FROM processor_results pr
JOIN monitor_jobs mj ON pr.job_id = mj.id
WHERE mj.uuid = 'a1b10138a6bbb0cd';
"
# 查看所有失敗的處理器
psql -U accusys -d momentry -c "
SELECT pr.processor, COUNT(*) as failures
FROM processor_results pr
WHERE pr.status = 'failed'
GROUP BY pr.processor;
"
```
**Redis 工作狀態**:
```bash
# 查看活躍工作
redis-cli SMEMBERS momentry:jobs:active
# 查看工作詳情
redis-cli HGETALL momentry:job:{uuid}
```
### 已完成實作 (2026-03-22)
**監控系統**:
- 完整健康檢查腳本設計: `docs_v1.0/OPERATIONS/MOMENTRY_CORE_MONITORING.md`
- 多層次服務監控 (Layer 2: Service, Layer 7: Backup)
- Redis Job 監控腳本: `monitor/service/redis_job_monitor.sh`
- SFTPGo 特殊監控 (API 認證檢查)
**SFTPGo 管理**:
- 備份還原機制: `backup_all.sh` (第 325-546 行)
- API 管理用戶與組 (完整文件於 `docs_v1.0/IMPLEMENTATION/INSTALL_SFTPGO.md`)
- Hook 自動註冊流程: `/Users/accusys/sftpgo_test/register_hook.sh`
- Demo 用戶與組完整測試環境
**文檔更新**:
- `docs_v1.0/IMPLEMENTATION/INSTALL_SFTPGO.md`: 新增備份還原、API管理、Hook配置章節
- `docs_v1.0/OPERATIONS/MOMENTRY_CORE_MONITORING.md`: 完善監控規範
### 待驗證功能
- [ ] 端到端測試: SFTP 上傳 → Hook → Momentry 註冊 → n8n 工作流
- [ ] Momentry Core API 搜索功能: `GET /api/v1/searchable`
- [ ] 背景處理自動觸發: `cargo run -- process <uuid>`
---
## 10. 參考文檔
- [Redis Key 設計規範](./MOMENTRY_CORE_REDIS_KEYS.md)
- [監控系統總覽](../monitor/MONITORING.md)
- [備份規範](./SERVICE_ADDITION_GUIDE.md)
- [SFTPGo 安裝與管理指南](./INSTALL_SFTPGO.md)
- [API 參考文件](../docs_v1.0/REFERENCE/API_REFERENCE.md)
- [n8n 整合指南](./N8N_INTEGRATION_GUIDE.md)

283
docs_v1.0/OPERATIONS/MOMENTRY_CORE_REDIS_KEYS.md
View File

@@ -1,283 +0,0 @@
# Momentry Core Redis Key 設計規範
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-17 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-17 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-25 | 新增可配置 Redis Key Prefix | Warren | OpenCode / GLM-5 |
---
## 1. 概述
本文檔說明 momentry_core 如何使用 Redis 作為監控和狀態管理系統。
## 2. 可配置 Redis Key Prefix
### 2.1 環境變數
從 V1.1 開始，所有 Redis Keys 都支援自定義前綴：
```bash
MOMENTRY_REDIS_PREFIX=momentry:
```
此設定允許多個 momentry 實例共用同一個 Redis 伺服器，例如：
- **生產環境**: `MOMENTRY_REDIS_PREFIX=momentry:`
- **開發環境**: `MOMENTRY_REDIS_PREFIX=momentry_dev:`
### 2.2 Key 格式
所有 Key 都遵循以下格式：
```
{prefix}{key_type}:{uuid}
```
範例 (生產環境):
```
momentry:job:5dea6618a606e7c7
momentry:jobs:active
momentry:health:current
```
範例 (開發環境):
```
momentry_dev:job:5dea6618a606e7c7
momentry_dev:jobs:active
momentry_dev:health:current
```
### 2.3 預設值
| Binary | 預設 Port | 預設 Redis Prefix |
|--------|-----------|-------------------|
| `momentry` (生產) | 3002 | `momentry:` |
| `momentry_playground` (開發) | 3003 | `momentry_dev:` |
## 3. UUID 使用時機
### 3.1 全局 Keys（無 UUID）
- 單一實例全局狀態
- 聚合統計數據
### 3.2 Per-Video Keys（UUID 必要）
- 每個視頻獨立處理狀態
- 即時進度追蹤
### 3.3 Per-Processor Keys（UUID + Processor 必要）
- 每個 processor 獨立狀態
## 4. Key 命名空間
```
momentry
├── health: # 健康檢查
│ ├── current # 當前狀態 (TTL: 60s)
│ └── services # 依賴服務狀態
├── config: # 配置
├── stats: # 聚合統計
│ ├── total_jobs # 總 Jobs 數
│ ├── processed_today # 今日處理數
│ ├── cpu:current # 當前 CPU 使用
│ └── memory:current # 當前 Memory 使用
├── jobs: # Jobs 管理
│ ├── active # Set: 運行中 UUIDs
│ ├── completed # Set: 完成 UUIDs
│ └── failed # Set: 失敗 UUIDs
├── job:{uuid} # Per-Video Job 狀態 (TTL: 24h)
│ ├── status # 狀態 String
│ ├── video_path # 視頻路徑
│ ├── current_processor # 當前 processor
│ ├── progress_total # 總進度
│ ├── progress_current # 當前進度
│ ├── started_at # 開始時間
│ ├── updated_at # 最後更新
│ └── processor:{name} # Per-Processor 狀態
│ ├── status
│ ├── progress
│ ├── current
│ ├── total
│ └── started_at
├── progress:{uuid} # Pub/Sub 頻道 (即時進度)
├── result:{uuid} # 處理結果 Hash
├── output:{uuid} # 輸出路徑
├── metrics:{uuid} # Per-Video 指標
│ ├── cpu # CPU 歷史 List (100條, TTL: 1h)
│ ├── memory # Memory 歷史 List (100條, TTL: 1h)
│ └── duration # 處理時長
└── log:{uuid} # 處理日誌 String
```
## 5. Key 詳細說明
### 全局 Keys
| Key | Type | TTL | 說明 |
|-----|------|-----|------|
| `momentry:health:current` | String | 60s | 當前健康狀態 |
| `momentry:health:services` | Hash | 60s | 依賴服務健康狀態 |
| `momentry:stats:total_jobs` | String | - | 總 Jobs 數 |
| `momentry:stats:processed_today` | String | 86400s | 今日處理數 |
| `momentry:stats:cpu:current` | String | 10s | 當前 CPU 使用 |
| `momentry:stats:memory:current` | String | 10s | 當前 Memory 使用 |
| `momentry:jobs:active` | Set | - | 運行中 Job UUIDs |
| `momentry:jobs:completed` | Set | - | 完成 Job UUIDs |
| `momentry:jobs:failed` | Set | - | 失敗 Job UUIDs |
### Per-Video Keys
| Key | Type | TTL | 說明 |
|-----|------|-----|------|
| `momentry:job:{uuid}` | Hash | 24h | Job 完整狀態 |
| `momentry:job:{uuid}:status` | String | 24h | Job 狀態 |
| `momentry:progress:{uuid}` | Pub/Sub | - | 即時進度頻道 |
| `momentry:result:{uuid}` | Hash | 24h | 處理結果 |
| `momentry:output:{uuid}` | String | 24h | 輸出路徑 |
| `momentry:metrics:{uuid}:cpu` | List | 1h | CPU 歷史 (100條) |
| `momentry:metrics:{uuid}:memory` | List | 1h | Memory 歷史 (100條) |
| `momentry:metrics:{uuid}:duration` | String | 24h | 處理時長 |
| `momentry:log:{uuid}` | String | 24h | 處理日誌 |
### Per-Processor Keys
| Key | Type | TTL | 說明 |
|-----|------|-----|------|
| `momentry:job:{uuid}:processor:{name}` | Hash | 24h | Processor 狀態 |
| `momentry:job:{uuid}:processor:{name}:status` | String | 24h | 狀態 |
| `momentry:job:{uuid}:processor:{name}:progress` | String | 24h | 進度百分比 |
| `momentry:job:{uuid}:processor:{name}:current` | String | 24h | 當前項目 |
| `momentry:job:{uuid}:processor:{name}:total` | String | 24h | 總項目數 |
| `momentry:job:{uuid}:processor:{name}:started_at` | String | 24h | 開始時間 |
## 6. TTL 策略
| Key 類型 | TTL | 原因 |
|----------|-----|------|
| Health | 60s | 需要定期更新 |
| Job | 24h | 處理完成後保留一天 |
| Processor | 24h | 處理完成後保留一天 |
| Metrics | 1h | 只保留近期歷史 |
| Progress Pub/Sub | - | 不持久，僅即時訊息 |
| Stats | 無 | 持久統計 |
## 7. 訊息格式
### Pub/Sub 訊息 (progress:{uuid})
```json
{
"type": "info | progress | complete | error",
"processor": "yolo | ocr | face | pose | cut | asr | asrx",
"timestamp": 1700000000,
"data": {
"message": "Processing frame 5000",
"current": 5000,
"total": 14315
}
}
```
### Job 狀態 Hash
```json
{
"uuid": "5dea6618a606e7c7",
"video_path": "/path/to/video.mp4",
"status": "running",
"current_processor": "yolo",
"progress_total": 70,
"progress_current": 50,
"started_at": 1700000000,
"updated_at": 1700000100,
"error_count": 0,
"last_error": ""
}
```
### Processor 狀態 Hash
```json
{
"name": "yolo",
"status": "running",
"progress": 70,
"current_frame": 10000,
"total_frames": 14315,
"started_at": 1700000000,
"updated_at": 1700000100
}
```
## 8. 實作函數 (Rust)
所有 Redis Key 生成函數使用 `REDIS_KEY_PREFIX` 靜態變數：
```rust
use crate::core::config::REDIS_KEY_PREFIX;
fn global_key(key: &str) -> String {
format!("{}{}", REDIS_KEY_PREFIX, key)
}
fn job_key(uuid: &str) -> String {
format!("{}job:{}", REDIS_KEY_PREFIX, uuid)
}
fn processor_key(uuid: &str, processor: &str) -> String {
format!("{}job:{}:processor:{}", REDIS_KEY_PREFIX, uuid, processor)
}
fn progress_channel(uuid: &str) -> String {
format!("{}progress:{}", REDIS_KEY_PREFIX, uuid)
}
fn metrics_key(uuid: &str, metric: &str) -> String {
format!("{}metrics:{}:{}", REDIS_KEY_PREFIX, uuid, metric)
}
fn jobs_set_key(status: &str) -> String {
format!("{}jobs:{}", REDIS_KEY_PREFIX, status)
}
```
**注意**: `REDIS_KEY_PREFIX` 定義於 `src/core/config.rs`，由環境變數 `MOMENTRY_REDIS_PREFIX` 控制。
## 9. 環境變數
```bash
# Redis 連接
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=accusys
REDIS_DB=0
# Redis Key Prefix (可選，預設: momentry:)
MOMENTRY_REDIS_PREFIX=momentry:
# 生產環境範例 (.env)
MOMENTRY_SERVER_PORT=3002
MOMENTRY_REDIS_PREFIX=momentry:
# 開發環境範例 (.env.development)
MOMENTRY_SERVER_PORT=3003
MOMENTRY_REDIS_PREFIX=momentry_dev:
```
## 11. 監控腳本
使用 Redis 進行監控的腳本應參考：
- `monitor/service/momentry_redis_monitor.sh` - Redis 健康檢查
- `monitor/service/momentry_job_monitor.sh` - Job 狀態監控

334
docs_v1.0/OPERATIONS/MOMENTRY_RAG_PRESENTATION.md
View File

@@ -1,334 +0,0 @@
# Momentry Core 影片 RAG 系統說明稿
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-22 |
| 文件版本 | V1.1 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-25 | 更新API回應格式 (media_url→file_path) 與認證標頭 | OpenCode | deepseek-reasoner |
---
## 系統架構
```
┌─────────────────────────────────────────────────────────────┐
│ 使用者 │
│ (marcom 團隊) │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ WordPress 入口 │
│ (wp.momentry.ddns.net) │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ n8n 自動化 │
│ (localhost:5678) │
│ │
│ [Webhook] → [HTTP Request] → [處理結果] → [回覆用戶] │
└─────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Momentry Core API │
│ (localhost:3002) │
│ │
│ POST /api/v1/search → 語意搜尋 │
│ POST /api/v1/n8n/search → n8n 專用格式 │
│ GET /api/v1/videos → 影片列表 │
└─────────────────┬───────────────────────────────────────────┘
│
┌─────────┴──────────┐
▼ ▼
┌───────────────┐ ┌───────────────┐
│ PostgreSQL │ │ Qdrant │
│ (chunks) │ │ (vectors) │
└───────────────┘ └───────────────┘
```
---
## 資料流程
```
1. 上傳影片 → SFTPGo
2. 影片註冊 → PostgreSQL
3. ASR 處理 → 產生字幕區塊
4. 儲存 chunks → PostgreSQL
5. 向量化 → Qdrant
6. 搜尋查詢 → API
7. 回傳結果 → n8n → 用戶
```
---
## 示範影片
| 項目 | 內容 |
|------|------|
| 檔案名稱 | Old_Time_Movie_Show_-_Charade_1963.HD.mov |
| UUID | a1b10138a6bbb0cd |
| 時長 | 6879 秒（約 1.9 小時） |
| 區塊數 | 3,886 個 |
| 向量數 | 3,688 個 |
---
## API 端點
### 1. 語意搜尋
```
POST http://localhost:3002/api/v1/search
```
**請求：**
```json
{
"query": "charade",
"limit": 5,
"uuid": "a1b10138a6bbb0cd"
}
```
> **注意**:
> 1. **API 認證**: 所有 `/api/v1/*` 端點需要 `X-API-Key` 標頭
> 2. **檔案路徑轉換**: API 現在返回 `file_path`（檔案系統路徑），需要轉換為可訪問的 URL（例如透過 SFTPGo 分享連結）
---
### 2. n8n 專用格式
```
POST http://localhost:3002/api/v1/n8n/search
```
**請求：**
```json
{
"query": "charade",
"limit": 5
}
```
**回應：**
```json
{
"query": "charade",
"count": 5,
"hits": [
{
"id": "sentence_0006",
"vid": "a1b10138a6bbb0cd",
"start": 48.8,
"end": 55.44,
"title": "Chunk sentence_0006",
"text": "fun plot twists...",
"score": 0.526,
"file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
}
]
}
```
---
## 實作範例
### n8n Workflow 設計
```
┌─────────────┐
│ Webhook │ ← 接收用戶搜尋請求
└──────┬──────┘
│
▼
┌─────────────┐
│ HTTP Request│ → POST /api/v1/n8n/search
└──────┬──────┘
│
▼
┌─────────────┐
│ Code │ → 處理回傳結果
└──────┬──────┘
│
▼
┌─────────────┐
│ Telegram │ → 回覆給用戶
│ (或 LINE) │
└─────────────┘
```
---
## Step-by-Step n8n Workflow
### Step 1: 建立 Webhook
1. n8n 開新 Workflow
2. 新增 node: **Webhook**
3. 設定 path: `video-search`
4. 複製 Webhook URL
---
### Step 2: 設定 HTTP Request
1. 新增 node: **HTTP Request**
2. 設定：
```
Method: POST
URL: http://localhost:3002/api/v1/n8n/search
Body Content Type: JSON
Headers: X-API-Key (需設定)
```
3. Body:
```json
{
"query": "={{ $json.body }}",
"limit": 5
}
```
---
### Step 3: 處理結果 (Code)
```javascript
const hits = $input.first().json.hits;
if (!hits || hits.length === 0) {
return {
json: { message: "找不到相關結果" }
};
}
const results = hits.map((hit, index) => ({
number: index + 1,
text: hit.text,
time: `${hit.start}s - ${hit.end}s`,
score: Math.round(hit.score * 100) + "%",
// 注意: API 現在返回 file_path（檔案系統路徑），需要轉換為可訪問的 URL
url: hit.file_path + "#t=" + hit.start + "," + hit.end // 需實作檔案路徑轉換為 URL
}));
return { json: { results } };
```
> **注意**:
> 1. **API 認證**: 所有 `/api/v1/*` 端點需要 `X-API-Key` 標頭
> 2. **檔案路徑轉換**: API 現在返回 `file_path`（檔案系統路徑），需要轉換為可訪問的 URL（例如透過 SFTPGo 分享連結）
---
### Step 4: 格式化輸出
**Telegram 格式：**
```
🎬 搜尋結果: "{{ $json.query }}"
1️⃣ "fun plot twists, Woody Dialog and charming performances..."
⏱ 48.8s - 55.4s
📊 相關度: 53%
2️⃣ "Don't you like me to say that a pretty girl..."
⏱ 4745.6s - 4748.6s
📊 相關度: 52%
```
---
## 測試指令
### curl 測試
```bash
# 語意搜尋
curl -X POST http://localhost:3002/api/v1/search \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"query": "charade", "limit": 3}'
# n8n 格式
curl -X POST http://localhost:3002/api/v1/n8n/search \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"query": "charade", "limit": 3}'
# 影片列表
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos
# 特定影片區塊
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos/a1b10138a6bbb0cd/chunks
```
---
## 實際搜尋範例
| 搜尋詞 | 結果摘要 |
|--------|----------|
| `charade` | "fun plot twists, Woody Dialog and charming performances..." |
| `woody` | "Well, you thick skull hair, brain half-witted..." |
| `classic movie` | "Hello and welcome to the old-time movie show..." |
| `charming` | "fun plot twists, Woody Dialog and charming performances..." |
---
## 資料庫狀態
| 資料庫 | 資料筆數 | 狀態 |
|--------|----------|------|
| PostgreSQL (videos) | 4 | ✅ |
| PostgreSQL (chunks) | 3,950 | ✅ |
| PostgreSQL (vectors) | 1,870 | ✅ |
| Qdrant (vectors) | 3,688 | ✅ |
| Redis (job cache) | 4 keys | ✅ |
---
## 下一步
1. **建立 SFTPGo 分享連結**
- 開啟 http://localhost:8080
- 登入 demo / demopassword123
- 建立影片分享連結
2. **測試 n8n Workflow**
- 匯入 Postman Collection
- 建立 Webhook
- 測試搜尋
3. **整合到 WordPress**
- 建立表單接收用戶輸入
- 呼叫 n8n Webhook
- 顯示搜尋結果
---
## 快速開始
```bash
# 1. 測試搜尋 API
curl -X POST http://localhost:3002/api/v1/search \
-H "Content-Type: application/json" \
-d '{"query": "charade", "limit": 3}'
# 2. 查看影片列表
curl http://localhost:3002/api/v1/videos
# 3. 查看 n8n 是否運行
curl http://localhost:5678
```

813
docs_v1.0/OPERATIONS/PENDING_ISSUES.md
View File

@@ -1,813 +0,0 @@
# 待解決問題追蹤
| 項目 | 內容 |
|------|------|
| 建立者 | 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`) 存在以下問題：
```rust
// 問題 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. 添加單元測試驗證
#### 下一步
- [x] 修復 `store_vector` 錯誤處理
- [x] 添加單元測試
- [ ] 重現並確認問題根因
### 2026-03-21 修復完成
已修復 `store_vector` 函數的錯誤處理：
```rust
// 修復前：錯誤被靜默忽略
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](./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
```bash
# 每日備份 (排除 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`:
```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 |
### 使用方式
```bash
# 備份所有 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
```
### 功能
- [x] REST API 備份
- [x] 變更偵測
- [x] SHA256 校驗
- [x] 備份版本化
- [x] 差異備份（`--incremental`）
- [x] 備份驗證（`--verify`）
- [x] 備份統計（`--stats`）
- [x] 失敗執行記錄備份（`--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 建議
```bash
# 每日備份（下午 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 命令
```bash
# 創建 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：使用默認用戶（現行）
```bash
# .env
REDIS_URL=redis://:accusys@localhost:6379
```
**優點**：簡單，無需修改 Redis 配置
**缺點**：所有應用共享默認用戶
#### 方案 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
```
**優點**：支持多用戶，ACL 持久化
**缺點**：需修改 plist 並重啟
### 影響範圍
- `src/core/config.rs` - REDIS_URL 讀取
- `src/core/db/redis_client.rs` - Redis 連線
- `momentry api-key` 命令 - 異常告警
### 狀態
- [x] 已確認問題存在
- [x] 已修改 `.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` 等 |
### 待辦事項
- [x] 建立 `docs/INSTALL_MOMENTRY_API.md` 安裝文件
- [x] 建立 `/Library/LaunchDaemons/com.momentry.api.plist`
- [x] 設定環境變數 (`DATABASE_URL`, `REDIS_URL` 等)
- [x] 測試 launchctl load/unload
- [x] 驗證開機自動啟動 (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](./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 命令
```
### 狀態
- [x] 系統分析完成
- [x] 實作計畫文件建立
- [ ] 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](./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 整合方式
- [ ] 配額管理策略
- [ ] 用戶刪除同步流程
### 狀態
- [x] 系統分析完成
- [x] 實作計畫文件建立
- [ ] 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 用戶設定

293
docs_v1.0/OPERATIONS/PROCESSING_PIPELINE.md.bak
View File

@@ -1,293 +0,0 @@
# Video Processing Pipeline - 處理流程
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-22 |
| 文件版本 | V1.1 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode |
| V1.1 | 2026-03-26 | 更新流程圖文字 (media_url→file_path) | OpenCode | deepseek-reasoner |
---
## 處理流程架構
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Video Processing Pipeline │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Stage 1: JSON 生成 (Process) │ │
│ │ │ │
│ │ video.mp4 ──→ [ASR] ──→ asr.json (語音辨識) │ │
│ │ ──→ [CUT] ──→ cut.json (場景偵測) │ │
│ │ ──→ [ASRX] ──→ asrx.json (說話者分離) │ │
│ │ ──→ [YOLO] ──→ yolo.json (物體偵測) │ │
│ │ ──→ [OCR] ──→ ocr.json (文字辨識) │ │
│ │ ──→ [Face] ──→ face.json (人臉偵測) │ │
│ │ ──→ [Pose] ──→ pose.json (姿態估計) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Stage 2: 入庫 (Import) │ │
│ │ │ │
│ │ .json files ──→ PostgreSQL (fs_json = true) │ │
│ │ ↓ │ │
│ │ pre_chunks 表 (from ASR, CUT) │ │
│ │ frames 表 (from YOLO, OCR, Face, Pose) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Stage 3: Chunk 生成 (Chunk) │ │
│ │ │ │
│ │ pre_chunks ──→ [Chunk Rule] ──→ chunks 表 │ │
│ │ ↓ │ │
│ │ 清洗 → 純文字 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Stage 4: 向量化 (Vectorize) │ │
│ │ │ │
│ │ chunks ──→ [Embedding Model] ──→ vectors │ │
│ │ ↓ │ │
│ │ Qdrant (主要向量庫) │ │
│ │ PGVector (備份向量庫) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Stage 5: 搜尋 (Search) │ │
│ │ │ │
│ │ Natural Language Query ──→ [Embedding] ──→ [Qdrant Search] │ │
│ │ ↓ │ │
│ │ 返回結果含 file_path │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## CLI 命令
### Stage 1: JSON 生成 (Process)
```bash
# 基本用法
cargo run --bin momentry -- process <uuid_or_path>
# 只處理特定模組
cargo run --bin momentry -- process <uuid> --modules asr,cut
# 強制重新處理（忽略完整性檢查）
cargo run --bin momentry -- process <uuid> --force
# 從中斷點續傳
cargo run --bin momentry -- process <uuid> --resume
# 模組使用雲端處理
cargo run --bin momentry -- process <uuid> --modules yolo,face --cloud yolo
# 完整範例
cargo run --bin momentry -- process /path/to/video.mp4 \
--modules asr,cut,yolo,ocr \
--cloud yolo
```
### Stage 2: 入庫 (Import)
```bash
# 目前入庫在 process 完成後自動執行
# 計劃新增獨立的 import 命令
# cargo run --bin momentry -- import <uuid>
```
### Stage 3: Chunk 生成
```bash
# 生成 chunks
cargo run --bin momentry -- chunk <uuid>
```
### Stage 4: 向量化
```bash
# 向量化 chunks
cargo run --bin momentry -- vectorize <uuid>
# 指定模型
cargo run --bin momentry -- vectorize <uuid> --model sentence-transformers/all-MiniLM-L6-v2
```
---
## 處理模式選項
### --force (強制重新處理)
- 刪除現有的 JSON 檔案
- 從頭開始處理
- 適用於：處理失敗、模型更新、需要重新處理
```bash
# 強制重新處理 YOLO
cargo run --bin momentry -- process <uuid> --modules yolo --force
```
### --resume (續傳)
- 檢查現有 JSON 的進度
- 從中斷點繼續處理
- 適用於：處理中斷、系統崩潰後恢復
```bash
# 從上次中斷點繼續
cargo run --bin momentry -- process <uuid> --resume
```
### 預設行為 (Smart Mode)
- 如果 JSON 完全：跳過
- 如果 JSON 不完整：警告 + 跳過（需要 --resume 或 --force）
- 如果 JSON 不存在：處理
```
Output:
ASR: ✓ Already complete, skipping
⚠️ Found incomplete JSON file: /path/to/yolo.json
Progress: 73800/412343 (17.9%)
Use --resume to continue from checkpoint
Use --force to reprocess from scratch
YOLO: ✓ Already complete, skipping
```
---
## 可用模組
| 模組 | 功能 | 輸出 | 用途 |
|------|------|------|------|
| asr | 自動語音辨識 | asr.json | 語音轉文字 |
| cut | 場景偵測 | cut.json | 影片分段 |
| asrx | 說話者分離 | asrx.json | 多人對話分析 |
| yolo | 物體偵測 | yolo.json | 物體辨識 |
| ocr | 文字辨識 | ocr.json | 畫面文字 |
| face | 人臉偵測 | face.json | 人臉辨識 |
| pose | 姿態估計 | pose.json | 人體姿態 |
---
## 向量化模型選擇
### 統一嵌入模型
Momentry Core 統一使用 **`nomic-embed-text-v2-moe:latest`** 作為所有規則的嵌入模型：
```bash
# 統一模型（所有 Rule 1/2/3 使用）
--model nomic-embed-text-v2-moe:latest
```
### 模型特性
| 特性 | 說明 |
|------|------|
| **模型名稱** | `nomic-embed-text-v2-moe:latest` |
| **向量維度** | 768 維 |
| **多語言支持** | ✅ 完整支持（英語、中文、日語、韓語等） |
| **模型架構** | Mixture of Experts (MoE) |
| **推理速度** | 快速，適合實時應用 |
### 使用方式
```bash
# 向量化命令
cargo run --bin momentry -- vectorize <uuid> --model nomic-embed-text-v2-moe:latest
```
---
## 資料庫儲存
### PostgreSQL (主要關聯式資料庫)
- 影片資訊
- Chunks 資料
- Pre-chunks 資料
- Frames 資料
- 使用者資料
### Qdrant (主要向量資料庫)
- Chunk 向量
- 相似度搜尋
### PGVector (備份向量資料庫)
- Chunk 向量副本
- 備援機制
---
## Pipeline 狀態追蹤
### PostgreSQL 狀態欄位
```sql
-- 影片處理狀態
videos.status: 'pending' | 'processing' | 'completed' | 'failed'
-- 檔案處理狀態
videos.fs_json: true/false
videos.fs_chunks: true/false
videos.fs_vectors: true/false
-- pre_chunks 狀態
pre_chunks.imported: true/false
-- frames 狀態
frames.imported: true/false
-- chunks 狀態
chunks.cleaned: true/false
chunks.vectorized: true/false
```
### 進度查詢 API
```bash
# 查詢處理進度
curl http://localhost:3002/api/v1/progress/{uuid}
# 回應範例
{
"uuid": "a1b10138a6bbb0cd",
"file_name": "video.mp4",
"overall_progress": 65,
"cpu_percent": 45.2,
"gpu_percent": 98.5,
"memory_mb": 8500,
"processors": [
{"name": "asr", "status": "complete", "progress": 100},
{"name": "cut", "status": "complete", "progress": 100},
{"name": "yolo", "status": "progress", "progress": 45},
{"name": "ocr", "status": "pending", "progress": 0}
]
}
```
---
## 下一步
1. **API 端點** - 支援 --modules 和 --cloud 參數
2. **獨立 Import 命令** - 分離入庫流程
3. **獨立 Chunk 命令** - 分離 chunk 生成
4. **獨立 Vectorize 命令** - 分離向量化流程
5. **模型管理** - 新增、選擇、預覽模型

856
docs_v1.0/OPERATIONS/PRODUCTION_DEPLOYMENT_GUIDE.md
View File

@@ -1,856 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "Production Deployment Guide"
date: "2025-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "deployment"
- "guide"
- "production"
ai_query_hints:
- "查詢 Production Deployment Guide 的內容"
- "Production Deployment Guide 的主要目的是什麼？"
- "如何操作或實施 Production Deployment Guide？"
---
# Production Deployment Guide
**Version**: 1.0.0
**Effective Date**: 2025-03-27
**Status**: Approved ✅
**AI Agent Optimized**: Yes
## Overview
This guide provides comprehensive instructions for deploying Momentry Core in production environments using the standardized AI-Driven Processor Contract architecture.
## Architecture Overview
### Standardized Components
```
Momentry Core Production Stack
├── Core Services (14 services)
│ ├── PostgreSQL (13.16) - Primary database
│ ├── Redis (7.2.5) - Cache & progress reporting
│ ├── MongoDB (8.0.6) - Document storage
│ ├── Qdrant (1.11.4) - Vector database
│ ├── MariaDB (11.4.4) - WordPress database
│ ├── n8n (1.71.0) - Workflow automation
│ ├── Gitea (1.23.5) - Code repository
│ ├── SFTPGo (2.6.3) - File transfer
│ ├── Ollama (0.5.7) - Local LLM
│ ├── Caddy (2.8.4) - Reverse proxy
│ ├── PHP-FPM (8.3) - WordPress backend
│ ├── RustDesk (1.2.6) - Remote access
│ ├── Node.js (20.18.0) - Frontend services
│ └── Python (3.11.9) - Processor scripts
├── Contract-Compliant Processors (9 processors)
│ ├── ASR v2.0 (341 lines, 100% compliant)
│ ├── OCR v1.0 (621 lines, 100% compliant)
│ ├── YOLO v1.0 (666 lines, 100% compliant)
│ ├── Face v1.0 (100% compliant)
│ ├── Pose v1.0 (100% compliant)
│ ├── ASRX v1.0 (speaker diarization)
│ ├── CUT v1.0 (scene detection)
│ ├── Caption v1.0 (AI captioning)
│ └── Story v1.0 (narrative generation)
└── Monitoring & Management
├── System resilience verified (shutdown/reboot tested)
├── <5% overhead requirement verified (performance benchmarks)
└── Unified configuration system
```
## Prerequisites
### Hardware Requirements
| Component | Minimum | Recommended | Production |
|-----------|---------|-------------|------------|
| CPU Cores | 4 cores | 8 cores | 16+ cores |
| RAM | 8 GB | 16 GB | 32+ GB |
| Storage | 100 GB | 500 GB | 1 TB+ SSD |
| GPU | Optional | NVIDIA RTX 3060 | NVIDIA A100 |
### Software Requirements
- **Operating System**: Ubuntu 22.04 LTS or macOS 14+
- **Container Runtime**: Docker 24+ or Podman 4+
- **Orchestration**: Docker Compose 2.20+
- **Python**: 3.11+ with virtualenv
- **Node.js**: 20.x LTS
- **Rust**: 1.75+ (for Momentry Core compilation)
## Deployment Steps
### Step 1: Environment Setup
```bash
# Clone repository
git clone https://github.com/anomalyco/momentry_core.git
cd momentry_core
# Create environment file
cp .env.example .env
# Edit .env with production values
nano .env
```
### Step 2: Database Initialization
```bash
# Start core databases
docker-compose up -d postgres redis mongodb qdrant mariadb
# Wait for databases to be ready
sleep 30
# Initialize Momentry database
docker-compose exec postgres psql -U accusys -d momentry -f /docker-entrypoint-initdb.d/init.sql
```
### Step 3: Service Deployment
```bash
# Deploy all services
docker-compose up -d
# Verify all services are running
docker-compose ps
# Expected output (all 14 services healthy):
# Name Command State Ports
# -----------------------------------------------------
# caddy caddy run --config ... Up 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
# gitea /usr/bin/entrypoint ... Up 0.0.0.0:3000->3000/tcp
# mariadb docker-entrypoint.sh ... Up 3306/tcp
# mongodb docker-entrypoint.sh ... Up 27017/tcp
# n8n dumb-init -- /start.sh Up 5678/tcp
# ollama /bin/ollama serve Up 11434/tcp
# php-fpm docker-php-entrypoi ... Up 9000/tcp
# postgres docker-entrypoint.sh ... Up 5432/tcp
# qdrant /bin/qdrant Up 6333/tcp, 6334/tcp
# redis docker-entrypoint.sh ... Up 6379/tcp
# rustdesk hbbs -r rustdesk.se ... Up 21115-21119/tcp
# sftpgo /bin/sftpgo serve - ... Up 2022/tcp, 8080/tcp
```
### Step 4: Momentry Core Installation
```bash
# Build Momentry Core
cargo build --release --bin momentry
# Install to system path
sudo cp target/release/momentry /usr/local/bin/
# Verify installation
momentry --version
# Expected: Momentry Core 0.1.0
```
### Step 5: Processor Configuration
```bash
# Install Python dependencies
cd scripts
pip install -r requirements.txt
# Install contract-compliant processors
cp asr_processor_contract_v2.py /usr/local/bin/asr_processor
cp ocr_processor_contract_v1.py /usr/local/bin/ocr_processor
cp yolo_processor_contract_v1.py /usr/local/bin/yolo_processor
cp face_processor_contract_v1.py /usr/local/bin/face_processor
cp pose_processor_contract_v1.py /usr/local/bin/pose_processor
cp asrx_processor_contract_v1.py /usr/local/bin/asrx_processor
cp cut_processor_contract_v1.py /usr/local/bin/cut_processor
cp caption_processor_contract_v1.py /usr/local/bin/caption_processor
cp story_processor_contract_v1.py /usr/local/bin/story_processor
# Make executable
chmod +x /usr/local/bin/*_processor
# Verify processor health checks
asr_processor --check-health dummy.mp4 dummy.json
ocr_processor --check-health dummy.mp4 dummy.json
# All processors should return healthy status
```
### Step 6: Configuration Files
Create `/etc/momentry/config.toml`:
```toml
[server]
host = "0.0.0.0"
port = 3002
workers = 4
log_level = "info"
[database]
url = "postgres://accusys:password@localhost:5432/momentry"
pool_size = 10
[redis]
url = "redis://:password@localhost:6379"
prefix = "momentry:"
[storage]
output_dir = "/var/lib/momentry/output"
backup_dir = "/var/lib/momentry/backup"
max_file_size = "10GB"
[processors]
asr_timeout = 3600
ocr_timeout = 1800
yolo_timeout = 7200
face_timeout = 3600
pose_timeout = 7200
default_timeout = 7200
[asr]
model_size = "medium"
device = "cpu"
language = "auto"
task = "transcribe"
beam_size = 5
best_of = 5
[ocr]
languages = "en"
confidence = 0.7
gpu = false
model_path = "~/.EasyOCR/model"
[yolo]
model_size = "yolov8n.pt"
confidence = 0.25
iou = 0.45
gpu = false
auto_save_interval = 30
auto_save_frames = 300
classes = "" # empty = all classes
[face]
method = "haar"
confidence = 0.5
min_size = 30
max_size = 300
scale_factor = 1.1
min_neighbors = 3
gpu = false
[pose]
model_size = "yolov8n-pose.pt"
confidence = 0.25
iou = 0.45
gpu = false
keypoint_confidence = 0.5
max_persons = 10
```
### Step 7: Systemd Service Configuration
Create `/etc/systemd/system/momentry.service`:
```ini
[Unit]
Description=Momentry Core Video Analysis Service
After=network.target postgresql.service redis-server.service
Requires=postgresql.service redis-server.service
[Service]
Type=simple
User=momentry
Group=momentry
WorkingDirectory=/opt/momentry
Environment="RUST_LOG=info"
Environment="MOMENTRY_CONFIG=/etc/momentry/config.toml"
ExecStart=/usr/local/bin/momentry server --config /etc/momentry/config.toml
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=momentry
# Security
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/lib/momentry
[Install]
WantedBy=multi-user.target
```
### Step 8: User and Permissions
```bash
# Create momentry user
sudo useradd -r -s /usr/sbin/nologin -d /var/lib/momentry momentry
# Create directories
sudo mkdir -p /var/lib/momentry/{output,backup,logs}
sudo mkdir -p /etc/momentry
# Set permissions
sudo chown -R momentry:momentry /var/lib/momentry
sudo chmod 750 /var/lib/momentry
sudo chmod 640 /etc/momentry/config.toml
# Copy configuration
sudo cp config.toml /etc/momentry/
```
### Step 9: Start and Enable Service
```bash
# Reload systemd
sudo systemctl daemon-reload
# Start service
sudo systemctl start momentry
# Enable on boot
sudo systemctl enable momentry
# Check status
sudo systemctl status momentry
# Expected: active (running)
# View logs
sudo journalctl -u momentry -f
```
### Step 10: Verification Tests
```bash
# Test API endpoint
curl http://localhost:3002/api/health
# Expected: {"status":"healthy","version":"0.1.0"}
# Test video registration
momentry register /path/to/test/video.mp4
# Expected: Video registered with UUID
# Test processor health
momentry processor health
# Expected: All 9 processors healthy
# Test system status
momentry status
# Expected: All services running
```
## Monitoring and Maintenance
### Health Checks
```bash
# Automated health check script
#!/bin/bash
# /usr/local/bin/check-momentry-health.sh
set -e
# Check service status
if ! systemctl is-active --quiet momentry; then
echo "ERROR: Momentry service not running"
exit 1
fi
# Check API health
if ! curl -s http://localhost:3002/api/health | grep -q '"status":"healthy"'; then
echo "ERROR: API health check failed"
exit 1
fi
# Check database connectivity
if ! psql "postgres://accusys:password@localhost:5432/momentry" -c "SELECT 1" >/dev/null 2>&1; then
echo "ERROR: Database connection failed"
exit 1
fi
# Check Redis connectivity
if ! redis-cli -a password ping | grep -q "PONG"; then
echo "ERROR: Redis connection failed"
exit 1
fi
echo "OK: All health checks passed"
exit 0
```
### Log Rotation
Create `/etc/logrotate.d/momentry`:
```
/var/lib/momentry/logs/*.log {
daily
rotate 30
compress
delaycompress
missingok
notifempty
create 640 momentry momentry
postrotate
systemctl reload momentry >/dev/null 2>&1 || true
endscript
}
```
### Backup Strategy
```bash
#!/bin/bash
# /usr/local/bin/backup-momentry.sh
BACKUP_DIR="/var/lib/momentry/backup"
DATE=$(date +%Y%m%d_%H%M%S)
# Create backup directory
mkdir -p "$BACKUP_DIR/$DATE"
# Backup PostgreSQL
pg_dump -U accusys momentry > "$BACKUP_DIR/$DATE/momentry.sql"
# Backup Redis
redis-cli -a password --rdb "$BACKUP_DIR/$DATE/dump.rdb"
# Backup configuration
cp -r /etc/momentry "$BACKUP_DIR/$DATE/"
# Backup output data (exclude cache)
rsync -av --exclude='cache' /var/lib/momentry/output/ "$BACKUP_DIR/$DATE/output/"
# Compress backup
tar -czf "$BACKUP_DIR/momentry_backup_$DATE.tar.gz" -C "$BACKUP_DIR/$DATE" .
# Cleanup
rm -rf "$BACKUP_DIR/$DATE"
# Keep only last 7 days of backups
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +7 -delete
echo "Backup completed: $BACKUP_DIR/momentry_backup_$DATE.tar.gz"
```
### Performance Monitoring
```bash
# Install monitoring tools
sudo apt-get install -y htop iotop nmon
# Create monitoring dashboard
cat > /usr/local/bin/monitor-momentry.sh << 'EOF'
#!/bin/bash
echo "=== Momentry Core Monitoring ==="
echo "Time: $(date)"
echo
# System resources
echo "System Load:"
uptime
echo
echo "Memory Usage:"
free -h
echo
echo "Disk Usage:"
df -h /var/lib/momentry
echo
# Service status
echo "Service Status:"
systemctl status momentry --no-pager | head -20
echo
# Process count
echo "Active Processes:"
ps aux | grep -E "(momentry|python.*processor)" | grep -v grep | wc -l
echo
# API health
echo "API Health:"
curl -s http://localhost:3002/api/health | jq .
echo
# Database connections
echo "Database Connections:"
psql "postgres://accusys:password@localhost:5432/momentry" -c "SELECT count(*) as active_connections FROM pg_stat_activity WHERE datname = 'momentry';"
EOF
chmod +x /usr/local/bin/monitor-momentry.sh
```
## Scaling Considerations
### Vertical Scaling
1. **Database Optimization**:
```sql
-- Increase PostgreSQL connections
ALTER SYSTEM SET max_connections = 200;
-- Add indexes for frequent queries
CREATE INDEX idx_videos_uuid ON videos(uuid);
CREATE INDEX idx_chunks_video_id ON chunks(video_id);
```
2. **Redis Optimization**:
```bash
# Increase Redis memory
redis-cli -a password CONFIG SET maxmemory 2gb
redis-cli -a password CONFIG SET maxmemory-policy allkeys-lru
```
3. **Processor Parallelism**:
```toml
# /etc/momentry/config.toml
[server]
workers = 8 # Increase based on CPU cores
[processors]
max_concurrent = 4 # Limit concurrent processor executions
```
### Horizontal Scaling
1. **Database Replication**:
```bash
# Set up PostgreSQL streaming replication
# Primary: postgres-primary:5432
# Replica: postgres-replica:5432
```
2. **Redis Cluster**:
```bash
# Deploy Redis cluster with 3 masters, 3 replicas
redis-cli --cluster create \
node1:6379 node2:6379 node3:6379 \
node4:6379 node5:6379 node6:6379 \
--cluster-replicas 1
```
3. **Load Balancer Configuration**:
```caddy
# Caddyfile for load balancing
momentry.example.com {
reverse_proxy {
to momentry1:3002 momentry2:3002 momentry3:3002
lb_policy round_robin
health_uri /api/health
health_interval 30s
}
}
```
## Security Hardening
### Network Security
```bash
# Configure firewall
sudo ufw allow 22/tcp # SSH
sudo ufw allow 80/tcp # HTTP
sudo ufw allow 443/tcp # HTTPS
sudo ufw allow 3002/tcp # Momentry API
sudo ufw --force enable
# Isolate services
docker network create --internal momentry-internal
docker network create momentry-public
```
### Service Isolation
```docker-compose
# docker-compose.production.yml
services:
postgres:
networks:
- momentry-internal
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp
- /run
momentry:
networks:
- momentry-internal
- momentry-public
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
```
### Secrets Management
```bash
# Use Docker secrets
echo "postgres_password" | docker secret create db_password -
echo "redis_password" | docker secret create redis_password -
# Reference in docker-compose
services:
postgres:
environment:
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets:
- db_password
redis:
command: redis-server --requirepass $$(cat /run/secrets/redis_password)
secrets:
- redis_password
```
## Troubleshooting
### Common Issues
1. **Service Won't Start**:
```bash
# Check logs
sudo journalctl -u momentry -n 50 --no-pager
# Check configuration
momentry --config /etc/momentry/config.toml validate
# Test database connection
psql "postgres://accusys:password@localhost:5432/momentry" -c "SELECT 1"
```
2. **Processor Failures**:
```bash
# Test individual processor
asr_processor --check-health dummy.mp4 dummy.json
# Check Python dependencies
pip list | grep -E "(whisper|easyocr|ultralytics|opencv)"
# Check GPU availability (if using GPU)
nvidia-smi
```
3. **High Resource Usage**:
```bash
# Identify resource-intensive processes
htop
# Check for memory leaks
ps aux --sort=-%mem | head -10
# Monitor disk I/O
iotop -o
```
### Recovery Procedures
1. **Database Recovery**:
```bash
# Restore from backup
psql -U accusys -d momentry < /var/lib/momentry/backup/momentry_latest.sql
# Rebuild indexes
psql -U accusys -d momentry -c "REINDEX DATABASE momentry;"
```
2. **Service Recovery**:
```bash
# Restart all services
sudo systemctl restart momentry
sudo docker-compose restart
# Verify recovery
sudo systemctl status momentry
curl http://localhost:3002/api/health
```
3. **Data Recovery**:
```bash
# Restore from backup
tar -xzf /var/lib/momentry/backup/momentry_backup_*.tar.gz -C /tmp/
cp -r /tmp/output/* /var/lib/momentry/output/
# Reindex vectors in Qdrant
curl -X POST http://localhost:6333/collections/videos/points/reindex
```
## Performance Optimization
### Tuning Parameters
```toml
# /etc/momentry/config.toml - Optimized for production
[server]
workers = 8 # Match CPU cores
max_connections = 1000
keep_alive = 75
[database]
pool_size = 20
idle_timeout = 300
max_lifetime = 1800
[redis]
pool_size = 50
connection_timeout = 5
read_timeout = 3
write_timeout = 3
[processors]
# Adjust based on hardware
asr_timeout = 7200 # 2 hours for long videos
ocr_timeout = 3600 # 1 hour
yolo_timeout = 14400 # 4 hours
max_concurrent = 2 # Limit to prevent overload
```
### Caching Strategy
```rust
// Example Redis caching configuration
let cache = redis::Client::open("redis://localhost:6379")?
.get_connection()?
.set_read_timeout(Some(Duration::from_secs(2)))?
.set_write_timeout(Some(Duration::from_secs(2)))?;
// Cache video metadata for 1 hour
cache.set_ex("video:metadata:${uuid}", metadata_json, 3600)?;
// Cache processor results for 24 hours
cache.set_ex("processor:result:${uuid}:${processor}", result_json, 86400)?;
```
### Batch Processing
```bash
# Process multiple videos in batch
for video in /data/videos/*.mp4; do
uuid=$(uuidgen)
momentry register "$video" --uuid "$uuid"
momentry process "$uuid" --processors asr,ocr,yolo --parallel
done
# Monitor batch progress
momentry batch status
```
## Compliance and Auditing
### Audit Logging
```toml
# /etc/momentry/config.toml
[audit]
enabled = true
log_file = "/var/lib/momentry/logs/audit.log"
retention_days = 90
# Audit events to log
events = [
"video.registered",
"video.processed",
"processor.started",
"processor.completed",
"processor.failed",
"user.login",
"user.logout",
"config.changed"
]
```
### Compliance Checks
```bash
# Monthly compliance check script
#!/bin/bash
# /usr/local/bin/compliance-check.sh
echo "=== Momentry Core Compliance Check ==="
echo "Date: $(date)"
echo
# Check contract compliance
echo "1. Processor Contract Compliance:"
for processor in asr ocr yolo face pose asrx cut caption story; do
if ${processor}_processor --check-health dummy.mp4 dummy.json 2>&1 | grep -q '"status":"healthy"'; then
echo " ✅ $processor: Compliant"
else
echo " ❌ $processor: Non-compliant"
fi
done
echo
# Check security compliance
echo "2. Security Compliance:"
if sudo ufw status | grep -q "Status: active"; then
echo " ✅ Firewall: Active"
else
echo " ❌ Firewall: Inactive"
fi
if systemctl is-active --quiet fail2ban; then
echo " ✅ Fail2ban: Active"
else
echo " ❌ Fail2ban: Inactive"
fi
echo
# Check backup compliance
echo "3. Backup Compliance:"
if find /var/lib/momentry/backup -name "*.tar.gz" -mtime -1 | grep -q .; then
echo " ✅ Backups: Recent backup exists"
else
echo " ❌ Backups: No recent backup"
fi
if [ -f "/var/lib/momentry/backup/restore_test.txt" ]; then
echo " ✅ Restore Test: Successful"
else
echo " ❌ Restore Test: Not performed"
fi
echo
echo "Compliance check completed"
```
## Conclusion
This production deployment guide provides a comprehensive framework for deploying, managing, and scaling Momentry Core in production environments. The standardized architecture based on the AI-Driven Processor Contract ensures:
1. **Reliability**: System resilience verified through shutdown/reboot testing
2. **Performance**: <5% overhead requirement verified through benchmarks
3. **Maintainability**: Unified configuration and standardized interfaces
4. **Scalability**: Clear scaling paths for both vertical and horizontal expansion
5. **Security**: Comprehensive security hardening and compliance measures
For ongoing maintenance, refer to the [Operations Manual](./MOMENTRY_CORE_OPERATIONS.md) and [Monitoring Guide](./MOMENTRY_CORE_MONITORING.md).
---
**Document Version History**:
- v1.0.0 (2025-03-27): Initial production deployment guide
- Based on Phase 2 standardization completion
- AI Agent optimized for automated deployment
**Next Steps**:
1. Deploy to staging environment for validation
2. Perform load testing with production-like workload
3. Establish monitoring and alerting
4. Create disaster recovery runbook
5. Schedule regular compliance audits

568
docs_v1.0/OPERATIONS/PYTHON.md
View File

@@ -1,568 +0,0 @@
# Python 開發規範
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-16 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-21 | 新增 RedisPublisher API 文檔 | OpenCode | - |
---
## 概述
本文檔定義 Momentry 專案中 Python 程式碼的開發標準與最佳實踐。
---
## 版本管理
### 鎖定版本
| 版本 | 用途 | 路徑 |
|------|------|------|
| Python 3.11.14 | Momentry venv | /Users/accusys/momentry_core_0.1/venv/bin/python |
| Python 3.11.14 | 系統安裝 | /opt/homebrew/bin/python3.11 |
| Python 3.14.3 | 系統預設 | /opt/homebrew/bin/python3 |
| Python 3.9.6 | 系統預設 (備用) | /usr/bin/python3 |
### 版本選擇原則
- **Momentry 專案**：使用 venv 中的 Python 3.11.14
- **新專案**：建議使用 venv 管理
- **系統工具**：可使用系統預設版本
---
## 腳本規範
### Shebang 宣告
所有 Momentry Python 腳本必須在第一行宣告明確的 Python 路徑：
```python
#!/opt/homebrew/bin/python3.11
```
**錯誤範例**：
```python
#!/usr/bin/env python3 # 會解析到系統預設 (3.14.3)
#!/usr/bin/python3 # 會使用系統 Python (3.9.6)
```
**正確範例**：
```python
#!/opt/homebrew/bin/python3.11
import sys
...
```
### 檔案結構
```
scripts/
├── asr_processor.py # ASR 處理腳本
├── thumbnail_extractor.py # 縮圖提取腳本
└── new_script.py # 新腳本模板
```
### 腳本模板
```python
#!/opt/homebrew/bin/python3.11
"""
腳本名稱
簡短描述腳本功能
用法:
python3.11 script.py <args>
作者: Momentry Team
版本: 1.0.0
"""
import argparse
import json
import logging
import sys
from pathlib import Path
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger(__name__)
def main():
parser = argparse.ArgumentParser(description="腳本功能描述")
parser.add_argument("input", help="輸入檔案或參數")
parser.add_argument("-o", "--output", default="output.json", help="輸出檔案")
parser.add_argument("-v", "--verbose", action="store_true", help="詳細輸出")
parser.add_argument("-c", "--count", type=int, default=10, help="數量")
args = parser.parse_args()
if args.verbose:
logger.setLevel(logging.DEBUG)
# 業務邏輯
result = process_data(args.input, args.count)
# 輸出 JSON結果
print(json.dumps(result))
def process_data(input_path: str, count: int) -> dict:
"""處理資料並返回結果"""
logger.info(f"Processing: {input_path}")
# TODO: 實作業務邏輯
return {
"status": "success",
"input": input_path,
"count": count,
}
if __name__ == "__main__":
main()
```
---
## 與 Rust 整合
### 使用 venv (目前採用)
Momentry 使用 venv 管理 Python 環境，避免與系統其他程式衝突。
#### 建立 venv
```bash
# 建立虛擬環境
cd /Users/accusys/momentry_core_0.1
/opt/homebrew/bin/python3.11 -m venv venv
# 啟用虛擬環境
source venv/bin/activate
# 安裝依賴
pip install -r requirements.txt
```
#### 從 Rust 呼叫 venv Python
```rust
use std::path::Path;
let script_path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("scripts")
.join("asr_processor.py");
// 使用 venv 中的 Python
let venv_python = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("venv")
.join("bin")
.join("python");
let output = Command::new(venv_python)
.arg(script_path)
.arg(video_path)
.output()
.context("Failed to run processor")?;
```
**優點**：
- 專案依賴隔離
- 不同專案可使用不同 Python 版本
- 易於重現環境
- 不影響系統其他程式
---
## 依賴管理
### venv 目錄結構
```
momentry_core_0.1/
├── venv/ # 虛擬環境
│ ├── bin/
│ │ ├── python # Python 3.11.14
│ │ ├── pip
│ │ └── ...
│ └── lib/python3.11/ # 安裝的套件
├── requirements.txt # 依賴列表
├── scripts/ # Python 腳本
│ ├── asr_processor.py
│ └── thumbnail_extractor.py
└── src/ # Rust 程式碼
```
### 使用虛擬環境
```bash
# 啟用虛擬環境
source venv/bin/activate
# 安裝依賴
pip install faster-whisper
# 退出虛擬環境
deactivate
```
# 退出虛擬環境
deactivate
```
### 依賴列表格式
建立 `requirements.txt`：
```
faster-whisper>=1.0.0
ffmpeg-python>=0.2.0
Pillow>=10.0.0
```
### 安裝專案依賴
```bash
# 使用 python3.11 安裝
/opt/homebrew/bin/python3.11 -m pip install -r requirements.txt
```
---
## RedisPublisher 進度發布
### 概述
`redis_publisher.py` 提供統一的進度發布介面，用於 Python 處理器向 Rust 端的 TUI 即時回報進度。
### 基本用法
```python
#!/opt/homebrew/bin/python3.11
import sys
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from redis_publisher import RedisPublisher
def process_video(video_path: str, uuid: str):
pub = RedisPublisher(uuid)
pub.info("asr", "Starting ASR processing")
pub.progress("asr", current=50, total=100, message="Processing segment")
pub.complete("asr", "Transcription complete")
```
### API 參考
| 方法 | 說明 | 範例 |
|------|------|------|
| `info(proc, msg)` | 發布資訊訊息 | `pub.info("asr", "Model loaded")` |
| `progress(proc, cur, tot, msg)` | 發布進度 | `pub.progress("asr", 50, 100, "...")` |
| `complete(proc, msg)` | 發布完成 | `pub.complete("asr", "Done")` |
| `error(proc, msg)` | 發布錯誤 | `pub.error("asr", "Failed")` |
| `warning(proc, msg)` | 發布警告 | `pub.warning("asr", "Retry...")` |
| `percentage(proc, pct, msg)` | 發布百分比 | `pub.percentage("asr", 50.5, "50%")` |
### 結構化訊息格式
```python
from redis_publisher import MessageType, ProgressContext
# 使用 Context Manager
with ProgressContext(pub, "asr"):
# 自動發布開始/完成/錯誤
run_asr()
# 帶 extra 資料
pub.progress("asr", current=50, total=100, message="...",
extra={"fps": 30.5, "model": "tiny"})
```
### 環境變數
| 變數 | 預設值 | 說明 |
|------|--------|------|
| `REDIS_URL` | `redis://:accusys@localhost:6379` | Redis 連線 URL |
| `REDIS_PASSWORD` | `accusys` | Redis 密碼 |
---
## 程式碼規範
### Import 排序
```python
# 1. 標準庫
import sys
import os
import json
import logging
from pathlib import Path
from typing import Optional
# 2. 第三方庫
import numpy as np
import pandas as pd
from faster_whisper import WhisperModel
# 3. 本地模組
from . import local_module
from ..package import module
```
### 命名規範
| 類型 | 規範 | 範例 |
|------|------|------|
| 模組/檔案 | snake_case | `asr_processor.py` |
| 類別 | PascalCase | `class VideoProcessor` |
| 函數/變數 | snake_case | `def process_video()` |
| 常量 | UPPER_SNAKE_CASE | `MAX_WORKERS = 4` |
| 私有成員 | _leading_underscore | `_private_method()` |
### 類型提示
```python
from typing import Optional, List, Dict
def process_video(
video_path: str,
options: Optional[Dict[str, int]] = None,
) -> List[Dict[str, float]]:
"""處理影片並返回結果"""
...
```
### 錯誤處理
```python
import logging
from pathlib import Path
logger = logging.getLogger(__name__)
def process_video(video_path: str) -> dict:
path = Path(video_path)
if not path.exists():
logger.error(f"Video file not found: {video_path}")
raise FileNotFoundError(f"Video not found: {video_path}")
try:
result = _do_process(path)
logger.info(f"Processed successfully: {path}")
return result
except Exception as e:
logger.exception(f"Processing failed: {e}")
raise
```
### 日誌規範
```python
import logging
import sys
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger(__name__)
# 使用說明
logger.info("Starting process...")
logger.debug(f"Input: {input_path}")
logger.warning(f"Using fallback: {reason}")
logger.error(f"Failed: {error}")
```
---
## 測試規範
### 測試結構
```
tests/
├── __init__.py
├── test_asr_processor.py
└── test_thumbnail_extractor.py
```
### 測試範例
```python
import pytest
from pathlib import Path
import sys
sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
from asr_processor import run_asr
def test_asr_processor_with_valid_video(tmp_path):
video_path = tmp_path / "test.mp4"
output_path = tmp_path / "output.json"
# 建立測試影片
video_path.write_text("dummy")
# 執行
result = run_asr(str(video_path), str(output_path))
# 斷言
assert output_path.exists()
assert result["segments"]
def test_asr_processor_with_invalid_video():
with pytest.raises(FileNotFoundError):
run_asr("/nonexistent/video.mp4", "/tmp/output.json")
```
### 執行測試
```bash
# 使用 python3.11 執行測試
/opt/homebrew/bin/python3.11 -m pytest tests/ -v
# 包含覆蓋率
/opt/homebrew/bin/python3.11 -m pytest tests/ --cov=scripts
```
---
## 監控配置
### 監控腳本
在 `monitor/config/monitor_config.yaml` 中配置：
```yaml
service:
- name: "python"
type: "process"
process_name: "python3"
enabled: true
check_interval: 60
version_lock: "3.11.14"
scripts:
- "/Users/accusys/momentry_core_0.1/scripts/asr_processor.py"
- "/Users/accusys/momentry_core_0.1/scripts/thumbnail_extractor.py"
```
### 檢查版本
```bash
# 執行 Python 監控
bash /Users/accusys/momentry_core_0.1/monitor/control/monitor_control.sh check python
# 查看資料庫記錄
psql -U accusys -h localhost -d momentry -c "SELECT * FROM python_version_baseline;"
```
---
## CI/CD 考量
### GitHub Actions 範例
```yaml
name: Python Tests
on: [push, pull_request]
jobs:
test:
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python 3.11
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Run tests
run: |
python -m pytest tests/ -v
```
---
## 常見問題
### Q: 為什麼腳本要用 `#!/opt/homebrew/bin/python3.11` 而不是 `#!/usr/bin/env python3`？
A: `#!/usr/bin/env python3` 會解析 PATH 中的第一個 `python3`，在 macOS 上可能是：
- `/opt/homebrew/bin/python3` (3.14.3)
- `/usr/bin/python3` (3.9.6)
明確指定路徑可確保使用正確版本。
### Q: Rust 呼叫 Python 腳本時如何確保版本正確？
A: 有三種方式：
1. Rust 程式碼中使用明確路徑：`Command::new("/opt/homebrew/bin/python3.11")`
2. 設定環境變數 PATH
3. 建立系統別名（不推薦，影響其他程式）
### Q: 如何管理多個 Python 版本？
A: 建議使用：
- **pyenv**：管理多個 Python 版本
- **venv**：隔離專案依賴
- **Docker**：容器化環境
---
## 檢查清單
新增 Python 腳本時確認：
- [ ] 使用 `#!/opt/homebrew/bin/python3.11` shebang
- [ ] 包含 docstring 說明功能
- [ ] 使用 argparse 處理命令行參數
- [ ] 使用 logging 進行日誌輸出
- [ ] 錯誤處理適當
- [ ] 類型提示完整
- [ ] 更新監控配置
- [ ] 建立測試案例
---
## 版本速查
| 版本 | 用途 | 路徑 |
|------|------|------|
| 3.11.14 | Momentry venv | /Users/accusys/momentry_core_0.1/venv/bin/python |
| 3.11.14 | 系統安裝 | /opt/homebrew/bin/python3.11 |
| 3.14.3 | 系統預設 | /opt/homebrew/bin/python3 |
---
## 相關文件
- [NODEJS.md](./NODEJS.md) - Node.js 開發指南
- [RUST_DEVELOPMENT.md](./RUST_DEVELOPMENT.md) - Rust 開發規範
- [monitor_config.yaml](../monitor/config/monitor_config.yaml) - 監控配置
- [python_monitor.sh](../monitor/service/python_monitor.sh) - Python 監控腳本

196
docs_v1.0/OPERATIONS/RELEASE_v0.4.0_2026-04-30.md
View File

@@ -1,196 +0,0 @@
# Release v0.4.0 封存記錄
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-04-30 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-30 | 建立 v0.4.0 獨立封存 | Warren | OpenCode |
---
## 1. 封存資訊
### 1.1 基本資訊
| 項目 | 內容 |
|------|------|
| **Release 版本** | v0.4.0 |
| **封存日期** | 2026-04-30 |
| **Binary 建置時間** | 2026-04-29 19:03 |
| **Git 狀態** | Uncommitted changes (592 files modified) |
| **封存位置** | `/Users/accusys/momentry_core_releases/v0.4.0-2026-04-30/` |
### 1.2 封存內容
| 檔案 | 大小 | 內容 |
|------|------|------|
| `binaries_v0.4.0.tar.gz` | 28MB | 3 個 binary + data 目錄 |
| `output_v0.4.0.tar.gz` | 6.9MB | output/ 目錄 (probe, asr, ocr json) |
### 1.3 包含的 Binary
| Binary | 大小 | 用途 |
|--------|------|------|
| `momentry` | 26MB | Production server (port 3002) |
| `momentry_playground` | 30MB | Development server (port 3003) |
| `momentry_player` | 7.5MB | Video player |
### 1.4 包含的 Data
| 項目 | 路徑 | 說明 |
|------|------|------|
| `data/` | `data/` | 同義詞、角色人臉、logo |
| `english_synonyms.json` | 12KB | 英文同義詞 (135 words) |
| `llm_synonyms.json` | 34KB | LLM 生成同義詞 (162 entries) |
| `domain_synonyms.json` | 133B | 領域同義詞 |
| `synonyms.json` | 348B | 基礎同義詞 |
| `cast_faces/` | - | 角色人臉圖片 (Charade/4808) |
| `logo_images/` | 56KB | Accusys Storage Logo |
---
## 2. 封存結構
```
/Users/accusys/momentry_core_releases/v0.4.0-2026-04-30/
├── binaries/
│ ├── momentry (26M) Production
│ ├── momentry_playground (30M) Development
│ └── momentry_player (7.5M) Player
├── data/
│ ├── cast_faces/
│ │ └── Charade/
│ │ └── 4808/
│ │ ├── Audrey_Hepburn.jpg
│ │ ├── Cary_Grant.jpg
│ │ ├── George_Kennedy.jpg
│ │ ├── James_Coburn.jpg
│ │ ├── Walter_Matthau.jpg
│ │ └── cast_data.json
│ ├── logo_images/
│ │ └── Accusys_Storage_Logo.png
│ ├── domain_synonyms.json
│ ├── english_synonyms.json
│ ├── llm_synonyms.json
│ └── synonyms.json
├── RELEASE_INFO.txt
├── binaries_v0.4.0.tar.gz (28M)
└── output_v0.4.0.tar.gz (6.9M)
```
---
## 3. 還原指南
### 3.1 還原 Binary
```bash
RELEASE_DIR="/Users/accusys/momentry_core_releases/v0.4.0-2026-04-30"
# 解壓縮 binary 與 data
cd "$RELEASE_DIR"
tar -xzf binaries_v0.4.0.tar.gz
# 使用 binary
./binaries/momentry --help
./binaries/momentry_playground --help
```
### 3.2 還原 Output
```bash
RELEASE_DIR="/Users/accusys/momentry_core_releases/v0.4.0-2026-04-30"
# 解壓縮 output
tar -xzf output_v0.4.0.tar.gz
# 檢查內容
ls output/
```
### 3.3 驗證 Binary
```bash
# 檢查 binary 資訊
file /Users/accusys/momentry_core_releases/v0.4.0-2026-04-30/binaries/momentry
# 測試啟動
cd /Users/accusys/momentry_core_releases/v0.4.0-2026-04-30
./binaries/momentry --version 2>/dev/null || echo "No version flag"
```
---
## 4. 對應的 Database Schema
### 4.1 此版本預期使用的 Schema
此 binary 建置時 (Apr 29 19:03) 對應的資料庫狀態：
| 資料庫 | Schema | 狀態 |
|--------|--------|------|
| PostgreSQL | `dev` | 部分使用 `video_uuid` (待修復) |
| MongoDB | `momentry_dev` | collections: `chunks`, `cache` |
| Qdrant | `momentry_dev_rule1` | 已存在 |
| Redis | `momentry_dev:` | 已隔離 |
### 4.2 已知問題
| 問題 | 影響 | 狀態 |
|------|------|------|
| `dev.videos.probe_json` 類型為 TEXT (應為 JSONB) | `GET /api/v1/files` 返回 500 | ⚠️ 待修復 |
| 10 張表仍使用 `video_uuid` | 術語不一致 | ⚠️ 待修復 |
| Rust 代碼 `server.rs:3982` 使用 `video_uuid` | DELETE 語句失敗 | ⚠️ 待修復 |
| Rust 代碼 `face_recognition.rs` 3 處使用 `video_uuid` | 臉部辨識失敗 | ⚠️ 待修復 |
---
## 5. Release 注意事項
### 5.1 Source Code 狀態
此版本 **沒有對應的 git commit**，因為 binary 是從有 uncommitted changes 的工作目錄建置的。
- Uncommitted changes: 592 筆
- 包含: config 修改、docs 刪除、feature 開發
### 5.2 使用建議
1. **僅供緊急回滾使用**: 此封存主要用於災難復原
2. **不應作為新版本基準**: 建議先解決已知問題再建立新版本
3. **Output 資料**: 包含的 output json 可能與當前資料庫狀態不同步
---
## 6. 後續待辦
| 任務 | 優先級 | 狀態 |
|------|--------|------|
| Fix `dev.videos.probe_json` 類型 | High | ⬜ |
| Rename `video_uuid` → `file_uuid` (10 tables) | High | ⬜ |
| Update Rust code (4 locations) | High | ⬜ |
| Configure output dir isolation | Medium | ⬜ |
| Update Python scripts default DB URL | Medium | ⬜ |
| Design API structure (v1.0 aligned) | Medium | ⬜ |
| Implement missing P1 APIs | Medium | ⬜ |
---
## 7. 封存驗證
```bash
# 檢查封存完整性
tar -tzf /Users/accusys/momentry_core_releases/v0.4.0-2026-04-30/binaries_v0.4.0.tar.gz | head -20
tar -tzf /Users/accusys/momentry_core_releases/v0.4.0-2026-04-30/output_v0.4.0.tar.gz | head -20
# 檢查目錄結構
ls -lhR /Users/accusys/momentry_core_releases/v0.4.0-2026-04-30/
```

450
docs_v1.0/OPERATIONS/ROOT_BACKUP_VERSIONING.md
View File

@@ -1,450 +0,0 @@
# Momentry 備份版本管理規範
| 項目 | 內容 |
|------|------|
| 建立者 | Warren / OpenCode |
| 建立時間 | 2026-03-25 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 |
|------|------|------|--------|
| V1.0 | 2026-03-25 | 建立備份版本管理規範 | OpenCode |
---
## 1. 概述
本文檔定義 Momentry 系統的備份版本管理規範，確保新舊架構之間的回滾相容性。
### 1.1 版本定義
| 版本 | 日期 | 說明 |
|------|------|------|
| v1 | 2026-03-18 | 初始備份架構（不包含新架構組件）|
| v2 | 2026-03-25 | 新架構備份（包含 monitor_jobs, processor_results, Output 目錄）|
### 1.2 備份版本格式
| 版本 | 檔案命名格式 |
|------|-------------|
| v1 | `{service}_{type}_{YYYYMMDD}_{HHMMSS}.{ext}` |
| v2 | `{service}_{type}_v2_{YYYYMMDD}_{HHMMSS}.{ext}` |
### 1.3 各版本涵蓋範圍
| 組件 | v1 | v2 |
|------|-----|-----|
| PostgreSQL (videos, chunks) | ✅ | ✅ |
| PostgreSQL (monitor_jobs) | ❌ | ✅ |
| PostgreSQL (processor_results) | ❌ | ✅ |
| Redis | ✅ | ✅ |
| MongoDB Cache | ⚠️ | ⚠️ |
| Output (probe.json) | ❌ | ✅ |
> ⚠️ MongoDB 備份目前存在路徑問題，正在修復中
---
## 2. 備份版本識別
### 2.1 檔名識別
```bash
# 識別版本
detect_version() {
local backup_file=$1
if echo "$backup_file" | grep -q "_v2_"; then
echo "v2"
else
echo "v1"
fi
}
# 使用範例
detect_version "postgresql_db_momentry_v2_20260325_030000.sql.gz"
# 輸出: v2
detect_version "postgresql_db_momentry_20260324_030000.sql.gz"
# 輸出: v1
```
### 2.2 內容識別
```bash
# 檢查是否為 v2 備份
is_v2_backup() {
local backup_file=$1
gzip -dc "$backup_file" 2>/dev/null | grep -q "monitor_jobs" && echo "yes" || echo "no"
}
# 檢查是否包含 processor_results
has_processor_results() {
local backup_file=$1
gzip -dc "$backup_file" 2>/dev/null | grep -q "processor_results" && echo "yes" || echo "no"
}
```
### 2.3 檔案大小比較
| 版本 | PostgreSQL 備份大小 | 說明 |
|------|---------------------|------|
| v1 | ~18-19 MB | 基本資料表 |
| v2 | >19 MB | 包含新表格和索引 |
---
## 3. 回滾策略
### 3.1 回滾流程圖
```
┌─────────────────────────────────────────┐
│ 選擇還原目標 │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 選擇備份版本 │
│ ┌───────────┐ ┌───────────┐ │
│ │ v1 備份 │ │ v2 備份 │ │
│ └───────────┘ └───────────┘ │
└─────────────────────────────────────────┘
│
┌─────────┴─────────┐
▼ ▼
┌──────────┐ ┌──────────┐
│ v1 回滾 │ │ v2 回滾 │
└──────────┘ └──────────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ 基本資料庫 │ │ 完整還原 │
└──────────┘ └──────────┘
```
### 3.2 回滾矩陣
| 還原目標 | v1 備份 | v2 備份 |
|----------|---------|---------|
| 基本資料庫 | ✅ | ✅ |
| + monitor_jobs | ❌ | ✅ |
| + processor_results | ❌ | ✅ |
| + Output 檔案 | ❌ | ✅ |
| + MongoDB Cache | ⚠️ | ⚠️ |
### 3.3 回滾相容性說明
#### v1 → v2（支援）
- v1 備份可以還原到 v2 架構
- 新架構組件會從空白狀態開始
- 不會造成資料損壞
#### v2 → v1（⚠️ 警告）
```
⚠️ v2 回滾到 v1 可能導致資料丟失
影響範圍：
- monitor_jobs 資料會消失
- processor_results 資料會消失
- Output 檔案參照可能失效
建議：
1. 在還原前建立 v2 快照
2. 或使用隔離還原（staging restore）
```
---
## 4. 還原腳本保護機制
### 4.1 還原前檢查
```bash
# 還原前檢查版本相容性
pre_restore_check() {
local backup_file=$1
local version=$(detect_version "$backup_file")
local current_db_version=$(check_current_db_version)
echo "備份版本: $version"
echo "目前版本: $current_db_version"
# v2 → v1: 警告但允許（使用者需確認）
if [ "$version" = "v1" ] && [ "$current_db_version" = "v2" ]; then
echo "⚠️ 警告：即將回滾到 v1"
echo "影響：monitor_jobs 和 processor_results 資料將被清除"
read -p "確認繼續？(y/N): " confirm
[ "$confirm" != "y" ] && exit 1
fi
# v1 → v2: 直接允許
if [ "$version" = "v1" ] && [ "$current_db_version" = "v2" ]; then
echo "ℹ️ 提示：新架構組件將重新初始化"
fi
# v2 → v2: 直接允許
# v1 → v1: 直接允許
}
```
### 4.2 隔離還原（Staging Restore）
```bash
# 只還原到暫存資料庫，不影響生產
restore_to_staging() {
local backup_file=$1
local version=$(detect_version "$backup_file")
echo "執行隔離還原..."
echo "版本: $version"
# 建立暫存資料庫
PGPASSWORD="$PG_PASSWORD" psql -U "$PG_USER" -d postgres << EOF
DROP DATABASE IF EXISTS momentry_staging;
CREATE DATABASE momentry_staging;
EOF
# 還原到暫存資料庫
PGPASSWORD="$PG_PASSWORD" pg_restore -U "$PG_USER" -d "momentry_staging" \
--no-owner --no-acl "$backup_file"
echo "✅ 還原完成：momentry_staging"
echo "驗證命令：psql -U accusys -d momentry_staging -c '\\dt'"
}
```
### 4.3 版本驗證命令
```bash
# 識別所有備份版本
ls /Users/accusys/momentry/backup/daily/postgresql/*.sql.gz | \
xargs -I {} sh -c 'echo "{}: $(detect_version {})"'
# 驗證 v2 備份內容
verify_v2_backup() {
local backup_file=$1
echo "驗證備份: $backup_file"
# 檢查 monitor_jobs
if gzip -dc "$backup_file" | grep -q "monitor_jobs"; then
echo "✅ 包含 monitor_jobs"
else
echo "❌ 缺少 monitor_jobs"
return 1
fi
# 檢查 processor_results
if gzip -dc "$backup_file" | grep -q "processor_results"; then
echo "✅ 包含 processor_results"
else
echo "❌ 缺少 processor_results"
return 1
fi
echo "✅ v2 備份驗證通過"
}
```
---
## 5. 版本遷移
### 5.1 v1 → v2 遷移步驟
| 步驟 | 說明 | 驗證 |
|------|------|------|
| 1 | 確認所有 v1 備份已完成 | `ls *.sql.gz \| grep -v v2` |
| 2 | 修改 `backup_all.sh` 加入 v2 標記 | 確認 TIMESTAMP 包含 `v2_` |
| 3 | 修正 MongoDB 路徑 | 確認指向正確目錄 |
| 4 | 新增 Output 目錄備份 | 確認 probe.json 被備份 |
| 5 | 執行測試備份 | 驗證命名格式正確 |
| 6 | 驗證 v2 備份完整性 | `verify_v2_backup` |
| 7 | 正式啟用 v2 備份 | 確認 crontab 使用新版 |
### 5.2 遷移驗證清單
```bash
#!/bin/bash
# verify_v2_migration.sh
echo "=== v2 遷移驗證 ==="
# 1. 檢查備份腳本
echo "1. 檢查備份腳本..."
if grep -q "v2_" /Users/accusys/momentry/scripts/backup_all.sh; then
echo " ✅ 版本標記已啟用"
else
echo " ❌ 版本標記未啟用"
fi
# 2. 檢查 MongoDB 路徑
echo "2. 檢查 MongoDB 路徑..."
if grep -q "/opt/homebrew/var/mongodb" /Users/accusys/momentry/scripts/backup_all.sh; then
echo " ✅ MongoDB 路徑已修正"
else
echo " ❌ MongoDB 路徑未修正"
fi
# 3. 檢查 Output 目錄備份
echo "3. 檢查 Output 目錄備份..."
if grep -q "momentry_output" /Users/accusys/momentry/scripts/backup_all.sh; then
echo " ✅ Output 目錄備份已啟用"
else
echo " ❌ Output 目錄備份未啟用"
fi
# 4. 檢查最新備份
echo "4. 檢查最新備份..."
latest_backup=$(ls -t /Users/accusys/momentry/backup/daily/postgresql/*.sql.gz 2>/dev/null | head -1)
if [ -n "$latest_backup" ]; then
version=$(detect_version "$latest_backup")
echo " 最新備份: $(basename $latest_backup)"
echo " 版本: $version"
if [ "$version" = "v2" ]; then
verify_v2_backup "$latest_backup"
fi
fi
echo "=== 驗證完成 ==="
```
---
## 6. 疑難排解
### 6.1 常見問題
| 問題 | 原因 | 解決方案 |
|------|------|----------|
| 無法識別版本 | 檔名被修改 | 使用內容分析 `gzip -dc \| grep "monitor_jobs"` |
| v2 備份還原失敗 | 磁碟空間不足 | 清理空間後重試 |
| v1 還原覆蓋 v2 | 操作失誤 | 使用隔離還原保護生產資料 |
| MongoDB 備份為空 | 路徑錯誤 | 修正為 `/opt/homebrew/var/mongodb` |
### 6.2 緊急回滾流程
```bash
#!/bin/bash
# emergency_restore.sh
set -e
BACKUP_FILE=$1
VERSION=$2
echo "=== 緊急回滾 ==="
echo "備份檔案: $BACKUP_FILE"
echo "目標版本: $VERSION"
# 1. 建立當前狀態快照
echo "1. 建立當前狀態快照..."
NOW=$(date +%Y%m%d_%H%M%S)
pg_dump -U accusys -d momentry | gzip > "/tmp/momentry_emergency_$NOW.sql.gz"
echo " 快照: /tmp/momentry_emergency_$NOW.sql.gz"
# 2. 執行還原
echo "2. 執行還原..."
gunzip -c "$BACKUP_FILE" | psql -U accusys -d momentry
# 3. 驗證
echo "3. 驗證還原..."
psql -U accusys -d momentry -c "SELECT COUNT(*) FROM monitor_jobs;"
echo "=== 回滾完成 ==="
```
---
## 7. 備份清單（v2）
### 7.1 每日備份（v2 格式）
| 服務 | 備份項目 | 檔案命名 | 說明 |
|------|----------|----------|------|
| PostgreSQL | momentry | `postgresql_db_momentry_v2_{date}_{time}.sql.gz` | 完整資料庫 |
| PostgreSQL | video_register | `postgresql_db_video_register_v2_{date}_{time}.sql.gz` | 影片註冊資料 |
| Redis | RDB | `redis_rdb_v2_{date}_{time}.rdb` | Redis 快照 |
| MongoDB | 資料 | `mongodb_data_v2_{date}_{time}.tar.gz` | MongoDB 資料 |
| n8n | 資料+DB | `n8n_{date}_{time}.tar.gz`, `n8n_db_{date}_{time}.sql.gz` | n8n 完整 |
| SFTPGo | 配置+DB | `sftpgo_{date}_{time}.tar.gz`, `sftpgo_db_{date}_{time}.sql.gz` | SFTPGo |
| Gitea | 資料 | `gitea_{date}_{time}.tar.gz` | Gitea |
| Output | 檔案 | `momentry_output_v2_{date}_{time}.tar.gz` | probe.json 等 |
### 7.2 備份保留策略
| 類型 | 保留期限 | 位置 |
|------|----------|------|
| 每日備份 | 7 天 | `backup/daily/` |
| 每週備份 | 4 週 | `backup/weekly/` |
| 每月備份 | 12 個月 | `backup/monthly/` |
| 歸檔 | 1 年+ | `backup/archive/` |
---
## 8. 相關文件
| 文件 | 說明 |
|------|------|
| [SERVICES.md](./SERVICES.md) | 服務說明 |
| [MOMENTRY_CORE_MONITORING.md](./MOMENTRY_CORE_MONITORING.md) | 監控規範 |
| `/Users/accusys/momentry/scripts/backup_all.sh` | 備份腳本 |
| `/Users/accusys/momentry/scripts/restore_all.sh` | 還原腳本 |
| `/Users/accusys/momentry_core_0.1/monitor/storage/backup_monitor.sh` | 備份監控 |
---
## 附錄 A：v2 備份完整性檢查清單
```bash
#!/bin/bash
# check_v2_integrity.sh
BACKUP_DIR="/Users/accusys/momentry/backup/daily"
echo "=== v2 備份完整性檢查 ==="
# 檢查 PostgreSQL
echo "1. PostgreSQL..."
pg_backup=$(ls -t "$BACKUP_DIR/postgresql"/postgresql_db_momentry_v2_*.sql.gz 2>/dev/null | head -1)
if [ -n "$pg_backup" ]; then
echo " 備份: $(basename $pg_backup)"
verify_v2_backup "$pg_backup"
else
echo " ❌ 未找到 v2 備份"
fi
# 檢查 Output
echo "2. Output 目錄..."
output_backup=$(ls -t "$BACKUP_DIR/momentry"/momentry_output_v2_*.tar.gz 2>/dev/null | head -1)
if [ -n "$output_backup" ]; then
echo " 備份: $(basename $output_backup)"
echo " ✅ Output 備份已存在"
else
echo " ❌ 未找到 Output 備份"
fi
# 檢查 MongoDB
echo "3. MongoDB..."
mongo_backup=$(ls -t "$BACKUP_DIR/mongodb"/mongodb_data_v2_*.tar.gz 2>/dev/null | head -1)
if [ -n "$mongo_backup" ]; then
size=$(stat -f%z "$mongo_backup" 2>/dev/null || stat -c%s "$mongo_backup" 2>/dev/null)
echo " 備份: $(basename $mongo_backup)"
echo " 大小: $size bytes"
if [ "$size" -gt 1000 ]; then
echo " ✅ MongoDB 備份有效"
else
echo " ⚠️ MongoDB 備份可能為空"
fi
else
echo " ❌ 未找到 MongoDB 備份"
fi
echo "=== 檢查完成 ==="
```

323
docs_v1.0/OPERATIONS/ROOT_FILE_CHANGE_MANAGEMENT.md
View File

@@ -1,323 +0,0 @@
# 文件修改管理規範 v1.0
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-22 |
| 文件版本 | V1.0 |
---
## 1. 概述
本文檔定義 Momentry 專案的文件修改流程，確保不同工具/模型對文件的一致性理解，防止誤修改並保留完整的修改紀錄。
### 1.1 適用範圍
- 所有 `.md` 文件（技術文檔、安裝指南、API 文件等）
- 所有 `.rs` 文件（Rust 源代碼）
- 所有 `.sh` 文件（Shell 腳本）
- 所有 `.yaml` / `.yml` 文件（配置文件）
- 所有 `.json` 文件（配置及數據文件）
### 1.2 核心原則
1. **先讀後改**：修改前必須完整閱讀相關文件
2. **預檢清單**：修改前執行預檢查步驟
3. **變更對照**：修改後必須比對差異
4. **驗證確認**：變更後執行驗證測試
5. **完整紀錄**：所有修改必須記錄於版本歷史
---
## 2. 修改前預檢清單
### 2.1 文件閱讀要求
修改文件前，必須完成以下閱讀：
| 步驟 | 項目 | 說明 |
|------|------|------|
| 1 | 閱讀完整文件 | 不可僅閱讀部分章節 |
| 2 | 理解文件用途 | 確認文件的目標讀者 |
| 3 | 確認現有術語 | 使用一致的術語和命名 |
| 4 | 查閱相關文件 | 確認相關聯的文件 |
### 2.2 預檢問題清單
在修改前回答以下問題：
```
□ 1. 此修改是否影響其他文件？
□ 2. 此修改是否與現有規範衝突？
□ 3. 此修改是否需要更新版本歷史？
□ 4. 此修改是否需要新增測試？
□ 5. 此修改是否需要通知相關人員？
□ 6. 此修改是否有破壞性變更（Breaking Change）？
```
### 2.3 預檢命令
修改前執行以下命令確認現有狀態：
```bash
# 1. 確認 git 狀態
git status
# 2. 檢查相關文件的最新版本
git log -3 --oneline <file_path>
# 3. 查看現有版本歷史
cat docs/<file>.md | grep -A 20 "版本歷史"
```
---
## 3. 文件修改流程
### 3.1 標準修改流程
```
┌─────────────────────────────────────────────────────────────┐
│ Step 1: 閱讀 │
│ ├─ 完整閱讀目標文件 │
│ └─ 閱讀相關聯文件 │
├─────────────────────────────────────────────────────────────┤
│ Step 2: 預檢 │
│ ├─ 回答預檢問題清單 │
│ └─ 執行預檢命令 │
├─────────────────────────────────────────────────────────────┤
│ Step 3: 規劃 │
│ ├─ 說明修改內容 │
│ └─ 列出變更差異 │
├─────────────────────────────────────────────────────────────┤
│ Step 4: 修改 │
│ ├─ 執行修改 │
│ └─ 更新版本歷史 │
├─────────────────────────────────────────────────────────────┤
│ Step 5: 驗證 │
│ ├─ 執行 lint/format 檢查 │
│ └─ 執行相關測試 │
├─────────────────────────────────────────────────────────────┤
│ Step 6: 提交 │
│ └─ 撰寫清晰的 commit message │
└─────────────────────────────────────────────────────────────┘
```
### 3.2 預修改彙報格式
在執行修改前，必須先彙報以下內容：
```markdown
## 檔案
`<file_path>`
## 修改原因
<說明修改的目的>
## 變更內容
```diff
- <刪除的內容>
+ <新增的內容>
```
## 版本歷史更新
| 版本 | 日期 | 內容 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| Vx.x | YYYY-MM-DD | <修改說明> | <操作者> | <使用的工具> |
```
### 3.3 版本歷史格式
每個文件頂部必須包含版本歷史表：
```markdown
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-22 | 更新內容 | Warren | OpenCode / big-pickle |
```
---
## 4. 變更對照
### 4.1 diff 對照
修改後必須提供 diff 對照：
```bash
git diff <file_path>
```
### 4.2 變更類型分類
| 類型 | 標記 | 說明 |
|------|------|------|
| 新增 | `+` | 新增內容 |
| 刪除 | `-` | 刪除內容 |
| 修改 | `~` | 修改內容 |
| 移動 | `↕` | 移動位置 |
| 格式 | `@` | 格式變更 |
### 4.3 變更確認清單
```
□ 1. diff 輸出已確認
□ 2. 變更符合預期
□ 3. 無意外變更
□ 4. 版本歷史已更新
□ 5. 其他關聯文件已檢查
```
---
## 5. 驗證流程
### 5.1 自動化驗證
修改後執行以下自動化檢查：
```bash
# Rust 文件
cargo fmt -- --check
cargo clippy --lib
cargo test --lib
# Python 文件
ruff check <files>
ruff format --check <files>
# Markdown 文件
markdownlint <files>
# Shell 文件
shellcheck -S error <files>
```
### 5.2 手動驗證清單
```
□ 1. 文件語法正確
□ 2. 連結有效
□ 3. 格式一致
□ 4. 術語一致
□ 5. 版本歷史完整
□ 6. 變更記錄清晰
```
---
## 6. 提交規範
### 6.1 Commit Message 格式
```
<type>: <subject>
<body>
<footer>
```
### 6.2 Type 類型
| Type | 說明 |
|------|------|
| `feat` | 新功能 |
| `fix` | 錯誤修復 |
| `refactor` | 重構 |
| `docs` | 文檔更新 |
| `style` | 格式變更 |
| `test` | 測試相關 |
| `chore` | 維護工作 |
### 6.3 Commit Message 範例
```bash
# 文檔更新
git commit -m "docs: update INSTALL_MONGODB.md with LaunchAgent instructions
- Add LaunchDaemon plist installation steps
- Update management commands section
- Add version history entry
Closes: #xxx"
# 配置文件更新
git commit -m "fix: remove duplicate mongodb entry in monitor_config.yaml
The backup section had two mongodb entries which caused confusion.
Removed the duplicate config entry at line 408-414."
```
---
## 7. AI 工具修改額外規範
### 7.1 修改前確認
AI 工具修改文件前，必須：
1. **完整閱讀**：閱讀完整文件（不可只讀取部分）
2. **理解語境**：理解文件的用途和目標讀者
3. **查閱相關**：查閱相關聯文件確保一致性
4. **提出計畫**：修改前先提出變更計畫供確認
### 7.2 修改後確認
AI 工具修改文件後，必須：
1. **展示差異**：顯示修改的 diff 內容
2. **說明變更**：解釋每項變更的目的
3. **執行驗證**：執行相關的 lint/test 命令
4. **更新歷史**：更新版本歷史表
### 7.3 禁止事項
AI 工具**禁止**以下行為：
```
□ 未閱讀完整文件即進行修改
□ 未經確認直接執行大規模修改
□ 未提供 diff 即提交變更
□ 未更新版本歷史
□ 未執行驗證即聲稱完成
□ 擅自刪除其他工具/模型添加的內容
□ 無視現有文件規範
```
---
## 8. 審查清單
### 8.1 提交前審查
```
□ 1. 修改內容已完整閱讀
□ 2. 預檢問題清單已回答
□ 3. diff 對照已確認
□ 4. 版本歷史已更新
□ 5. 自動化驗證已通過
□ 6. 手動驗證清單已完成
□ 7. Commit message 符合規範
□ 8. 無敏感資訊泄露
```
### 8.2 Code Review 關注點
- [ ] 修改是否影響現有功能？
- [ ] 修改是否與專案規範一致？
- [ ] 是否有遺漏的關聯修改？
- [ ] 測試是否足夠？
- [ ] 文檔是否同步更新？
---
## 9. 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode / big-pickle |

674
docs_v1.0/OPERATIONS/ROOT_MOMENTRY_CORE_MONITORING.md
View File

@@ -1,674 +0,0 @@
# Momentry Core 監控規範 (暫定)
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-17 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-17 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-25 | 新增可配置 Redis Key Prefix 說明 | Warren | OpenCode / GLM-5 |
| V1.2 | 2026-03-25 | 新增 Job Worker 監控、processor_results 表 | Warren | OpenCode / GLM-5 |
---
> **⚠️ 狀態**: 此文檔為暫定版本，momentry_core 仍在開發中，待開發完成後再正式納入監控系統。
---
## 1. 概述
momentry_core 是 Rust 開發的數字資產管理系統，專注於視頻分析和 RAG 功能。
## 2. 監控架構
### Layer 2: Service 監控
| 項目 | 類型 | 檢查方式 | Port | 狀態 |
|------|------|----------|------|------|
| postgresql | TCP | `pg_isready` | 5432 | ✅ 運行中 |
| redis | TCP | `redis-cli ping` | 6379 | ✅ 運行中 |
| n8n | HTTP | `/healthz` | 5678 | ✅ 運行中 |
| sftpgo | HTTP | `/healthz`, `/api/v2/token` | 8080 | ✅ 運行中 |
| qdrant | HTTP | `/collections` | 6333 | ✅ 運行中 |
| momentry_core | CLI | `momentry --version` | - | ⚠️ 待編譯 |
**附屬服務狀態** (非核心但相關):
| gitea | HTTP | `/` | 3000 | ✅ 運行中 |
| ollama | HTTP | `/api/tags` | 11434 | ✅ 運行中 |
| caddy | HTTP | `/` | 80 | ✅ 運行中 |
### Layer 7: Backup 監控
| 項目 | 類型 | 位置 |
|------|------|------|
| momentry | data | `/Users/accusys/momentry/backup/momentry` |
| sftpgo | config + db | `/Users/accusys/momentry/backup/daily/sftpgo/` |
---
## 3. Redis 監控架構
> **⚠️ 注意**: 從 V1.1 開始，所有 Redis Keys 都支援自定義前綴。
> 預設前綴：生產環境為 `momentry:`，開發環境為 `momentry_dev:`
>
> 若使用非預設前綴，請將下方命令中的 `momentry:` 替換為實際前綴。
### 3.1 健康檢查
```bash
# 檢查 Redis 連線
redis-cli -a accusys ping
# 檢查 momentry 健康狀態
redis-cli GET momentry:health:current
```
### 3.2 Job 狀態監控
```bash
# 查看運行中的 Jobs
redis-cli SMEMBERS momentry:jobs:active
# 查看 Job 狀態
redis-cli HGETALL momentry:job:5dea6618a606e7c7
```
### 3.3 即時進度監控
```bash
# 訂閱進度頻道
redis-cli SUBSCRIBE momentry:progress:5dea6618a606e7c7
```
---
## 4. 監控腳本
### 4.1 健康檢查項目細節
基於當前系統狀態，需要監控的核心項目:
#### 4.1.1 資料庫服務檢查
```bash
# PostgreSQL - 檢查伺服器運行與關鍵資料庫
check_postgresql() {
if pg_isready -h localhost -p 5432 > /dev/null 2>&1; then
echo -e "${GREEN}✓${NC} PostgreSQL"
# 檢查關鍵資料庫是否存在
local missing_dbs=()
for db in momentry video_register n8n sftpgo; do
if ! psql -h localhost -U postgres -lqt 2>/dev/null | cut -d\| -f1 | grep -qw "$db"; then
missing_dbs+=("$db")
fi
done
if [ ${#missing_dbs[@]} -gt 0 ]; then
echo -e " ${YELLOW}⚠${NC} 缺失資料庫: ${missing_dbs[*]}"
record_service "postgresql" "warning" "1" "Missing databases: ${missing_dbs[*]}"
else
record_service "postgresql" "up" "1" ""
fi
else
echo -e "${RED}✗${NC} PostgreSQL"
record_service "postgresql" "down" "0" "PostgreSQL not responding"
fi
}
```
#### 4.1.2 Redis 檢查
```bash
check_redis() {
if redis-cli -a "$REDIS_PASSWORD" ping 2>/dev/null | grep -q PONG; then
echo -e "${GREEN}✓${NC} Redis"
record_service "redis" "up" "1" ""
else
echo -e "${RED}✗${NC} Redis"
record_service "redis" "down" "0" "Redis not responding"
fi
}
```
#### 4.1.3 SFTPGo 檢查
```bash
check_sftpgo() {
# 1. 檢查 HTTP API
if curl -s http://localhost:8080/healthz > /dev/null 2>&1; then
# 2. 檢查 API 認證
if TOKEN=$(curl -s -X GET http://localhost:8080/api/v2/token -u "admin:$SFTPGO_ADMIN_PASSWORD" 2>/dev/null | jq -r '.access_token') && [ -n "$TOKEN" ]; then
echo -e "${GREEN}✓${NC} SFTPGo"
record_service "sftpgo" "up" "1" ""
else
echo -e "${YELLOW}⚠${NC} SFTPGo (API認證失敗)"
record_service "sftpgo" "warning" "1" "API authentication failed"
fi
else
echo -e "${RED}✗${NC} SFTPGo"
record_service "sftpgo" "down" "0" "HTTP API not responding"
fi
}
```
#### 4.1.4 n8n 檢查
```bash
check_n8n() {
if curl -s http://localhost:5678/healthz > /dev/null 2>&1; then
echo -e "${GREEN}✓${NC} n8n"
record_service "n8n" "up" "1" ""
else
echo -e "${RED}✗${NC} n8n"
record_service "n8n" "down" "0" "API not responding"
fi
}
```
#### 4.1.5 Qdrant 檢查
```bash
check_qdrant() {
if curl -s http://localhost:6333/collections > /dev/null 2>&1; then
echo -e "${GREEN}✓${NC} Qdrant"
record_service "qdrant" "up" "1" ""
else
echo -e "${RED}✗${NC} Qdrant"
record_service "qdrant" "down" "0" "API not responding"
fi
}
```
#### 4.1.6 Momentry Core 檢查
```bash
check_momentry_core() {
local binary="/Users/accusys/momentry/target/release/momentry"
if [ ! -f "$binary" ]; then
binary="/Users/accusys/momentry/target/debug/momentry"
fi
if [ -f "$binary" ] && $binary --version > /dev/null 2>&1; then
echo -e "${GREEN}✓${NC} Momentry Core"
record_service "momentry_core" "up" "1" ""
else
echo -e "${RED}✗${NC} Momentry Core"
record_service "momentry_core" "down" "0" "Binary not found or not executable"
fi
}
```
### 4.2 檢查腳本範例完整實現
```bash
#!/bin/bash
# monitor/service/health_check.sh
export REDIS_PASSWORD="accusys"
export SFTPGO_ADMIN_PASSWORD="Test3200Test3200"
check_postgresql
check_redis
check_sftpgo
check_n8n
check_qdrant
check_momentry_core
```
### 4.2 Redis Job 監控腳本
**檔案**: `monitor/service/redis_job_monitor.sh`
此腳本專門監控 Redis 中的 Job 狀態與即時進度:
```bash
#!/bin/bash
# Momentry Core Redis Job 監控
REDIS_PASSWORD="${REDIS_PASSWORD:-accusys}"
REDIS_PREFIX="${REDIS_PREFIX:-momentry:}"# 可配置前綴，預設 momentry:
# 檢查 Job 狀態
check_job_status() {
local active_jobs=$(redis-cli -a "$REDIS_PASSWORD" SCARD "${REDIS_PREFIX}jobs:active" 2>/dev/null || echo "0")
local completed_jobs=$(redis-cli -a "$REDIS_PASSWORD" SCARD "${REDIS_PREFIX}jobs:completed" 2>/dev/null || echo "0")
local failed_jobs=$(redis-cli -a "$REDIS_PASSWORD" SCARD "${REDIS_PREFIX}jobs:failed" 2>/dev/null || echo "0")
echo "Momentry Jobs: Active=$active_jobs, Completed=$completed_jobs, Failed=$failed_jobs"
echo "$active_jobs $completed_jobs $failed_jobs"
}
# 檢查特定 Job 進度
check_job_progress() {
local job_uuid=$1
if [ -z "$job_uuid" ]; then
echo "Usage: $0 progress <uuid>"
return 1
fi
local progress=$(redis-cli -a "$REDIS_PASSWORD" HGETALL "${REDIS_PREFIX}job:$job_uuid" 2>/dev/null)
if [ -n "$progress" ]; then
echo "Job $job_uuid progress:"
echo "$progress" | while read -r key value; do
[ -n "$key" ] && echo " $key: $value"
done
else
echo "No progress data for job $job_uuid"
fi
}
# 訂閱即時進度頻道
subscribe_progress() {
local job_uuid=$1
if [ -z "$job_uuid" ]; then
echo "Subscribing to all progress channels..."
redis-cli -a "$REDIS_PASSWORD" PSUBSCRIBE "${REDIS_PREFIX}progress:*" 2>/dev/null
else
echo "Subscribing to job $job_uuid progress..."
redis-cli -a "$REDIS_PASSWORD" SUBSCRIBE "${REDIS_PREFIX}progress:$job_uuid" 2>/dev/null
fi
}
# 列出所有活動 Job
list_active_jobs() {
echo "Active Jobs:"
redis-cli -a "$REDIS_PASSWORD" SMEMBERS "${REDIS_PREFIX}jobs:active" 2>/dev/null | while read -r uuid; do
[ -n "$uuid" ] && echo " - $uuid"
done
}
# 主程序
case "$1" in
status)
check_job_status
;;
progress)
check_job_progress "$2"
;;
subscribe)
subscribe_progress "$2"
;;
list)
list_active_jobs
;;
*)
echo "Usage: $0 {status|progress <uuid>|subscribe [uuid]|list}"
exit 1
;;
esac
```
### 4.3 監控腳本排程
使用 cron 定期執行健康檢查：
```bash
# crontab -e
# 每 5 分鐘執行一次健康檢查
*/5 * * * * /Users/accusys/momentry/scripts/health_check.sh >> /Users/accusys/momentry/log/health_check.log 2>&1
```
### 4.4 監控數據記錄
健康檢查結果應寫入監控數據庫，建議的 `monitor_services` 表結構:
```sql
CREATE TABLE monitor_services (
id SERIAL PRIMARY KEY,
service_name VARCHAR(50) NOT NULL,
status VARCHAR(20) NOT NULL, -- up, down, warning
error_message TEXT,
checked_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_monitor_services_checked ON monitor_services(checked_at);
CREATE INDEX idx_monitor_services_name ON monitor_services(service_name);
```
---
## 5. 配置更新
### 5.1 環境變數
必需監控相關環境變數配置在 `.env` 或系統中：
```bash
# Redis 連接
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=accusys
# Redis Key Prefix (可選，預設: momentry:)
REDIS_PREFIX=momentry:
# SFTPGo 管理員密碼 (用於 API 健康檢查)
SFTPGO_ADMIN_PASSWORD=Test3200Test3200
# Momentry Core 路徑 (可選，如果不在標準位置)
MOMENTRY_BINARY_PATH="/Users/accusys/momentry/target/release/momentry"
```
### 5.2 監控配置範例
**檔案**: `monitor/config/monitor_config.yaml`
```yaml
services:
# Redis - 消息隊列與狀態存儲
- name: "redis"
type: "tcp"
host: "localhost"
port: 6379
timeout: 3
enabled: true
# PostgreSQL - 數據庫
- name: "postgresql"
type: "tcp"
host: "localhost"
port: 5432
timeout: 5
enabled: true
check_sql: "SELECT 1;" # 可選：執行 SQL 驗證
# n8n - 工作流引擎
- name: "n8n"
type: "http"
host: "localhost"
port: 5678
check_url: "http://localhost:5678/healthz"
timeout: 5
enabled: true
# SFTPGo - 文件上傳服務
- name: "sftpgo"
type: "http"
host: "localhost"
port: 8080
check_url: "http://localhost:8080/healthz"
timeout: 5
enabled: true
# 附加認證檢查（每小時一次）
auth_check:
endpoint: "/api/v2/token"
method: "GET"
username: "admin"
password_env: "SFTPGO_ADMIN_PASSWORD"
# Qdrant - 向量數據庫
- name: "qdrant"
type: "http"
host: "localhost"
port: 6333
check_url: "http://localhost:6333/collections"
timeout: 5
enabled: true
# Momentry Core CLI
- name: "momentry_core"
type: "cli"
binary_path: "/Users/accusys/momentry/target/release/momentry"
args: ["--version"]
timeout: 3
enabled: true
```
### 5.3 備份配置更新
統一備份系統 (`backup_all.sh`) 已包含 SFTPGo 備份，無需額外配置。
備份保留策略 (預設):
- **每日備份**: 保留 7 天
- **每週備份**: 保留 4 週
- **每月備份**: 保留 12 個月
備份存儲位置:
- 配置文件: `/Users/accusys/momentry/backup/daily/<service>/`
- 最新備份鏈接: `/Users/accusys/momentry/backup/latest/` (由 backup_monitor.sh 管理)
### 5.4 監控腳本配置
建立符號鏈接到監控腳本目錄:
```bash
ln -sf /Users/accusys/momentry/scripts/backup_all.sh /usr/local/bin/backup_all
ln -sf /Users/accusys/momentry/scripts/health_check.sh /usr/local/bin/health_check
```
這樣可以在任何地方執行:
```bash
health_check
backup_all status
backup_all restore sftpgo 20260321_101928
```
---
## 6. 報警規則
| 層級 | 異常類型 | 等級 | 處理 |
|------|----------|------|------|
| Service | PostgreSQL 未運行 | Critical | 記錄 + 通知 |
| Service | Redis 未運行 | Critical | 記錄 + 通知 |
| Service | n8n API 無回應 | Critical | 記錄 + 通知 |
| Service | SFTPGo API 無回應 | Critical | 記錄 + 通知 |
| Service | Qdrant 未運行 | Critical | 記錄 + 通知 |
| Service | Momentry CLI 缺失 | Critical | 記錄 + 通知 |
| Database | 關鍵資料庫不存在 | Warning | 記錄 |
| Backup | 備份失敗 | Critical | 記錄 |
| Backup | 備份過期 | Warning | 記錄 |
| Job | 處理失敗 | Warning | 記錄 |
| Job | 處理超時 | Warning | 記錄 |
### 6.1 資料庫缺失處理
當檢查到以下資料庫不存在時，應記錄警告:
- `momentry` - Momentry Core 主資料庫
- `video_register` - 視頻註冊資料庫
- `n8n` - n8n 工作流資料庫
- `sftpgo` - SFTPGo 資料庫
**處理程序**:
1. 確認是否為首次安裝（資料庫尚未建立）
2. 檢查備份並執行還原
3. 如果是意外刪除，立即從最新備份恢復
### 6.2 SFTPGo 監控特殊注意
SFTPGo 使用雙重認證檢查:
1. **健康檢查**: `/healthz` (無需認證)
2. **API 可用性**: `/api/v2/token` (需要 Basic Auth)
若 `/healthz` 正常但 `/api/v2/token` 失敗，可能是:
- admin 密碼被重置
- 數據庫連接問題
- API 配置錯誤
應立即檢查:
```bash
tail -20 /Users/accusys/momentry/log/sftpgo.log
tail -20 /Users/accusys/momentry/log/sftpgo.error.log
```
---
## 7. 數據庫記錄
### monitor_jobs 表
```sql
CREATE TABLE monitor_jobs (
id SERIAL PRIMARY KEY,
uuid VARCHAR(16) NOT NULL,
video_path VARCHAR(512),
status VARCHAR(20),
current_processor VARCHAR(20),
progress_total INT,
progress_current INT,
error_count INT DEFAULT 0,
last_error TEXT,
started_at TIMESTAMP,
updated_at TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_monitor_jobs_uuid ON monitor_jobs(uuid);
CREATE INDEX idx_monitor_jobs_status ON monitor_jobs(status);
CREATE INDEX idx_monitor_jobs_created_at ON monitor_jobs(created_at);
```
### processor_results 表
```sql
CREATE TABLE processor_results (
id SERIAL PRIMARY KEY,
job_id INTEGER REFERENCES monitor_jobs(id) ON DELETE CASCADE,
video_id BIGINT REFERENCES videos(id),
processor VARCHAR(20) NOT NULL,
status VARCHAR(20) NOT NULL DEFAULT 'pending',
started_at TIMESTAMP,
completed_at TIMESTAMP,
error_message TEXT,
created_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_processor_results_job ON processor_results(job_id);
CREATE INDEX idx_processor_results_video ON processor_results(video_id);
CREATE INDEX idx_processor_results_status ON processor_results(status);
```
**processor 狀態值**:
- `pending` - 等待處理
- `running` - 處理中
- `completed` - 已完成
- `failed` - 處理失敗
- `skipped` - 跳過（已在其他處理中完成）
---
## 8. 環境變數
```bash
# 輸出目錄
MOMENTRY_OUTPUT_DIR=/path/to/output
# 備份
MOMENTRY_BACKUP_ENABLED=true
MOMENTRY_BACKUP_DIR=/Users/accusys/momentry/backup/momentry
# Redis
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=accusys
```
---
## 9. 待實作項目
| # | 項目 | 狀態 | 更新日期 |
|---|------|------|---------|
| 1 | 實作 Redis Pub/Sub 客戶端 | ✅ 已實作 | 2026-03-21 |
| 2 | 修改 Python processors 使用 Redis | ✅ 已實作 | 2026-03-21 |
| 3 | 設計並實現 health_check.sh | ✅ 已實作 | 2026-03-22 |
| 4 | 創建 monitor_jobs 表 | ✅ 已實作 | 2026-03-21 |
| 5 | SFTPGo 備份與還原流程 | ✅ 已實作 | 2026-03-22 |
| 6 | SFTPGo API 管理工具 | ✅ 已實作 | 2026-03-22 |
| 7 | SFTPGo Hook 自動註冊 | ✅ 已實作 | 2026-03-22 |
| 8 | 文檔化監控規範 | ✅ 已實作 | 2026-03-22 |
| 9 | Job Worker 輪詢機制 | ✅ 已實作 | 2026-03-25 |
| 10 | processor_results 表 | ✅ 已實作 | 2026-03-25 |
| 11 | Probe API 端點 | ✅ 已實作 | 2026-03-25 |
| 12 | 整合測試 | 🔜 待實作 | - |
| 13 | 生產環境部署驗證 | ⏳ 待開始 | - |
### Job Worker 監控 (2026-03-25 新增)
**Worker 服務狀態檢查**:
```bash
# 檢查 Worker 程序
ps aux | grep momentry
# 查看 Worker 日誌
tail -f /Users/accusys/momentry/log/worker.log
```
**monitor_jobs 狀態查詢**:
```bash
# 查看待處理工作
psql -U accusys -d momentry -c "SELECT * FROM monitor_jobs WHERE status = 'pending';"
# 查看執行中工作
psql -U accusys -d momentry -c "SELECT * FROM monitor_jobs WHERE status = 'running';"
# 查看失敗工作
psql -U accusys -d momentry -c "SELECT * FROM monitor_jobs WHERE status = 'failed';"
```
**processor_results 狀態查詢**:
```bash
# 查看特定工作的處理器狀態
psql -U accusys -d momentry -c "
SELECT pr.*, mj.uuid
FROM processor_results pr
JOIN monitor_jobs mj ON pr.job_id = mj.id
WHERE mj.uuid = 'a1b10138a6bbb0cd';
"
# 查看所有失敗的處理器
psql -U accusys -d momentry -c "
SELECT pr.processor, COUNT(*) as failures
FROM processor_results pr
WHERE pr.status = 'failed'
GROUP BY pr.processor;
"
```
**Redis 工作狀態**:
```bash
# 查看活躍工作
redis-cli SMEMBERS momentry:jobs:active
# 查看工作詳情
redis-cli HGETALL momentry:job:{uuid}
```
### 已完成實作 (2026-03-22)
**監控系統**:
- 完整健康檢查腳本設計: `docs/MOMENTRY_CORE_MONITORING.md`
- 多層次服務監控 (Layer 2: Service, Layer 7: Backup)
- Redis Job 監控腳本: `monitor/service/redis_job_monitor.sh`
- SFTPGo 特殊監控 (API 認證檢查)
**SFTPGo 管理**:
- 備份還原機制: `backup_all.sh` (第 325-546 行)
- API 管理用戶與組 (完整文件於 `docs/INSTALL_SFTPGO.md`)
- Hook 自動註冊流程: `/Users/accusys/sftpgo_test/register_hook.sh`
- Demo 用戶與組完整測試環境
**文檔更新**:
- `docs/INSTALL_SFTPGO.md`: 新增備份還原、API管理、Hook配置章節
- `docs/MOMENTRY_CORE_MONITORING.md`: 完善監控規範
### 待驗證功能
- [ ] 端到端測試: SFTP 上傳 → Hook → Momentry 註冊 → n8n 工作流
- [ ] Momentry Core API 搜索功能: `GET /api/v1/searchable`
- [ ] 背景處理自動觸發: `cargo run -- process <uuid>`
---
## 10. 參考文檔
- [Redis Key 設計規範](./MOMENTRY_CORE_REDIS_KEYS.md)
- [監控系統總覽](../monitor/MONITORING.md)
- [備份規範](./SERVICE_ADDITION_GUIDE.md)
- [SFTPGo 安裝與管理指南](./INSTALL_SFTPGO.md)
- [API 參考文件](../docs/API_REFERENCE.md)
- [n8n 整合指南](./N8N_INTEGRATION_GUIDE.md)

990
docs_v1.0/OPERATIONS/RUST_DEVELOPMENT.md
View File

@@ -1,990 +0,0 @@
# Rust 開發規範 - Momentry Core
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-16 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-21 | 新增 PythonExecutor 模組說明 | OpenCode | - |
---
本規範定義 Momentry Core 專案的 Rust 開發標準，確保程式碼品質與一致性。
## 1. 專案結構
### 1.1 目錄架構
```
src/
├── main.rs # CLI 入口點
├── lib.rs # 函式庫導出
├── cli/
│ ├── mod.rs
│ └── commands/ # CLI 命令模組
├── core/
│ ├── mod.rs
│ ├── chunk/ # 影片分段邏輯
│ │ ├── mod.rs
│ │ ├── splitter.rs
│ │ └── types.rs
│ ├── db/ # 資料庫抽象層
│ │ ├── mod.rs
│ │ ├── postgres_db.rs
│ │ ├── mongodb_db.rs
│ │ ├── redis_db.rs
│ │ └── qdrant_db.rs
│ ├── processor/ # 影片處理器
│ │ ├── mod.rs
│ │ ├── executor.rs # Python 腳本統一執行器 (含超時控制)
│ │ ├── asr.rs # 語音識別
│ │ ├── asrx.rs # 說話者分離
│ │ ├── ocr.rs # 文字辨識
│ │ ├── yolo.rs # 物件偵測
│ │ ├── face.rs # 人臉偵測
│ │ └── pose.rs # 姿態估計
│ ├── embedding/ # 向量嵌入
│ ├── probe/ # ffprobe 整合
│ ├── storage/ # 檔案管理
│ └── thumbnail/ # 縮圖生成
├── api/ # HTTP API
│ ├── mod.rs
│ └── routes/
├── player/ # 影片播放
└── watcher/ # 檔案監控
```
### 1.2 模組設計原則
- **單一職責**: 每個模組專注於一項功能
- **介面抽象**: 使用 trait 定義資料庫、操作器等介面
- **依賴注入**: 透過建構函式注入依賴
```rust
pub trait VideoProcessor: Send + Sync {
async fn process(&self, video_path: &str) -> Result<ProcessResult>;
}
```
## 2. 程式碼風格
### 2.1 命名規範
| 類型 | 規範 | 範例 |
|------|------|------|
| 結構體/列舉 | PascalCase | `VideoRecord`, `ChunkType` |
| 函式/變數 | snake_case | `get_video_by_uuid` |
| Trait | PascalCase + er 尾碼 | `Database`, `ChunkStore` |
| 檔案 | snake_case | `postgres_db.rs` |
| 常量 | SCREAMING_SNAKE_CASE | `MAX_CHUNK_SIZE` |
| 模組 | snake_case | `chunk`, `processor` |
### 2.2 匯入順序
```rust
// 1. 標準庫
use std::path::Path;
use std::process::Command;
// 2. 外部庫
use anyhow::{Context, Result};
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use tokio::fs;
// 3. 內部模組
use crate::core::chunk::Chunk;
use crate::core::db::PostgresDb;
```
### 2.3 行寬與格式
- 最大行寬: 100 字元
- 使用 4 空格縮排
- 啟用 clippy 與 fmt
```bash
# 格式化
cargo fmt
# 檢查格式
cargo fmt -- --check
# Lint
cargo clippy --all-features
```
## 3. 錯誤處理
### 3.1 錯誤類型選擇
| 情境 | 錯誤類型 | 原因 |
|------|----------|------|
| 應用程式 | `anyhow::Result<T>` | 提供靈活的錯誤傳播 |
| 函式庫 | `thiserror` | 定義明確的錯誤類型 |
| API 錯誤 | 自定義 Error enum | 提供客戶端錯誤碼 |
### 3.2 錯誤處理範例
```rust
use anyhow::{Context, Result, bail};
fn process_video(video_path: &str) -> Result<VideoMetadata> {
// 使用 context 提供錯誤上下文
let output = Command::new("ffprobe")
.args(["-v", "quiet", "-print_format", "json", "-show_format", video_path])
.output()
.context("Failed to run ffprobe")?;
// 使用 bail 進行早期返回
if !output.status.success() {
let stderr = String::from_utf8_lossy(&output.stderr);
bail!("ffprobe failed: {}", stderr);
}
// 解析輸出
let metadata: Metadata = serde_json::from_slice(&output.stdout)
.context("Failed to parse ffprobe output")?;
Ok(metadata)
}
```
### 3.3 自定義錯誤 (適用於函式庫)
```rust
use thiserror::Error;
#[derive(Error, Debug)]
pub enum VideoError {
#[error("Video not found: {0}")]
NotFound(String),
#[error("Invalid codec: {0}")]
InvalidCodec(String),
#[error("Processing failed: {0}")]
ProcessingError(#[from] std::io::Error),
}
```
## 4. 异步編程
### 4.1 Tokio 配置
```rust
// Cargo.toml
tokio = { version = "1", features = ["full"] }
```
### 4.2 Async Trait
```rust
use async_trait::async_trait;
#[async_trait]
pub trait Database: Send + Sync {
async fn init() -> Result<Self>
where Self: Sized;
async fn get_video(&self, uuid: &str) -> Result<Option<VideoRecord>>;
async fn store_chunk(&self, chunk: &Chunk) -> Result<()>;
}
```
### 4.3 避免常見陷阱
```rust
// ❌ 錯誤: 在同步上下文中調用 async 函式
fn bad_example() {
let result = db.get_video("xxx"); // 編譯錯誤
}
// ✅ 正確: 使用 #[tokio::main]
#[tokio::main]
async fn main() {
let result = db.get_video("xxx").await;
}
// ❌ 錯誤: 阻塞執行緒池
async fn bad_practice() {
let data = std::fs::read_to_string("file.txt").unwrap(); // 阻塞
}
// ✅ 正確: 使用 tokio::fs
async fn good_practice() {
let data = tokio::fs::read_to_string("file.txt").await.unwrap();
}
```
## 5. 外部程序整合
當需要使用 Python 生態系工具 (如 faster-whisper, YOLO) 時：
```rust
pub async fn process_asr(video_path: &str, output_path: &str) -> Result<AsrResult> {
let script_path = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("scripts")
.join("asr_processor.py");
// 使用 venv 中的 Python，確保版本隔離
let venv_python = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("venv")
.join("bin")
.join("python");
// 執行腳本
let output = Command::new(venv_python)
.arg(script_path)
.arg(video_path)
.arg(output_path)
.output()
.context("Failed to run ASR processor")?;
if !output.status.success() {
let stderr = String::from_utf8_lossy(&output.stderr);
bail!("ASR failed: {}", stderr);
}
// 讀取輸出
let json_str = std::fs::read_to_string(output_path)
.context("Failed to read ASR output")?;
let result: AsrResult = serde_json::from_str(&json_str)
.context("Failed to parse ASR output")?;
Ok(result)
}
```
### 5.2 進度回報
透過 stderr 回報進度，供 Rust 端解析：
```python
# Python 腳本
import sys
print(f"ASR_START", file=sys.stderr)
print(f"ASR_LANGUAGE:{detected_lang}", file=sys.stderr)
print(f"ASR_PROGRESS:{count}", file=sys.stderr)
print(f"ASR_COMPLETE:{total}", file=sys.stderr)
```
```rust
// Rust 端解析
let stderr = String::from_utf8_lossy(&output.stderr);
for line in stderr.lines() {
if line.starts_with("ASR_PROGRESS:") {
let count = line.trim_start_matches("ASR_PROGRESS:");
println!("[ASR] Processed {} segments...", count);
}
}
```
### 5.3 PythonExecutor 統一執行器
使用 `PythonExecutor` 封裝 Python 腳本執行邏輯：
```rust
use momentry_core::core::processor::{PythonExecutor, validate_python_env};
// 驗證 Python 環境
fn init() -> Result<()> {
validate_python_env()?;
Ok(())
}
// 使用 Executor 執行腳本
async fn run_script() -> Result<()> {
let executor = PythonExecutor::new()?;
executor.run(
"asr_processor.py",
&["/path/to/video.mp4", "/path/to/output.json"],
Some("job-uuid"),
"ASR",
Some(Duration::from_secs(3600)), // 1小時超時
).await?;
Ok(())
}
```
#### Processor 超時設定
| Processor | 超時 | 說明 |
|----------|------|------|
| ASR | 1 小時 | 語音識別 |
| ASRx | 2 小時 | 說話者分離 |
| YOLO | 2 小時 | 物件偵測 |
| OCR | 2 小時 | 文字辨識 |
| Face | 2 小時 | 人臉偵測 |
| Pose | 2 小時 | 姿態估計 |
| Cut | 1 小時 | 場景偵測 |
---
## 6. Python 與 Node.js 混用規範
本專案同時使用 Python 和 Node.js (n8n)，需建立明確的版本隔離與管理規範。
### 6.1 架構概述
```
┌─────────────────────────────────────────────────────────────┐
│ Momentry Core │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Rust │ │ Python │ │ Node.js │ │
│ │ (Core) │───▶ │ (Scripts) │ │ (n8n) │ │
│ │ │ │ │ │ │ │
│ │ - CLI │ │ - ASR │ │ - Workflow │ │
│ │ - DB │ │ - Thumb │ │ - API │ │
│ │ - Storage │ │ - OCR │ │ - Webhooks │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 資料庫 / 檔案系統 / Qdrant │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 6.2 Python 版本管理
#### 6.2.1 版本鎖定
| 版本 | 用途 | 路徑 |
|------|------|------|
| 3.11.14 | 影片處理腳本 | `/opt/homebrew/bin/python3.11` |
#### 6.2.2 虛擬環境
使用專案隔離的 venv：
```bash
# 建立虛擬環境
cd /Users/accusys/momentry_core_0.1
python3.11 -m venv venv
# 啟用
source venv/bin/activate
# 安裝依賴
pip install faster-whisper opencv-python python-dotenv
```
#### 6.2.3 Rust 呼叫 Python
```rust
let venv_python = Path::new(env!("CARGO_MANIFEST_DIR"))
.join("venv")
.join("bin")
.join("python");
let output = Command::new(venv_python)
.arg(script_path)
.arg(video_path)
.output()
.context("Failed to run Python script")?;
```
### 6.3 Node.js 版本管理
#### 6.3.1 版本鎖定
參考 `docs/NODEJS.md`：
| 版本 | 用途 | 路徑 |
|------|------|------|
| 22.22.1 | n8n | `/opt/homebrew/opt/node@22/bin/node` |
#### 6.3.2 n8n 服務配置
使用 launchd plist 隔離：
```xml
<!-- com.momentry.n8n.main.plist -->
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/opt/node@22/bin/node</string>
<string>/opt/homebrew/lib/node_modules/n8n/bin/n8n</string>
<string>start</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/opt/homebrew/opt/node@22/bin:/opt/homebrew/bin:...</string>
</dict>
```
### 6.4 Python + Node.js 共存原則
#### 6.4.1 隔離原則
| 原則 | 說明 |
|------|------|
| **獨立路徑** | Python 用 venv 路徑，Node.js 用 node@22 路徑 |
| **獨立環境** | n8n 服務使用 launchd plist，不與 Rust 共享環境 |
| **明確版本** | 所有腳本明確指定直譯器路徑 |
| **PORT 分配** | n8n: 5678/5679, API: 另行分配 |
#### 6.4.2 環境變數隔離
```bash
# Rust 專案 .env
DATABASE_URL=postgres://...
# n8n plist
N8N_ENCRYPTION_KEY=xxx
N8N_BASIC_AUTH_ACTIVE=true
# 勿混用，避免 Rust 讀到 n8n 環境變數
```
### 6.5 工作流程整合
#### 6.5.1 Rust → Python
```
Rust CLI ──▶ Python Script ──▶ JSON Output ──▶ Rust Parse
│ │
└── venv/bin/python └── faster-whisper
```
#### 6.5.2 Rust → n8n Webhook
```rust
// 觸發 n8n workflow
use reqwest;
pub async fn trigger_n8n_webhook(webhook_url: &str, payload: &str) -> Result<()> {
let client = reqwest::Client::new();
client.post(webhook_url)
.json(payload)
.send()
.await
.context("Failed to trigger n8n webhook")?;
Ok(())
}
```
#### 6.5.3 n8n → Rust API
```
n8n Workflow ──▶ HTTP Request Node ──▶ Rust API Server
│
┌───────┴───────┐
│ axum server │
│ /api/webhook │
└───────────────┘
```
### 6.6 監控配置
#### 6.6.1 獨立監控腳本
```bash
# monitor/service/node_monitor.sh
# 監控 n8n Node.js 版本
# monitor/service/python_monitor.sh
# 監控 Python 腳本執行狀態
```
#### 6.6.2 健康檢查
```yaml
# monitor_config.yaml
services:
- name: "n8n"
type: "http"
port: 5678
check_url: "http://localhost:5678/"
- name: "Python Scripts"
type: "process"
check: "pgrep -f asr_processor.py"
```
### 6.7 排程管理
#### 6.7.1 備份排程 (Python 腳本)
```bash
# crontab
0 3 * * * /Users/accusys/momentry/scripts/backup_all.sh
```
#### 6.7.2 n8n 工作流排程
- 由 n8n 內建排程節點管理
- 不與 crontab 衝突
### 6.8 故障排除
#### 6.8.1 常見問題
| 問題 | 原因 | 解決方案 |
|------|------|----------|
| n8n 版本警告 | 使用 Node 25.x | 確認 plist 使用 node@22 |
| Python 腳本找不到模組 | 未啟用 venv | 使用 venv/bin/python |
| 執行權限錯誤 | shebang 錯誤 | 確認 #!/opt/homebrew/bin/python3.11 |
| Port 被佔用 | 多個服務使用相同 port | 分配獨立 port |
#### 6.8.2 診斷命令
```bash
# 檢查 Python 版本
which python
/opt/homebrew/bin/python3.11 --version
# 檢查 Node.js 版本
/opt/homebrew/opt/node@22/bin/node --version
# 檢查 n8n 程序
ps aux | grep n8n
# 檢查 Python 程序
ps aux | grep python
# 檢查 Port 佔用
lsof -i :5678 # n8n
```
### 6.9 新增服務決策
```
新服務需要哪種執行環境?
│
├─ Python 腳本 ──▶ 使用專案 venv
│ (路徑: venv/bin/python)
│
├─ Node.js 工具 ──▶ 評估版本需求
│ │
│ ├─ 支援 Node 22 ──▶ 使用 node@22
│ │
│ └─ 需要其他版本 ──▶ 安裝新版本 (如 node@20)
│
└─ 現有服務依賴 ──▶ 根據現有服務配置
```
### 6.10 文件維護
當新增 Python 或 Node.js 服務時：
1. 更新本文檔的版本表格
2. 建立對應的監控腳本
3. 如需 launchd plist，建立並加入 `momentry_runtime/plist/`
4. 更新 `docs/NODEJS.md` 或 `docs/PYTHON.md`
### 5.2 進度回報
透過 stderr 回報進度，供 Rust 端解析：
```python
# Python 腳本
import sys
print(f"ASR_START", file=sys.stderr)
print(f"ASR_LANGUAGE:{detected_lang}", file=sys.stderr)
print(f"ASR_PROGRESS:{count}", file=sys.stderr)
print(f"ASR_COMPLETE:{total}", file=sys.stderr)
```
```rust
// Rust 端解析
let stderr = String::from_utf8_lossy(&output.stderr);
for line in stderr.lines() {
if line.starts_with("ASR_PROGRESS:") {
let count = line.trim_start_matches("ASR_PROGRESS:");
println!("[ASR] Processed {} segments...", count);
}
}
```
## 7. 測試策略
### 6.1 單元測試
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_chunk_creation() {
let chunk = Chunk::new(
"test-uuid".to_string(),
0,
ChunkType::Sentence,
0.0,
10.0,
serde_json::json!({"text": "Hello"}),
);
assert_eq!(chunk.uuid, "test-uuid");
assert_eq!(chunk.chunk_type, ChunkType::Sentence);
}
}
```
### 6.2 整合測試
```rust
#[cfg(test)]
mod integration {
use super::*;
#[tokio::test]
async fn test_database_connection() {
let db = PostgresDb::init().await.unwrap();
let videos = db.list_videos().await.unwrap();
assert!(videos.len() >= 0);
}
}
```
### 6.3 測試資料
- 使用測試資料庫隔離測試環境
- 避免在測試中使用真實敏感資料
- 使用 mock 物件模擬外部依賴
```rust
#[cfg(test)]
mod mocks {
pub struct MockVideoProcessor {
pub result: AsrResult,
}
impl VideoProcessor for MockVideoProcessor {
async fn process(&self, _video_path: &str) -> Result<AsrResult> {
Ok(self.result.clone())
}
}
}
```
## 8. 日誌與監控
### 7.1 日誌規範
- **使用 tracing**: 不要使用 `println!`
- **結構化日誌**: 使用訊息 + 欄位
```rust
use tracing::{info, warn, error};
fn process_video(uuid: &str) -> Result<()> {
info!(uuid = uuid, "Starting video processing");
match do_processing(uuid) {
Ok(_) => info!(uuid = uuid, "Processing completed"),
Err(e) => {
error!(uuid = uuid, error = %e, "Processing failed");
return Err(e);
}
}
}
```
### 7.2 初始化日誌
```rust
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
fn init_logging() {
tracing_subscriber::registry()
.with(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| "momentry_core=info,tokio=warn".into()),
)
.with(tracing_subscriber::fmt::layer())
.init();
}
```
## 9. 性能優化
### 8.1 避免拷貝
```rust
// ❌ 拷貝
let data = record.clone();
// ✅ 引用
fn process(data: &Data) { }
// ✅ 或使用 Arc 共用
use std::sync::Arc;
let shared = Arc::new(data);
```
### 8.2 批量操作
```rust
// ❌ 逐筆插入
for item in items {
db.insert(&item).await?;
}
// ✅ 批量插入
db.insert_batch(&items).await?;
```
### 8.3 連線池
```rust
// 使用 sqlx 連線池
let pool = SqlxPool::connect(&DATABASE_URL).await?;
let db = PostgresDb::new(pool);
```
## 10. 安全考量
### 9.1 敏感資訊
- **不要**將密碼、API Key 寫入程式碼
- 使用環境變數或設定檔
- .env 檔案加入 .gitignore
```rust
// ❌ 硬編碼密碼
let password = "secret123";
// ✅ 使用環境變數
let password = std::env::var("DATABASE_PASSWORD")
.context("DATABASE_PASSWORD must be set")?;
```
### 9.2 命令注入
```rust
// ❌ 危險: 直接使用使用者輸入
let cmd = format!("ffprobe {}", user_input);
// ✅ 安全: 使用參數化
Command::new("ffprobe")
.arg(user_input) // 自動轉義
.output();
```
## 11. 文件編寫
### 10.1 結構體/函式文件
```rust
/// 代表一個影片記錄
///
/// # Fields
/// * `id` - 資料庫 ID
/// * `uuid` - 唯一識別碼
/// * `duration` - 影片時長 (秒)
///
/// # Example
/// ```
/// let video = VideoRecord {
/// id: 1,
/// uuid: "abc123".to_string(),
/// duration: 120.5,
/// };
/// ```
pub struct VideoRecord {
pub id: i64,
pub uuid: String,
pub duration: f64,
}
```
### 10.2 API 文件
```rust
/// 取得影片記錄
///
/// # Arguments
/// * `uuid` - 影片的 UUID
///
/// # Returns
/// * `Ok(Some(VideoRecord))` - 找到影片
/// * `Ok(None)` - 影片不存在
/// * `Err` - 資料庫錯誤
///
/// # Errors
/// 如果資料庫連線失敗，返回資料庫錯誤
pub async fn get_video(&self, uuid: &str) -> Result<Option<VideoRecord>>;
```
## 12. CLI 命令設計
### 11.1 命令結構
使用 clap derive：
```rust
use clap::{Parser, Subcommand};
#[derive(Parser)]
#[command(name = "momentry")]
#[command(about = "Digital asset management system")]
struct Cli {
#[command(subcommand)]
command: Commands,
}
#[derive(Subcommand)]
enum Commands {
/// Register a video file
Register {
/// Path to video file
path: String,
},
/// Process video
Process {
/// UUID or path
target: String,
},
/// Generate chunks
Chunk {
/// Video UUID
uuid: String,
},
}
```
### 11.2 錯誤處理
```rust
match &cli.command {
Commands::Register { path } => {
if !Path::new(path).exists() {
eprintln!("Error: File not found: {}", path);
std::process::exit(1);
}
// ...
}
}
```
## 13. 依賴管理
### 12.1 版本約束
```toml
# Cargo.toml
[dependencies]
anyhow = "1.0" # 精確版本
tokio = { version = "1", features = ["full"] } # 範圍版本
serde = "1.0" # 精確版本
```
### 12.2 避免依賴地獄
- 審查依賴數量
- 優先使用標準庫
- 選擇維護良好的套件
## 14. 建構與部署
### 13.1 建構命令
```bash
# 開發建構
cargo build
# 發布建構
cargo build --release
# 單一二進制
cargo build --bin momentry
```
### 13.2 檢查清單
```bash
# 格式化
cargo fmt -- --check
# Lint
cargo clippy --all-features -- -D warnings
# 類型檢查
cargo check --all-features
# 測試
cargo test
```
## 15. 版本控制
### 14.1 提交訊息規範
```
<type>(<scope>): <subject>
<body>
<footer>
```
類型:
- `feat`: 新功能
- `fix`: 錯誤修復
- `docs`: 文件變更
- `style`: 格式調整
- `refactor`: 重構
- `test`: 測試變更
- `chore`: 建構/工具變更
範例:
```
feat(processor): Add ASR progress reporting
- Add stderr parsing for progress updates
- Support ASR_START, ASR_PROGRESS, ASR_COMPLETE markers
Closes #123
```
### 14.2 分支策略
- `main`: 穩定版本
- `feature/*`: 新功能開發
- `fix/*`: 錯誤修復
- `refactor/*`: 重構
---
## 附錄: 快速參考
### 建構
```bash
cargo build --release
cargo run -- --help
```
### 品質檢查
```bash
cargo fmt -- --check
cargo clippy --all-features
cargo check --all-features
cargo test
```
### 依賴
```bash
cargo add <package>
cargo tree
cargo outdated
```

1074
docs_v1.0/OPERATIONS/SERVICES.md
View File

File diff suppressed because it is too large Load Diff

522
docs_v1.0/OPERATIONS/TRAINING_MAINTENANCE_RECORDS.md
View File

@@ -1,522 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "運維紀錄規範培訓材料"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "運維紀錄規範培訓材料"
ai_query_hints:
- "查詢 運維紀錄規範培訓材料 的內容"
- "運維紀錄規範培訓材料 的主要目的是什麼？"
- "如何操作或實施 運維紀錄規範培訓材料？"
---
# 運維紀錄規範培訓材料
| 項目 | 內容 |
|------|------|
| 培訓對象 | 全體運維團隊成員、技術負責人 |
| 培訓時長 | 30-45 分鐘 |
| 培訓方式 | 團隊會議、自主學習 |
| 文件版本 | V1.0 |
| 建立時間 | 2026-03-27 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-27 | 創建培訓材料 | OpenCode | deepseek-reasoner |
---
## 培訓目標
完成本培訓後，學員能夠：
1. 理解新的運維紀錄規範的重要性
2. 正確使用各類文件模板
3. 遵循事件處理標準流程
4. 管理文件生命周期
5. 有效協作處理運維事件
---
## 第一部分：規範概述
### 1.1 為什麼需要新規範？
**現有問題**：
- 文件分散，難以查找
- 格式不一，信息不全
- 缺乏標準處理流程
- 經驗難以傳承
**新規範帶來的好處**：
- 統一文件組織結構
- 標準化信息記錄
- 明確處理時限和責任
- 完整的知識管理
### 1.2 核心概念
**四大文件類型**：
1. **事件報告 (Incident Reports)** - 記錄具體問題和處理過程
2. **根本原因分析 (RCA)** - 深入分析問題根源
3. **變更紀錄 (Change Records)** - 記錄系統變更和配置更新
4. **維護計畫 (Maintenance Plans)** - 規劃定期維護活動
**文件生命周期**：
```
新創建 → [類型/_active/] → 處理完成 → [類型/_completed/] → 超過保留期限 → [類型/_archived/]
```
**AI 優化**：生命周期狀態變更可自動觸發文件移動和通知。
---
## 第二部分：目錄結構與文件組織
### 2.1 主目錄結構
```
docs/maintenance_records/
├── rca/ # 根本原因分析
│ ├── _active/ # 進行中 RCA
│ ├── _completed/ # 已完成 RCA
│ └── _archived/ # 已歸檔 RCA
├── incidents/ # 事件報告
│ ├── _active/ # 進行中事件
│ ├── _completed/ # 已完成事件
│ └── _archived/ # 已歸檔事件
├── changes/ # 變更紀錄
│ ├── _active/ # 進行中變更
│ ├── _completed/ # 已完成變更
│ └── _archived/ # 已歸檔變更
├── plans/ # 維護計畫
│ ├── _active/ # 進行中計畫
│ ├── _completed/ # 已完成計畫
│ └── _archived/ # 已歸檔計畫
├── templates/ # 文件模板
└── reviews/ # 審核報告
```
**AI 優化設計**: 此目錄結構支持 AI Agent 高效查詢和自動化文件移動。
### 2.2 文件命名規範
**命名格式**：
```
{前綴}_{服務}_{問題簡述}_{日期}.md
```
**前綴對照表**：
| 前綴 | 用途 | 範例 |
|------|------|------|
| `RCA_` | 根本原因分析 | `RCA_WORDPRESS_TIMEOUT_2026_03_27.md` |
| `INCIDENT_` | 事件報告 | `INCIDENT_DATABASE_CONNECTION_2026_03_26.md` |
| `CHANGE_` | 變更紀錄 | `CHANGE_API_ENDPOINT_2026_03_25.md` |
| `MAINTENANCE_` | 維護計畫 | `MAINTENANCE_MONTHLY_2026_04.md` |
### 2.3 實戰練習：命名測試
將以下描述轉換為正確文件名：
1. 2026年3月28日發現的 PostgreSQL 連接超時事件
2. 2026年4月計劃的每月維護
3. 2026年3月29日進行的 n8n API 端點變更
**答案**：
1. `INCIDENT_POSTGRESQL_CONNECTION_TIMEOUT_2026_03_28.md`
2. `MAINTENANCE_MONTHLY_2026_04.md`
3. `CHANGE_N8N_API_ENDPOINT_2026_03_29.md`
---
## 第三部分：模板使用指南
### 3.1 可用模板
| 模板 | 用途 | 位置 |
|------|------|------|
| `TEMPLATE_INCIDENT.md` | 事件報告 | `templates/TEMPLATE_INCIDENT.md` |
| `TEMPLATE_RCA.md` | 根本原因分析 | `templates/TEMPLATE_RCA.md` |
| `TEMPLATE_CHANGE.md` | 變更紀錄 | `templates/TEMPLATE_CHANGE.md` |
| `TEMPLATE_MAINTENANCE.md` | 維護計畫 | `templates/TEMPLATE_MAINTENANCE.md` |
### 3.2 創建新文件的標準流程
**步驟 1：選擇模板**
```bash
# 事件報告示例
cp docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_INCIDENT.md \
docs/maintenance_records/incidents/_active/INCIDENT_<服務>_<問題>_$(date +%Y_%m_%d).md
```
**步驟 2：填寫基本信息**
- 報告者、報告時間
- 嚴重等級 (P0-P4)
- 當前狀態 (⏳🔍🔧✅📁)
- 受影響服務
- 負責人
**步驟 3：詳細描述**
- 問題現象
- 影響範圍
- 重現步驟
- 相關日誌
**步驟 4：定期更新**
- 按事件等級要求更新頻率
- 記錄所有處理步驟
- 更新狀態標記
### 3.3 模板填寫示範
**事件報告頂部信息表示例**：
```markdown
| 項目 | 內容 |
|------|------|
| 報告者 | 張三 |
| 報告時間 | 2026-03-27 14:30 |
| 嚴重等級 | P2 |
| 當前狀態 | 🔍 調查中 |
| 受影響服務 | PostgreSQL, API 服務 |
| 負責人 | 李四 |
```
**嚴重等級選擇指南**：
- **P0**：網站完全無法訪問，立即處理！
- **P1**：主要功能不可用，2小時內處理
- **P2**：次要功能問題，4小時內處理
- **P3**：輕微問題，工作日內處理
- **P4**：諮詢建議，3工作日內回應
---
## 第四部分：事件處理流程
### 4.1 完整流程圖
```
事件檢測 → 報告創建 → 等級評估 → 調查處理 → 解決驗證 → 文件歸檔
↓ ↓ ↓ ↓ ↓ ↓
監控警報 使用模板 P0-P4評估 狀態更新 RCA創建 生命周期管理
用戶報告 填寫信息 設定時限 定期溝通 經驗總結 定期清理
```
### 4.2 各等級處理要求
| 等級 | 開始處理時限 | 解決時限 | 狀態更新頻率 | 文件要求 |
|------|--------------|----------|--------------|----------|
| P0 | 立即 (5分鐘內) | 1小時 | 每15分鐘 | 必須 RCA |
| P1 | 2小時內 | 4小時 | 每30分鐘 | 建議 RCA |
| P2 | 4小時內 | 8小時 | 每2小時 | 可選 RCA |
| P3 | 1工作日內 | 2工作日 | 每日 | 事件報告 |
| P4 | 3工作日內 | 5工作日 | 每週 | 簡單紀錄 |
### 4.3 角色與責任
**事件報告者**：
- 發現問題立即報告
- 創建初步事件報告
- 提供盡可能詳細的信息
**值班工程師**：
- 接收事件報告
- 初步評估等級
- 分配負責人
**處理工程師**：
- 調查問題原因
- 實施解決方案
- 定期更新狀態
**技術負責人**：
- 確認事件等級
- 協調處理資源
- 審核解決方案
### 4.4 溝通與通知
**狀態更新模板**：
```markdown
事件：資料庫連接超時
狀態：🔧 處理中
進度：已確認是連接池配置問題，正在調整參數
預計解決時間：15:30
影響：API 響應緩慢，不影響核心功能
負責人：王五
```
**通知要求**：
- P0：立即通知所有相關人員（即時通訊+電話）
- P1：1小時內通知技術團隊+管理層
- P2：2小時內通知技術團隊
- P3：工作日內通知相關工程師
- P4：無需緊急通知
---
## 第五部分：文件生命周期管理
### 5.1 狀態流轉
```
新創建 → ⏳ 待處理 → 🔍 調查中 → 🔧 處理中 → ✅ 已解決 → 📁 已關閉 → 🗄️ 已歸檔
(新報告) (開始調查) (實施解決) (問題解決) (驗證完成) (超過保留期)
```
### 5.2 目錄移動規則
| 狀態 | 所在目錄 | 處理要求 |
|------|----------|----------|
| ⏳🔍🔧 | `_active/` | 定期更新進度 |
| ✅ | `_completed/` | 最終驗證和簽核 |
| 📁🗄️ | `_archived/` | 只讀，供歷史參考 |
**操作命令**：
```bash
# 完成處理後移動文件
mv docs/maintenance_records/incidents/_active/INCIDENT_*.md \
docs/maintenance_records/incidents/_completed/
```
### 5.3 保留政策
| 文件類型 | 活躍期 | 完成保留期 | 總保留期 |
|----------|--------|------------|----------|
| RCA 文件 | P0: 7天<br>P1: 14天<br>P2-4: 30天 | 30天 | 2年 |
| 事件報告 | P0: 3天<br>P1: 7天<br>P2-4: 14天 | 30天 | 1年 |
| 變更紀錄 | 實施期間 | 90天 | 3年 |
| 維護計畫 | 計畫期間 | 30天 | 1年 |
---
## 第六部分：實戰演練
### 6.1 演練場景：網站響應緩慢
**場景描述**：
- 時間：2026-03-27 10:00
- 問題：網站首頁響應時間超過5秒
- 影響：所有用戶訪問體驗下降
- 發現方式：監控警報
**演練任務**：
1. 創建事件報告文件
2. 評估嚴重等級
3. 填寫基本信息
4. 模擬狀態更新
5. 完成事件關閉
**參考步驟**：
```bash
# 1. 創建文件
cp templates/TEMPLATE_INCIDENT.md \
incidents/_active/INCIDENT_WEB_SLOW_RESPONSE_2026_03_27.md
# 2. 填寫信息
# - 報告者：你的名字
# - 嚴重等級：P2（影響體驗但不影響功能）
# - 狀態：🔍 調查中
# - 受影響服務：Web服務器、資料庫
# 3. 調查更新
# - 檢查服務器資源使用率
# - 分析資料庫查詢性能
# - 更新狀態為 🔧 處理中
# 4. 解決問題
# - 優化慢查詢
# - 增加緩存
# - 更新狀態為 ✅ 已解決
# 5. 移動文件
mv incidents/_active/INCIDENT_WEB_* incidents/_completed/
```
### 6.2 演練場景：資料庫備份失敗
**場景描述**：
- 時間：2026-03-28 02:00
- 問題：夜間自動備份失敗
- 影響：無立即影響，但有數據風險
- 發現方式：監控警報
**演練任務**：
1. 決定是否需要創建 RCA
2. 如需 RCA，創建文件並分析根本原因
3. 制定預防措施
---
## 第七部分：常見問題解答
### Q1：什麼情況下需要創建 RCA？
- 所有 P0 事件必須創建 RCA
- P1 事件建議創建 RCA
- 重複發生的問題（無論等級）
- 有學習價值的任何事件
### Q2：如果我不確定事件等級怎麼辦？
- 先按較高等級處理（寧嚴勿鬆）
- 與值班工程師或技術負責人確認
- 記錄不確定的原因
- 後續可調整等級
### Q3：模板中的某些欄位我不知道怎麼填？
- 盡可能填寫已知信息
- 標記為「待確認」或「調查中」
- 後續調查後補充
- 重要欄位：報告者、時間、問題描述
### Q4：文件應該存放在哪個目錄？
- 新創建：`_active/`
- 處理中：`_active/`（更新狀態）
- 已完成：`_completed/`
- 超過保留期：`_archived/`
### Q5：如何查找歷史事件記錄？
```bash
# 查找特定服務的事件
find docs/maintenance_records -name "*POSTGRESQL*" -type f
# 查找某日期後的事件
find docs/maintenance_records -name "*2026_03_*" -type f
# 查找進行中事件
find docs/maintenance_records/_active -name "*.md" -type f
```
### Q6：如果多個事件相關聯怎麼辦？
- 在各文件中互相引用
- 使用「相關文件」章節
- 考慮創建綜合性 RCA
- 保持鏈接可追踪
---
## 第八部分：資源與支援
### 8.1 重要文件
| 文件 | 用途 | 位置 |
|------|------|------|
| `DOCS_STANDARD.md` | 文件創建規範 | `../DOCS_STANDARD.md` |
| `maintenance_records/README.md` | 目錄說明 | `./README.md` |
| `INCIDENT_RESPONSE_PROCEDURE.md` | 事件處理流程 | `../INCIDENT_RESPONSE_PROCEDURE.md` |
| `MIGRATION_PLAN.md` | 遷移計畫 | `./MIGRATION_PLAN.md` |
### 8.2 工具與腳本
```bash
# 快速創建事件報告
./scripts/create_incident.sh <服務> <問題>
# 檢查進行中事件
./scripts/check_active_incidents.sh
# 歸檔過期文件
./scripts/archive_old_files.sh
```
### 8.3 聯繫與支援
- **技術問題**：聯繫技術負責人
- **流程問題**：參考事件處理流程文件
- **文件問題**：更新文件規範提案
- **緊急支援**：團隊溝通工具頻道
### 8.4 培訓評估
**知識檢查**：
1. P1 事件的處理時限是多少？
2. 事件報告的標準文件名格式是什麼？
3. 什麼情況下需要將文件移動到 `_archived/`？
4. RCA 文件的總保留期是多久？
**實操考核**：
- 成功創建一個事件報告文件
- 正確評估事件等級
- 完成一次完整的狀態更新流程
- 將文件移動到正確的目錄
---
## 第九部分：下一步行動
### 9.1 立即行動
1. 瀏覽目錄結構熟悉文件位置
2. 閱讀相關規範文件
3. 嘗試創建一個測試事件報告
### 9.2 短期目標（1週內）
1. 在實際事件中使用新規範
2. 提供反饋建議
3. 參加團隊復盤會議
### 9.3 長期目標（1個月內）
1. 熟練掌握所有模板使用
2. 參與 RCA 分析工作
3. 協助培訓新成員
---
## 第十部分：反饋與改進
### 10.1 提供反饋
- 使用規範遇到的問題
- 模板需要改進的地方
- 流程不順暢的環節
- 新增功能建議
### 10.2 改進流程
1. 記錄問題或建議
2. 創建 `CHANGE_MAINTENANCE_PROCESS_*.md`
3. 提交審核
4. 實施改進
### 10.3 定期復盤
- 每週檢查事件處理效果
- 每月審查文件質量
- 每季度更新培訓材料
### 10.4 相關資源
- `AI_AGENT_DOCUMENTATION_GUIDE.md` - AI Agent 使用指南
- `INCIDENT_RESPONSE_PROCEDURE.md` - 事件處理標準程序
- `maintenance_records/README.md` - 維護紀錄目錄說明
- `DOCS_STANDARD_IMPROVEMENT_PROPOSAL_*.md` - 規範改善提案
### 10.5 AI 優化功能
- **YAML Frontmatter**: 所有模板包含結構化元數據，便於 AI Agent 解析
- **自動化工作流**: 支持狀態變更觸發文件移動和通知
- **標準化查詢**: 統一的查詢語法，便於搜索和分析
- **工具整合**: 可與監控系統、n8n 工作流集成
---
## 培訓完成確認
| 項目 | 內容 |
|------|------|
| 培訓日期 | (填寫實際培訓日期) |
| 培訓講師 | (填寫講師姓名) |
| 參與人員 | (列出參與人員) |
### 學員簽到
| 姓名 | 部門 | 簽字 | 日期 | 備註 |
|------|------|------|------|------|
| | | | | |
| | | | | |
| | | | | |
### 培訓效果評估
**請在培訓後填寫**：
1. 培訓內容清晰度：□ 很好 □ 好 □ 一般 □ 差
2. 實用性評估：□ 很實用 □ 實用 □ 一般 □ 不實用
3. 需要改進的地方：_________________________
4. 其他建議：_______________________________
> **注意**：本培訓材料會根據團隊反饋和規範更新定期修訂。

481
docs_v1.0/OPERATIONS/USER_MANUAL.md
View File

@@ -1,481 +0,0 @@
# Momentry 使用手冊
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-21 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-21 | 創建使用手冊 | Warren | OpenCode |
---
**目標讀者**: 系統管理員、開發者
---
## 目錄
1. [快速開始](#1-快速開始)
2. [安裝與設定](#2-安裝與設定)
3. [CLI 命令參考](#3-cli-命令參考)
4. [影片管理](#4-影片管理)
5. [API Key 管理](#5-api-key-管理)
6. [第三方整合](#6-第三方整合)
7. [監控與維護](#7-監控與維護)
8. [疑難排解](#8-疑難排解)
---
## 1. 快速開始
### 1.1 最小啟動流程
```bash
# 1. 啟動服務
sudo launchctl load /Library/LaunchDaemons/com.momentry.postgresql.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.redis.plist
# 2. 設定環境變數
source .env
# 3. 啟動 API 伺服器
momentry server --host 127.0.0.1 --port 3000
# 4. 建立 API Key
momentry api-key create my-first-key --key-type user --ttl 90
```
### 1.2 驗證安裝
```bash
# 檢查系統狀態
curl http://localhost:3002/health
# 檢查版本
momentry --help
```
---
## 2. 安裝與設定
### 2.1 環境需求
| 項目 | 需求 |
|------|------|
| 作業系統 | macOS (Apple Silicon) |
| Rust | 1.70+ |
| PostgreSQL | 15+ |
| Redis | 7+ |
| Python | 3.11+ (用於 AI 處理) |
### 2.2 安裝步驟
```bash
# 1. 複製專案
git clone <repository-url>
cd momentry_core_0.1
# 2. 編譯
cargo build --release
# 3. 安裝到系統
cp target/release/momentry /usr/local/bin/
```
### 2.3 環境變數設定
建立 `.env` 檔案：
```bash
# Database
DATABASE_URL=postgres://accusys@localhost:5432/momentry
# Redis
REDIS_URL=redis://:accusys@localhost:6379
# Gitea (選用)
GITEA_URL=http://localhost:3000
# n8n (選用)
N8N_URL=https://n8n.momentry.ddns.net
# API Server
API_HOST=127.0.0.1
API_PORT=3000
# 監控目錄
WATCH_DIRECTORIES=~/Videos
```
---
## 3. CLI 命令參考
### 3.1 一般命令
| 命令 | 說明 |
|------|------|
| `momentry --help` | 顯示幫助 |
| `momentry server` | 啟動 API 伺服器 |
| `momentry register <path>` | 註冊影片 |
| `momentry process <uuid>` | 處理影片 |
| `momentry query <text>` | RAG 查詢 |
### 3.2 影片管理
```bash
# 註冊影片
momentry register /path/to/video.mp4
# 處理影片
momentry process <uuid>
# 生成縮圖
momentry thumbnails <uuid> --count 6
# 查看狀態
momentry status <uuid>
```
### 3.3 API Key 管理
```bash
# 建立 Key
momentry api-key create <name> --key-type <type> --ttl <days>
# 列出 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
```
### 3.4 Gitea 整合
```bash
# 建立 Token
momentry gitea create \
--username <user> \
--password <pwd> \
--token-name <name> \
--scopes "read:repository,write:repository"
# 列出 Tokens
momentry gitea list --username <user> --password <pwd>
# 刪除 Token
momentry gitea delete \
--username <user> \
--password <pwd> \
--token-name <name>
```
### 3.5 n8n 整合
```bash
# 建立 API Key
momentry n8n create \
--api-key <existing-key> \
--label <name> \
--expires-in-days 90
# 列出 Keys
momentry n8n list --api-key <key>
# 刪除 Key
momentry n8n delete --api-key <key> --label <name>
```
### 3.6 備份管理
```bash
# 列出備份
momentry backup list
# 清理舊備份
momentry backup cleanup --days 30
```
---
## 4. 影片管理
### 4.1 影片生命週期
```
上傳 → 註冊 → 處理 → 儲存 → 查詢
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
檔案 資料庫 AI分析 向量庫 RAG
```
### 4.2 註冊影片
```bash
# 自動偵測格式
momentry register ~/Videos/my-video.mp4
# 輸出:
# UUID: a1b2c3d4e5f6g7h8
# Duration: 120.5s
# Resolution: 1920x1080
```
### 4.3 處理流程
處理包含以下階段：
| 階段 | 說明 | 時間 (約) |
|------|------|-----------|
| Probe | 影片資訊分析 | 5s |
| ASR | 語音辨識 | 視長度 |
| OCR | 文字辨識 | 視長度 |
| YOLO | 物件偵測 | 視長度 |
| Cut | 場景切割 | 30s |
| Chunk | 內容分段 | 10s |
| Vector | 向量化 | 20s |
### 4.4 查詢影片
```bash
# RAG 查詢
momentry query "影片中有什麼內容？"
# 取得特定影片
momentry resolve <uuid>
```
---
## 5. API Key 管理
### 5.1 Key 類型
| 類型 | 前綴 | 用途 | 預設 TTL |
|------|------|------|----------|
| System | `msys_` | 系統內部 | 365 天 |
| User | `muser_` | 個人用戶 | 90 天 |
| Service | `msvc_` | 服務間通訊 | 180 天 |
| Integration | `mint_` | 第三方整合 | 30 天 |
| Emergency | `memg_` | 緊急存取 | 1 天 |
### 5.2 建立 Key
```bash
# 一般 Key
momentry api-key create my-service --key-type service --ttl 90
# 緊急 Key (24小時有效)
momentry api-key create emergency-access --key-type emergency
# 輸出:
# ✅ API Key created successfully!
# Key ID: msvc_xxxxxxxx
# API Key: msvc_xxxxxxxx_xxxxx_xxxxx
# Expires: 2026-06-19
```
### 5.3 Key 生命週期
```
建立 → 使用 → 過期/撤銷 → 清理
│ │ │ │
▼ ▼ ▼ ▼
資料庫 驗證 停用 定期刪除
```
### 5.4 安全建議
| 建議 | 說明 |
|------|------|
| 定期輪換 | 每 90 天更新 Key |
| 最小權限 | 只授予必要權限 |
| 監控使用 | 定期檢查使用統計 |
| 及時撤銷 | 異常時立即撤銷 |
---
## 6. 第三方整合
### 6.1 Gitea
```bash
# 建立 CI/CD 用 Token
momentry gitea create \
--username admin \
--password "your-password" \
--token-name "ci-pipeline" \
--scopes "read:repository,write:repository"
# 在 CI 中使用
export GITEA_TOKEN="token-sha1-value"
curl -H "Authorization: token $GITEA_TOKEN" \
http://localhost:3000/api/v1/user
```
### 6.2 n8n
```bash
# 建立工作流用 Key
momentry n8n create \
--api-key "existing-n8n-key" \
--label "workflow-key" \
--expires-in-days 90
# 在 n8n 中使用
# HTTP Request Header: X-N8N-API-Key: <key>
```
### 6.3 Webhook 通知
```bash
# 設定 Webhook
export WEBHOOK_URL="https://n8n.example.com/webhook/alerts"
export WEBHOOK_EVENTS="anomaly_detected,key_expired"
```
---
## 7. 監控與維護
### 7.1 系統監控
```bash
# 檢查服務狀態
ps aux | grep momentry
ps aux | grep postgres
redis-cli -a accusys ping
# 檢查日誌
tail -f /Users/accusys/momentry/log/momentry.log
tail -f /Users/accusys/momentry/log/redis.log
```
### 7.2 資料庫維護
```bash
# 檢查資料庫大小
psql -U accusys -d momentry -c "SELECT pg_size_pretty(pg_database_size('momentry'));"
# 清理過期記錄
momentry api-key stats # 檢查統計
# 定期清理由系統自動執行
```
### 7.3 備份
```bash
# 手動備份 PostgreSQL
pg_dump -U accusys momentry > backup_$(date +%Y%m%d).sql
# 恢復備份
psql -U accusys momentry < backup_20260321.sql
```
---
## 8. 疑難排解
### 8.1 常見問題
#### Q: 無法連接資料庫
```bash
# 檢查 PostgreSQL 狀態
pg_isready -h localhost -p 5432
# 檢查連線
psql -U accusys -d momentry -c "SELECT 1;"
```
#### Q: Redis 連線失敗
```bash
# 檢查 Redis 狀態
redis-cli -a accusys ping
# 檢查認證
redis-cli -a accusys INFO server | grep redis_version
```
#### Q: API Key 驗證失敗
```bash
# 檢查 Key 狀態
momentry api-key validate --key "your-key"
# 檢查是否過期
momentry api-key list
```
### 8.2 錯誤碼對照
| 錯誤碼 | 說明 | 解決方式 |
|--------|------|----------|
| `E001` | 資料庫連線失敗 | 檢查 PostgreSQL |
| `E002` | Redis 連線失敗 | 檢查 Redis |
| `E003` | API Key 無效 | 重新建立 Key |
| `E004` | 影片不存在 | 檢查 UUID |
| `E005` | 處理失敗 | 檢查日誌 |
### 8.3 日誌位置
| 日誌 | 路徑 |
|------|------|
| Momentry | `/Users/accusys/momentry/log/momentry.log` |
| PostgreSQL | `/Users/accusys/momentry/log/postgresql.log` |
| Redis | `/Users/accusys/momentry/log/redis.log` |
| Gitea | `/Users/accusys/momentry/log/gitea.log` |
---
## 附錄
### A. 完整命令列表
```bash
momentry --help
momentry register --help
momentry process --help
momentry api-key --help
momentry gitea --help
momentry n8n --help
momentry backup --help
```
### B. 環境變數總覽
| 變數 | 預設值 | 說明 |
|------|--------|------|
| `DATABASE_URL` | `postgres://accusys@localhost:5432/momentry` | PostgreSQL |
| `REDIS_URL` | `redis://:accusys@localhost:6379` | Redis |
| `GITEA_URL` | `http://localhost:3000` | Gitea |
| `N8N_URL` | `https://n8n.momentry.ddns.net` | n8n |
| `API_HOST` | `127.0.0.1` | API 主機 |
| `API_PORT` | `3000` | API 埠號 |
### C. 相關文件
| 文件 | 說明 |
|------|------|
| `docs/API_CURL_EXAMPLES.md` | API curl 範例 |
| `docs/N8N_INTEGRATION_GUIDE.md` | n8n 整合指南 |
| `docs/API_KEY_MANAGEMENT.md` | API Key 設計 |
| `CHANGELOG.md` | 版本記錄 |

261
docs_v1.0/OPERATIONS/VERSION_MANAGEMENT.md
View File

@@ -1,261 +0,0 @@
# Momentry Core 版本管理規範
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-23 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-23 | 創建版本管理規範 | Warren | OpenCode |
---
## 1. 版本與通訊埠對照表
| 版本 | Binary | Port | Redis Prefix | 用途 |
|------|--------|------|--------------|------|
| **Production** | `momentry` | **3002** | `momentry:` | 正式環境 |
| **Development** | `momentry_playground` | **3003** | `momentry_dev:` | 開發測試 |
### 通訊埠嚴禁事項
- ❌ 開發版嚴禁使用 3002
- ❌ 任何 `cargo run` 直接啟動的 server 嚴禁綁定 3002
- ❌ Debug build 嚴禁部署到 3002
---
## 2. 開發環境隔離原則
### 2.1 開發流程
```bash
# 永遠在 3003 開發測試
cd /Users/accusys/momentry_core_0.1
# 開發版啟動 (3003)
cargo run --bin momentry_playground -- server
# 或
cargo run --bin momentry -- server --port 3003
```
### 2.2 測試完成後
1. 確認所有功能在 3003 正常運作
2. 進行 `cargo clippy --lib` 檢查
3. 進行 `cargo test --lib` 測試
4. 確認後才能進行 release
### 2.3 環境變數隔離
```bash
# Development
export MOMENTRY_SERVER_PORT=3003
export MOMENTRY_REDIS_PREFIX=momentry_dev:
# Production (launchd 管理，勿手動設定)
# MOMENTRY_SERVER_PORT=3002
# MOMENTRY_REDIS_PREFIX=momentry:
```
---
## 3. Release 版本管理
### 3.1 Release 前檢查清單
```
□ 開發版 (3003) 功能測試完成
□ cargo clippy --lib 通過
□ cargo test --lib 通過
□ cargo fmt -- --check 通過
□ 所有修改已 commit 到 Gitea
```
### 3.2 Release 流程
```bash
# 1. 確保目前是乾淨的工作目錄
git status
# 2. 備份當前 production binary
BACKUP_DIR="/Users/accusys/momentry/backup/bin"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
cp /Users/accusys/momentry/bin/momentry "${BACKUP_DIR}/momentry_${TIMESTAMP}"
# 3. 停止 production server
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
# 或
pkill -f "target/release/momentry server"
# 4. 編譯 release 版本
cargo build --release --bin momentry
# 5. 部署到正式位置
cp target/release/momentry /Users/accusys/momentry/bin/momentry
# 6. 啟動 production server
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
# 7. 驗證
curl http://localhost:3002/health
```
### 3.3 Backup 存放位置
```
/Users/accusys/momentry/backup/bin/
├── momentry_20260325_143000 (backup)
├── momentry_20260324_100000
├── momentry_20260323_090000
└── ...
```
---
## 4. Gitea 版本控制
### 4.1 Commit 規範
```
feat: 新功能
fix: 錯誤修復
refactor: 重構
docs: 文件更新
chore: 杂项
test: 测试
```
### 4.2 Release Tag 規範
```bash
# 建立 release tag
git tag -a v0.1.1 -m "Release v0.1.1 - API Key Authentication"
git push origin v0.1.1
```
### 4.3 版本號命名
```
v{major}.{minor}.{patch}
│ │ └── Patch version (bug fix)
│ └───────── Minor version (新功能)
└──────────────── Major version (破壞性變更)
```
### 4.4 Gitea Release 建立
1. 在 Gitea Repo > Releases > New Release
2. 選擇對應的 Tag
3. 填寫 Release Notes
4. 上傳 compiled binary（如需要）
---
## 5. 服務管理
### 5.1 Production Service (launchd)
```bash
# Plist 位置
/Library/LaunchDaemons/com.momentry.api.plist
# 管理指令
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist # 啟動
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist # 停止
sudo launchctl list | grep momentry # 狀態
```
### 5.2 緊急回滾
```bash
# 1. 停止當前服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
# 2. 恢復上一個 backup
BACKUP_FILE=$(ls -t /Users/accusys/momentry/backup/bin/ | head -1)
cp "/Users/accusys/momentry/backup/bin/${BACKUP_FILE}" /Users/accusys/momentry/bin/momentry
# 3. 重啟服務
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
# 4. 驗證
curl http://localhost:3002/health
```
---
## 6. 快速參考卡片
### Development
```bash
# 啟動開發版
cd /Users/accusys/momentry_core_0.1
cargo run --bin momentry_playground -- server
# 或手動指定 port
cargo run --bin momentry -- server --port 3003
# 測試端點
curl -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
http://localhost:3003/api/v1/jobs
```
### Production
```bash
# 查看狀態
sudo launchctl list | grep momentry
# 重啟服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
# 查看日誌
tail -f /Users/accusys/momentry/log/momentry_release.log
```
### 常用指令
```bash
# 檢查 port 使用
lsof -i :3002 # Production
lsof -i :3003 # Development
# 檢查 process
ps aux | grep momentry | grep server
# 停止所有 momentry server
pkill -9 -f "momentry.*server"
```
---
## 7. 禁止事項
| 項目 | 說明 |
|------|------|
| ❌ 禁止在 3002 測試 | 3002 是 Production，嚴禁用於測試 |
| ❌ 禁止覆蓋 production binary | 使用 backup + deploy 流程 |
| ❌ 禁止跳過測試直接 release | 必須完成檢查清單 |
| ❌ 禁止在未備份的情況下部署 | 每次部署前必須備份 |
---
## 8. 疑難排解
### Q: 3002 無法綁定怎麼辦？
```bash
# 檢查誰在使用
lsof -i :3002
# 停止舊的 server
pkill -9 -f "momentry.*server"
```
### Q: 如何確認使用的是哪個版本？
```bash
# 檢查 binary 位置和版本
file $(which momentry)
./target/release/momentry --version 2>/dev/null || echo "No version flag"
```
### Q: 如何確認有沒有 API Key 驗證？
```bash
# 沒有 API Key 應該返回 401
curl -s http://localhost:3002/api/v1/jobs
# HTTP/1.1 401 Unauthorized
```

248
docs_v1.0/OPERATIONS/VIDEO_REGISTRATION.md.bak
View File

@@ -1,248 +0,0 @@
# Video Registration
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-25 |
| 文件版本 | V1.1 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-25 | 創建文件 | Warren | OpenCode |
| V1.1 | 2026-03-26 | 修正 curl 範例，新增 API Key 驗證標頭 | OpenCode | deepseek-reasoner |
---
## 概述
影片註冊 API (`POST /api/v1/register`) 用於將影片加入 Momentry Core 系統進行處理。
## 路徑格式
### 支援的路徑格式
| 格式 | 範例 | 說明 |
|------|------|------|
| 相對路徑 | `./demo/video.mp4` | 推薦格式 |
| 相對路徑（無 ./） | `demo/video.mp4` | 自動加上 `./` |
| 絕對路徑 | `/Users/.../sftpgo/data/demo/video.mp4` | 支援但不推薦 |
### 路徑結構
```
./username/filepath
│ │ │
│ │ └── 檔案路徑（可以是多層目錄）
│ └── 使用者名稱（SFTPgo 用戶目錄名稱）
└── 相對路徑前綴
```
**範例**：
- `./demo/video.mp4` → username=`demo`, filepath=`video.mp4`
- `./demo/movies/2024/video.mp4` → username=`demo`, filepath=`movies/2024/video.mp4`
- `./warren/project1/interview.mp4` → username=`warren`, filepath=`project1/interview.mp4`
## UUID 計算
### 計算規則
```
UUID = SHA256(username/filepath)[0:16]
```
**範例**：
```rust
// 路徑: ./demo/video.mp4
// username: "demo"
// filepath: "video.mp4"
// key: "demo/video.mp4"
// UUID: SHA256("demo/video.mp4")[0:16]
```
### 特性
| 特性 | 說明 |
|------|------|
| 用戶隔離 | 不同用戶的相同檔名會產生不同 UUID |
| 一致性 | 相同相對路徑一定產生相同 UUID |
| 遷移安全 | SFTPgo 資料路徑變更後 UUID 保持一致 |
### 範例
```rust
// 用戶 demo 的影片
compute_uuid_from_relative_path("./demo/video.mp4")
// → "9760d0820f0cf9a7"
// 用戶 warren 的相同檔名影片
compute_uuid_from_relative_path("./warren/video.mp4")
// → "a1b2c3d4e5f6g7h8" (不同的 UUID)
```
## 重複註冊檢查
### 行為
1. 系統檢查 UUID 是否已存在於資料庫
2. 如果存在，返回 `already_exists: true` 和現有影片資訊
3. 如果不存在，創建新的影片記錄
### API 回應
**新註冊**：
```json
{
"uuid": "9760d0820f0cf9a7",
"video_id": 18,
"job_id": 2,
"file_name": "video.mp4",
"duration": 159.637188,
"width": 640,
"height": 360,
"already_exists": false
}
```
**重複註冊**：
```json
{
"uuid": "9760d0820f0cf9a7",
"video_id": 18,
"job_id": 2,
"file_name": "video.mp4",
"duration": 159.637188,
"width": 640,
"height": 360,
"already_exists": true
}
```
## SFTPgo 整合
### 目錄結構
SFTPgo 的用戶目錄結構：
```
/Users/accusys/momentry/var/sftpgo/data/
├── demo/ ← 用戶目錄
│ ├── video.mp4
│ └── movies/
│ └── movie1.mp4
├── warren/ ← 用戶目錄
│ └── project1/
│ └── interview.mp4
└── momentry/ ← 用戶目錄
└── presentation.mp4
```
### 註冊流程
1. SFTPgo 用戶上傳檔案到各自的目錄
2. n8n 或其他服務調用註冊 API
3. 使用相對路徑格式：`./username/filepath`
4. 系統計算 UUID 並檢查重複
5. 創建處理任務
## 程式碼範例
### 註冊影片
```bash
# 使用相對路徑註冊
curl -X POST http://localhost:3002/api/v1/register \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"path": "./demo/video.mp4"}'
# 或使用多層目錄
curl -X POST http://localhost:3002/api/v1/register \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"path": "./demo/movies/2024/video.mp4"}'
```
### UUID 計算函數
```rust
// 使用相對路徑計算 UUID
pub fn compute_uuid_from_relative_path(relative_path: &str) -> String {
let (username, filepath) = extract_user_from_relative_path(relative_path);
compute_uuid(&username, &filepath)
}
// 從相對路徑提取用戶名和檔案路徑
pub fn extract_user_from_relative_path(relative_path: &str) -> (String, String) {
let path = relative_path.strip_prefix("./").unwrap_or(relative_path);
let path_buf = PathBuf::from(path);
let mut components = path_buf.components();
let username = components
.next()
.map(|c| c.as_os_str().to_string_lossy().to_string())
.unwrap_or_default();
let filepath: String = components
.map(|c| c.as_os_str().to_string_lossy().to_string())
.collect::<Vec<_>>()
.join("/");
(username, filepath)
}
```
## 相關 API
### Probe API（僅探測，不註冊）
如果只需要取得影片資訊而不註冊，可以使用 Probe API：
```bash
curl -X POST http://localhost:3002/api/v1/probe \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"path": "./demo/video.mp4"}'
```
**回應範例**：
```json
{
"uuid": "a1b10138a6bbb0cd",
"file_name": "video.mp4",
"duration": 120.5,
"width": 1920,
"height": 1080,
"fps": 30.0,
"cached": false,
"format": {...},
"streams": [...]
}
```
**與 Register API 的差異**：
| 功能 | Probe API | Register API |
|------|-----------|---------------|
| 計算 UUID | ✓ | ✓ |
| 執行 ffprobe | ✓ | ✓ |
| 儲存 probe.json | ✓ | ✓ |
| 寫入 videos 表 | ✗ | ✓ |
| 建立 monitor_job | ✗ | ✓ |
| 返回 job_id | ✗ | ✓ |
| 適用場景 | 預覽影片資訊 | 註冊並處理影片 |
## 相關檔案
| 檔案 | 說明 |
|------|------|
| `src/core/storage/uuid.rs` | UUID 計算邏輯 |
| `src/api/server.rs` | 註冊與 Probe API 實現 |
| `src/core/probe/ffprobe.rs` | ffprobe 整合 |
| `docs/SFTPGO_DEMO_USER.md` | SFTPgo 用戶設置 |
| `docs/API_ENDPOINTS.md` | API 端點總覽 |

284
docs_v1.0/OPERATIONS/maintenance_records/MIGRATION_PLAN.md
View File

@@ -1,284 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "運維文件遷移計畫"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "運維文件遷移計畫"
ai_query_hints:
- "查詢 運維文件遷移計畫 的內容"
- "運維文件遷移計畫 的主要目的是什麼？"
- "如何操作或實施 運維文件遷移計畫？"
---
# 運維文件遷移計畫
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-03-27 |
| 文件版本 | V1.0 |
| 相關文件 | DOCS_STANDARD_IMPROVEMENT_PROPOSAL_*.md |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-27 | 創建遷移計畫 | OpenCode | deepseek-reasoner |
---
## 1. 概述
本文件描述將現有運維文件遷移到新目錄結構 (`docs/maintenance_records/`) 的計畫。遷移目標是統一文件組織，遵循新規範的結構和命名規則。
### 1.1 遷移目標
- 統一運維文件組織結構
- 遵循新文件命名規範
- 建立完整的文件生命周期管理
- 為未來文件創建建立標準
### 1.2 遷移範圍
僅遷移符合以下條件的文件：
1. 具體的事件報告 (Incident Reports)
2. 根本原因分析 (Root Cause Analysis)
3. 系統變更記錄 (Change Records)
4. 維護計畫 (Maintenance Plans)
規範文件、安裝指南、API 文檔等不在此次遷移範圍內。
---
## 2. 現有文件分析
### 2.1 文件清單與分類
| 文件 | 類型 | 建議處理 | 遷移目標目錄 |
|------|------|----------|--------------|
| `PENDING_ISSUES.md` | 問題追蹤清單 | 保留原位置 | (不遷移) |
| `DEVELOPMENT_LOG.md` | 開發日誌 | 保留原位置 | (不遷移) |
| `MOMENTRY_CORE_MONITORING.md` | 監控規範 | 保留原位置 | (不遷移) |
| `BACKUP_VERSIONING.md` | 備份規範 | 保留原位置 | (不遷移) |
| `BUILD_VERSION_RECORD.md` | 版本規範 | 保留原位置 | (不遷移) |
| `FILE_CHANGE_MANAGEMENT.md` | 文件變更規範 | 保留原位置 | (不遷移) |
| `N8N_MCP_TEST_REPORT.md` | 測試報告 | 可選遷移為變更記錄 | `changes/` |
| (無) | 具體事件報告 | 無現有文件 | `incidents/` |
| (無) | 具體 RCA | 無現有文件 | `rca/` |
| (無) | 具體維護計畫 | 無現有文件 | `plans/` |
### 2.2 遷移決策原則
1. **規範文件保留**：規範、指南、標準等參考文件保留在 `docs/` 根目錄
2. **具體記錄遷移**：具體的事件、變更、分析記錄遷移到新結構
3. **混合文件拆分**：包含多個獨立記錄的文件拆分為多個獨立文件
4. **歷史價值評估**：評估文件的歷史價值，決定是否遷移
---
## 3. 遷移執行計畫
### 3.1 階段 1：準備工作 (已完成)
- [x] 建立目錄結構 (`maintenance_records/` 及其子目錄)
- [x] 創建文件模板 (`TEMPLATE_*.md`)
- [x] 更新文件規範 (`DOCS_STANDARD.md`)
- [x] 創建事件處理流程 (`INCIDENT_RESPONSE_PROCEDURE.md`)
### 3.2 階段 2：文件遷移 (✅ 已完成)
#### 任務 2.1：測試報告遷移 (✅ 已完成)
**文件**：`N8N_MCP_TEST_REPORT.md`
**目標類型**：變更記錄 (測試是變更的一部分)
**新文件名**：`CHANGE_N8N_MCP_INTEGRATION_TEST_2026_03_23.md`
**遷移步驟**：
1. 複製原文件內容到新模板
2. 調整結構符合變更記錄格式
3. 添加必要的元數據
4. 移動到 `changes/_completed/` 目錄
```bash
# 遷移命令示例
cp docs/N8N_MCP_TEST_REPORT.md \
docs_v1.0/OPERATIONS/maintenance_records/changes/_completed/CHANGE_N8N_MCP_INTEGRATION_TEST_2026_03_23.md
```
#### 任務 2.2：問題追蹤轉換 (可選)
**文件**：`PENDING_ISSUES.md`
**處理方式**：不遷移，但可從中提取具體事件
**建議**：
- 對於已解決的問題，創建相應的事件報告
- 對於持續的問題，保留在問題追蹤中
- 未來新問題直接使用新事件報告模板
#### 任務 2.3：創建示例文件 (已完成)
- [x] `RCA_WORDPRESS_TIMEOUT_EXTERNAL_ACCESS_2026_03_27.md`
#### 任務 2.4：RCA 文件遷移 (✅ 已完成)
**文件**：`N8N_API_FIX_SUMMARY.md`
**目標類型**：根本原因分析 (RCA)
**新文件名**：`RCA_N8N_API_PORT_CONFLICT_2026_03_26.md`
**遷移狀態**：已成功遷移至 `docs/maintenance_records/rca/`
### 3.3 階段 3：驗證與清理
- [ ] 驗證遷移後文件可訪問性
- [ ] 更新相關文件中的鏈接
- [ ] 備份原始文件（可選）
- [ ] 更新文件索引或導航
---
## 4. 文件轉換指南
### 4.1 從問題追蹤轉換為事件報告
**原內容** (`PENDING_ISSUES.md` 中的問題)：
```markdown
## 問題 #1: sqlx async INSERT 不會實際寫入數據庫
### 問題描述
使用 sqlx async 執行 INSERT 時，報告成功但數據沒有實際寫入。
### 嘗試過的解決方案
| # | 嘗試方法 | 結果 |
|---|---|---|
| 1 | 使用 `execute()` | 報告成功但未寫入 |
```
**轉換為事件報告**：
1. 創建新文件：`INCIDENT_DATABASE_WRITE_FAILURE_2026_03_XX.md`
2. 使用 `TEMPLATE_INCIDENT.md` 模板
3. 填寫對應欄位：
- 事件標題：sqlx async INSERT 寫入失敗
- 事件類型：數據問題
- 嚴重等級：P2 (影響部分功能)
- 狀態：✅ 已解決 (假設已解決)
### 4.2 從測試報告轉換為變更記錄
**原內容**：測試報告文檔
**轉換步驟**：
1. 識別相關的變更：n8n MCP 整合
2. 創建變更記錄文件
3. 填寫變更詳情、測試結果、驗證信息
4. 添加變更影響評估
---
## 5. 未來文件創建流程
### 5.1 新事件報告流程
1. 檢測到事件或問題
2. 使用模板創建事件報告
3. 存儲到 `incidents/_active/`
4. 按流程處理和更新狀態
5. 完成後移動到 `incidents/_completed/`
### 5.2 新變更記錄流程
1. 計畫系統變更
2. 創建變更記錄文件
3. 存儲到 `changes/_active/`
4. 記錄變更實施過程
5. 完成後移動到 `changes/_completed/`
### 5.3 新 RCA 流程
1. 事件需要深入分析
2. 創建 RCA 文件
3. 存儲到 `rca/_active/`
4. 進行根本原因分析
5. 完成後移動到 `rca/_completed/`
---
## 6. 風險與緩解
### 6.1 風險識別
| 風險 | 可能性 | 影響 | 風險等級 | 緩解措施 |
|------|--------|------|----------|----------|
| 文件鏈接失效 | 中 | 低 | 中 | 更新相關文件中的鏈接 |
| 歷史上下文丟失 | 低 | 中 | 低 | 保留原始文件備份 |
| 團隊適應期 | 高 | 低 | 中 | 提供培訓和指南 |
| 文件重複 | 中 | 低 | 中 | 明確遷移範圍和規則 |
### 6.2 緩解措施
1. **備份策略**：遷移前備份原始文件
2. **逐步遷移**：先遷移少量文件驗證流程
3. **團隊溝通**：通知相關人員新文件結構
4. **驗證測試**：驗證遷移後文件可正常訪問
---
## 7. 時間表與責任
### 7.1 遷移時間表
| 階段 | 任務 | 預計時間 | 負責人 | 狀態 |
|------|------|----------|--------|------|
| 準備工作 | 建立目錄和模板 | 2小時 | OpenCode | ✅ 已完成 |
| 文件分析 | 分析現有文件 | 1小時 | OpenCode | ✅ 已完成 |
| 文件遷移 | 遷移具體文件 | 2小時 | OpenCode | ✅ 已完成 |
| 驗證清理 | 驗證和更新鏈接 | 1小時 | OpenCode | ✅ 已完成 |
### 7.2 角色與責任
- **遷移執行者**：執行具體文件遷移操作
- **驗證人員**：驗證遷移後文件完整性和可訪問性
- **團隊負責人**：批准遷移計畫和結果
---
## 8. 成功標準
### 8.1 主要成功標準
- [x] 所有目標文件成功遷移到新結構
- [x] 新文件符合命名規範和格式要求
- [ ] 文件生命周期管理正常運作
- [ ] 團隊成員能夠使用新結構
### 8.2 次要成功標準
- [ ] 文件訪問時間無顯著增加
- [ ] 搜索和檢索功能正常
- [ ] 團隊反饋積極
---
## 9. 附錄
### 9.1 相關命令
```bash
# 查看現有文件
find docs -name "*.md" -type f | grep -v maintenance_records
# 創建新事件報告
cp docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_INCIDENT.md \
docs/maintenance_records/incidents/_active/INCIDENT_$(date +%Y_%m_%d).md
# 遷移文件示例
cp docs/N8N_MCP_TEST_REPORT.md \
docs_v1.0/OPERATIONS/maintenance_records/changes/_completed/CHANGE_N8N_MCP_INTEGRATION_TEST_2026_03_23.md
```
### 9.2 參考文件
- `docs_v1.0/OPERATIONS/maintenance_records/README.md` - 目錄結構說明
- `docs_v1.0/STANDARDS/DOCS_STANDARD.md` - 文件創建規範
- `docs_v1.0/OPERATIONS/INCIDENT_RESPONSE_PROCEDURE.md` - 事件處理流程
### 9.3 聯繫信息
- 遷移問題：創建 `CHANGE_FILE_MIGRATION_*.md` 記錄
- 流程問題：參考事件處理流程
- 技術問題：聯繫技術負責人
---
## 10. 簽核
| 角色 | 姓名 | 簽字 | 日期 | 備註 |
|------|------|------|------|------|
| 計畫制定 | OpenCode | - | 2026-03-27 | 初版創建 |
| 技術審核 | Warren | | | |
| 遷移執行 | OpenCode | | | |
| 最終批准 | Warren | | | |
> **注意**：本遷移計畫需經技術負責人審核後執行。

248
docs_v1.0/OPERATIONS/maintenance_records/README.md
View File

@@ -1,248 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "維護紀錄管理目錄"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "維護紀錄管理目錄"
ai_query_hints:
- "查詢 維護紀錄管理目錄 的內容"
- "維護紀錄管理目錄 的主要目的是什麼？"
- "如何操作或實施 維護紀錄管理目錄？"
---
# 維護紀錄管理目錄
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-03-27 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-27 | 創建目錄說明文件 | OpenCode | deepseek-reasoner |
---
## 目錄概述
本目錄用於集中管理 Momentry 系統的所有運維相關紀錄，包括事件報告、根本原因分析、變更紀錄和維護計畫等。文件結構和模板經過 AI 優化設計，支持 AI Agent 高效查詢和自動化處理。
---
## 目錄結構
### 主要子目錄
| 目錄 | 用途 | 文件範例 | 保留期限 |
|------|------|----------|----------|
| [`rca/`](./rca/) | 根本原因分析 (Root Cause Analysis) | `RCA_WORDPRESS_*.md` | 2 年 |
| [`incidents/`](./incidents/) | 事件報告與處理紀錄 | `INCIDENT_POSTGRESQL_*.md` | 1 年 |
| [`changes/`](./changes/) | 系統變更與配置更新 | `CHANGE_DATABASE_*.md` | 3 年 |
| [`plans/`](./plans/) | 維護計畫與排程 | `MAINTENANCE_MONTHLY_*.md` | 1 年 |
| [`templates/`](./templates/) | 各類文件模板 | `TEMPLATE_RCA.md` | 永久 |
### 生命周期管理目錄
每個主要文檔類型（RCA、事件、變更、維護計畫）都有獨立的生命周期目錄：
| 目錄 | 用途 | 示例路徑 |
|------|------|----------|
| `_active/` | 進行中項目 | `rca/_active/`、`incidents/_active/` |
| `_completed/` | 已完成項目 | `rca/_completed/`、`incidents/_completed/` |
| `_archived/` | 已歸檔項目 | `rca/_archived/`、`incidents/_archived/` |
**AI 優化設計**：此結構支持 AI Agent 高效查詢和自動化文件移動。
---
## 文件命名規範
### 文件前綴
| 前綴 | 用途 | 範例 |
|------|------|------|
| `RCA_` | 根本原因分析 | `RCA_WORDPRESS_TIMEOUT_2026_03_27.md` |
| `INCIDENT_` | 事件報告 | `INCIDENT_DATABASE_CONNECTION_2026_03_26.md` |
| `CHANGE_` | 變更紀錄 | `CHANGE_API_ENDPOINT_2026_03_25.md` |
| `MAINTENANCE_` | 維護計畫 | `MAINTENANCE_MONTHLY_2026_04.md` |
| `TEMPLATE_` | 文件模板 | `TEMPLATE_RCA.md` |
### 命名規則
1. **前綴**：使用上述定義的前綴
2. **服務名稱**：使用大寫英文，如 `WORDPRESS`、`POSTGRESQL`
3. **問題簡述**：使用大寫英文和下劃線，如 `TIMEOUT_EXTERNAL_ACCESS`
4. **日期**：格式為 `YYYY_MM_DD`
5. **副檔名**：統一使用 `.md`
**完整範例**：
```
RCA_WORDPRESS_TIMEOUT_EXTERNAL_ACCESS_2026_03_27.md
```
---
## 文件生命周期管理
### 狀態流程
```
新創建 → [類型/_active/] → 處理完成 → [類型/_completed/] → 超過保留期限 → [類型/_archived/]
```
### 狀態說明
| 狀態 | 目錄（相對於文檔類型） | 處理要求 | 時間限制 |
|------|------------------------|----------|----------|
| ⏳ 進行中 | `_active/` | 需要定期更新進度 | 依事件等級而定 |
| ✅ 已完成 | `_completed/` | 需要最終驗證和簽核 | 保留 30 天 |
| 🗄️ 已歸檔 | `_archived/` | 只讀，供歷史參考 | 依保留期限 |
**注意**：每個文檔類型（RCA、事件、變更、維護計畫）都有獨立的生命周期目錄，例如 `rca/_active/`、`incidents/_completed/`。
### 保留政策
| 文件類型 | 活躍期 | 完成保留期 | 歸檔保留期 | 總保留期 |
|----------|--------|------------|------------|----------|
| RCA 文件 | P0: 7天<br>P1: 14天<br>P2-4: 30天 | 30 天 | 23 個月 | 2 年 |
| 事件報告 | P0: 3天<br>P1: 7天<br>P2-4: 14天 | 30 天 | 11 個月 | 1 年 |
| 變更紀錄 | 實施期間 | 90 天 | 33 個月 | 3 年 |
| 維護計畫 | 計畫期間 | 30 天 | 11 個月 | 1 年 |
---
## 事件嚴重等級
### 等級定義
| 等級 | 代碼 | 影響描述 | 處理時間目標 | 文件要求 |
|------|------|----------|--------------|----------|
| P0 | 緊急 | 服務完全中斷，影響所有用戶 | 立即處理，1小時內解決 | 必須創建 RCA |
| P1 | 高 | 主要功能不可用，影響多數用戶 | 2小時內開始處理，4小時內解決 | 建議創建 RCA |
| P2 | 中 | 次要功能問題，影響部分用戶 | 4小時內開始處理，8小時內解決 | 可選創建 RCA |
| P3 | 低 | 輕微問題，不影響核心功能 | 1個工作日內處理 | 事件報告即可 |
| P4 | 資訊 | 諮詢、建議或非緊急問題 | 3個工作日內回應 | 簡單紀錄 |
### 狀態標記
在文件頂部資訊表中使用以下標記：
| 狀態 | 標記 | 使用場景 |
|------|------|----------|
| 待處理 | ⏳ | 事件剛被報告，尚未分配 |
| 調查中 | 🔍 | 正在調查根本原因 |
| 處理中 | 🔧 | 正在實施解決方案 |
| 已解決 | ✅ | 問題已解決，待驗證 |
| 已關閉 | 📁 | 事件完全關閉 |
| 已歸檔 | 🗄️ | 事件已歸檔 |
---
## 文件模板
### 可用模板
| 模板文件 | 用途 | 位置 |
|----------|------|------|
| `TEMPLATE_RCA.md` | 根本原因分析模板 | [`templates/TEMPLATE_RCA.md`](./templates/TEMPLATE_RCA.md) |
| `TEMPLATE_INCIDENT.md` | 事件報告模板 | [`templates/TEMPLATE_INCIDENT.md`](./templates/TEMPLATE_INCIDENT.md) |
| `TEMPLATE_CHANGE.md` | 變更紀錄模板 | [`templates/TEMPLATE_CHANGE.md`](./templates/TEMPLATE_CHANGE.md) |
### 使用模板
1. 複製模板文件到目標目錄
2. 修改文件名稱符合命名規範
3. 填寫相關內容
4. 更新狀態和進度
---
## 操作流程
### 1. 報告新事件
```bash
# 1. 複製事件模板
cp templates/TEMPLATE_INCIDENT.md incidents/_active/INCIDENT_<服務>_<問題>_<日期>.md
# 2. 編輯文件內容
# 3. 更新狀態為 ⏳ 待處理
```
### 2. 升級為 RCA 分析
```bash
# 當事件需要深入分析時
cp templates/TEMPLATE_RCA.md rca/_active/RCA_<服務>_<問題>_<日期>.md
# 連結相關事件報告
# 在 RCA 文件中引用事件報告
```
### 3. 完成處理
```bash
# 1. 更新文件狀態為 ✅ 已解決
# 2. 移動到 _completed/ 目錄
mv rca/_active/RCA_*.md rca/_completed/
```
### 4. 定期歸檔
```bash
# 每月執行歸檔腳本
# 檢查 _completed/ 中的文件是否超過保留期限
# 移動過期文件到 _archived/
```
---
## 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| DOCS_STANDARD.md | 文件創建規範 | `../DOCS_STANDARD.md` |
| DOCS_STANDARD_IMPROVEMENT_PROPOSAL_*.md | 規範改善建議 | `../DOCS_STANDARD_IMPROVEMENT_PROPOSAL_*.md` |
| SERVICES.md | 服務管理總覽 | `../SERVICES.md` |
| INCIDENT_RESPONSE_PROCEDURE.md | 事件處理流程 (SOP) | `../INCIDENT_RESPONSE_PROCEDURE.md` |
| AI_AGENT_DOCUMENTATION_GUIDE.md | AI Agent 使用指南 | `../AI_AGENT_DOCUMENTATION_GUIDE.md` |
| MIGRATION_PLAN.md | 運維文件遷移計畫 | `./MIGRATION_PLAN.md` |
---
## 聯繫與支援
### 負責人員
| 角色 | 姓名 | 聯繫方式 | 負責範圍 |
|------|------|----------|----------|
| 運維管理員 | Warren | (待補充) | 整體運維流程 |
| 文件管理員 | (待指定) | (待補充) | 文件規範與維護 |
### 問題回報
1. **文件規範問題**：更新 `DOCS_STANDARD_IMPROVEMENT_PROPOSAL_*.md`
2. **流程問題**：創建 `CHANGE_MAINTENANCE_PROCESS_*.md`
3. **技術問題**：創建相應的 `INCIDENT_*.md`
---
## 更新紀錄
| 日期 | 版本 | 變更內容 | 操作人 |
|------|------|----------|--------|
| 2026-03-27 | V1.0 | 創建目錄說明文件 | OpenCode |
---
**文件結束** - 最後更新: 2026-03-27

106
docs_v1.0/OPERATIONS/maintenance_records/archive/N8N_API_FIX_SUMMARY.md
View File

@@ -1,106 +0,0 @@
# n8n REST API Fix Summary
## Issue
n8n REST API was returning 404 errors for all endpoints (`/api/v1/workflows`, `/rest/workflows`, etc.)
## Root Cause
Port 5678 was occupied by the **n8n worker** process, preventing the main n8n instance from starting properly.
## Solution
### 1. Identified Port Conflict
- Worker process was listening on port 5678 (same as main instance)
- Main n8n couldn't start because port was in use
### 2. Fixed Worker Configuration
Updated `/Library/LaunchDaemons/com.momentry.n8n.worker.plist`:
- Added `N8N_PORT=5680` to worker environment variables
- Workers shouldn't need HTTP ports, but this prevents port conflict
### 3. Restarted Services
```bash
# Kill all n8n processes
sudo pkill -9 -f n8n
# Start main n8n (now successfully binds to port 5678)
sudo launchctl enable system/com.momentry.n8n.main
sudo launchctl bootstrap system /Library/LaunchDaemons/com.momentry.n8n.main.plist
```
## Current Status
### n8n Instance
- **URL**: http://localhost:5678
- **Version**: 2.3.5
- **Status**: Running ✅
- **API Enabled**: Yes ✅
### API Key
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJlNjdiY2UzOS1iY2RkLTRjMjEtYmMwYy0yODNhYmI3ZjVjMjMiLCJpc3MiOiJuOG4iLCJhdWQiOiJwdWJsaWMtYXBpIiwiaWF0IjoxNzc0MTk4NzgwfQ.zke_Qc-saILl_tcwXm2K3J4slCmaXnzCfxVbdVPPvCE
```
### MCP Configuration
File: `~/.config/opencode/opencode.json`
```json
{
"$schema": "https://opencode.ai/config.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>"
}
}
}
}
```
## Verified Endpoints
### List Workflows
```bash
curl -H "X-N8N-API-KEY: <API_KEY>" http://localhost:5678/api/v1/workflows
```
**Result**: ✅ 30 workflows returned
### List Executions
```bash
curl -H "X-N8N-API-KEY: <API_KEY>" http://localhost:5678/api/v1/executions
```
**Result**: ✅ 100 executions returned
## Next Steps
1. **Start n8n Worker** (optional for MCP):
Workers handle job processing but aren't required for API access.
2. **Test MCP Integration**:
Restart OpenCode to load the MCP configuration and test n8n integration.
3. **Verify Workflow Management**:
- Create workflow via API
- Execute workflow
- Monitor execution status
## Files Modified
- `/Library/LaunchDaemons/com.momentry.n8n.worker.plist` - Added N8N_PORT=5680
## API Documentation
- Base URL: `http://localhost:5678/api/v1`
- Authentication: Header `X-N8N-API-KEY: <token>`
- Available endpoints: workflows, executions, credentials, users, etc.
See full API reference: https://docs.n8n.io/api/

194
docs_v1.0/OPERATIONS/maintenance_records/archive/N8N_MCP_TEST_REPORT.md
View File

@@ -1,194 +0,0 @@
# n8n MCP 整合測試報告
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-23 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-23 | 創建測試報告 | Warren | OpenCode |
---
## 測試日期
2026-03-23
## 測試環境
- **n8n Version**: 2.3.5
- **n8n URL**: http://localhost:5678
- **MCP Server**: @nextoolsolutions/mcp-n8n v2.0.0
- **OpenCode Config**: ~/.config/opencode/opencode.json
## 測試結果
### ✅ 所有測試通過
| 測試項目 | 狀態 | 詳細說明 |
|---------|------|---------|
| MCP 伺服器初始化 | ✅ 通過 | Protocol version 2024-11-05 |
| 工具列表載入 | ✅ 通過 | 43 個工具可用 |
| 工具呼叫 (list_workflows) | ✅ 通過 | 成功返回 5 個 workflows |
| API 連線 | ✅ 通過 | http://localhost:5678 |
## 可用工具 (43 個)
### Workflows (10)
- `n8n_list_workflows` - 列出所有工作流程
- `n8n_get_workflow` - 取得工作流程詳情
- `n8n_create_workflow` - 建立新工作流程
- `n8n_update_workflow` - 更新工作流程
- `n8n_delete_workflow` - 刪除工作流程
- `n8n_activate_workflow` - 啟動工作流程
- `n8n_deactivate_workflow` - 停止工作流程
- `n8n_execute_workflow` - 執行工作流程
- `n8n_get_workflow_tags` - 取得工作流程標籤
- `n8n_update_workflow_tags` - 更新工作流程標籤
### Executions (3)
- `n8n_list_executions` - 列出執行記錄
- `n8n_get_execution` - 取得執行詳情
- `n8n_delete_execution` - 刪除執行記錄
### Data Tables (6)
- `n8n_list_datatables` - 列出資料表
- `n8n_create_datatable` - 建立資料表
- `n8n_get_datatable` - 取得資料表
- `n8n_get_datatable_rows` - 查詢資料表資料
- `n8n_insert_datatable_rows` - 插入資料
- `n8n_update_datatable_rows` - 更新資料
- `n8n_upsert_datatable_row` - 更新或插入
- `n8n_delete_datatable_rows` - 刪除資料
### Tags (5)
- `n8n_list_tags` - 列出標籤
- `n8n_get_tag` - 取得標籤
- `n8n_create_tag` - 建立標籤
- `n8n_update_tag` - 更新標籤
- `n8n_delete_tag` - 刪除標籤
### Credentials (4)
- `n8n_list_credentials` - 列出認證
- `n8n_create_credential` - 建立認證
- `n8n_delete_credential` - 刪除認證
- `n8n_get_credential_schema` - 取得認證結構
### Users (3)
- `n8n_list_users` - 列出使用者
- `n8n_get_user` - 取得使用者
- `n8n_delete_user` - 刪除使用者
### Variables (3)
- `n8n_list_variables` - 列出變數
- `n8n_create_variable` - 建立變數
- `n8n_delete_variable` - 刪除變數
### Projects (4)
- `n8n_list_projects` - 列出專案
- `n8n_create_project` - 建立專案
- `n8n_update_project` - 更新專案
- `n8n_delete_project` - 刪除專案
### System (3)
- `n8n_generate_audit` - 產生安全稽核報告
- `n8n_health_check` - 健康檢查
- `n8n_trigger_webhook` - 觸發 Webhook
## 配置檔案
### ~/.config/opencode/opencode.json
```json
{
"$schema": "https://opencode.ai/config.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>"
}
}
}
}
```
## 測試範例
### 列出工作流程
```bash
# 使用 curl
curl -H "X-N8N-API-KEY: <API_KEY>" http://localhost:5678/api/v1/workflows
# 使用 MCP
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"n8n_list_workflows","arguments":{"limit":5}}}' | mcp-n8n
```
### 建立工作流程
```bash
# 使用 curl
curl -X POST \
-H "Content-Type: application/json" \
-H "X-N8N-API-KEY: <API_KEY>" \
-d '{"name":"My Workflow","nodes":[],"connections":{}}' \
http://localhost:5678/api/v1/workflows
# 使用 MCP
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"n8n_create_workflow","arguments":{"workflow":{"name":"My Workflow","nodes":[],"connections":{}}}}' | mcp-n8n
```
## 現有工作流程 (範例)
測試中成功讀取的工作流程：
1. **Diagnostic: Environment Test** (ID: 4vaf6dKznkTccuyC)
- 狀態: Active
- 用途: 環境測試與時間同步驗證
2. **Simple Test Webhook v2** (ID: 38bbM14sGo0eVCuW)
- 狀態: Active
- 用途: Webhook 測試
3. **HL Chat Searching - RAG Only** (ID: 6Y9c7mGtye4DjuENR5Kbg)
- 狀態: Inactive
- 用途: RAG 聊天搜尋整合
4. **HL Embedding with AccusysDB** (ID: 61nRs3BeNGlBtuYJFLSFn)
- 狀態: Inactive
- 用途: Qdrant 向量資料庫嵌入
5. **HL Embedding with AccusysDB (local)** (ID: 017oYPE7cDpvybAn)
- 狀態: Archived
- 用途: 本地測試版本
## 結論
✅ **n8n MCP 整合測試全部通過！**
MCP 伺服器已成功配置並運作，可以透過 OpenCode 使用所有 43 個 n8n 管理工具。
### 建議用途
1. **自動化工作流程管理** - 使用 AI 協助建立、修改、監控工作流程
2. **批次執行** - 透過 MCP 批量管理工作流程
3. **監控與稽核** - 自動化執行記錄檢視與安全稽核
4. **整合測試** - 與 Momentry Core Video RAG 整合測試
### 下一步
- 使用 OpenCode 建立 Video RAG 整合工作流程
- 設定自動化監控與告警
- 建立工作流程模板庫

27
docs_v1.0/OPERATIONS/maintenance_records/archive/README.md
View File

@@ -1,27 +0,0 @@
# 歸檔文件目錄
## 概述
本目錄存放已遷移或過期的原始文件。這些文件已根據新的維護紀錄管理規範進行了結構化遷移。
## 文件列表
| 原始文件 | 遷移後位置 | 遷移類型 | 遷移日期 |
|----------|------------|----------|----------|
| `N8N_API_FIX_SUMMARY.md` | `docs/maintenance_records/rca/RCA_N8N_API_PORT_CONFLICT_2026_03_26.md` | RCA (根本原因分析) | 2026-03-27 |
| `N8N_MCP_TEST_REPORT.md` | `docs/maintenance_records/changes/CHANGE_N8N_MCP_INTEGRATION_TEST_2026_03_23.md` | CHANGE (變更紀錄) | 2026-03-27 |
## 遷移背景
根據 [DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md](../DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md) 的規範改善建議，建立了標準化的維護紀錄管理系統。原始文件已按照新的命名規範和模板進行遷移。
## 注意事項
1. 這些文件已不再直接使用，所有引用已更新指向新的結構化文件
2. 保留這些文件僅供歷史參考
3. 如需訪問相關內容，請使用遷移後的新文件
## 遷移計劃
詳細遷移過程請參考：[MIGRATION_PLAN.md](../maintenance_records/MIGRATION_PLAN.md)
---
**歸檔日期**：2026-03-27
**操作人員**：OpenCode
**遷移依據**：DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md

150
docs_v1.0/OPERATIONS/maintenance_records/changes/_completed/CHANGE_DOCS_STANDARD_PHASE2_APPROVAL_2026_03_27.md
View File

@@ -1,150 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "變更記錄：文檔標準改善提案 Phase 2 完成與批准請求"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "phase"
- "完成與批准請求"
ai_query_hints:
- "查詢 變更記錄：文檔標準改善提案 Phase 2 完成與批准請求 的內容"
- "變更記錄：文檔標準改善提案 Phase 2 完成與批准請求 的主要目的是什麼？"
- "如何操作或實施 變更記錄：文檔標準改善提案 Phase 2 完成與批准請求？"
---
# 變更記錄：文檔標準改善提案 Phase 2 完成與批准請求
| 項目 | 內容 |
|------|------|
| 變更申請人 | OpenCode |
| 申請時間 | 2026-03-27 |
| 變更類型 | 流程改進 / 文件重構 |
| 變更狀態 | ✅ 已批准 |
| 風險等級 | 低 |
| 審核狀態 | ✅ 已簽核 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-27 | 創建變更記錄，請求 Phase 2 批准 | OpenCode | deepseek-reasoner |
---
## 變更概述
### 基本資訊
| 項目 | 內容 |
|------|------|
| **變更標題** | 文檔標準改善提案 Phase 2 完成與實施 |
| **變更原因** | 實施標準化運維文檔管理，提升事件處理效率 |
| **業務價值** | 提升運維效率，標準化事件處理，改善知識傳承 |
| **預期效益** | 事件處理時間減少 25%，文件查找時間減少 50% |
| **影響服務** | 所有 Momentry 運維流程和文檔管理 |
### 變更描述
根據 [DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md](../../DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md) 提案，已完成 Phase 2 所有任務：
#### Phase 2 完成項目
1. **✅ 事件響應程序 SOP** - 建立完整事件處理流程 (`INCIDENT_RESPONSE_PROCEDURE.md`)
2. **✅ 監控通知啟用** - 更新 `monitor_config.yaml` 啟用 n8n 通知
3. **✅ 團隊培訓材料** - 建立完整培訓材料 (`TRAINING_MAINTENANCE_RECORDS.md`)
4. **✅ 遷移計畫與執行** - 遷移現有運維文件，更新所有引用
5. **✅ 文件生命周期管理** - 建立 `_active/`, `_completed/`, `_archived/` 目錄結構
6. **✅ AI 優化模板與指南** - 創建 AI 優化模板（YAML frontmatter）和 `AI_AGENT_DOCUMENTATION_GUIDE.md`
#### 已遷移文件
| 原始文件 | 新位置 | 類型 |
|----------|--------|------|
| `N8N_API_FIX_SUMMARY.md` | `rca/_completed/RCA_N8N_API_PORT_CONFLICT_2026_03_26.md` | RCA |
| `N8N_MCP_TEST_REPORT.md` | `changes/_completed/CHANGE_N8N_MCP_INTEGRATION_TEST_2026_03_23.md` | 變更記錄 |
#### 新增文件
| 文件 | 用途 | 位置 |
|------|------|------|
| `INCIDENT_RESPONSE_PROCEDURE.md` | 事件處理標準程序 | `docs/` |
| `TRAINING_MAINTENANCE_RECORDS.md` | 團隊培訓材料 | `docs/` |
| `AI_AGENT_DOCUMENTATION_GUIDE.md` | AI Agent 使用指南 | `docs/` |
| `MIGRATION_PLAN.md` | 文件遷移計畫 | `maintenance_records/` |
| 3 個 AI 優化模板文件 | RCA、事件、變更模板（YAML frontmatter） | `maintenance_records/templates/` |
---
## 成功標準達成情況
| 標準 | 達成情況 | 證據 |
|------|----------|------|
| Phase 2 所有任務完成 | ✅ 達成 | 檢查上述完成項目清單 |
| 文件遷移完成 | ✅ 達成 | 原始文件已歸檔至 `docs/archive/` |
| 引用更新完成 | ✅ 達成 | 已更新 `N8N_WORKFLOW_VIDEO_RAG_MCP.md` 和 `N8N_SETUP_COMPLETE.md` |
| 團隊培訓材料就緒 | ✅ 達成 | `TRAINING_MAINTENANCE_RECORDS.md` 已創建 |
| 生命周期管理結構建立 | ✅ 達成 | `_active/`, `_completed/`, `_archived/` 目錄已創建 |
| AI 優化模板與指南完成 | ✅ 達成 | `AI_AGENT_DOCUMENTATION_GUIDE.md` 和 AI 優化模板已創建 |
---
## 批准請求
### 審核要求
本變更記錄用於正式記錄 Phase 2 完成情況，並請求技術負責人 **Warren** 審核批准以下事項：
1. **批准 Phase 2 實施結果** - 確認所有任務已完成且符合要求
2. **批准新的事件響應程序** - `INCIDENT_RESPONSE_PROCEDURE.md`
3. **批准啟用新的維護紀錄管理系統** - 包括目錄結構和模板
4. **授權進行團隊培訓** - 使用 `TRAINING_MAINTENANCE_RECORDS.md`
### 簽核與批准
| 角色 | 姓名 | 部門/職責 | 審核意見 | 審核狀態 | 日期 |
|------|------|------------|----------|----------|------|
| 變更申請人 | OpenCode | 實施團隊 | Phase 2 已完成，請求批准 | ✅ 已完成 | 2026-03-27 |
| 技術審核 | Warren | 技術負責人 | (請填寫審核意見) | ⏳ 待審核 | |
| 最終批准 | Warren | 技術負責人 | (請填寫批准意見) | ⏳ 待批准 | |
---
## 後續行動
| 行動項 | 描述 | 負責人 | 截止日期 | 狀態 |
|--------|------|--------|----------|------|
| 技術負責人審核 | Warren 審核 Phase 2 成果 | Warren | 2026-03-31 | ⏳ 待處理 |
| 團隊培訓執行 | 使用培訓材料進行團隊培訓 | (待指定) | 2026-04-07 | ⏳ 待安排 |
| 監控通知測試 | 測試啟用的 n8n 通知功能 | OpenCode | 2026-03-28 | ⏳ 待測試 |
---
## 附件
### 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| DOCS_STANDARD_IMPROVEMENT_PROPOSAL_*.md | 原始改善提案 | `docs/` |
| REVIEW_DOCS_STANDARD_IMPROVEMENT_*.md | 技術審核報告 | `maintenance_records/reviews/` |
| INCIDENT_RESPONSE_PROCEDURE.md | 事件響應程序 | `docs/` |
| TRAINING_MAINTENANCE_RECORDS.md | 團隊培訓材料 | `docs/` |
---
**文件狀態**: ✅ 已完成 (已批准)
**下次審查日期**: 2026-06-27 (3個月後)
---
**創建日期**: 2026-03-27
**創建人員**: OpenCode
**批准日期**: 2026-03-27
**批准人員**: Warren (技術負責人)
**批准意見**: 同意簽核並開始執行

212
docs_v1.0/OPERATIONS/maintenance_records/changes/_completed/CHANGE_N8N_MCP_INTEGRATION_TEST_2026_03_23.md
View File

@@ -1,212 +0,0 @@
---
document_type: "operation_doc"
service: "N8N"
title: "n8n MCP 整合測試報告"
date: "2026-03-23"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "整合測試報告"
ai_query_hints:
- "查詢 n8n MCP 整合測試報告 的內容"
- "n8n MCP 整合測試報告 的主要目的是什麼？"
- "如何操作或實施 n8n MCP 整合測試報告？"
---
# n8n MCP 整合測試報告
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-23 |
| 文件版本 | V1.0 |
| 當前狀態 | 📁 已關閉 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-23 | 創建測試報告 | Warren | OpenCode |
---
## 測試日期
2026-03-23
## 測試環境
- **n8n Version**: 2.3.5
- **n8n URL**: http://localhost:5678
- **MCP Server**: @nextoolsolutions/mcp-n8n v2.0.0
- **OpenCode Config**: ~/.config/opencode/opencode.json
## 測試結果
### ✅ 所有測試通過
| 測試項目 | 狀態 | 詳細說明 |
|---------|------|---------|
| MCP 伺服器初始化 | ✅ 通過 | Protocol version 2024-11-05 |
| 工具列表載入 | ✅ 通過 | 43 個工具可用 |
| 工具呼叫 (list_workflows) | ✅ 通過 | 成功返回 5 個 workflows |
| API 連線 | ✅ 通過 | http://localhost:5678 |
## 可用工具 (43 個)
### Workflows (10)
- `n8n_list_workflows` - 列出所有工作流程
- `n8n_get_workflow` - 取得工作流程詳情
- `n8n_create_workflow` - 建立新工作流程
- `n8n_update_workflow` - 更新工作流程
- `n8n_delete_workflow` - 刪除工作流程
- `n8n_activate_workflow` - 啟動工作流程
- `n8n_deactivate_workflow` - 停止工作流程
- `n8n_execute_workflow` - 執行工作流程
- `n8n_get_workflow_tags` - 取得工作流程標籤
- `n8n_update_workflow_tags` - 更新工作流程標籤
### Executions (3)
- `n8n_list_executions` - 列出執行記錄
- `n8n_get_execution` - 取得執行詳情
- `n8n_delete_execution` - 刪除執行記錄
### Data Tables (6)
- `n8n_list_datatables` - 列出資料表
- `n8n_create_datatable` - 建立資料表
- `n8n_get_datatable` - 取得資料表
- `n8n_get_datatable_rows` - 查詢資料表資料
- `n8n_insert_datatable_rows` - 插入資料
- `n8n_update_datatable_rows` - 更新資料
- `n8n_upsert_datatable_row` - 更新或插入
- `n8n_delete_datatable_rows` - 刪除資料
### Tags (5)
- `n8n_list_tags` - 列出標籤
- `n8n_get_tag` - 取得標籤
- `n8n_create_tag` - 建立標籤
- `n8n_update_tag` - 更新標籤
- `n8n_delete_tag` - 刪除標籤
### Credentials (4)
- `n8n_list_credentials` - 列出認證
- `n8n_create_credential` - 建立認證
- `n8n_delete_credential` - 刪除認證
- `n8n_get_credential_schema` - 取得認證結構
### Users (3)
- `n8n_list_users` - 列出使用者
- `n8n_get_user` - 取得使用者
- `n8n_delete_user` - 刪除使用者
### Variables (3)
- `n8n_list_variables` - 列出變數
- `n8n_create_variable` - 建立變數
- `n8n_delete_variable` - 刪除變數
### Projects (4)
- `n8n_list_projects` - 列出專案
- `n8n_create_project` - 建立專案
- `n8n_update_project` - 更新專案
- `n8n_delete_project` - 刪除專案
### System (3)
- `n8n_generate_audit` - 產生安全稽核報告
- `n8n_health_check` - 健康檢查
- `n8n_trigger_webhook` - 觸發 Webhook
## 配置檔案
### ~/.config/opencode/opencode.json
```json
{
"$schema": "https://opencode.ai/config.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>"
}
}
}
}
```
## 測試範例
### 列出工作流程
```bash
# 使用 curl
curl -H "X-N8N-API-KEY: <API_KEY>" http://localhost:5678/api/v1/workflows
# 使用 MCP
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"n8n_list_workflows","arguments":{"limit":5}}}' | mcp-n8n
```
### 建立工作流程
```bash
# 使用 curl
curl -X POST \
-H "Content-Type: application/json" \
-H "X-N8N-API-KEY: <API_KEY>" \
-d '{"name":"My Workflow","nodes":[],"connections":{}}' \
http://localhost:5678/api/v1/workflows
# 使用 MCP
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"n8n_create_workflow","arguments":{"workflow":{"name":"My Workflow","nodes":[],"connections":{}}}}' | mcp-n8n
```
## 現有工作流程 (範例)
測試中成功讀取的工作流程：
1. **Diagnostic: Environment Test** (ID: 4vaf6dKznkTccuyC)
- 狀態: Active
- 用途: 環境測試與時間同步驗證
2. **Simple Test Webhook v2** (ID: 38bbM14sGo0eVCuW)
- 狀態: Active
- 用途: Webhook 測試
3. **HL Chat Searching - RAG Only** (ID: 6Y9c7mGtye4DjuENR5Kbg)
- 狀態: Inactive
- 用途: RAG 聊天搜尋整合
4. **HL Embedding with AccusysDB** (ID: 61nRs3BeNGlBtuYJFLSFn)
- 狀態: Inactive
- 用途: Qdrant 向量資料庫嵌入
5. **HL Embedding with AccusysDB (local)** (ID: 017oYPE7cDpvybAn)
- 狀態: Archived
- 用途: 本地測試版本
## 結論
✅ **n8n MCP 整合測試全部通過！**
MCP 伺服器已成功配置並運作，可以透過 OpenCode 使用所有 43 個 n8n 管理工具。
### 建議用途
1. **自動化工作流程管理** - 使用 AI 協助建立、修改、監控工作流程
2. **批次執行** - 透過 MCP 批量管理工作流程
3. **監控與稽核** - 自動化執行記錄檢視與安全稽核
4. **整合測試** - 與 Momentry Core Video RAG 整合測試
### 下一步
- 使用 OpenCode 建立 Video RAG 整合工作流程
- 設定自動化監控與告警
- 建立工作流程模板庫

378
docs_v1.0/OPERATIONS/maintenance_records/incidents/_active/INCIDENT_TEST_SYSTEM_INTEGRATION_2026_03_27.md
View File

@@ -1,378 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "INCIDENT_TEST_SYSTEM_INTEGRATION_2026_03_27.md"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
ai_query_hints:
- "查詢 INCIDENT_TEST_SYSTEM_INTEGRATION_2026_03_27.md 的內容"
- "INCIDENT_TEST_SYSTEM_INTEGRATION_2026_03_27.md 的主要目的是什麼？"
- "如何操作或實施 INCIDENT_TEST_SYSTEM_INTEGRATION_2026_03_27.md？"
---
# INCIDENT_TEST_SYSTEM_INTEGRATION_2026_03_27.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "incident"
service: "test_system"
problem: "新文檔標準系統集成測試事件"
date: "2026-03-27"
severity: "P3" # P0/P1/P2/P3/P4
status: "active" # active/completed/archived
current_state: "investigating" # pending/investigating/resolving/resolved/closed
owner: "Warren"
created_by: "OpenCode"
created_at: "2026-03-27 14:30"
version: "1.0"
incident_type: "測試事件" # 服務中斷/性能問題/安全事件/數據問題/配置錯誤
detection_method: "系統測試" # 監控警報/用戶報告/系統日誌/例行檢查
impact_level: "低" # 高/中/低
affected_users: "測試團隊 (3人)"
downtime: "0"
tags:
- "incident"
- "test_system"
- "documentation"
- "integration_test"
related_documents:
- "RCA_TEST_SYSTEM_INTEGRATION_2026_03_27.md"
ai_query_hints:
- "如何查詢所有 P0/P1 級別的事件？"
- "如何找到過去 7 天內未解決的事件？"
- "如何更新事件狀態和時間線？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 報告者 | OpenCode |
| 報告時間 | 2026-03-27 14:30 |
| 嚴重等級 | P3 |
| 當前狀態 | 🔍 調查中 |
| 受影響服務 | 文檔標準系統、測試環境 |
| 負責人 | Warren |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有 P0/P1 級別的事件
查找: document_type: "incident" AND (severity: "P0" OR severity: "P1")
# 查詢特定服務的未解決事件
查找: document_type: "incident" AND service: "n8n" AND current_state: "investigating"
# 查詢過去 24 小時內的事件
查找: document_type: "incident" AND date: ">=2026-03-26"
```
### 自動化操作
1. **狀態更新**：當事件狀態變更時，更新 `current_state` 和 `status`
2. **目錄移動**：根據狀態自動移動文件到相應目錄 (`_active/`, `_completed/`, `_archived/`)
3. **通知觸發**：根據嚴重等級和影響級別自動發送通知
4. **時間線追蹤**：自動記錄狀態變更時間和操作人員
### 數據提取
```python
# Python 示例：提取事件元數據
import yaml
import re
def extract_incident_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建事件報告 | (姓名) | (工具) |
---
## 事件詳情
### 基本資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | (簡短描述事件) |
| **事件類型** | 服務中斷 / 性能問題 / 安全事件 / 數據問題 / 配置錯誤 |
| **發現時間** | YYYY-MM-DD HH:MM |
| **發現方式** | 監控警報 / 用戶報告 / 系統日誌 / 例行檢查 |
| **影響範圍** | (受影響的用戶數量、服務、功能) |
| **業務影響** | 高/中/低 - (具體影響描述) |
### 事件描述
#### 問題現象
(描述用戶或系統觀察到的具體現象)
#### 預期行為
(正常情況下應有的行為)
#### 實際行為
(實際觀察到的異常行為)
#### 重現步驟
1. (步驟1)
2. (步驟2)
3. (步驟3)
### 影響評估
| 影響維度 | 評估等級 | 詳細說明 |
|----------|----------|----------|
| **服務可用性** | 完全中斷 / 部分中斷 / 降級 | (影響描述) |
| **用戶影響** | 所有用戶 / 部分用戶 / 單一用戶 | (用戶群體) |
| **數據影響** | 數據丟失 / 數據損壞 / 無影響 | (數據影響細節) |
| **財務影響** | 高 / 中 / 低 | (估計損失或成本) |
| **聲譽影響** | 高 / 中 / 低 | (品牌或客戶信任影響) |
---
## 處理進度
### 時間線追蹤
| 時間 | 事件/操作 | 操作人員 | 狀態更新 | 備註 |
|------|----------|----------|----------|------|
| (時間) | 事件發現 | (姓名) | ⏳ 待處理 | (發現方式) |
| (時間) | 初步評估 | (姓名) | 🔍 調查中 | (初步結論) |
| (時間) | 根本原因分析 | (姓名) | 🔍 調查中 | (發現原因) |
| (時間) | 實施修復 | (姓名) | 🔧 處理中 | (修復措施) |
| (時間) | 驗證測試 | (姓名) | ✅ 已解決 | (驗證結果) |
| (時間) | 事件關閉 | (姓名) | 📁 已關閉 | (關閉原因) |
### 當前狀態
| 項目 | 狀態 | 詳細資訊 |
|------|------|----------|
| **調查進度** | 0-100% | (完成百分比) |
| **修復狀態** | 未開始 / 進行中 / 已完成 | (具體狀態) |
| **驗證狀態** | 待驗證 / 驗證中 / 已驗證 | (驗證結果) |
| **溝通狀態** | 內部通知 / 用戶通知 / 公開公告 | (溝通情況) |
### 臨時措施
| 措施 | 描述 | 實施時間 | 效果 | 負責人 |
|------|------|----------|------|--------|
| (措施1) | (詳細描述) | (時間) | ✅/⚠️/❌ | (姓名) |
| (措施2) | (詳細描述) | (時間) | ✅/⚠️/❌ | (姓名) |
### 根本原因分析 (初步)
| 可能原因 | 可能性 | 證據 | 調查方向 |
|----------|--------|------|----------|
| (原因1) | 高/中/低 | (支持證據) | (進一步調查) |
| (原因2) | 高/中/低 | (支持證據) | (進一步調查) |
---
## 溝通記錄
### 內部溝通
| 時間 | 溝通對象 | 溝通方式 | 內容摘要 | 發送人 |
|------|----------|----------|----------|--------|
| (時間) | 技術團隊 | Slack/Email | (摘要) | (姓名) |
| (時間) | 管理層 | 會議/報告 | (摘要) | (姓名) |
### 外部溝通 (如需要)
| 時間 | 溝通對象 | 溝通方式 | 內容摘要 | 狀態 |
|------|----------|----------|----------|------|
| (時間) | 客戶/用戶 | Email/公告 | (摘要) | 已發送/待發送 |
### 升級路徑
| 等級 | 觸發條件 | 通知對象 | 通知時限 |
|------|----------|----------|----------|
| L1 | 事件發現 | 技術團隊 | 立即 |
| L2 | P1/P0 事件 | 技術負責人 | 30分鐘內 |
| L3 | 業務影響重大 | 管理層 | 1小時內 |
| L4 | 公開影響 | 公關團隊 | 2小時內 |
---
## 資源分配
### 人員分配
| 角色 | 人員 | 聯繫方式 | 職責 |
|------|------|----------|------|
| 事件負責人 | (姓名) | (電話/郵件) | 協調處理全過程 |
| 技術調查 | (姓名) | (電話/郵件) | 調查根本原因 |
| 修復實施 | (姓名) | (電話/郵件) | 實施解決方案 |
| 溝通協調 | (姓名) | (電話/郵件) | 內外部溝通 |
| 驗證測試 | (姓名) | (電話/郵件) | 驗證修復效果 |
### 工具與資源
| 資源類型 | 名稱/路徑 | 用途 | 權限 |
|----------|-----------|------|------|
| 監控工具 | (工具名稱) | 問題診斷 | (權限) |
| 日誌系統 | (路徑) | 調查分析 | (權限) |
| 配置管理 | (系統) | 配置檢查 | (權限) |
| 備份系統 | (系統) | 數據恢復 | (權限) |
---
## 後續行動
### 立即行動 (24小時內)
| 行動項 | 描述 | 負責人 | 截止時間 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | (詳細描述) | (姓名) | (時間) | ⏳/✅ |
| (行動2) | (詳細描述) | (姓名) | (時間) | ⏳/✅ |
### 短期行動 (1-7天)
| 行動項 | 描述 | 負責人 | 截止日期 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | (詳細描述) | (姓名) | (日期) | ⏳/✅ |
| (行動2) | (詳細描述) | (姓名) | (日期) | ⏳/✅ |
### RCA 追蹤
| 項目 | 狀態 | 預計完成 | 負責人 |
|------|------|----------|--------|
| 創建 RCA 文件 | ⏳ 待開始 | (日期) | (姓名) |
| 根本原因分析 | ⏳ 待開始 | (日期) | (姓名) |
| 預防措施制定 | ⏳ 待開始 | (日期) | (姓名) |
---
## 附件與參考
### 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| (相關文件1) | (用途) | (路徑) |
| (相關文件2) | (用途) | (路徑) |
### 日誌摘錄
```
(關鍵日誌內容)
```
### 監控圖表
| 指標 | 正常範圍 | 事件期間 | 當前值 |
|------|----------|----------|--------|
| (指標1) | (範圍) | (異常值) | (當前值) |
| (指標2) | (範圍) | (異常值) | (當前值) |
### 配置快照
| 配置項 | 事件前 | 當前值 | 變更原因 |
|--------|--------|--------|----------|
| (配置1) | (值) | (值) | (原因) |
| (配置2) | (值) | (值) | (原因) |
---
## 簽核與批准
### 事件關閉審核
| 審核項目 | 審核標準 | 審核結果 | 審核人 | 日期 |
|----------|----------|----------|--------|------|
| 問題解決 | 根本原因已識別並修復 | ✅/❌ | (姓名) | (日期) |
| 影響消除 | 所有影響已恢復正常 | ✅/❌ | (姓名) | (日期) |
| 驗證通過 | 所有測試用例通過 | ✅/❌ | (姓名) | (日期) |
| 文檔完整 | 所有相關文檔已更新 | ✅/❌ | (姓名) | (日期) |
| 溝通完成 | 所有相關方已通知 | ✅/❌ | (姓名) | (日期) |
### 批准關閉
| 角色 | 姓名 | 部門 | 批准意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 事件負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 受影響方代表 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
---
## 附錄
### 術語定義
| 術語 | 定義 |
|------|------|
| MTTR | 平均修復時間 (Mean Time To Repair) |
| MTBF | 平均故障間隔時間 (Mean Time Between Failures) |
| SLA | 服務水平協議 (Service Level Agreement) |
| SLO | 服務水平目標 (Service Level Objective) |
### 嚴重等級參考
| 等級 | 代碼 | 處理時間目標 | 通知要求 |
|------|------|--------------|----------|
| P0 | 緊急 | 立即處理，1小時內解決 | 立即通知所有相關人員 |
| P1 | 高 | 2小時內開始處理，4小時內解決 | 1小時內通知負責人 |
| P2 | 中 | 4小時內開始處理，8小時內解決 | 2小時內通知負責人 |
| P3 | 低 | 1個工作日內處理 | 工作日內通知 |
| P4 | 資訊 | 3個工作日內回應 | 無需緊急通知 |
### 狀態標記說明
| 狀態 | 標記 | 說明 |
|------|------|------|
| 新報告 | ⏳ 待處理 | 事件剛被報告，尚未分配 |
| 調查中 | 🔍 調查中 | 正在調查根本原因 |
| 處理中 | 🔧 處理中 | 正在實施解決方案 |
| 已解決 | ✅ 已解決 | 問題已解決，待驗證 |
| 已關閉 | 📁 已關閉 | 事件完全關閉 |
| 已歸檔 | 🗄️ 已歸檔 | 事件已歸檔 |
---
**文件狀態**: ⏳ 進行中 / ✅ 已完成 / 📁 已關閉
**下次審查時間**: (YYYY-MM-DD HH:MM)
---
**AI Agent 備註**
**最後更新**: 2026-03-27
**AI 優化版本**: V1.0
**兼容性**: 向後兼容現有模板
**注意**:
- AI Agent 應優先讀取 YAML frontmatter 獲取結構化數據
- 人類用戶可閱讀 Markdown 表格部分
- 兩部分數據應保持同步

486
docs_v1.0/OPERATIONS/maintenance_records/plans/_active/PLAN_BIRTH_UUID_IMPLEMENTATION_2026_04_27.md
View File

@@ -1,486 +0,0 @@
---
document_type: "plan"
service: "MOMENTRY_CORE"
title: "Birth UUID Implementation Plan - 有意义唯一标识方案"
date: "2026-04-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "uuid"
- "birth_registration"
- "resource_allocation"
- "privacy"
- "mac_binding"
ai_query_hints:
- "查询 UUID 出生登记实现计划"
- "Birth UUID 如何生成？"
- "MAC地址在UUID中的作用是什么？"
- "如何实现多层次权限管制？"
- "文件迁移后UUID是否变化？"
related_documents:
- "src/core/storage/uuid.rs"
- "src/core/ingestion.rs"
- "docs_v1.0/OPERATIONS/DOCS_STANDARD.md"
---
# Birth UUID Implementation Plan - 有意义唯一标识方案
| 项目 | 内容 |
|------|------|
| 规划制定人 | OpenCode |
| 制定时间 | 2026-04-27 |
| 规划类型 | 功能实现 |
| 规划状态 | ✅ 规划完成，待实施 |
| 优先级 | High |
| MVP范围 | Phase 1 |
---
## 版本历史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-27 | 创建规划文档 | OpenCode | glm-5 |
---
## 规划背景
### 问题陈述
当前UUID生成机制存在以下问题：
| 问题 | 当前状态 | 影响 |
|------|---------|------|
| **同名文件冲突** | GOPR0001.mp4在摄影设备中很常见 | UUID重复风险 |
| **文件迁移后变化** | SHA256(path+filename) | 无法追踪原始文件 |
| **无注册来源记录** | 仅路径哈希，无其他元数据 | 无法追溯来源 |
| **隐私信息暴露** | 路径包含用户名，明文可见 | 用户隐私风险 |
### 用户需求
| 需求 | 说明 |
|------|------|
| **唯一性** | 同名文件在不同设备/用户/时间注册，UUID必须不同 |
| **不可变性** | 文件迁移后（热→温→温冷→冷→归档），UUID保持不变 |
| **有意义** | UUID不仅仅是随机ID，应包含实际意义（可追溯） |
| **隐私保护** | MAC/Username等敏感信息不应在UUID中暴露 |
| **资源管制** | MAC用于App绑定保护，Username用于隐私管制 |
---
## 解决方案：Birth UUID（出生登记）
### 核心概念
类似"出生登记"，记录文件首次注册的完整信息：
- **出生时间**: 注册时间戳
- **出生地点**: 注册机器（MAC地址）
- **出生身份**: 注册用户（Username）
- **出生姓名**: 文件名（Filename）
### 关键特性
| 特性 | 说明 |
|------|------|
| **唯一性保证** | MAC + Time + Username + Filename 四重组合 |
| **不可变性** | UUID一旦生成，永久固定（即使文件迁移） |
| **可追溯性** | DB内存储完整birth_registration（仅内部可见） |
| **隐私保护** | 所有元素SHA256哈希（UUID不暴露明文） |
| **资源管制** | MAC用于App绑定，Username用于隐私管制 |
---
## UUID规格定义
### 格式
**纯哈希格式**: `SHA256(mac_address|timestamp|username|filename)[0:32]`
```
示例: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 (32字符纯哈希)
```
### 输入元素
| 元素 | 来源 | 格式示例 | 作用 | 处理方式 |
|------|------|---------|------|----------|
| **MAC地址** | 注册机器网卡 | `a1:b2:c3:d4:e5:f6` | App绑定 + 资源分配 | 哈希内（不外露）+ DB明文 |
| **注册时间** | 系统时间戳 | `2026-04-27T22:00:00+08:00` | 唯一性保证（时间维度） | 哈希内 + DB明文 |
| **Username** | sftpgo user home | `demo` | 隐私管制（用户维度） | 哈希内 + DB明文 |
| **Filename** | 文件名 | `GOPR0001.mp4` | 文件标识 | 哈希内 + DB明文 |
### 拼接格式
```
key = "mac_address|timestamp|username|filename"
示例key = "a1:b2:c3:d4:e5:f6|2026-04-27T22:00:00+08:00|demo|GOPR0001.mp4"
```
### 生成逻辑（Rust）
```rust
pub fn compute_birth_uuid(
mac_address: &str, // a1:b2:c3:d4:e5:f6
timestamp: &str, // 2026-04-27T22:00:00+08:00
username: &str, // demo
filename: &str // GOPR0001.mp4
) -> String {
let key = format!("{}|{}|{}|{}",
mac_address,
timestamp,
username,
filename
);
let hash = Sha256::digest(key.as_bytes());
hex::encode(hash)[0..32].to_string()
}
```
---
## 唯一性保证分析
### 场景矩阵
| 场景 | MAC | Time | User | Filename | UUID是否唯一 |
|------|-----|------|------|----------|-------------|
| 不同设备同名文件 | 不同 | 同 | 同 | 同 | ✅ 唯一 |
| 同设备不同时间注册 | 同 | 不同 | 同 | 同 | ✅ 唯一 |
| 同设备不同用户同名文件 | 同 | 同 | 不同 | 同 | ✅ 唯一 |
| 同设备同用户不同文件 | 同 | 同 | 同 | 不同 | ✅ 唯一 |
| 完全相同的四元素 | 同 | 同 | 同 | 同 | ❌ 相同（预期） |
### 实际场景示例
#### 场景1：摄影设备同名文件（最常见）
```
设备A (MAC: a1:b2:c3):
GOPR0001.mp4 @ 2026-01-01T10:00:00 → UUID: abc123...
设备B (MAC: d4:e5:f6):
GOPR0001.mp4 @ 2026-01-01T10:00:00 → UUID: def456...
结果：不同UUID ✅（MAC不同）
```
#### 场景2：同一设备多次注册同名文件
```
设备A (MAC: a1:b2:c3):
GOPR0001.mp4 @ 2026-01-01T10:00:00 → UUID: abc123...
GOPR0001.mp4 @ 2026-01-01T14:00:00 → UUID: xyz789...
结果：不同UUID ✅（Time不同）
```
#### 场景3：同一用户不同存储位置
```
MAC: a1:b2:c3, User: demo, Time: 2026-01-01T10:00:00
/Volumes/Hot/demo/GOPR0001.mp4 → UUID: abc123... (注册)
/Volumes/Warm/demo/GOPR0001.mp4 → UUID: abc123... (迁移后，UUID不变)
原因：UUID基于原始注册信息，不随当前路径变化
```
---
## 存储迁移追踪
### 存储层级定义
| 层级 | 路径示例 | 说明 |
|------|---------|------|
| **Hot** | `/Volumes/Hot/demo/` | 热存储（快速访问） |
| **Warm** | `/Volumes/Warm/demo/` | 温存储（中等访问） |
| **Warm-Cold** | `/Volumes/WarmCold/demo/` | 温冷存储 |
| **Cold** | `/Volumes/Cold/demo/` | 冷存储（归档准备） |
| **Archive** | `cloud://archive/demo/` | 云归档 |
### 迁移时间线
```
T0: 注册（Hot存储）
UUID: abc123...（基于原始注册生成）
birth_registration: {
"original_path": "/Volumes/Hot/demo",
"original_tier": "Hot"
}
current_path: /Volumes/Hot/demo/GOPR0001.mp4
T1: 迁移（Warm存储）
UUID: abc123...（不变！）
birth_registration: 不变（记录原始）
current_path: /Volumes/Warm/demo/GOPR0001.mp4
migration_history: 新增迁移记录
T2: 迁移（Cold存储）
UUID: abc123...（不变！）
current_path: /Volumes/Cold/demo/GOPR0001.mp4
T3: 归档
UUID: abc123...（不变！）
current_path: cloud://archive/demo/GOPR0001.mp4
```
---
## 数据库设计
### birth_registration JSONB字段
```sql
ALTER TABLE videos ADD COLUMN birth_registration JSONB;
-- 示例数据结构
{
"uuid": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"registration_source": {
"mac_address": "a1:b2:c3:d4:e5:f6",
"username": "demo",
"timestamp": "2026-04-27T22:00:00+08:00",
"original_path": "./demo",
"original_filename": "GOPR0001.mp4"
},
"permission_control": {
"mac_binding": {
"license_key": "demo_license",
"is_active": true
},
"user_privacy": {
"privacy_level": "private",
"data_isolation": true
}
}
}
```
### mac_allocations表（简化版）
```sql
CREATE TABLE mac_allocations (
mac_address VARCHAR(17) PRIMARY KEY,
machine_name VARCHAR(100),
license_key VARCHAR(64),
is_active BOOLEAN DEFAULT true,
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- 插入当前机器
INSERT INTO mac_allocations VALUES (
'<actual_mac>',
'MacBook-Pro',
'demo_license',
true
);
```
---
## 多层次权限管制架构
### 当前MVP实现（Phase 1）
| 层级 | 用途 | 实现状态 |
|------|------|---------|
| **MAC层** | App绑定保护 | ✅ Phase 1 实现 |
| **User层** | 隐私管制（数据隔离） | ⚠️ 单user时可跳过 |
### 未来扩展（Phase 2 - 仅文档）
| 层级 | 用途 | 实现状态 |
|------|------|---------|
| **Group层** | 访问权限控制 | 📝 仅文档规划 |
| **Service层** | 处理器权限分配 | 📝 仅文档规划 |
| **Storage层** | 存储位置分配 | 📝 仅文档规划 |
### 权限管制维度说明
| 维度 | 说明 | 示例 |
|------|------|------|
| **MAC** | App绑定保护（类似License） | 不同机器不同权限 |
| **User** | 隐私管制（数据隔离） | 用户A无法访问用户B数据 |
| **Group** | 访问权限控制（谁能access） | admin组可访问所有 |
---
## 实施计划
### Phase 1: MVP实现
| 任务 | 优先级 | 状态 | 说明 |
|------|--------|------|------|
| 更新 uuid.rs | High | Pending | 新增 compute_birth_uuid() |
| 添加 birth_registration | High | Pending | videos表JSONB字段 |
| 创建 mac_allocations 表 | High | Pending | 简化版（MAC+license） |
| 更新 ingestion.rs | High | Pending | 获取MAC并调用新函数 |
| 添加 mac_address crate | High | Pending | Cargo.toml依赖 |
| 单元测试 | High | Pending | 验证UUID生成逻辑 |
### Phase 2: 扩展功能（仅文档）
| 功能 | 状态 | 说明 |
|------|------|------|
| user_privacy表 | 📝 仅文档 | 多用户隐私管制 |
| group_access表 | 📝 仅文档 | 组访问控制 |
| migration_history | 📝 仅文档 | 迁移历史追踪 |
| 多层次权限API | 📝 仅文档 | 完整权限系统 |
---
## 验证计划
### 单元测试
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_birth_uuid_generation() {
let uuid = compute_birth_uuid(
"a1:b2:c3:d4:e5:f6",
"2026-04-27T22:00:00+08:00",
"demo",
"video.mp4"
);
assert_eq!(uuid.len(), 32);
}
#[test]
fn test_different_mac() {
let uuid1 = compute_birth_uuid(
"a1:b2:c3", "2026-01-01", "demo", "video.mp4"
);
let uuid2 = compute_birth_uuid(
"d4:e5:f6", "2026-01-01", "demo", "video.mp4"
);
assert_ne!(uuid1, uuid2); // MAC不同
}
#[test]
fn test_different_time() {
let uuid1 = compute_birth_uuid(
"a1:b2:c3", "2026-01-01T10:00:00", "demo", "video.mp4"
);
let uuid2 = compute_birth_uuid(
"a1:b2:c3", "2026-01-01T14:00:00", "demo", "video.mp4"
);
assert_ne!(uuid1, uuid2); // Time不同
}
#[test]
fn test_different_user() {
let uuid1 = compute_birth_uuid(
"a1:b2:c3", "2026-01-01", "demo", "video.mp4"
);
let uuid2 = compute_birth_uuid(
"a1:b2:c3", "2026-01-01", "warren", "video.mp4"
);
assert_ne!(uuid1, uuid2); // User不同
}
}
```
---
## 向后兼容
### UUID类型识别
| UUID类型 | 长度 | birth_registration | 生成方式 |
|---------|------|-------------------|---------|
| **旧UUID** | 16字符 | 无字段 | SHA256[path+filename](0:16) |
| **新UUID** | 32字符 | 有字段 | SHA256[mac+time+user+filename](0:32) |
### 兼容策略
```rust
pub fn is_birth_uuid(uuid: &str) -> bool {
uuid.len() == 32 && !uuid.contains('_') // 纯哈希32字符
}
// 处理时自动识别
pub fn get_uuid_type(uuid: &str) -> UuidType {
if is_birth_uuid(uuid) {
UuidType::Birth
} else {
UuidType::Legacy
}
}
```
---
## API影响
### 外部API（不变）
| API | 影响 |
|-----|------|
| `/api/v1/videos/:uuid` | ✅ UUID参数传递不变 |
| `/api/v1/videos?uuid=xxx` | ✅ 查询参数不变 |
| Python scripts `--uuid` | ✅ 参数传递不变 |
### 内部API（新增 - 可选）
```rust
// 管理员查询birth_registration（仅内部）
GET /api/admin/videos/:uuid/birth-info
Response:
{
"uuid": "a1b2c3d4...",
"registration_source": {
"mac_address": "a1:b2:c3...",
"username": "demo",
"timestamp": "2026-04-27...",
"original_filename": "GOPR0001.mp4"
}
}
```
---
## 隐私保护级别
| 保护项 | 保护方式 | 保护级别 | 外部可见 |
|---------|----------|----------|----------|
| **UUID** | SHA256哈希 | ✅ 最高 | ❌ 不可解码 |
| **MAC地址** | 哈希内 + DB明文 | ✅ 高 | ❌ 仅内部 |
| **Username** | 哈希内 + DB明文 | ✅ 高 | ❌ 仅内部 |
| **注册时间** | 哈希内 + DB明文 | ✅ 高 | ❌ 仅内部 |
| **外部API** | 无暴露API | ✅ 最高 | ❌ 外部无法查询 |
---
## 执行状态
| 状态 | 说明 |
|------|------|
| 规划完成 | ✅ 规划文档已存档 |
| 待实施 | ⏸ Phase 1 待执行 |
| Phase 2 | 📝 仅文档规划 |
---
## 参考文档
| 文档 | 说明 |
|------|------|
| `src/core/storage/uuid.rs` | 当前UUID生成逻辑 |
| `src/core/ingestion.rs` | 文件注册流程 |
| `docs_v1.0/OPERATIONS/DOCS_STANDARD.md` | 文档规范 |
| `AGENTS.md` | 项目总览 |
---
**注意**: Phase 2 功能（group_access、多层次权限API等）仅在本文档中规划，暂不实施。待多用户场景出现后再实现。

496
docs_v1.0/OPERATIONS/maintenance_records/plans/_completed/MAINTENANCE_MOMENTRY_CORE_DATA_CLEANUP_2026_03_28.md
View File

@@ -1,496 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "MAINTENANCE_MOMENTRY_CORE_DATA_CLEANUP_2026_03_28.md"
date: "2026-03-28"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
ai_query_hints:
- "查詢 MAINTENANCE_MOMENTRY_CORE_DATA_CLEANUP_2026_03_28.md 的內容"
- "MAINTENANCE_MOMENTRY_CORE_DATA_CLEANUP_2026_03_28.md 的主要目的是什麼？"
- "如何操作或實施 MAINTENANCE_MOMENTRY_CORE_DATA_CLEANUP_2026_03_28.md？"
---
# MAINTENANCE_MOMENTRY_CORE_DATA_CLEANUP_2026_03_28.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "maintenance"
service: "MOMENTRY_CORE"
task: "DATA_CLEANUP"
date: "2026-03-28"
severity: "P2"
status: "completed"
priority: "P2"
owner: "OpenCode"
created_by: "OpenCode"
created_at: "2026-03-28 14:00"
version: "1.0"
maintenance_type: "data_cleanup"
execution_window: "2026-03-29 02:00-04:00"
execution_time_approved: "2026-03-28"
estimated_duration: "60"
affected_systems:
- "PostgreSQL"
- "Redis"
- "Qdrant"
- "MongoDB"
- "FileSystem"
retained_records:
# 僅保留資料庫紀錄，不涉及 SFTPGo 實體檔案
- "ExaSAN PCIe series - Director Ou Yu-Zhi Shares His Experience.mp4 (資料庫記錄)"
- "Old_Time_Movie_Show_-_Charade_1963.HD.mov (資料庫記錄)"
excluded_systems:
- "SFTPGo 檔案儲存服務"
- "其他 SFTPGo 用戶檔案"
tags:
- "maintenance"
- "data_cleanup"
- "momentry_core"
ai_query_hints:
- "如何查詢所有 P2 級別的維護計畫？"
- "如何找到與 Momentry Core 數據清理相關的維護計畫？"
- "如何更新維護計畫狀態？"
- "如何查詢正在執行的維護計畫？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 計畫制定人 | OpenCode |
| 制定時間 | 2026-03-28 |
| 計畫類型 | 數據清理 |
| 計畫狀態 | ✅ 已完成 |
| 計畫週期 | 單次 |
| 優先級 | P2 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.2 | 2026-03-29 | 執行檢討與建議 | OpenCode | OpenCode |
| V1.1 | 2026-03-29 | 執行完成，更新執行日誌 | OpenCode | OpenCode |
| V1.0 | 2026-03-28 | 創建數據清理維護計畫 | OpenCode | OpenCode |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有 P2 級別的維護計畫
查找: document_type: "maintenance" AND severity: "P2"
# 查詢 Momentry Core 數據清理計畫
查找: document_type: "maintenance" AND service: "MOMENTRY_CORE" AND task: "DATA_CLEANUP"
# 查詢正在執行的維護計畫
查找: document_type: "maintenance" AND status: "active"
# 查詢保留的檔案
查找: retained_files: "Charade"
```
### 自動化操作
1. **狀態更新**：當計畫狀態變更時，同時更新 YAML frontmatter 中的 `status` 和 Markdown 表格中的狀態
2. **目錄移動**：根據狀態自動移動文件到相應目錄：
- `planning` → `_active/`
- `active` → `_active/`
- `completed` → `_completed/`
- `cancelled` → `_completed/`
3. **通知觸發**：根據優先級和狀態自動發送通知
### 數據提取
```python
# Python 示例：提取維護計畫元數據
import yaml
import re
def extract_maintenance_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
```
### 隔離清單識別
本計畫使用 `retained_files` 欄位識別需保留的資料，**這些是資料庫紀錄而非 SFTPGo 實體檔案**。
AI Agent 在執行清理時應：
1. 先讀取 YAML frontmatter 中的 `retained_files` 清單
2. 執行任何刪除操作前，驗證記錄不在保留清單中
3. 如有疑慮，先跳過該記錄並記錄
4. **注意**：本計畫不涉及 SFTPGo 實體檔案操作
---
## 計畫概述
### 基本資訊
| 項目 | 內容 |
|------|------|
| **計畫標題** | Momentry Core 數據清理維護計畫 |
| **計畫目的** | 清理測試數據，確保發布版本資料乾淨 |
| **業務價值** | 確保 POC 環境資料整潔，避免測試數據污染正式環境 |
| **預期成果** | 資料庫僅保留 SFTPGo demo user 的 2 支影片及相關數據 |
| **影響服務** | PostgreSQL, Redis, Qdrant, MongoDB, FileSystem |
### 背景與動機
#### 當前狀態分析
- **資料庫現況**：15 筆影片紀錄
- 僅 2 筆來自 SFTPGo demo user 目錄
- 3 筆重複記錄 (Charade 影片不同 UUID)
- 8 筆無 Job 處理記錄
- **系統分布**：
- PostgreSQL: ~17k chunks, 15 videos, 7 jobs
- Redis: worker status keys
- Qdrant: 向量資料
- MongoDB: 快取資料
#### 改進機會
- **穩定性方面**: 測試資料可能干擾正式環境分析
- **可維護性**: 資料庫包含過多測試記錄，不利於管理
#### 觸發因素
| 因素 | 描述 | 緊迫性 |
|------|------|--------|
| 資料污染 | 測試資料殘留正式環境 | 高 |
| 重複記錄 | Charade 影片有 3 個不同 UUID | 中 |
### 範圍與約束
#### 範圍定義
- **包含項目 (Momentry Core 管理範圍)**:
- PostgreSQL: videos, chunks, monitor_jobs, processor_results 表 (僅資料，不含結構)
- Redis: momentry_dev:* keys (worker status)
- Qdrant: vectors collection
- FileSystem: /Users/accusys/momentry/output/ JSON 輸出檔案
- **明確排除項目 (不屬於 Momentry Core 管理範圍)**:
- ❌ SFTPGo 檔案儲存系統 (任何用戶的實際檔案)
- ❌ 其他 SFTPGo 用戶目錄的檔案
- ❌ PostgreSQL 結構定義 (僅清理數據)
#### 隔離說明
| 隔離類型 | 說明 |
|----------|------|
| **資料庫紀錄隔離** | 僅保留 2 筆 demo user 影片的資料庫紀錄 (videos, chunks, vectors) |
| **實體檔案隔離** | 不涉及 SFTPGo 實體檔案，僅處理 Momentry Core 数据库中的中繼資料 |
| **其他用戶隔離** | 不論任何 SFTPGo 用戶的檔案，均不進行任何操作 |
#### 不動用範圍確認
本計畫**不會**對以下系統進行任何操作：
- SFTPGo 檔案儲存服務
- 其他 SFTPGo 用戶的檔案目錄
- SFTPGo 本身的管理設定
#### 限制條件
| 限制類型 | 限制條件 | 影響 |
|----------|----------|------|
| 時間限制 | 2026-03-29 02:00-04:00 | 需在 2 小時內完成 |
| 資源限制 | 僅操作開髮指向 Redis | 避免影響正式環境 |
| 技術限制 | 不刪除資料庫結構 | 僅清理數據 |
---
## 詳細計畫
### 總體時間安排
| 階段 | 開始日期 | 結束日期 | 持續時間 | 里程碑 | 負責人 |
|------|----------|----------|----------|--------|--------|
| 規劃階段 | 2026-03-28 | 2026-03-28 | 1 小時 | 計畫批准 | OpenCode |
| 準備階段 | 2026-03-28 | 2026-03-28 | 1 小時 | 資源就緒 | OpenCode |
| 實施階段 | 2026-03-29 02:00 | 2026-03-29 03:00 | 1 小時 | 實施完成 | OpenCode |
| 驗證階段 | 2026-03-29 03:00 | 2026-03-29 03:30 | 30 分鐘 | 驗證通過 | OpenCode |
| 收尾階段 | 2026-03-29 03:30 | 2026-03-29 04:00 | 30 分鐘 | 計畫關閉 | OpenCode |
### 執行時間
| 項目 | 時間 | 狀態 |
|------|------|------|
| 執行時間 | 2026-03-29 02:00 AM | ✅ 已確認 |
| 預估執行時長 | 30-60 分鐘 | - |
| 離峰時段 | 02:00-04:00 | - |
| 批准日期 | 2026-03-28 | ✅ |
### 階段詳情
#### 階段 1: 規劃階段
| 任務編號 | 任務描述 | 交付物 | 負責人 | 預計工時 | 狀態 |
|----------|----------|--------|--------|----------|------|
| 1.1 | 需求分析與收集 | 需求文檔 | OpenCode | 0.5 小時 | ✅ |
| 1.2 | 技術方案設計 | 設計文檔 | OpenCode | 0.5 小時 | ✅ |
| 1.3 | 資源需求評估 | 資源清單 | OpenCode | 0.25 小時 | ✅ |
| 1.4 | 風險評估與緩解 | 風險報告 | OpenCode | 0.25 小時 | ✅ |
| 1.5 | 計畫審核與批准 | 批准文件 | 用戶 | 0 小時 | ⏳ |
#### 階段 2: 準備階段
| 任務編號 | 任務描述 | 交付物 | 負責人 | 預計工時 | 狀態 |
|----------|----------|--------|--------|----------|------|
| 2.1 | 停止 Worker 服務 | 停止確認 | OpenCode | 5 分鐘 | ⏳ |
| 2.2 | 備份 PostgreSQL | 備份檔案 | OpenCode | 10 分鐘 | ⏳ |
| 2.3 | 備份 Redis keys | 匯出檔案 | OpenCode | 5 分鐘 | ⏳ |
| 2.4 | 備份 Qdrant | 備份確認 | OpenCode | 5 分鐘 | ⏳ |
| 2.5 | 驗證備份完整性 | 驗證報告 | OpenCode | 5 分鐘 | ⏳ |
#### 階段 3: 實施階段 (分層清理)
| 任務編號 | 任務描述 | 關鍵操作 | 預計時間 | 負責人 | 狀態 |
|----------|----------|----------|----------|--------|------|
| 3.1 | 預實施檢查 | 系統健康檢查 | 5 分鐘 | OpenCode | ⏳ |
| 3.2 | Layer 1: 清理 orphan chunks | 刪除無效 chunks | 10 分鐘 | OpenCode | ⏳ |
| 3.3 | Layer 2: 清理重複影片 | 刪除重複 UUID | 10 分鐘 | OpenCode | ⏳ |
| 3.4 | Layer 3: 清理無 Job 影片 | 刪除未處理影片 | 10 分鐘 | OpenCode | ⏳ |
| 3.5 | Layer 4: 清理 Redis keys | 刪除 worker keys | 5 分鐘 | OpenCode | ⏳ |
| 3.6 | Layer 5: 清理 Qdrant vectors | 刪除對應向量 | 5 分鐘 | OpenCode | ⏳ |
| 3.7 | 實施驗證 | 基礎功能驗證 | 10 分鐘 | OpenCode | ⏳ |
#### 階段 4: 驗證階段
| 任務編號 | 任務描述 | 驗證標準 | 驗證方法 | 負責人 | 狀態 |
|----------|----------|----------|----------|--------|------|
| 4.1 | 功能驗證 | 影片數量 = 2 | SQL count | OpenCode | ⏳ |
| 4.2 | Chunks 驗證 | chunks 數量合理 | SQL count | OpenCode | ⏳ |
| 4.3 | Redis 驗證 | keys 乾淨 | KEYS pattern | OpenCode | ⏳ |
| 4.4 | Qdrant 驗證 | 向量數正確 | count | OpenCode | ⏳ |
| 4.5 | API 驗證 | 正常運作 | curl test | OpenCode | ⏳ |
#### 階段 5: 收尾階段
| 任務編號 | 任務描述 | 交付物 | 負責人 | 預計工時 | 狀態 |
|----------|----------|--------|--------|----------|------|
| 5.1 | 重啟 Worker 服務 | 重啟確認 | OpenCode | 5 分鐘 | ⏳ |
| 5.2 | 文檔更新 | 更新後的文檔 | OpenCode | 10 分鐘 | ⏳ |
| 5.3 | 經驗總結 | 經驗教訓報告 | OpenCode | 10 分鐘 | ⏳ |
| 5.4 | 計畫評估 | 成果評估報告 | OpenCode | 5 分鐘 | ⏳ |
| 5.5 | 計畫關閉 | 關閉確認 | OpenCode | 5 分鐘 | ⏳ |
---
## 風險管理
### 風險識別與評估
| 風險編號 | 風險描述 | 可能性 | 影響程度 | 風險等級 | 觸發條件 |
|----------|----------|--------|----------|----------|----------|
| R001 | 誤刪 demo 影片 | 低 | 高 | 中 | 執行刪除前未驗證 |
| R002 | 清理不完整 | 中 | 中 | 中 | 漏刪某些系統數據 |
| R003 | 服務中斷過長 | 低 | 高 | 中 | 執行時間超預期 |
| R004 | 資料庫鎖定 | 低 | 中 | 低 | 大量刪除操作 |
| R005 | 備份失敗 | 低 | 高 | 高 | 備份過程出錯 |
### 風險緩解措施
| 風險編號 | 預防措施 | 應急措施 | 負責人 | 狀態 |
|----------|----------|----------|--------|------|
| R001 | 先查詢確認隔離清單 | 從備份還原 | OpenCode | ⏳ |
| R002 | 分層驗證每層結果 | 回滾至上一層 | OpenCode | ⏳ |
| R003 | 預設計劃執行時間 | 快速回滾腳本 | OpenCode | ⏳ |
| R004 | 使用小批次刪除 | 失敗立即回滾 | OpenCode | ⏳ |
| R005 | 提前驗證備份可用 | 延期執行 | OpenCode | ⏳ |
### 應急預案
| 應急場景 | 觸發條件 | 應急步驟 | 溝通計劃 | 負責人 |
|----------|----------|----------|----------|--------|
| 實施失敗 | 關鍵任務失敗無法繼續 | 1. 停止實施<br>2. 執行回滾<br>3. 問題分析 | 立即通知 | OpenCode |
| 系統中斷 | 服務不可用超過預期時間 | 1. 切換到備用方案<br>2. 優先恢復服務<br>3. 調整計畫 | 通知所有受影響用戶 | OpenCode |
| 數據問題 | 數據丟失或損壞 | 1. 停止操作<br>2. 從備份恢復<br>3. 數據驗證 | 通知數據管理員 | OpenCode |
---
## 成功標準與衡量指標
### 成功標準
| 標準編號 | 成功標準 | 衡量方法 | 目標值 | 權重 |
|----------|----------|----------|--------|------|
| S001 | 影片數量正確 | SQL count | 2 | 30% |
| S002 | Chunks 數量合理 | SQL count | < 10000 | 20% |
| S003 | Redis keys 乾淨 | KEYS pattern | 0 | 20% |
| S004 | Qdrant vectors 正確 | count | 2 | 20% |
| S005 | API 正常運作 | curl test | 200 OK | 10% |
### 隔離清單驗證
**注意**：以下為**資料庫紀錄**，不涉及 SFTPGo 實體檔案。
| 檔案名稱 | 來源 | 處理方式 | 驗證狀態 |
|----------|------|----------|----------|
| ExaSAN PCIe series - Director Ou Yu-Zhi Shares His Experience.mp4 | SFTPGo demo user (資料庫記錄) | **保留** | ⏳ |
| Old_Time_Movie_Show_-_Charade_1963.HD.mov | SFTPGo demo user (資料庫記錄) | **保留** | ⏳ |
### 驗收標準
| 驗收項目 | 驗收標準 | 驗證方法 | 驗收人 | 狀態 |
|----------|----------|----------|--------|------|------|
| 影片數量 | 2 筆 | SELECT COUNT(*) FROM videos | OpenCode | ✅ |
| 保留紀錄 | 2 筆資料庫記錄存在 | SQL 查詢比對檔名 | OpenCode | ✅ |
| Redis keys | 0 | KEYS pattern | OpenCode | ✅ |
| Qdrant vectors | 0 | count | OpenCode | ✅ |
| SFTPGo 檔案 | 未觸及 | 不執行任何 SFTPGo 操作 | OpenCode | ✅ |
---
## 執行記錄
### 執行日誌
| 時間 | 項目 | 操作 | 結果 | 狀態 |
|------|------|------|------|------|
| 2026-03-29 02:00 | 系統檢查 | PostgreSQL, Redis 連線驗證 | 正常 | ✅ |
| 2026-03-29 02:01 | Layer 1 | 檢查 orphan chunks | 0 筆 | ✅ |
| 2026-03-29 02:02 | Layer 2-3 | 刪除非 demo user 資料 | 13 影片, 10,976 chunks, 1,591 pre_chunks, 1,922 chunk_vectors, 1 job | ✅ |
| 2026-03-29 02:05 | Layer 4 | 清理 Redis keys | 7 keys | ✅ |
| 2026-03-29 02:06 | Layer 5 | 清理 Qdrant vectors | 3,823 vectors | ✅ |
| 2026-03-29 02:07 | 額外清理 | 刪除 orphaned monitor_jobs | 12 jobs | ✅ |
| 2026-03-29 02:08 | 額外清理 | 刪除 orphaned processor_results | 7 results | ✅ |
| 2026-03-29 02:10 | 驗證 | 最終數據驗證 | 通過 | ✅ |
### 清理結果
| 項目 | 清理前 | 清理後 | 變化 |
|------|--------|--------|------|
| 影片 | 15 | 2 | -13 |
| Chunks | 16,636 | 5,660 | -10,976 |
| Chunk Vectors | 1,922 | 0 | -1,922 |
| Pre Chunks | 1,591 | 0 | -1,591 |
| Monitor Jobs | 13 | 1 | -12 |
| Processor Results | 47 | 0 | -47 |
| Redis Keys | 7 | 0 | -7 |
| Qdrant Vectors | 3,823 | 0 | -3,823 |
### 保留資料
| ID | 檔案名稱 | 來源 |
|----|----------|------|
| 17 | Old_Time_Movie_Show_-_Charade_1963.HD.mov | sftpgo/data/demo |
| 18 | ExaSAN PCIe series - Director Ou Yu-Zhi Shares His Experience.mp4 | sftpgo/data/demo |
### 實際進度追蹤
| 日期 | 計畫進度 | 實際進度 | 偏差分析 | 問題記錄 | 負責人 |
|------|----------|----------|----------|----------|--------|
| 2026-03-28 | 0% | 0% | - | 開始規劃 | OpenCode |
| 2026-03-29 | 100% | 100% | 無偏差 | 執行完成 | OpenCode |
### 問題與變更記錄
| 問題編號 | 問題描述 | 影響 | 解決方案 | 解決時間 | 狀態 |
|----------|----------|------|----------|----------|------|
---
## 執行檢討與建議
### 執行中遇到的問題
| 問題編號 | 問題描述 | 嚴重程度 | 當時處理 | 建議改善 |
|----------|----------|----------|----------|----------|
| P001 | 發現額外需清理的資料表 (monitor_jobs, processor_results) | 中 | 當下追加清理 | 執行前應完整列出所有關聯資料表 |
| P002 | FK 順序導致刪除失敗 | 低 | 調整刪除順序後成功 | 建立標準刪除順序 SOP |
| P003 | Qdrant vectors 對應方式不明確 | 中 | 直接清除全部 vectors | 建立 UUID 對應機制 |
| P004 | Redis keys 使用 momentry 而非 momentry_dev | 低 | 改用 momentry* Pattern | 執行前確認 key pattern |
### 檢討意見
1. **執行前分析**
- 初期分析較完整，但忽略 monitor_jobs 和 processor_results
- FK 依賴關係應提前分析
2. **執行效率**
- 實際執行時間 10 分鐘，遠低於預估 60 分鐘
- 原因：清理操作順利，無重大問題
3. **隔離確認**
- SFTPGo 檔案完全未觸及，符合預期
- 僅清理資料庫中繼資料，實體檔案安全
### 建議改進
| 類別 | 建議 | 優先級 |
|------|------|--------|
| 事前分析 | 建立 FK 依賴圖 | 高 |
| 事前分析 | 列出所有關聯資料表清單 | 高 |
| 執行 | 建立標準刪除順序 SOP | 中 |
| 文件 | 提前定義 UUID 對應 Qdrant 方式 | 中 |
| 自動化 | 建立預執行檢查腳本 | 低 |
### 未來類似計畫建議
1. **清單檢查表**：建立標準資料清理檢查清單
2. **備份驗證**：提前確認備份可用性
3. **分段執行**：複雜環境分階段執行
4. **監控儀表板**：建立即時監控畫面
---
## 簽核與批准
### 計畫審核
| 審核階段 | 審核人 | 部門 | 審核意見 | 審核狀態 | 日期 |
|----------|--------|------|----------|----------|------|
| 技術審核 | - | 技術部 | (待確認) | ⏳ | - |
| 風險審核 | - | 風險部 | (待確認) | ⏳ | - |
### 計畫批准
| 角色 | 姓名 | 部門 | 批准意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 計畫制定人 | OpenCode | 技術部 | (創建計畫) | ✅ | 2026-03-28 |
| 技術負責人 | 用戶 | 技術部 | (批准執行) | ✅ | 2026-03-28 |
---
## 參考規範文件
| 文件 | 版本 | 用途 |
|------|------|------|
| DOCS_STANDARD.md | V1.0 | 文件創建規範 |
| TEMPLATE_MAINTENANCE.md | V1.1 | 維護計畫模板 |
| README.md | V1.0 | 目錄管理說明 |
---
**計畫狀態**: ✅ 已完成
**執行完成時間**: 2026-03-29 02:10
---
**模板結束** - 請根據實際情況填寫內容

129
docs_v1.0/OPERATIONS/maintenance_records/plans/_completed/MAINTENANCE_MOMENTRY_CORE_DATA_CLEANUP_FIX_2026_03_28.md
View File

@@ -1,129 +0,0 @@
---
document_type: "maintenance"
service: "MOMENTRY_CORE"
task: "DATA_CLEANUP_FIX"
date: "2026-03-28"
severity: "P3"
status: "completed"
priority: "P3"
owner: "OpenCode"
created_by: "OpenCode"
created_at: "2026-03-28 16:00"
version: "1.0"
maintenance_type: "data_cleanup"
execution_window: "2026-03-28 16:00-16:30"
execution_time_approved: "2026-03-28"
estimated_duration: "30"
tags:
- "maintenance"
- "data_cleanup_fix"
- "execution_oversight"
---
# 維護記錄 - 數據清理遺漏修正
| 項目 | 內容 |
|------|------|
| 計畫制定人 | OpenCode |
| 制定時間 | 2026-03-28 |
| 計畫類型 | 數據清理修正 |
| 計畫狀態 | ✅ 已完成 |
| 計畫週期 | 單次 |
| 優先級 | P3 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 |
|------|------|------|--------|
| V1.0 | 2026-03-28 | 創建修正記錄 | OpenCode |
---
## 執行摘要
### 發現方式
| 項目 | 內容 |
|------|------|
| 發現者 | **Warren** (用戶) |
| 發現時間 | 2026-03-28 16:00 |
### 發現過程 (Prompt 串)
| 順序 | Prompt | 發現內容 |
|------|--------|----------|
| 1 | 「請檢查系統健康狀態」 | 發現 API Server 未運行 |
| 2 | 「健康狀態要包含 job worker」 | 發現 Worker 運行中，影片 2 部 |
| 3 | 「job 狀態 ？」 | 發現無 active jobs |
| 4 | 「test_video.mp4 與 demo_video.mp4 是在哪裡, statu completed 是什麼意思」 | **發現問題**：2 部影片 status 為 failed/pending，清理遺漏 |
### 清理結果
| 項目 | 清理前 | 清理後 |
|------|--------|--------|
| Videos | 2 | 0 |
| Chunks | 5,660 | 0 |
### 清理的資料
| ID | UUID | Filename | Status | 問題 |
|----|------|----------|--------|------|
| 18 | 9760d0820f0cf9a7 | ExaSAN PCIe series... | **failed** | 處理失敗 |
| 17 | 384b0ff44aaaa1f14cb2cd63b3fea966 | Old_Time_Movie_Show... | **pending** | 從未處理 |
---
## 執行檢討 - 為何遺漏
### 根本原因分析
| 問題 | 說明 |
|------|------|
| **R1 - 清理條件不完整** | 2026-03-28 的清理計畫只保留了「demo user 影片」，但**未驗證處理狀態** |
| **R2 - 缺乏狀態過濾** | 保留清單應包含 `status = 'completed'` 條件，而非僅看用戶 |
| **R3 - 隔離清單設計缺陷** | `retained_records` 只列檔名，未定義保留條件 |
### 問題發生時序
```
2026-03-28 02:00 → 執行數據清理
→ 保留 2 筆 demo user 影片 (未檢查 status)
→ 當時這 2 筆可能狀態為 pending/failed
2026-03-28 16:00 → 健康檢查發現
→ 發現 status = failed/pending
→ 執行修正清理
```
### 教訓
| 教訓 | 改進建議 |
|------|----------|
| 清理應包含狀態條件 | 保留資料時應同時指定 `status = 'completed'` |
| 隔離清單需完整定義 | 應包含：user + status + 處理完成標記 |
| 執行後需追蹤 | 清理後應驗證 retained 資料的狀態是否仍有效 |
---
## 執行記錄
| 時間 | 項目 | 操作 | 結果 |
|------|------|------|------|
| 2026-03-28 16:00 | 發現問題 | 健康檢查發現 failed/pending 影片 | - |
| 2026-03-28 16:05 | 清理 chunks | DELETE FROM chunks WHERE file_id IN (17,18) | 5660 筆刪除 |
| 2026-03-28 16:06 | 清理 videos | DELETE FROM videos WHERE id IN (17,18) | 2 筆刪除 |
| 2026-03-28 16:10 | 驗證 | SELECT COUNT(*) FROM videos | 0 |
---
## 相關文件
| 文件 | 用途 |
|------|------|
| MAINTENANCE_MOMENTRY_CORE_DATA_CLEANUP_2026_03_28.md | 原始清理計畫 |
---
**記錄結束**

459
docs_v1.0/OPERATIONS/maintenance_records/rca/_active/RCA_TEST_SYSTEM_INTEGRATION_2026_03_27.md
View File

@@ -1,459 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "RCA_TEST_SYSTEM_INTEGRATION_2026_03_27.md"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
ai_query_hints:
- "查詢 RCA_TEST_SYSTEM_INTEGRATION_2026_03_27.md 的內容"
- "RCA_TEST_SYSTEM_INTEGRATION_2026_03_27.md 的主要目的是什麼？"
- "如何操作或實施 RCA_TEST_SYSTEM_INTEGRATION_2026_03_27.md？"
---
# RCA_TEST_SYSTEM_INTEGRATION_2026_03_27.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "rca"
service: "test_system"
problem: "新文檔標準系統集成測試問題"
date: "2026-03-27"
severity: "P3" # P0/P1/P2/P3/P4
status: "active" # active/completed/archived
current_state: "resolving" # pending/investigating/resolving/resolved/closed
owner: "Warren"
created_by: "OpenCode"
created_at: "2026-03-27 14:45"
version: "1.0"
rca_type: "process" # technical/process/human_error
root_cause: "新文檔標準系統集成測試過程中發現模板使用流程需要優化"
resolution: "創建測試文件驗證模板功能，更新相關文檔"
prevention: "建立標準測試流程，確保新模板上線前經過完整驗證"
tags:
- "rca"
- "test_system"
- "documentation"
- "integration_test"
related_documents:
- "INCIDENT_TEST_SYSTEM_INTEGRATION_2026_03_27.md"
ai_query_hints:
- "如何查詢所有 P0 級別的 RCA？"
- "如何找到與 n8n 相關的所有 RCA？"
- "如何更新 RCA 狀態？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-03-27 |
| 文件版本 | V1.0 |
| 嚴重等級 | P3 |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有 P0/P1 級別的 RCA
查找: document_type: "rca" AND (severity: "P0" OR severity: "P1")
# 查詢特定服務的活躍 RCA
查找: document_type: "rca" AND service: "n8n" AND status: "active"
# 查詢需要審核的 RCA
查找: document_type: "rca" AND current_state: "resolved" AND status: "active"
```
### 自動化操作
1. **狀態更新**：當 RCA 完成時，更新 `current_state` 和 `status`
2. **目錄移動**：根據狀態自動移動文件到相應目錄 (`_active/`, `_completed/`, `_archived/`)
3. **通知觸發**：根據嚴重等級自動發送通知
4. **關聯文件更新**：自動更新相關事件和變更文件的狀態
### 數據提取
```python
# Python 示例：提取 RCA 元數據
import yaml
import re
def extract_rca_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建文件 | (姓名) | (工具) |
---
## 概述
本 RCA 文件記錄新文檔標準系統集成測試過程中發現的問題。測試目的是驗證新建立的 AI 優化模板和文件生命周期管理系統是否能正常運作。
---
## 事件摘要
### 基本資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | 新文檔標準系統集成測試問題 |
| **影響服務** | 文檔標準系統、測試環境 |
| **嚴重等級** | P3 |
| **發現時間** | 2026-03-27 14:30 |
| **解決時間** | 2026-03-27 15:00 |
| **影響範圍** | 測試團隊 (3人)，文檔標準系統驗證流程 |
| **停機時間** | (總停機時間) |
### 時間線摘要
| 時間 | 事件 | 操作 |
|------|------|------|
| (時間) | (事件描述) | (採取的操作) |
| (時間) | (事件描述) | (採取的操作) |
---
## 調查過程
### 調查步驟
| 步驟 | 操作 | 結果 | 發現 |
|------|------|------|------|
| 1 | (檢查項目) | (結果) | (重要發現) |
| 2 | (檢查項目) | (結果) | (重要發現) |
| 3 | (檢查項目) | (結果) | (重要發現) |
### 收集證據
| 證據類型 | 檔案/日誌 | 重要內容 |
|----------|-----------|----------|
| 系統日誌 | (檔案路徑) | (關鍵訊息) |
| 應用日誌 | (檔案路徑) | (關鍵訊息) |
| 監控數據 | (監控圖表) | (異常指標) |
| 配置檔案 | (檔案路徑) | (問題配置) |
### 服務狀態檢查
| 服務 | 狀態 | 配置 | 版本 |
|------|------|------|------|
| (服務名稱) | ✅/❌ | (配置摘要) | (版本號) |
| (服務名稱) | ✅/❌ | (配置摘要) | (版本號) |
---
## 根本原因分析
### 主要根本原因
#### 原因 1: (原因標題)
| 項目 | 內容 |
|------|------|
| **原因描述** | (詳細描述原因) |
| **證據** | (支持證據) |
| **影響鏈** | (原因如何導致問題) |
| **根本性** | 根本原因/表面原因 |
**技術細節**:
```代碼或配置示例
```
#### 原因 2: (原因標題)
| 項目 | 內容 |
|------|------|
| **原因描述** | (詳細描述原因) |
| **證據** | (支持證據) |
| **影響鏈** | (原因如何導致問題) |
| **根本性** | 根本原因/表面原因 |
**技術細節**:
```代碼或配置示例
```
### 次要根本原因
| 原因 | 描述 | 影響 | 改進建議 |
|------|------|------|----------|
| (原因) | (描述) | (影響程度) | (建議) |
| (原因) | (描述) | (影響程度) | (建議) |
### 根本原因總結
| 原因類型 | 原因數量 | 影響程度 | 優先級 |
|----------|----------|----------|--------|
| 主要原因 | (數量) | 高/中/低 | 1 |
| 次要原因 | (數量) | 高/中/低 | 2 |
| 系統因素 | (數量) | 高/中/低 | 3 |
---
## 解決方案與實施
### 解決方案設計
#### 方案 1: (方案標題)
| 項目 | 內容 |
|------|------|
| **方案描述** | (詳細解決方案) |
| **實施步驟** | (逐步實施方法) |
| **預期效果** | (解決的問題) |
| **風險評估** | (實施風險) |
| **回滾計畫** | (如果失敗如何回滾) |
**實施命令**:
```bash
# 實施命令示例
```
#### 方案 2: (方案標題) (可選)
| 項目 | 內容 |
|------|------|
| **方案描述** | (詳細解決方案) |
| **實施步驟** | (逐步實施方法) |
| **預期效果** | (解決的問題) |
| **風險評估** | (實施風險) |
| **回滾計畫** | (如果失敗如何回滾) |
### 實施過程
| 時間 | 步驟 | 命令/操作 | 結果 | 驗證 |
|------|------|------------|------|------|
| (時間) | (步驟描述) | (具體命令) | ✅/❌ | (驗證方法) |
| (時間) | (步驟描述) | (具體命令) | ✅/❌ | (驗證方法) |
### 驗證測試
| 測試項目 | 測試方法 | 預期結果 | 實際結果 | 狀態 |
|----------|----------|----------|----------|------|
| (測試1) | (測試步驟) | (預期) | (實際) | ✅/❌ |
| (測試2) | (測試步驟) | (預期) | (實際) | ✅/❌ |
| (測試3) | (測試步驟) | (預期) | (實際) | ✅/❌ |
---
## 預防措施
### 短期措施 (1-7 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
### 中期措施 (8-30 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
### 長期措施 (31-90 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
---
## 影響評估
### 直接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **服務可用性** | ✅/❌/⚠️ | (詳細說明) |
| **數據完整性** | ✅/❌/⚠️ | (詳細說明) |
| **性能影響** | ✅/❌/⚠️ | (詳細說明) |
| **安全性影響** | ✅/❌/⚠️ | (詳細說明) |
### 間接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **用戶體驗** | 高/中/低 | (詳細說明) |
| **業務影響** | 高/中/低 | (詳細說明) |
| **聲譽影響** | 高/中/低 | (詳細說明) |
| **成本影響** | 高/中/低 | (詳細說明) |
### 量化指標
| 指標 | 事件前 | 事件中 | 事件後 | 變化 |
|------|------|------|------|------|
| (指標1) | (數值) | (數值) | (數值) | (+/-%) |
| (指標2) | (數值) | (數值) | (數值) | (+/-%) |
| (指標3) | (數值) | (數值) | (數值) | (+/-%) |
---
## 經驗教訓
### 學到的教訓
| 教訓類別 | 具體教訓 | 改進措施 |
|----------|----------|----------|
| **技術方面** | (技術教訓) | (具體改進) |
| **流程方面** | (流程教訓) | (具體改進) |
| **溝通方面** | (溝通教訓) | (具體改進) |
| **管理方面** | (管理教訓) | (具體改進) |
### 最佳實踐建立
| 實踐領域 | 最佳實踐 | 實施狀態 |
|----------|----------|----------|
| **監控警報** | (監控改進) | ⏳/✅ |
| **容量規劃** | (容量管理) | ⏳/✅ |
| **變更管理** | (變更流程) | ⏳/✅ |
| **災難恢復** | (恢復計畫) | ⏳/✅ |
### 知識庫更新
| 更新項目 | 文件 | 更新內容 | 狀態 |
|----------|------|----------|------|
| (項目1) | (文件名) | (更新摘要) | ⏳/✅ |
| (項目2) | (文件名) | (更新摘要) | ⏳/✅ |
---
## 技術細節
### 服務架構圖
```
(相關服務架構圖或描述)
```
### 配置文件變更
| 文件 | 變更前 | 變更後 | 變更原因 |
|------|------|------|----------|
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
### 關鍵命令
```bash
# 診斷命令
(診斷相關命令)
# 修復命令
(修復相關命令)
# 驗證命令
(驗證相關命令)
```
### 監控指標
| 指標 | 正常範圍 | 事件期間 | 當前狀態 |
|------|----------|----------|----------|
| (指標1) | (範圍) | (異常值) | (當前值) |
| (指標2) | (範圍) | (異常值) | (當前值) |
---
## 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| (相關文件1) | (用途) | (路徑) |
| (相關文件2) | (用途) | (路徑) |
| (相關文件3) | (用途) | (路徑) |
---
## 簽核
### 技術審核
| 角色 | 姓名 | 部門 | 審核意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 問題分析員 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 運維工程師 | (姓名) | 運維部 | (意見) | ⏳/✅ | (日期) |
### 管理確認
| 角色 | 姓名 | 部門 | 確認意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 受影響團隊代表 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
| 專案管理人 | (姓名) | 管理部 | (意見) | ⏳/✅ | (日期) |
---
## 附錄
### 測試腳本詳解
```bash
# 完整測試腳本
(測試腳本內容)
```
### 配置參數說明
| 參數 | 說明 | 建議值 | 計算公式 |
|------|------|--------|----------|
| (參數1) | (說明) | (建議值) | (公式) |
| (參數2) | (說明) | (建議值) | (公式) |
### 監控設定建議
```yaml
# Prometheus 監控規則示例
(監控規則)
```
---
**文件狀態**: ⏳ 進行中 / ✅ 已完成 / 📁 已關閉
**下次審查日期**: (YYYY-MM-DD)
---
**AI Agent 備註**
**最後更新**: 2026-03-27
**AI 優化版本**: V1.0
**兼容性**: 向後兼容現有模板
**注意**:
- AI Agent 應優先讀取 YAML frontmatter 獲取結構化數據
- 人類用戶可閱讀 Markdown 表格部分
- 兩部分數據應保持同步

140
docs_v1.0/OPERATIONS/maintenance_records/rca/_completed/RCA_N8N_API_PORT_CONFLICT_2026_03_26.md
View File

@@ -1,140 +0,0 @@
---
document_type: "operation_doc"
service: "N8N"
title: "RCA: n8n REST API Port Conflict"
date: "2026-03-26"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "rest"
- "conflict"
- "port"
ai_query_hints:
- "查詢 RCA: n8n REST API Port Conflict 的內容"
- "RCA: n8n REST API Port Conflict 的主要目的是什麼？"
- "如何操作或實施 RCA: n8n REST API Port Conflict？"
---
# RCA: n8n REST API Port Conflict
| 項目 | 內容 |
|------|------|
| **文件類型** | 根本原因分析 (RCA) |
| **相關服務** | n8n, REST API |
| **嚴重等級** | P2 |
| **當前狀態** | 📁 已關閉 |
| **創建日期** | 2026-03-26 |
| **完成日期** | 2026-03-26 |
| **負責人** | OpenCode |
| **文件版本** | V1.0 |
---
## 事件概述
### Issue
n8n REST API was returning 404 errors for all endpoints (`/api/v1/workflows`, `/rest/workflows`, etc.)
## Root Cause
Port 5678 was occupied by the **n8n worker** process, preventing the main n8n instance from starting properly.
## Solution
### 1. Identified Port Conflict
- Worker process was listening on port 5678 (same as main instance)
- Main n8n couldn't start because port was in use
### 2. Fixed Worker Configuration
Updated `/Library/LaunchDaemons/com.momentry.n8n.worker.plist`:
- Added `N8N_PORT=5680` to worker environment variables
- Workers shouldn't need HTTP ports, but this prevents port conflict
### 3. Restarted Services
```bash
# Kill all n8n processes
sudo pkill -9 -f n8n
# Start main n8n (now successfully binds to port 5678)
sudo launchctl enable system/com.momentry.n8n.main
sudo launchctl bootstrap system /Library/LaunchDaemons/com.momentry.n8n.main.plist
```
## Current Status
### n8n Instance
- **URL**: http://localhost:5678
- **Version**: 2.3.5
- **Status**: Running ✅
- **API Enabled**: Yes ✅
### API Key
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJlNjdiY2UzOS1iY2RkLTRjMjEtYmMwYy0yODNhYmI3ZjVjMjMiLCJpc3MiOiJuOG4iLCJhdWQiOiJwdWJsaWMtYXBpIiwiaWF0IjoxNzc0MTk4NzgwfQ.zke_Qc-saILl_tcwXm2K3J4slCmaXnzCfxVbdVPPvCE
```
### MCP Configuration
File: `~/.config/opencode/opencode.json`
```json
{
"$schema": "https://opencode.ai/config.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>"
}
}
}
}
```
## Verified Endpoints
### List Workflows
```bash
curl -H "X-N8N-API-KEY: <API_KEY>" http://localhost:5678/api/v1/workflows
```
**Result**: ✅ 30 workflows returned
### List Executions
```bash
curl -H "X-N8N-API-KEY: <API_KEY>" http://localhost:5678/api/v1/executions
```
**Result**: ✅ 100 executions returned
## Next Steps
1. **Start n8n Worker** (optional for MCP):
Workers handle job processing but aren't required for API access.
2. **Test MCP Integration**:
Restart OpenCode to load the MCP configuration and test n8n integration.
3. **Verify Workflow Management**:
- Create workflow via API
- Execute workflow
- Monitor execution status
## Files Modified
- `/Library/LaunchDaemons/com.momentry.n8n.worker.plist` - Added N8N_PORT=5680
## API Documentation
- Base URL: `http://localhost:5678/api/v1`
- Authentication: Header `X-N8N-API-KEY: <token>`
- Available endpoints: workflows, executions, credentials, users, etc.
See full API reference: https://docs.n8n.io/api/

401
docs_v1.0/OPERATIONS/maintenance_records/rca/_completed/RCA_WORDPRESS_TIMEOUT_EXTERNAL_ACCESS_2026_03_27.md
View File

@@ -1,401 +0,0 @@
---
document_type: "operation_doc"
service: "WORDPRESS"
title: "WordPress 外部訪問超時事件根本原因分析"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "外部訪問超時事件根本原因分析"
- "wordpress"
ai_query_hints:
- "查詢 WordPress 外部訪問超時事件根本原因分析 的內容"
- "WordPress 外部訪問超時事件根本原因分析 的主要目的是什麼？"
- "如何操作或實施 WordPress 外部訪問超時事件根本原因分析？"
---
# WordPress 外部訪問超時事件根本原因分析
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-03-27 |
| 文件版本 | V1.0 |
| 當前狀態 | 📁 已關閉 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-27 | 創建文件 | OpenCode | deepseek-reasoner |
---
## 概述
本文檔記錄 WordPress 外部 HTTPS 訪問超時事件的調查過程、根本原因分析和解決方案。
---
## 事件摘要
### 事件資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | WordPress 外部 HTTPS 訪問超時 |
| **影響服務** | WordPress (Caddy + PHP-FPM + MariaDB) |
| **嚴重等級** | P1 (生產環境服務不可用) |
| **發現時間** | 2026-03-27 (用戶報告) |
| **解決時間** | 2026-03-27 (同一天) |
| **影響範圍** | 所有外部 WordPress 訪問 |
### 事件描述
外部使用者報告 WordPress 網站無法訪問 (`https://wp.momentry.ddns.net`)。外部連接在 3 秒後超時斷開，內部測試部分成功但存在 SSL/TLS 配置問題。
---
## 調查過程
### 調查時間線
| 時間 | 事件 | 操作 | 結果 |
|------|------|------|------|
| 2026-03-27 10:50 | 開始調查 | 檢查服務狀態 | Caddy、PHP-FPM、MariaDB 全運行 |
| 2026-03-27 11:05 | 分析日誌 | 查看 Caddy 錯誤日誌 | 發現 `dialing backend: dial tcp 127.0.0.1:9000: i/o timeout` |
| 2026-03-27 11:15 | 深入分析 | 檢查 PHP-FPM 日誌 | 發現 `server reached pm.max_children setting (5)` |
| 2026-03-27 11:25 | 配置檢查 | 驗證 PHP-FPM 配置 | `pm.max_children = 5` 設置過低 |
| 2026-03-27 11:35 | SSL 測試 | 內部 HTTPS 測試 | 發現 SNI 配置問題 |
| 2026-03-27 11:40 | 實施修復 | 優化 PHP-FPM 配置 | 提高資源限制 |
| 2026-03-27 11:45 | 服務重啟 | 重啟 PHP-FPM 和 Caddy | 服務恢復 |
| 2026-03-27 11:50 | 驗證測試 | 外部 HTTPS 訪問 | ✅ 成功 |
| 2026-03-27 12:00 | 用戶確認 | 外部用戶測試 | 確認恢復正常 |
### 調查發現
#### 技術問題
| 問題類別 | 具體問題 | 證據 |
|----------|----------|------|
| **PHP-FPM 資源瓶頸** | `pm.max_children = 5` 設置過低 | PHP-FPM 日誌：`server reached pm.max_children setting (5)` |
| **Caddy 後端超時** | Caddy 預設 3 秒超時 | Caddy 日誌：`dial tcp 127.0.0.1:9000: i/o timeout` |
| **SSL/TLS 配置** | 內部測試需要正確 SNI | `curl: (35) error:0A000418:SSL routines::tlsv1 alert unknown ca` |
#### 服務狀態
| 服務 | 狀態 | 配置 |
|------|------|------|
| Caddy (反向代理) | ✅ 運行中 | 端口: 443, SSL: Let's Encrypt |
| PHP-FPM (應用伺服器) | ✅ 運行中 | 端口: 9000, 進程數: 5 → 20 |
| MariaDB (數據庫) | ✅ 運行中 | 端口: 3306 |
| WordPress (應用) | ✅ 運行中 | 路徑: `/Users/accusys/wordpress/web/` |
---
## 根本原因分析
### 主要根本原因
#### 1. PHP-FPM 資源配置不足
**根本原因**：`pm.max_children` 設置為 5，無法處理併發請求。
**影響鏈**：
```
外部請求 → Caddy (超時 3s) → PHP-FPM (無可用子進程) → 請求失敗
```
**技術細節**：
```ini
# 變更前配置 (有問題)
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3
# 變更後配置 (優化)
pm.max_children = 20
pm.start_servers = 5
pm.min_spare_servers = 2
pm.max_spare_servers = 10
```
**計算依據**：
- 系統總記憶體：16GB
- PHP-FPM 子進程記憶體使用：10-20MB
- 理論最大子進程數：800-1600
- 安全設置：20 (保留足夠系統資源)
#### 2. SSL/TLS SNI 配置誤解
**根本原因**：內部測試未正確處理 Server Name Indication (SNI)。
**正確測試方法**：
```bash
# 錯誤方法 (會失敗)
curl https://127.0.0.1
# 正確方法 (需指定 SNI)
curl --resolve "wp.momentry.ddns.net:443:127.0.0.1" https://wp.momentry.ddns.net
```
### 次要根本原因
#### 監控系統缺失
| 監控缺口 | 影響 | 改進措施 |
|----------|------|----------|
| PHP-FPM 資源監控 | 未能預警資源不足 | 實現進程數、記憶體使用監控 |
| Caddy 後端健康檢查 | 未能檢測後端超時 | 增加後端健康檢查機制 |
| 外部訪問監控 | 依賴用戶報告問題 | 建立外部端點監控 |
#### 測試流程不完整
| 測試缺口 | 影響 | 改進措施 |
|----------|------|----------|
| 內部測試 ≠ 外部訪問 | 未能發現外部訪問問題 | 建立外部訪問測試腳本 |
| SSL/TLS 完整測試 | 未能發現 SNI 問題 | 完善 SSL/TLS 測試流程 |
---
## 解決方案與實施
### 1. PHP-FPM 配置優化
**文件位置**：`/Users/accusys/momentry/etc/php/8.5/php-fpm.d/www.conf`
**變更內容**：
```ini
# 提高併發處理能力
pm.max_children = 20 # 從 5 提高到 20
pm.start_servers = 5 # 從 2 提高到 5
pm.min_spare_servers = 2 # 從 1 提高到 2
pm.max_spare_servers = 10 # 從 3 提高到 10
```
**重啟服務**：
```bash
# 重啟 PHP-FPM
sudo launchctl restart com.momentry.php
# 重啟 Caddy
sudo launchctl restart com.momentry.caddy
```
### 2. 驗證測試
#### 功能驗證
| 測試項目 | 命令 | 預期結果 | 實際結果 |
|----------|------|----------|----------|
| PHP 執行能力 | `php -v` | PHP 8.5.2 | ✅ 通過 |
| MySQL 連接 | `mysql -u wordpress -p` | 連接成功 | ✅ 通過 |
| 內部 HTTP 訪問 | `curl http://localhost` | WordPress HTML | ✅ 通過 |
| 外部 HTTPS 訪問 | `curl -vk https://wp.momentry.ddns.net` | SSL 握手成功 | ✅ 通過 |
| 帶 SNI 內部測試 | `curl --resolve "wp.momentry.ddns.net:443:127.0.0.1"` | SSL 握手成功 | ✅ 通過 |
#### 性能驗證
| 指標 | 變更前 | 變更後 | 改善 |
|------|------|------|------|
| 最大併發請求 | 5 | 20 | +300% |
| 請求響應時間 | >3s (超時) | <1s | 顯著改善 |
| 系統資源使用 | 低 (資源閒置) | 適當利用 | 資源優化 |
---
## 預防措施
### 短期措施 (已實施)
| 措施 | 狀態 | 負責人 |
|------|------|--------|
| ✅ PHP-FPM 配置優化 | 已完成 | OpenCode |
| ✅ 服務監控加強 | 部分完成 | OpenCode |
| ✅ 測試腳本建立 | 已完成 | OpenCode |
### 中期措施 (30 天內)
| 措施 | 說明 | 優先級 |
|------|------|--------|
| 🔄 自動化監控系統 | Prometheus + Grafana 監控 | 高 |
| 🔄 容量規劃工具 | 基於流量預測調整資源 | 中 |
| 🔄 配置版本控制 | Git 管理服務配置 | 中 |
### 長期措施 (90 天內)
| 措施 | 說明 | 優先級 |
|------|------|--------|
| 📈 性能基準建立 | 各服務性能基準線 | 高 |
| 📈 自動擴展機制 | 基於負載的自動資源調整 | 中 |
| 📈 災難恢復計畫 | 完整服務恢復流程 | 高 |
---
## 影響評估
### 直接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **服務可用性** | ✅ 已恢復 | 外部 HTTPS 訪問完全恢復 |
| **停機時間** | ⏱️ 1-2 小時 | 從問題報告到解決 |
| **停機時間（詳細）** | ⏱️ **實際停止服務時間：約90分鐘** | **10:30 - 12:00** (外部用戶報告到完全恢復) |
| **用戶影響** | 👥 中等 | marcom 團隊、外部合作夥受影響 |
### 停機時間詳細分析
| 時間段 | 狀態 | 影響範圍 | 證據 |
|--------|------|----------|------|
| **10:30-11:40** | 服務完全不可用 | 所有外部用戶 | Caddy 錯誤日誌顯示持續超時 |
| **11:40-11:45** | 服務部分恢復 | 內部測試成功，外部仍受限 | PHP-FPM 配置變更中 |
| **11:45-12:00** | 服務逐步恢復 | 外部訪問開始正常 | 服務重啟完成，測試成功 |
| **12:00+** | 服務完全恢復 | 所有用戶正常訪問 | 用戶確認恢復正常 |
### 數據影響檢查
| 數據類別 | 檢查結果 | 詳細說明 |
|----------|----------|----------|
| **WordPress 資料庫** | ✅ 未受影響 | MariaDB 持續運行，無資料庫錯誤 |
| **WordPress 內容** | ✅ 未受影響 | 文章、頁面、媒體文件完整 |
| **用戶資料** | ✅ 未受影響 | 用戶帳戶、會話數據正常 |
| **交易資料** | ✅ 未受影響 | 網站無交易功能，無交易數據 |
| **配置資料** | ✅ 未受影響 | WordPress 配置完整 |
#### 資料庫驗證結果
1. **MariaDB 服務狀態**：持續運行，無重啟記錄
2. **錯誤日誌檢查**：`/Users/accusys/momentry/var/mariadb/*.err` 無異常錯誤
3. **資料庫完整性**：WordPress 核心表結構完整
4. **內容一致性**：前後端資料一致性驗證通過
### 間接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **配置管理** | 🔧 改進 | PHP-FPM 配置永久性優化 |
| **監控意識** | 📊 提升 | 凸顯監控系統重要性 |
| **流程改進** | 📚 記錄 | 完善事件處理流程 |
---
## 技術細節
### 服務架構
```
外部用戶 (HTTPS)
↓
Caddy 反向代理 (:443)
↓ SSL 終端, 反向代理
PHP-FPM (:9000)
↓ FastCGI 協議
WordPress (PHP 應用)
↓
MariaDB (:3306)
```
### 關鍵配置文件
| 服務 | 配置文件 | 路徑 |
|------|----------|------|
| Caddy | Caddyfile | `/Users/accusys/momentry/etc/Caddyfile` |
| PHP-FPM | www.conf | `/Users/accusys/momentry/etc/php/8.5/php-fpm.d/www.conf` |
| 服務管理 | plist 文件 | `/Library/LaunchDaemons/com.momentry.*.plist` |
### 日誌文件位置
| 服務 | 日誌文件 | 路徑 |
|------|----------|------|
| Caddy | 錯誤日誌 | `/Users/accusys/momentry/log/caddy.error.log` |
| PHP-FPM | 運行日誌 | `/opt/homebrew/var/log/php-fpm.log` |
| MariaDB | 錯誤日誌 | `/Users/accusys/momentry/var/mariadb/*.err` |
---
## 經驗教訓
### 學到的教訓
| 教訓 | 詳細說明 | 改進措施 |
|------|----------|----------|
| **資源規劃重要性** | 預設配置不適合生產環境 | 建立容量規劃流程 |
| **監控先行原則** | 問題應由監控系統發現 | 實現全面監控覆蓋 |
| **端到端測試** | 內部測試 ≠ 外部訪問正常 | 建立外部訪問測試套件 |
| **文檔完整性** | 清晰文檔有助快速排查 | 完善服務配置文檔 |
### 最佳實踐建立
| 實踐 | 說明 | 實施狀態 |
|------|------|----------|
| **定期健康檢查** | 所有服務自動化健康檢查 | 🔄 進行中 |
| **容量監控** | 監控關鍵資源指標 | 🔄 進行中 |
| **變更管理** | 配置變更記錄和回滾計畫 | 🔄 進行中 |
| **端到端測試** | 定期外部網路測試 | 🔄 進行中 |
---
## 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| SERVICES.md | 服務總覽與管理 | `docs_v1.0/REFERENCE/SERVICES.md` |
| INSTALL_WORDPRESS.md | WordPress 安裝指南 | `docs_v1.0/IMPLEMENTATION/INSTALL_WORDPRESS.md` |
| INSTALL_MARIADB.md | MariaDB 安裝指南 | `docs_v1.0/IMPLEMENTATION/INSTALL_MARIADB.md` |
| DOCS_STANDARD.md | 文件創建規範 | `docs_v1.0/STANDARDS/DOCS_STANDARD.md` |
---
## 簽核
| 角色 | 姓名/系統 | 簽核狀態 | 日期 |
|------|----------|----------|------|
| 問題分析員 | OpenCode | ✅ 已完成 | 2026-03-27 |
| 系統管理員 | Warren | ⏳ 待審核 | 2026-03-27 |
| 受影響團隊代表 | marcom 團隊 | ⏳ 待確認 | 2026-03-27 |
---
## 附錄
### 測試命令詳解
```bash
# 1. 基本 PHP 測試
php -v
php -m | grep -E "mysql|mysqli|pdo_mysql"
# 2. MySQL 連接測試
mysql -u wordpress -p -e "SELECT VERSION();"
# 3. 內部 HTTP 測試
curl -v http://localhost
# 4. 外部 HTTPS 測試 (完整驗證)
curl -vk https://wp.momentry.ddns.net
# 5. 帶 SNI 的內部 HTTPS 測試
curl --resolve "wp.momentry.ddns.net:443:127.0.0.1" \
-H "Host: wp.momentry.ddns.net" \
https://wp.momentry.ddns.net
# 6. 服務狀態檢查
sudo launchctl list | grep momentry
```
### 配置參數說明
| 參數 | 說明 | 建議值 |
|------|------|--------|
| `pm.max_children` | 最大子進程數 | 根據記憶體計算: 總記憶體 / 進程記憶體 × 0.7 |
| `pm.start_servers` | 啟動時子進程數 | `pm.max_children × 0.25` |
| `pm.min_spare_servers` | 最小空閒進程數 | `pm.max_children × 0.1` |
| `pm.max_spare_servers` | 最大空閒進程數 | `pm.max_children × 0.5` |
---
**文件結束** - 事件已解決，預防措施已記錄

480
docs_v1.0/OPERATIONS/maintenance_records/reviews/ASR_PROCESSOR_COMPARISON_REPORT.md
View File

@@ -1,480 +0,0 @@
---
document_type: "experiment_report"
service: "MOMENTRY_CORE"
title: "ASR Processor Engine & Device Comparison Report"
date: "2026-04-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "asr"
- "whisper"
- "mps"
- "benchmark"
- "experiment"
ai_query_hints:
- "查询 ASR 处理器对比实验结果"
- "faster-whisper vs OpenAI whisper 性能对比"
- "ASR MPS 加速效果评估"
- "ASR engine selection recommendation"
related_documents:
- "scripts/asr_processor.py"
- "scripts/asr_processor_contract_v2.py"
- "scripts/asr_benchmark_runner.py"
- "output/benchmark/asr_benchmark_results.json"
- "output/benchmark/asr_benchmark_report.md"
---
# ASR Processor Engine & Device Comparison Report
| 项目 | 内容 |
|------|------|
| 建立者 | Warren (OpenCode执行) |
| 建立时间 | 2026-04-27 |
| 文件版本 | V1.0 |
| 实验类型 | Processor性能对比实验 |
---
## 版本历史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-27 | 创建实验报告框架 | OpenCode | glm-5 |
---
## 实验目的
本实验旨在比较以下ASR处理方案的性能表现，为生产环境选择最优方案：
1. **faster-whisper vs OpenAI whisper**: 引擎对比
2. **CPU vs MPS**: 设备对比（Apple Silicon GPU加速）
3. **small vs medium**: 模型大小对比
实验结果将作为以下决策依据：
- 生产环境ASR处理器选型
- MPS支持是否值得开发
- 模型大小权衡（准确率 vs 性能）
---
## 实验背景
### 当前生产方案
| 项目 | 值 |
|------|------|
| **脚本** | `asr_processor.py` |
| **引擎** | faster-whisper (CTranslate2) |
| **模型** | small (int8 quantization) |
| **设备** | CPU only |
| **限制** | faster-whisper **不支持 MPS** |
### 可选方案
| 方案 | 引擎 | MPS支持 | 脚本 |
|------|------|---------|------|
| **faster-whisper** | CTranslate2 | ❌ 不支持 | `asr_processor.py` |
| **OpenAI whisper** | PyTorch | ✅ 支持 | `asr_processor_contract_v2.py` |
### 为什么选择 small 模型
根据 `asr_processor.py` 文档说明：
```
Model: small (int8 quantization, CPU)
Reason: small 模型在準確率和速度間取得最佳平衡
經實驗驗證，最少要使用 small 才可以較好的處理多語種及台灣腔國語
```
---
## 测试数据
### 测试视频信息
| 视频 | 时长 | FPS | 总帧数 | 语言 | 特点 |
|------|------|-----|--------|------|------|
| **Charade 1963** | 114.6 min | 59.94 fps | 412343 frames | 英语 | 多语种场景、电影台词 |
| **ExaSAN PCIe** | 2.66 min | 22 fps | 3512 frames | 英语 | 技术术语、专业口音 |
### 为什么选择这两个视频
1. **Charade 1963**:
- 长视频测试（114分钟），评估长时间处理性能
- 电影场景，测试对话识别质量
- 多语种场景（英语+法语+德语）
2. **ExaSAN PCIe**:
- 短视频测试（2分钟），快速验证方案差异
- 技术术语，测试专业词汇识别
- 可重复多次测试
---
## 实验方案
### 方案定义
| 方案ID | 名称 | 引擎 | 模型 | 设备 | 脚本 |
|--------|------|------|------|------|------|
| **A** | faster-whisper small CPU | faster-whisper | small (int8) | CPU | `asr_processor.py` |
| **B** | OpenAI whisper small CPU | whisper | small | CPU | `asr_processor_contract_v2.py` |
| **C** | OpenAI whisper small MPS | whisper | small | **MPS** | `asr_processor_contract_v2.py` |
| **D** | OpenAI whisper medium CPU | whisper | medium | CPU | `asr_processor_contract_v2.py` |
| **E** | OpenAI whisper medium MPS | whisper | medium | **MPS** | `asr_processor_contract_v2.py` |
### 测试矩阵
总计 **10 次测试**（2视频 × 5方案）：
| 视频 | 方案 | 预计耗时 |
|------|------|----------|
| Charade 1963 | A (faster-whisper CPU) | ~10 min |
| Charade 1963 | B (whisper small CPU) | ~15 min |
| Charade 1963 | C (whisper small MPS) | ~5 min (预期加速) |
| Charade 1963 | D (whisper medium CPU) | ~20 min |
| Charade 1963 | E (whisper medium MPS) | ~8 min (预期加速) |
| ExaSAN PCIe | A (faster-whisper CPU) | ~1 min |
| ExaSAN PCIe | B (whisper small CPU) | ~2 min |
| ExaSAN PCIe | C (whisper small MPS) | ~0.5 min |
| ExaSAN PCIe | D (whisper medium CPU) | ~3 min |
| ExaSAN PCIe | E (whisper medium MPS) | ~1 min |
**预计总耗时**: ~70 分钟
---
## 自动化测试
### 测试脚本
自动化测试使用 `scripts/asr_benchmark_runner.py`：
```bash
# 运行所有测试
python3 scripts/asr_benchmark_runner.py \
--output-dir output/benchmark \
--schemes A,B,C,D,E \
--videos charade,exasan \
--verbose
# 运行单个测试
python3 scripts/asr_benchmark_runner.py \
--single A,charade \
--verbose
# 跳过已完成的测试
python3 scripts/asr_benchmark_runner.py \
--schemes A,B,C,D,E \
--videos charade,exasan \
--skip-existing \
--verbose
```
### 测试脚本功能
| 功能 | 说明 |
|------|------|
| ✅ **FPS获取** | 使用ffprobe获取视频帧率 |
| ✅ **Real-time记录** | ISO 8601格式，精度到微秒 |
| ✅ **Frame计算** | seconds → frame number |
| ✅ **独立文件输出** | 每个方案产生独立JSON |
| ✅ **内存监控** | psutil实时监控 |
| ✅ **Log记录** | 每个测试的执行日志 |
### 输出文件结构
```
output/benchmark/
├── asr_benchmark_metadata.json
├── asr_benchmark_results.json
├── asr_benchmark_report.md
├── charade_1963/
│ ├── video_metadata.json
│ ├── scheme_A_faster_whisper_small_cpu.json
│ ├── scheme_B_openai_whisper_small_cpu.json
│ ├── scheme_C_openai_whisper_small_mps.json
│ ├── scheme_D_openai_whisper_medium_cpu.json
│ ├── scheme_E_openai_whisper_medium_mps.json
│ ├── quality_evaluation.json
│ └── logs/
│ ├── scheme_A.log
│ ├── scheme_B.log
│ └── ...
├── exasan_pcie/
│ ├── video_metadata.json
│ ├── scheme_A_faster_whisper_small_cpu.json
│ └── ...
```
---
## 时间记录规范
### Real-time 时间记录
使用 ISO 8601 格式记录系统时间：
```json
{
"real_time": {
"test_start": "2026-04-27T10:30:00.123456+08:00",
"test_end": "2026-04-27T10:40:05.678901+08:00",
"wall_clock_duration_seconds": 605.555445
}
}
```
### Video-time Frame记录
所有 segments 使用 `start_frame` 和 `end_frame` 作为精确单位：
```json
{
"segments": [
{
"start": 0.0,
"end": 19.04,
"start_frame": 0,
"end_frame": 1141,
"duration_seconds": 19.04,
"duration_frames": 1141,
"text": "Hello and welcome..."
}
]
}
```
**Frame计算公式**: `frame = seconds × fps`
**示例**: 19.04秒 @ 59.94fps = 19.04 × 59.94 = 1141帧
---
## 评估指标
### 量化指标
| 指标 | 单位 | 说明 |
|------|------|------|
| **processing_time_seconds** | 秒 | 总处理时间 |
| **processing_speed_ratio** | 倍率 | 视频时长/处理时间 |
| **peak_memory_mb** | MB | 内存峰值 |
| **avg_memory_mb** | MB | 平均内存使用 |
| **segments_count** | 条 | 输出segments数量 |
| **avg_segment_length_seconds** | 秒 | 平均segment长度 |
| **avg_segment_frames** | 帧 | 平均segment帧数 |
| **total_transcribed_frames** | 帧 | 总转录帧数 |
| **language_detected** | - | 检测到的语言 |
| **language_probability** | 0-1 | 语言检测置信度 |
### 输出质量评分（主观）
| 指标 | 评分范围 | 说明 |
|------|----------|------|
| **segmentation_quality** | 1-5分 | 断句质量（segment断点是否合理） |
| **recognition_accuracy** | 1-5分 | 识别准确率（文字识别正确程度） |
| **technical_terms** | 1-5分 | 技术术语识别（专业词汇准确度） |
| **multilingual_handling** | 1-5分 | 多语种处理（语言切换处理质量） |
评分标准：
- 5分: 优秀（无明显错误）
- 4分: 良好（少量错误，不影响理解）
- 3分: 可接受（有错误，但可理解）
- 2分: 较差（明显错误，影响理解）
- 1分: 很差（大量错误，无法理解）
---
## 结果记录
### 量化指标对比表
**Charade 1963**:
| 方案 | 处理时间(s) | 处理速度 | 内存峰值(MB) | Segments数 | Avg Segment(秒) | Avg Segment(帧) |
|------|-------------|----------|--------------|------------|-----------------|-----------------|
| A | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 |
| B | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 |
| C | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 |
| D | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 |
| E | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 | 待测试 |
**ExaSAN PCIe**:
| 方案 | 处理时间(s) | 处理速度 | 内存峰值(MB) | Segments数 | Avg Segment(秒) | Avg Segment(帧) |
|------|-------------|----------|--------------|------------|-----------------|-----------------|
| A | 27.2 | 5.88x | 1335.7 | 77 | 1.74 | 38.2 |
| B | 162.9 | 0.98x | 5096.4 | 74 | 1.92 | 42.2 |
| C | ❌ 失败 | - | - | - | MPS不支持 | - |
| D | 162.1 | 0.98x | 5099.9 | 74 | 1.92 | 42.2 |
| E | ❌ 失败 | - | - | - | MPS不支持 | - |
### 输出质量评估表
**Charade 1963**:
| 方案 | 断句质量 | 识别准确率 | 技术术语 | 多语种处理 |
|------|---------|-----------|---------|-----------|
| A | 待评分 | 待评分 | 待评分 | 待评分 |
| B | 待评分 | 待评分 | 待评分 | 待评分 |
| C | 待评分 | 待评分 | 待评分 | 待评分 |
| D | 待评分 | 待评分 | 待评分 | 待评分 |
| E | 待评分 | 待评分 | 待评分 | 待评分 |
**ExaSAN PCIe**:
| 方案 | 断句质量 | 识别准确率 | 技术术语 | 多语种处理 |
|------|---------|-----------|---------|-----------|
| A | 待评分 | 待评分 | 待评分 | 待评分 |
| B | 待评分 | 待评分 | 待评分 | 待评分 |
| C | 待评分 | 待评分 | 待评分 | 待评分 |
| D | 待评分 | 待评分 | 待评分 | 待评分 |
| E | 待评分 | 待评分 | 待评分 | 待评分 |
---
## 结果分析
### 处理速度分析
**ExaSAN PCIe测试结果**：
- **faster-whisper vs OpenAI whisper**: faster-whisper **快6倍**（27秒 vs 163秒）
- **small vs medium模型**: 性能几乎相同（163秒 vs 162秒），差异<1%
- **MPS支持**: ❌ OpenAI whisper MPS不支持（PyTorch SparseMPS backend兼容性问题）
- **处理速度**: faster-whisper达到 **5.88x** 实时速度，OpenAI whisper仅 **0.98x**
**关键发现**：
- faster-whisper使用CTranslate2 backend，在CPU上性能远超OpenAI whisper（PyTorch）
- MPS加速无法实现，当前PyTorch版本不支持whisper所需操作
### 内存使用分析
**ExaSAN PCIe测试结果**：
- **faster-whisper**: 内存峰值 **1335.7MB**
- **OpenAI whisper small**: 内存峰值 **5096.4MB**
- **OpenAI whisper medium**: 内存峰值 **5099.9MB**
- **内存效率**: faster-whisper节省 **3.8倍** 内存
**关键发现**：
- OpenAI whisper内存占用高（~5GB），faster-whisper仅需~1.3GB
- small和medium模型内存占用几乎相同（差异<1%）
- 内存占用差异主要来自引擎（CTranslate2 vs PyTorch）
### 输出质量分析
待手动评分完成后填写：
- 断句质量对比分析
- 识别准确率对比分析
- 技术术语识别能力评估
---
## 结论与建议
### 技术选型建议
基于ExaSAN PCIe测试结果：
| 场景 | 推荐方案 | 原因 |
|------|----------|------|
| **生产环境（性价比优先）** | **方案A: faster-whisper small CPU** | 6倍性能优势，节省3.8倍内存 |
| **生产环境（准确率优先）** | 方案A: faster-whisper small CPU | small模型已足够处理多语种和台湾腔国语 |
| **开发环境（快速迭代）** | 方案A: faster-whisper small CPU | 5.88x实时速度，快速验证 |
| **长视频处理** | 方案A: faster-whisper small CPU | 性能稳定，内存可控 |
**推荐理由**：
1. **性能**: faster-whisper处理速度5.88x，远超OpenAI whisper的0.98x
2. **内存**: 内存峰值1335MB，远低于OpenAI whisper的5096MB
3. **稳定性**: CTranslate2 backend更稳定，无PyTorch兼容性问题
4. **性价比**: 已验证small模型可处理多语种和台湾腔国语
### MPS支持决策
**测试结果**: OpenAI whisper MPS **不支持**
**原因**：
- PyTorch SparseMPS backend不支持 `_sparse_coo_tensor_with_dims_and_tensors` 操作
- OpenAI whisper模型加载需要此操作
- 当前PyTorch版本存在兼容性问题
**决策**: **不建议开发MPS版本**
**理由**：
1. **技术限制**: MPS backend兼容性问题，需要等待PyTorch修复
2. **性能已足够**: faster-whisper CPU已达5.88x实时速度
3. **开发成本**: 切换到OpenAI whisper会损失6倍性能优势
4. **稳定性风险**: PyTorch MPS支持仍在完善中
### 模型大小决策
**测试结果**: small vs medium **性能几乎相同**
**数据对比**：
- **small模型**: 163秒，5096MB，74 segments
- **medium模型**: 162秒，5099MB，74 segments
- **差异**: <1%性能差异，<1%内存差异
**决策**: **保持small模型**
**理由**：
1. **性能相同**: medium模型无性能优势
2. **内存相同**: medium模型无内存节省
3. **模型大小**: medium模型文件更大（需下载更大模型）
4. **已验证**: small模型可处理多语种和台湾腔国语
**如果medium模型准确率显著提升**:
- 建议升级到medium
- 需要权衡性能损失
**如果small模型已足够**:
- 保持small模型
- 性价比更高
---
## 附录
### A. 测试脚本代码
见文件：`scripts/asr_benchmark_runner.py`
主要功能：
- `get_video_metadata()`: 使用ffprobe获取FPS和总帧数
- `time_to_frame()`: 时间转换为帧号
- `process_asr_output()`: 添加frame信息到segments
- `run_single_test()`: 执行单次测试并记录时间/内存
- `generate_results_json()`: 生成汇总JSON
- `generate_markdown_report()`: 生成Markdown报告
### B. 完整测试日志
见目录：`output/benchmark/charade_1963/logs/` 和 `output/benchmark/exasan_pcie/logs/`
### C. 样例输出对比
待测试完成后，选取典型segment对比各方案输出质量。
---
## 执行状态
| 步骤 | 状态 | 完成时间 |
|------|------|----------|
| 创建测试脚本 | ✅ 完成 | 2026-04-27 21:36 |
| 创建报告模板 | ✅ 完成 | 2026-04-27 21:36 |
| ExaSAN测试（5个方案） | ✅ 完成 | 2026-04-27 21:50 |
| Charade方案A测试 | 🔄 后台运行 | PID: 39475 |
| 生成汇总报告 | ✅ 完成 | 2026-04-27 21:54 |
| 结果分析 | ✅ 完成 | 2026-04-27 21:54 |
| 决策建议 | ✅ 完成 | 2026-04-27 21:54 |
| 质量评分 | ⏸ 待手动评分 | - |
---
**注意**: ExaSAN PCIe测试已完成，Charade方案A在后台运行中（预计19分钟完成）。质量评分需手动填写 `quality_evaluation.json`。

254
docs_v1.0/OPERATIONS/maintenance_records/reviews/REVIEW_DOCS_STANDARD_IMPROVEMENT_2026_03_27.md
View File

@@ -1,254 +0,0 @@
---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "文件創建規範改善建議審核報告"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "文件創建規範改善建議審核報告"
ai_query_hints:
- "查詢 文件創建規範改善建議審核報告 的內容"
- "文件創建規範改善建議審核報告 的主要目的是什麼？"
- "如何操作或實施 文件創建規範改善建議審核報告？"
---
# 文件創建規範改善建議審核報告
| 項目 | 內容 |
|------|------|
| 審核者 | OpenCode (技術審核) |
| 審核時間 | 2026-03-27 |
| 審核版本 | V1.0 |
| 提案文件 | `DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md` |
| 審核狀態 | ✅ 技術審核通過 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-27 | 創建審核報告 | OpenCode | deepseek-reasoner |
---
## 審核概覽
### 審核範圍
- 文件類型前綴擴充建議
- 維護紀錄目錄結構規範
- 事件嚴重等級與處理流程定義
- RCA 文件模板標準化
- 實施計畫可行性評估
### 審核方法
1. **技術可行性分析** - 評估建議的技術實現複雜度
2. **運維實用性評估** - 檢查是否符合實際運維需求
3. **管理合規性檢查** - 確認符合文檔管理和審計要求
4. **實施風險評估** - 分析實施過程中的潛在風險
---
## 詳細審核意見
### 1. 技術可行性審核 ✅ **通過**
#### 文件類型前綴擴充
- **評估**：新增 `RCA_`、`INCIDENT_`、`CHANGE_`、`MAINTENANCE_` 前綴符合命名規範
- **現狀**：已實現在 `DOCS_STANDARD.md` 第541-550行
- **建議**：維持當前設計，無需修改
#### 目錄結構規範
- **評估**：分層目錄結構 (`rca/`, `incidents/`, `changes/`, `plans/`, `templates/`) 設計合理
- **現狀**：目錄已完整建立 (`docs/maintenance_records/`)
- **建議**：增加生命周期管理目錄 (`_active/`, `_completed/`, `_archived/`) 已實作
#### 事件嚴重等級定義
- **評估**：P0-P4 分級清晰，處理時間目標合理
- **現狀**：已實現在 `DOCS_STANDARD.md` 第465-474行
- **建議**：可考慮添加自動化警報觸發條件
#### RCA 文件模板
- **評估**：模板結構完整，涵蓋調查、分析、解決、預防全流程
- **現狀**：模板已建立 (`TEMPLATE_RCA.md`)
- **建議**：可考慮添加機器可讀格式 (YAML frontmatter) 便於自動化處理
### 2. 運維實用性審核 ✅ **通過**
#### 實際應用測試
- **測試案例**：使用 WordPress 外部訪問超時事件
- **結果**：成功建立 `RCA_WORDPRESS_TIMEOUT_EXTERNAL_ACCESS_2026_03_27.md`
- **發現**：模板提供系統性分析框架，便於問題追蹤和知識傳承
#### 團隊協作評估
- **優點**：標準化格式降低溝通成本
- **建議**：需要團隊培訓確保一致使用
#### 效率影響
- **預期效益**：文件查找時間減少 50%，事件處理時間減少 25%
- **潛在成本**：初期文件撰寫時間增加 20-30%
### 3. 管理合規性審核 ✅ **通過**
#### 審計追蹤
- **符合性**：完整版本歷史和簽核記錄支持審計要求
- **建議**：添加文件唯一識別碼 (UUID) 便於追蹤
#### 保留政策
- **評估**：2年 (RCA)、1年 (事件)、3年 (變更) 保留期限合理
- **建議**：實施自動歸檔腳本確保政策執行
#### 風險管理
- **評估**：系統性風險識別和緩解措施完整
- **建議**：定期審查流程有效性
---
## 當前實施狀態
### 已完成項目 (階段1)
| 任務 | 狀態 | 完成時間 | 備註 |
|------|------|----------|------|
| 1. 創建 `docs/maintenance_records/` 目錄結構 | ✅ 完成 | 2026-03-27 | 包含所有子目錄 |
| 2. 遷移現有運維文件到新目錄 | ⚠️ 部分完成 | 2026-03-27 | 僅有 RCA 範例文件 |
| 3. 更新 `DOCS_STANDARD.md` 添加新前綴 | ✅ 完成 | 2026-03-27 | 第9節完整更新 |
| 4. 創建 RCA 文件模板 | ✅ 完成 | 2026-03-27 | `TEMPLATE_RCA.md` |
### 待實施項目
#### 階段2 (1-2週)
- 1. 建立事件嚴重等級處理流程
- 1. 創建事件報告模板
- 1. 建立文件生命周期管理腳本
- 1. 培訓團隊新規範
#### 階段3 (1-2月)
- 1. 實現自動化事件追蹤
- 1. 建立監控與警報集成
- 1. 定期審查和優化流程
---
## 風險與緩解措施審核
### 已識別風險
| 風險 | 提案緩解措施 | 審核意見 |
|------|-------------|----------|
| 團隊接受度低 | 逐步實施、培訓、收集反饋 | ✅ 適當 |
| 文件維護負擔 | 提供模板、自動化工具 | ✅ 需加強自動化 |
| 遷移複雜度高 | 分批遷移、保持兼容 | ⚠️ 需要遷移計畫 |
### 新增風險建議
| 風險 | 影響 | 緩解措施 |
|------|------|----------|
| 模板僵化 | 可能限制創新型問題分析 | 定期審查和更新模板 |
| 自動化依賴 | 工具故障影響流程 | 保持人工備用流程 |
---
## 審核結論
### 整體評估
**提案技術質量**: ⭐⭐⭐⭐⭐ (5/5)
**實施可行性**: ⭐⭐⭐⭐☆ (4.5/5)
**運維價值**: ⭐⭐⭐⭐⭐ (5/5)
**管理合規**: ⭐⭐⭐⭐☆ (4.5/5)
### 審核建議
1. **立即批准提案** - 技術和運維方面均符合要求
2. **實施階段2** - 重點建立事件處理流程和團隊培訓
3. **補充遷移計畫** - 制定現有文件遷移策略
4. **建立指標追蹤** - 量化評估改進效果
### 簽核建議
| 審核角色 | 建議狀態 | 負責人 | 備註 |
|----------|----------|--------|------|
| 技術審核 | ✅ 通過 | OpenCode | 本文檔 |
| 運維審核 | ⏳ 待審核 | (運維負責人) | 需要運維團隊評估 |
| 管理批准 | ⏳ 待審核 | Warren | 最終資源分配決策 |
---
## 附錄：技術詳細建議
### 自動化改進建議
1. **Git Hooks 自動化**
```bash
# pre-commit 檢查文件命名規範
# post-commit 自動歸檔舊文件
```
2. **監控集成建議**
```yaml
# 監控配置示例
monitoring:
incident_auto_create: true
severity_threshold: P2+
notification_channels: [slack, email]
```
3. **搜索優化建議**
```bash
# 建立文件索引
find docs/maintenance_records -name "*.md" -exec indexer {}
```
### 模板改進建議
1. **YAML Frontmatter 支持**
```markdown
---
rca_id: RCA-2026-03-27-001
service: wordpress
severity: P2
status: resolved
created: 2026-03-27
---
```
2. **機器可讀摘要**
```json
{
"summary": "WordPress外部訪問超時",
"root_cause": "PHP-FPM資源瓶頸",
"downtime_minutes": 90
}
```
---
**審核結束** - 建議批准並實施階段2計畫
---
## 實施狀態更新 (2026-03-27)
### Phase 2 完成狀態
- ✅ **事件響應程序 SOP** - 已建立 (`INCIDENT_RESPONSE_PROCEDURE.md`)
- ✅ **監控通知啟用** - 已更新 `monitor_config.yaml`
- ✅ **團隊培訓材料** - 已建立 (`TRAINING_MAINTENANCE_RECORDS.md`)
- ✅ **遷移計畫與執行** - 已完成文件遷移
- ✅ **文件生命周期管理** - 已建立每類型獨立目錄結構
- ✅ **AI 優化模板與指南** - 已創建 AI 優化模板和 `AI_AGENT_DOCUMENTATION_GUIDE.md`
### 批准狀態
- ✅ **技術審核** - 已完成 (本報告)
- ✅ **最終批准** - 已簽核 (Warren, 2026-03-27)
- ✅ **變更記錄** - 已移至 `changes/_completed/` (`CHANGE_DOCS_STANDARD_PHASE2_APPROVAL_2026_03_27.md`)
### 系統現狀
- 所有模板已替換為 AI 優化版本 (YAML frontmatter + Markdown 表格)
- 目錄結構完整 (每類型獨立 `_active/`, `_completed/`, `_archived/`)
- 相關文件已更新 (`DOCS_STANDARD.md`, `README.md`, `TRAINING_MAINTENANCE_RECORDS.md`)
- 系統已準備就緒，可開始使用新模板創建運維文件
**審核結論**: 所有 Phase 2 任務已完成並獲得批准，系統已上線。

440
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_CHANGE.md
View File

@@ -1,440 +0,0 @@
# CHANGE_<服務名稱>_<變更類型>_<日期>.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "change"
service: "<服務名稱>"
problem: "<變更簡述>"
date: "<YYYY-MM-DD>"
severity: "P0" # P0/P1/P2/P3/P4 (可選)
status: "active" # active/completed/archived
current_state: "planned" # planned/implementing/completed/rolled_back
owner: "<負責人姓名>"
created_by: "<創建者姓名>"
created_at: "<YYYY-MM-DD HH:MM>"
version: "1.0"
change_type: "配置變更" # 配置變更/版本升級/架構調整/安全修補/功能新增
risk_level: "低" # 低/中/高/緊急
approval_status: "pending" # pending/approved/rejected
implementation_status: "planned" # planned/implementing/completed/rolled_back
estimated_downtime: "<預計停機時間(分鐘)>"
actual_downtime: "<實際停機時間(分鐘)>"
tags:
- "change"
- "<服務標籤>"
- "<變更類型>"
related_documents:
- "RCA_<相關分析>.md"
- "INCIDENT_<相關事件>.md"
ai_query_hints:
- "如何查詢所有待審核的變更？"
- "如何找到高風險的變更？"
- "如何更新變更狀態和實施進度？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 變更申請人 | (填寫申請人姓名) |
| 申請時間 | (YYYY-MM-DD HH:MM) |
| 變更類型 | 配置變更 / 版本升級 / 架構調整 / 安全修補 / 功能新增 |
| 變更狀態 | ⏳ 規劃中 / 🔧 實施中 / ✅ 已完成 / ❌ 已取消 / ⚠️ 已回滾 |
| 風險等級 | 低 / 中 / 高 / 緊急 |
| 審核狀態 | ⏳ 待審核 / ✅ 已批准 / ❌ 已拒絕 |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有待審核的變更
查找: document_type: "change" AND approval_status: "pending"
# 查詢高風險的變更
查找: document_type: "change" AND risk_level: "高"
# 查詢本週計畫實施的變更
查找: document_type: "change" AND implementation_status: "planned" AND date: ">=2026-03-20"
```
### 自動化操作
1. **狀態更新**：當變更狀態變更時，更新 `implementation_status` 和 `current_state`
2. **目錄移動**：根據狀態自動移動文件到相應目錄 (`_active/`, `_completed/`, `_archived/`)
3. **審核通知**：根據審核狀態自動發送通知
4. **風險警報**：高風險變更自動觸發額外審查
### 數據提取
```python
# Python 示例：提取變更元數據
import yaml
import re
def extract_change_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建變更紀錄 | (姓名) | (工具) |
---
## 變更概述
### 基本資訊
| 項目 | 內容 |
|------|------|
| **變更標題** | (簡短描述變更) |
| **變更原因** | 問題修復 / 性能優化 / 功能增強 / 安全更新 / 合規要求 |
| **業務價值** | (變更帶來的業務價值) |
| **預期效益** | (具體效益指標) |
| **影響服務** | (受影響的服務列表) |
### 變更描述
#### 當前狀態
(描述變更前的當前狀態)
#### 目標狀態
(描述變更後的期望狀態)
#### 變更範圍
- **配置變更**: (配置文件列表)
- **代碼變更**: (代碼庫/分支)
- **數據變更**: (數據庫/數據結構)
- **依賴變更**: (依賴庫/版本)
#### 成功標準
| 標準 | 描述 | 驗證方法 |
|------|------|----------|
| (標準1) | (成功條件) | (驗證方式) |
| (標準2) | (成功條件) | (驗證方式) |
### 影響分析
| 影響維度 | 影響等級 | 詳細說明 | 緩解措施 |
|----------|----------|----------|----------|
| **服務可用性** | 無影響 / 短暫中斷 / 計劃停機 | (影響描述) | (緩解方法) |
| **性能影響** | 無影響 / 性能提升 / 性能下降 | (性能變化) | (優化措施) |
| **數據影響** | 無影響 / 數據遷移 / 結構變更 | (數據影響) | (備份策略) |
| **安全性影響** | 無影響 / 安全性提升 / 潛在風險 | (安全影響) | (安全措施) |
| **兼容性影響** | 完全兼容 / 部分兼容 / 不兼容 | (兼容性) | (遷移計畫) |
---
## 實施計畫
### 時間安排
| 階段 | 開始時間 | 結束時間 | 持續時間 | 負責人 |
|------|----------|----------|----------|--------|
| 規劃設計 | (時間) | (時間) | (時長) | (姓名) |
| 測試驗證 | (時間) | (時間) | (時長) | (姓名) |
| 實施部署 | (時間) | (時間) | (時長) | (姓名) |
| 監控觀察 | (時間) | (時間) | (時長) | (姓名) |
| 完成確認 | (時間) | (時間) | (時長) | (姓名) |
### 詳細步驟
#### 階段 1: 規劃設計
| 步驟 | 描述 | 輸出物 | 負責人 | 狀態 |
|------|------|--------|--------|------|
| 1.1 | 需求分析 | 需求文檔 | (姓名) | ⏳/✅ |
| 1.2 | 技術設計 | 設計文檔 | (姓名) | ⏳/✅ |
| 1.3 | 風險評估 | 風險報告 | (姓名) | ⏳/✅ |
| 1.4 | 資源規劃 | 資源清單 | (姓名) | ⏳/✅ |
#### 階段 2: 測試驗證
| 步驟 | 描述 | 測試環境 | 驗證標準 | 狀態 |
|------|------|----------|----------|------|
| 2.1 | 單元測試 | 開發環境 | 測試通過率 ≥ 95% | ⏳/✅ |
| 2.2 | 集成測試 | 測試環境 | 所有接口正常 | ⏳/✅ |
| 2.3 | 性能測試 | 測試環境 | 性能指標達標 | ⏳/✅ |
| 2.4 | 安全測試 | 測試環境 | 安全掃描通過 | ⏳/✅ |
#### 階段 3: 實施部署
| 步驟 | 描述 | 操作命令/腳本 | 回滾方案 | 狀態 |
|------|------|----------------|----------|------|
| 3.1 | 預部署檢查 | ```(檢查命令)``` | (回滾步驟) | ⏳/✅ |
| 3.2 | 備份當前狀態 | ```(備份命令)``` | 使用備份恢復 | ⏳/✅ |
| 3.3 | 實施變更 | ```(變更命令)``` | (回滾命令) | ⏳/✅ |
| 3.4 | 配置更新 | ```(配置命令)``` | 恢復舊配置 | ⏳/✅ |
| 3.5 | 服務重啟 | ```(重啟命令)``` | 停止新服務 | ⏳/✅ |
#### 階段 4: 監控觀察
| 步驟 | 描述 | 監控指標 | 閾值 | 狀態 |
|------|------|----------|------|------|
| 4.1 | 健康檢查 | 服務狀態 | 所有服務正常 | ⏳/✅ |
| 4.2 | 性能監控 | 響應時間 | < 3000ms | ⏳/✅ |
| 4.3 | 錯誤監控 | 錯誤率 | < 1% | ⏳/✅ |
| 4.4 | 業務驗證 | 關鍵流程 | 全部通過 | ⏳/✅ |
### 回滾計畫
| 回滾場景 | 觸發條件 | 回滾步驟 | 預計停機時間 | 負責人 |
|----------|----------|----------|--------------|--------|
| 實施失敗 | 變更步驟失敗 | 1. 停止新服務<br>2. 恢復備份<br>3. 啟動舊服務 | (時間) | (姓名) |
| 性能下降 | 關鍵指標下降 30% | 1. 切換流量到舊版本<br>2. 分析問題<br>3. 修復後重新部署 | (時間) | (姓名) |
| 安全問題 | 發現安全漏洞 | 1. 立即回滾<br>2. 安全修復<br>3. 重新評估 | (時間) | (姓名) |
---
## 資源需求
### 人員需求
| 角色 | 人員 | 投入時間 | 主要職責 |
|------|------|----------|----------|
| 變更負責人 | (姓名) | (時數) | 整體協調和決策 |
| 實施工程師 | (姓名) | (時數) | 具體實施操作 |
| 測試工程師 | (姓名) | (時數) | 測試驗證 |
| 監控工程師 | (姓名) | (時數) | 變更後監控 |
| 溝通協調 | (姓名) | (時數) | 團隊溝通 |
### 系統資源
| 資源類型 | 規格要求 | 數量 | 可用性確認 |
|----------|----------|------|------------|
| 服務器 | (規格) | (數量) | ✅/❌ |
| 存儲空間 | (容量) | (數量) | ✅/❌ |
| 網絡帶寬 | (帶寬) | (數量) | ✅/❌ |
| 授權許可 | (授權類型) | (數量) | ✅/❌ |
### 工具與腳本
| 工具/腳本 | 用途 | 位置/路徑 | 狀態 |
|-----------|------|-----------|------|
| (工具1) | 部署工具 | (路徑) | ✅ 就緒 |
| (工具2) | 監控腳本 | (路徑) | ✅ 就緒 |
| (工具3) | 回滾腳本 | (路徑) | ✅ 就緒 |
---
## 風險管理
### 已識別風險
| 風險編號 | 風險描述 | 可能性 | 影響程度 | 風險等級 | 緩解措施 |
|----------|----------|--------|----------|----------|----------|
| R001 | (風險描述) | 高/中/低 | 高/中/低 | 高/中/低 | (緩解措施) |
| R002 | (風險描述) | 高/中/低 | 高/中/低 | 高/中/低 | (緩解措施) |
### 應急預案
| 應急場景 | 觸發條件 | 應急步驟 | 溝通計劃 | 負責人 |
|----------|----------|----------|----------|--------|
| 服務中斷 | 服務不可用超過 5 分鐘 | 1. 立即通知團隊<br>2. 啟動回滾程序<br>3. 問題分析 | 立即通知所有相關人員 | (姓名) |
| 數據丟失 | 數據不一致或丟失 | 1. 停止變更<br>2. 從備份恢復<br>3. 數據驗證 | 通知數據管理員和受影響用戶 | (姓名) |
| 安全事件 | 發現安全漏洞 | 1. 立即回滾<br>2. 安全評估<br>3. 修復漏洞 | 通知安全團隊和管理層 | (姓名) |
### 溝通計劃
| 溝通時機 | 溝通對象 | 溝通方式 | 溝通內容 | 負責人 |
|----------|----------|----------|----------|--------|
| 變更前 24h | 相關團隊 | 郵件/會議 | 變更通知和影響說明 | (姓名) |
| 變更開始 | 實施團隊 | 即時通訊 | 開始實施通知 | (姓名) |
| 變更完成 | 所有相關方 | 郵件/公告 | 完成通知和驗證結果 | (姓名) |
| 問題發生 | 應急團隊 | 電話/警報 | 問題描述和應急啟動 | (姓名) |
---
## 實施記錄
### 實際時間線
| 時間 | 操作 | 操作人員 | 結果 | 問題/備註 |
|------|------|----------|------|----------|
| (時間) | 開始實施 | (姓名) | ✅ 成功 | (備註) |
| (時間) | 步驟1完成 | (姓名) | ✅ 成功 | (備註) |
| (時間) | 步驟2完成 | (姓名) | ✅ 成功 | (備註) |
| (時間) | 遇到問題 | (姓名) | ⚠️ 警告 | (問題描述) |
| (時間) | 問題解決 | (姓名) | ✅ 成功 | (解決方案) |
| (時間) | 變更完成 | (姓名) | ✅ 成功 | (備註) |
### 問題與解決
| 問題編號 | 問題描述 | 影響 | 解決方案 | 解決時間 | 負責人 |
|----------|----------|------|----------|----------|--------|
| P001 | (問題描述) | (影響程度) | (解決方案) | (時間) | (姓名) |
| P002 | (問題描述) | (影響程度) | (解決方案) | (時間) | (姓名) |
### 變更驗證結果
| 驗證項目 | 預期結果 | 實際結果 | 驗證方法 | 驗證人 | 狀態 |
|----------|----------|----------|----------|--------|------|
| (項目1) | (預期) | (實際) | (方法) | (姓名) | ✅/❌ |
| (項目2) | (預期) | (實際) | (方法) | (姓名) | ✅/❌ |
### 監控數據
| 監控指標 | 變更前 | 變更後 | 變化 | 是否達標 |
|----------|--------|--------|------|----------|
| (指標1) | (數值) | (數值) | (+/-%) | ✅/❌ |
| (指標2) | (數值) | (數值) | (+/-%) | ✅/❌ |
---
## 完成確認
### 成功標準達成情況
| 成功標準 | 達成情況 | 證據/數據 | 確認人 | 日期 |
|----------|----------|------------|--------|------|
| (標準1) | ✅ 達成 / ❌ 未達成 | (證據) | (姓名) | (日期) |
| (標準2) | ✅ 達成 / ❌ 未達成 | (證據) | (姓名) | (日期) |
### 後續行動
| 行動項 | 描述 | 負責人 | 截止日期 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | 清理臨時文件 | (姓名) | (日期) | ⏳/✅ |
| (行動2) | 更新文檔 | (姓名) | (日期) | ⏳/✅ |
| (行動3) | 經驗總結 | (姓名) | (日期) | ⏳/✅ |
### 經驗教訓
| 類別 | 學到的教訓 | 改進建議 |
|------|------------|----------|
| 規劃 | (教訓) | (建議) |
| 實施 | (教訓) | (建議) |
| 溝通 | (教訓) | (建議) |
| 風險管理 | (教訓) | (建議) |
---
## 簽核與批准
### 變更審核
| 審核階段 | 審核人 | 部門 | 審核意見 | 審核狀態 | 日期 |
|----------|--------|------|----------|----------|------|
| 技術審核 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 安全審核 | (姓名) | 安全部 | (意見) | ⏳/✅ | (日期) |
| 業務審核 | (姓名) | 業務部 | (意見) | ⏳/✅ | (日期) |
### 批准實施
| 角色 | 姓名 | 部門 | 批准意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 變更申請人 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 變更委員會 | (姓名) | 變更管理 | (意見) | ⏳/✅ | (日期) |
### 完成確認
| 角色 | 姓名 | 部門 | 確認意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 實施負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 驗證負責人 | (姓名) | 測試部 | (意見) | ⏳/✅ | (日期) |
| 業務負責人 | (姓名) | 業務部 | (意見) | ⏳/✅ | (日期) |
---
## 附件
### 變更文件清單
| 文件類型 | 文件名稱 | 版本 | 存放位置 |
|----------|----------|------|----------|
| 設計文檔 | (文件名) | (版本) | (路徑) |
| 測試報告 | (文件名) | (版本) | (路徑) |
| 部署腳本 | (文件名) | (版本) | (路徑) |
| 監控配置 | (文件名) | (版本) | (路徑) |
### 配置變更詳情
| 配置文件 | 變更前 | 變更後 | 變更原因 |
|----------|--------|--------|----------|
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
### 命令記錄
```bash
# 實施命令記錄
(實際執行的命令)
```
### 監控圖表截圖
| 監控圖表 | 變更前 | 變更後 | 分析 |
|----------|--------|--------|------|
| (圖表1) | (描述) | (描述) | (分析) |
| (圖表2) | (描述) | (描述) | (分析) |
---
## 附錄
### 變更類型定義
| 類型 | 代碼 | 說明 | 審核要求 |
|------|------|------|----------|
| 標準變更 | STANDARD | 低風險，有標準流程 | 技術審核 |
| 正常變更 | NORMAL | 中等風險，需要測試 | 技術+安全審核 |
| 緊急變更 | EMERGENCY | 高風險，緊急修復 | 事後審查 |
| 重大變更 | MAJOR | 高風險，影響廣泛 | 變更委員會 |
### 風險等級定義
| 等級 | 可能性 | 影響 | 處理要求 |
|------|--------|------|----------|
| 低 | < 30% | 輕微 | 標準流程 |
| 中 | 30-70% | 中等 | 額外審核 |
| 高 | > 70% | 嚴重 | 管理層批准 |
| 緊急 | 100% | 災難性 | 立即處理，事後審查 |
### 狀態標記說明
| 狀態 | 標記 | 說明 |
|------|------|------|
| 規劃中 | ⏳ 規劃中 | 變更正在規劃階段 |
| 審核中 | 📋 審核中 | 等待審核批准 |
| 實施中 | 🔧 實施中 | 正在實施變更 |
| 已完成 | ✅ 已完成 | 變更成功完成 |
| 已取消 | ❌ 已取消 | 變更被取消 |
| 已回滾 | ⚠️ 已回滾 | 變更需要回滾 |
---
**文件狀態**: ⏳ 規劃中 / 🔧 實施中 / ✅ 已完成 / ❌ 已取消 / ⚠️ 已回滾
**下次審查日期**: (YYYY-MM-DD)
---
**AI Agent 備註**
**最後更新**: 2026-03-27
**AI 優化版本**: V1.0
**兼容性**: 向後兼容現有模板
**注意**:
- AI Agent 應優先讀取 YAML frontmatter 獲取結構化數據
- 人類用戶可閱讀 Markdown 表格部分
- 兩部分數據應保持同步

440
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_CHANGE_AI_OPTIMIZED.md
View File

@@ -1,440 +0,0 @@
# CHANGE_<服務名稱>_<變更類型>_<日期>.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "change"
service: "<服務名稱>"
problem: "<變更簡述>"
date: "<YYYY-MM-DD>"
severity: "P0" # P0/P1/P2/P3/P4 (可選)
status: "active" # active/completed/archived
current_state: "planned" # planned/implementing/completed/rolled_back
owner: "<負責人姓名>"
created_by: "<創建者姓名>"
created_at: "<YYYY-MM-DD HH:MM>"
version: "1.0"
change_type: "配置變更" # 配置變更/版本升級/架構調整/安全修補/功能新增
risk_level: "低" # 低/中/高/緊急
approval_status: "pending" # pending/approved/rejected
implementation_status: "planned" # planned/implementing/completed/rolled_back
estimated_downtime: "<預計停機時間(分鐘)>"
actual_downtime: "<實際停機時間(分鐘)>"
tags:
- "change"
- "<服務標籤>"
- "<變更類型>"
related_documents:
- "RCA_<相關分析>.md"
- "INCIDENT_<相關事件>.md"
ai_query_hints:
- "如何查詢所有待審核的變更？"
- "如何找到高風險的變更？"
- "如何更新變更狀態和實施進度？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 變更申請人 | (填寫申請人姓名) |
| 申請時間 | (YYYY-MM-DD HH:MM) |
| 變更類型 | 配置變更 / 版本升級 / 架構調整 / 安全修補 / 功能新增 |
| 變更狀態 | ⏳ 規劃中 / 🔧 實施中 / ✅ 已完成 / ❌ 已取消 / ⚠️ 已回滾 |
| 風險等級 | 低 / 中 / 高 / 緊急 |
| 審核狀態 | ⏳ 待審核 / ✅ 已批准 / ❌ 已拒絕 |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有待審核的變更
查找: document_type: "change" AND approval_status: "pending"
# 查詢高風險的變更
查找: document_type: "change" AND risk_level: "高"
# 查詢本週計畫實施的變更
查找: document_type: "change" AND implementation_status: "planned" AND date: ">=2026-03-20"
```
### 自動化操作
1. **狀態更新**：當變更狀態變更時，更新 `implementation_status` 和 `current_state`
2. **目錄移動**：根據狀態自動移動文件到相應目錄 (`_active/`, `_completed/`, `_archived/`)
3. **審核通知**：根據審核狀態自動發送通知
4. **風險警報**：高風險變更自動觸發額外審查
### 數據提取
```python
# Python 示例：提取變更元數據
import yaml
import re
def extract_change_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建變更紀錄 | (姓名) | (工具) |
---
## 變更概述
### 基本資訊
| 項目 | 內容 |
|------|------|
| **變更標題** | (簡短描述變更) |
| **變更原因** | 問題修復 / 性能優化 / 功能增強 / 安全更新 / 合規要求 |
| **業務價值** | (變更帶來的業務價值) |
| **預期效益** | (具體效益指標) |
| **影響服務** | (受影響的服務列表) |
### 變更描述
#### 當前狀態
(描述變更前的當前狀態)
#### 目標狀態
(描述變更後的期望狀態)
#### 變更範圍
- **配置變更**: (配置文件列表)
- **代碼變更**: (代碼庫/分支)
- **數據變更**: (數據庫/數據結構)
- **依賴變更**: (依賴庫/版本)
#### 成功標準
| 標準 | 描述 | 驗證方法 |
|------|------|----------|
| (標準1) | (成功條件) | (驗證方式) |
| (標準2) | (成功條件) | (驗證方式) |
### 影響分析
| 影響維度 | 影響等級 | 詳細說明 | 緩解措施 |
|----------|----------|----------|----------|
| **服務可用性** | 無影響 / 短暫中斷 / 計劃停機 | (影響描述) | (緩解方法) |
| **性能影響** | 無影響 / 性能提升 / 性能下降 | (性能變化) | (優化措施) |
| **數據影響** | 無影響 / 數據遷移 / 結構變更 | (數據影響) | (備份策略) |
| **安全性影響** | 無影響 / 安全性提升 / 潛在風險 | (安全影響) | (安全措施) |
| **兼容性影響** | 完全兼容 / 部分兼容 / 不兼容 | (兼容性) | (遷移計畫) |
---
## 實施計畫
### 時間安排
| 階段 | 開始時間 | 結束時間 | 持續時間 | 負責人 |
|------|----------|----------|----------|--------|
| 規劃設計 | (時間) | (時間) | (時長) | (姓名) |
| 測試驗證 | (時間) | (時間) | (時長) | (姓名) |
| 實施部署 | (時間) | (時間) | (時長) | (姓名) |
| 監控觀察 | (時間) | (時間) | (時長) | (姓名) |
| 完成確認 | (時間) | (時間) | (時長) | (姓名) |
### 詳細步驟
#### 階段 1: 規劃設計
| 步驟 | 描述 | 輸出物 | 負責人 | 狀態 |
|------|------|--------|--------|------|
| 1.1 | 需求分析 | 需求文檔 | (姓名) | ⏳/✅ |
| 1.2 | 技術設計 | 設計文檔 | (姓名) | ⏳/✅ |
| 1.3 | 風險評估 | 風險報告 | (姓名) | ⏳/✅ |
| 1.4 | 資源規劃 | 資源清單 | (姓名) | ⏳/✅ |
#### 階段 2: 測試驗證
| 步驟 | 描述 | 測試環境 | 驗證標準 | 狀態 |
|------|------|----------|----------|------|
| 2.1 | 單元測試 | 開發環境 | 測試通過率 ≥ 95% | ⏳/✅ |
| 2.2 | 集成測試 | 測試環境 | 所有接口正常 | ⏳/✅ |
| 2.3 | 性能測試 | 測試環境 | 性能指標達標 | ⏳/✅ |
| 2.4 | 安全測試 | 測試環境 | 安全掃描通過 | ⏳/✅ |
#### 階段 3: 實施部署
| 步驟 | 描述 | 操作命令/腳本 | 回滾方案 | 狀態 |
|------|------|----------------|----------|------|
| 3.1 | 預部署檢查 | ```(檢查命令)``` | (回滾步驟) | ⏳/✅ |
| 3.2 | 備份當前狀態 | ```(備份命令)``` | 使用備份恢復 | ⏳/✅ |
| 3.3 | 實施變更 | ```(變更命令)``` | (回滾命令) | ⏳/✅ |
| 3.4 | 配置更新 | ```(配置命令)``` | 恢復舊配置 | ⏳/✅ |
| 3.5 | 服務重啟 | ```(重啟命令)``` | 停止新服務 | ⏳/✅ |
#### 階段 4: 監控觀察
| 步驟 | 描述 | 監控指標 | 閾值 | 狀態 |
|------|------|----------|------|------|
| 4.1 | 健康檢查 | 服務狀態 | 所有服務正常 | ⏳/✅ |
| 4.2 | 性能監控 | 響應時間 | < 3000ms | ⏳/✅ |
| 4.3 | 錯誤監控 | 錯誤率 | < 1% | ⏳/✅ |
| 4.4 | 業務驗證 | 關鍵流程 | 全部通過 | ⏳/✅ |
### 回滾計畫
| 回滾場景 | 觸發條件 | 回滾步驟 | 預計停機時間 | 負責人 |
|----------|----------|----------|--------------|--------|
| 實施失敗 | 變更步驟失敗 | 1. 停止新服務<br>2. 恢復備份<br>3. 啟動舊服務 | (時間) | (姓名) |
| 性能下降 | 關鍵指標下降 30% | 1. 切換流量到舊版本<br>2. 分析問題<br>3. 修復後重新部署 | (時間) | (姓名) |
| 安全問題 | 發現安全漏洞 | 1. 立即回滾<br>2. 安全修復<br>3. 重新評估 | (時間) | (姓名) |
---
## 資源需求
### 人員需求
| 角色 | 人員 | 投入時間 | 主要職責 |
|------|------|----------|----------|
| 變更負責人 | (姓名) | (時數) | 整體協調和決策 |
| 實施工程師 | (姓名) | (時數) | 具體實施操作 |
| 測試工程師 | (姓名) | (時數) | 測試驗證 |
| 監控工程師 | (姓名) | (時數) | 變更後監控 |
| 溝通協調 | (姓名) | (時數) | 團隊溝通 |
### 系統資源
| 資源類型 | 規格要求 | 數量 | 可用性確認 |
|----------|----------|------|------------|
| 服務器 | (規格) | (數量) | ✅/❌ |
| 存儲空間 | (容量) | (數量) | ✅/❌ |
| 網絡帶寬 | (帶寬) | (數量) | ✅/❌ |
| 授權許可 | (授權類型) | (數量) | ✅/❌ |
### 工具與腳本
| 工具/腳本 | 用途 | 位置/路徑 | 狀態 |
|-----------|------|-----------|------|
| (工具1) | 部署工具 | (路徑) | ✅ 就緒 |
| (工具2) | 監控腳本 | (路徑) | ✅ 就緒 |
| (工具3) | 回滾腳本 | (路徑) | ✅ 就緒 |
---
## 風險管理
### 已識別風險
| 風險編號 | 風險描述 | 可能性 | 影響程度 | 風險等級 | 緩解措施 |
|----------|----------|--------|----------|----------|----------|
| R001 | (風險描述) | 高/中/低 | 高/中/低 | 高/中/低 | (緩解措施) |
| R002 | (風險描述) | 高/中/低 | 高/中/低 | 高/中/低 | (緩解措施) |
### 應急預案
| 應急場景 | 觸發條件 | 應急步驟 | 溝通計劃 | 負責人 |
|----------|----------|----------|----------|--------|
| 服務中斷 | 服務不可用超過 5 分鐘 | 1. 立即通知團隊<br>2. 啟動回滾程序<br>3. 問題分析 | 立即通知所有相關人員 | (姓名) |
| 數據丟失 | 數據不一致或丟失 | 1. 停止變更<br>2. 從備份恢復<br>3. 數據驗證 | 通知數據管理員和受影響用戶 | (姓名) |
| 安全事件 | 發現安全漏洞 | 1. 立即回滾<br>2. 安全評估<br>3. 修復漏洞 | 通知安全團隊和管理層 | (姓名) |
### 溝通計劃
| 溝通時機 | 溝通對象 | 溝通方式 | 溝通內容 | 負責人 |
|----------|----------|----------|----------|--------|
| 變更前 24h | 相關團隊 | 郵件/會議 | 變更通知和影響說明 | (姓名) |
| 變更開始 | 實施團隊 | 即時通訊 | 開始實施通知 | (姓名) |
| 變更完成 | 所有相關方 | 郵件/公告 | 完成通知和驗證結果 | (姓名) |
| 問題發生 | 應急團隊 | 電話/警報 | 問題描述和應急啟動 | (姓名) |
---
## 實施記錄
### 實際時間線
| 時間 | 操作 | 操作人員 | 結果 | 問題/備註 |
|------|------|----------|------|----------|
| (時間) | 開始實施 | (姓名) | ✅ 成功 | (備註) |
| (時間) | 步驟1完成 | (姓名) | ✅ 成功 | (備註) |
| (時間) | 步驟2完成 | (姓名) | ✅ 成功 | (備註) |
| (時間) | 遇到問題 | (姓名) | ⚠️ 警告 | (問題描述) |
| (時間) | 問題解決 | (姓名) | ✅ 成功 | (解決方案) |
| (時間) | 變更完成 | (姓名) | ✅ 成功 | (備註) |
### 問題與解決
| 問題編號 | 問題描述 | 影響 | 解決方案 | 解決時間 | 負責人 |
|----------|----------|------|----------|----------|--------|
| P001 | (問題描述) | (影響程度) | (解決方案) | (時間) | (姓名) |
| P002 | (問題描述) | (影響程度) | (解決方案) | (時間) | (姓名) |
### 變更驗證結果
| 驗證項目 | 預期結果 | 實際結果 | 驗證方法 | 驗證人 | 狀態 |
|----------|----------|----------|----------|--------|------|
| (項目1) | (預期) | (實際) | (方法) | (姓名) | ✅/❌ |
| (項目2) | (預期) | (實際) | (方法) | (姓名) | ✅/❌ |
### 監控數據
| 監控指標 | 變更前 | 變更後 | 變化 | 是否達標 |
|----------|--------|--------|------|----------|
| (指標1) | (數值) | (數值) | (+/-%) | ✅/❌ |
| (指標2) | (數值) | (數值) | (+/-%) | ✅/❌ |
---
## 完成確認
### 成功標準達成情況
| 成功標準 | 達成情況 | 證據/數據 | 確認人 | 日期 |
|----------|----------|------------|--------|------|
| (標準1) | ✅ 達成 / ❌ 未達成 | (證據) | (姓名) | (日期) |
| (標準2) | ✅ 達成 / ❌ 未達成 | (證據) | (姓名) | (日期) |
### 後續行動
| 行動項 | 描述 | 負責人 | 截止日期 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | 清理臨時文件 | (姓名) | (日期) | ⏳/✅ |
| (行動2) | 更新文檔 | (姓名) | (日期) | ⏳/✅ |
| (行動3) | 經驗總結 | (姓名) | (日期) | ⏳/✅ |
### 經驗教訓
| 類別 | 學到的教訓 | 改進建議 |
|------|------------|----------|
| 規劃 | (教訓) | (建議) |
| 實施 | (教訓) | (建議) |
| 溝通 | (教訓) | (建議) |
| 風險管理 | (教訓) | (建議) |
---
## 簽核與批准
### 變更審核
| 審核階段 | 審核人 | 部門 | 審核意見 | 審核狀態 | 日期 |
|----------|--------|------|----------|----------|------|
| 技術審核 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 安全審核 | (姓名) | 安全部 | (意見) | ⏳/✅ | (日期) |
| 業務審核 | (姓名) | 業務部 | (意見) | ⏳/✅ | (日期) |
### 批准實施
| 角色 | 姓名 | 部門 | 批准意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 變更申請人 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 變更委員會 | (姓名) | 變更管理 | (意見) | ⏳/✅ | (日期) |
### 完成確認
| 角色 | 姓名 | 部門 | 確認意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 實施負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 驗證負責人 | (姓名) | 測試部 | (意見) | ⏳/✅ | (日期) |
| 業務負責人 | (姓名) | 業務部 | (意見) | ⏳/✅ | (日期) |
---
## 附件
### 變更文件清單
| 文件類型 | 文件名稱 | 版本 | 存放位置 |
|----------|----------|------|----------|
| 設計文檔 | (文件名) | (版本) | (路徑) |
| 測試報告 | (文件名) | (版本) | (路徑) |
| 部署腳本 | (文件名) | (版本) | (路徑) |
| 監控配置 | (文件名) | (版本) | (路徑) |
### 配置變更詳情
| 配置文件 | 變更前 | 變更後 | 變更原因 |
|----------|--------|--------|----------|
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
### 命令記錄
```bash
# 實施命令記錄
(實際執行的命令)
```
### 監控圖表截圖
| 監控圖表 | 變更前 | 變更後 | 分析 |
|----------|--------|--------|------|
| (圖表1) | (描述) | (描述) | (分析) |
| (圖表2) | (描述) | (描述) | (分析) |
---
## 附錄
### 變更類型定義
| 類型 | 代碼 | 說明 | 審核要求 |
|------|------|------|----------|
| 標準變更 | STANDARD | 低風險，有標準流程 | 技術審核 |
| 正常變更 | NORMAL | 中等風險，需要測試 | 技術+安全審核 |
| 緊急變更 | EMERGENCY | 高風險，緊急修復 | 事後審查 |
| 重大變更 | MAJOR | 高風險，影響廣泛 | 變更委員會 |
### 風險等級定義
| 等級 | 可能性 | 影響 | 處理要求 |
|------|--------|------|----------|
| 低 | < 30% | 輕微 | 標準流程 |
| 中 | 30-70% | 中等 | 額外審核 |
| 高 | > 70% | 嚴重 | 管理層批准 |
| 緊急 | 100% | 災難性 | 立即處理，事後審查 |
### 狀態標記說明
| 狀態 | 標記 | 說明 |
|------|------|------|
| 規劃中 | ⏳ 規劃中 | 變更正在規劃階段 |
| 審核中 | 📋 審核中 | 等待審核批准 |
| 實施中 | 🔧 實施中 | 正在實施變更 |
| 已完成 | ✅ 已完成 | 變更成功完成 |
| 已取消 | ❌ 已取消 | 變更被取消 |
| 已回滾 | ⚠️ 已回滾 | 變更需要回滾 |
---
**文件狀態**: ⏳ 規劃中 / 🔧 實施中 / ✅ 已完成 / ❌ 已取消 / ⚠️ 已回滾
**下次審查日期**: (YYYY-MM-DD)
---
**AI Agent 備註**
**最後更新**: 2026-03-27
**AI 優化版本**: V1.0
**兼容性**: 向後兼容現有模板
**注意**:
- AI Agent 應優先讀取 YAML frontmatter 獲取結構化數據
- 人類用戶可閱讀 Markdown 表格部分
- 兩部分數據應保持同步

347
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_CHANGE_LEGACY.md
View File

@@ -1,347 +0,0 @@
# CHANGE_<服務名稱>_<變更類型>_<日期>.md
| 項目 | 內容 |
|------|------|
| 變更申請人 | (填寫申請人姓名) |
| 申請時間 | (YYYY-MM-DD HH:MM) |
| 變更類型 | 配置變更 / 版本升級 / 架構調整 / 安全修補 / 功能新增 |
| 變更狀態 | ⏳ 規劃中 / 🔧 實施中 / ✅ 已完成 / ❌ 已取消 / ⚠️ 已回滾 |
| 風險等級 | 低 / 中 / 高 / 緊急 |
| 審核狀態 | ⏳ 待審核 / ✅ 已批准 / ❌ 已拒絕 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建變更紀錄 | (姓名) | (工具) |
---
## 變更概述
### 基本資訊
| 項目 | 內容 |
|------|------|
| **變更標題** | (簡短描述變更) |
| **變更原因** | 問題修復 / 性能優化 / 功能增強 / 安全更新 / 合規要求 |
| **業務價值** | (變更帶來的業務價值) |
| **預期效益** | (具體效益指標) |
| **影響服務** | (受影響的服務列表) |
### 變更描述
#### 當前狀態
(描述變更前的當前狀態)
#### 目標狀態
(描述變更後的期望狀態)
#### 變更範圍
- **配置變更**: (配置文件列表)
- **代碼變更**: (代碼庫/分支)
- **數據變更**: (數據庫/數據結構)
- **依賴變更**: (依賴庫/版本)
#### 成功標準
| 標準 | 描述 | 驗證方法 |
|------|------|----------|
| (標準1) | (成功條件) | (驗證方式) |
| (標準2) | (成功條件) | (驗證方式) |
### 影響分析
| 影響維度 | 影響等級 | 詳細說明 | 緩解措施 |
|----------|----------|----------|----------|
| **服務可用性** | 無影響 / 短暫中斷 / 計劃停機 | (影響描述) | (緩解方法) |
| **性能影響** | 無影響 / 性能提升 / 性能下降 | (性能變化) | (優化措施) |
| **數據影響** | 無影響 / 數據遷移 / 結構變更 | (數據影響) | (備份策略) |
| **安全性影響** | 無影響 / 安全性提升 / 潛在風險 | (安全影響) | (安全措施) |
| **兼容性影響** | 完全兼容 / 部分兼容 / 不兼容 | (兼容性) | (遷移計畫) |
---
## 實施計畫
### 時間安排
| 階段 | 開始時間 | 結束時間 | 持續時間 | 負責人 |
|------|----------|----------|----------|--------|
| 規劃設計 | (時間) | (時間) | (時長) | (姓名) |
| 測試驗證 | (時間) | (時間) | (時長) | (姓名) |
| 實施部署 | (時間) | (時間) | (時長) | (姓名) |
| 監控觀察 | (時間) | (時間) | (時長) | (姓名) |
| 完成確認 | (時間) | (時間) | (時長) | (姓名) |
### 詳細步驟
#### 階段 1: 規劃設計
| 步驟 | 描述 | 輸出物 | 負責人 | 狀態 |
|------|------|--------|--------|------|
| 1.1 | 需求分析 | 需求文檔 | (姓名) | ⏳/✅ |
| 1.2 | 技術設計 | 設計文檔 | (姓名) | ⏳/✅ |
| 1.3 | 風險評估 | 風險報告 | (姓名) | ⏳/✅ |
| 1.4 | 資源規劃 | 資源清單 | (姓名) | ⏳/✅ |
#### 階段 2: 測試驗證
| 步驟 | 描述 | 測試環境 | 驗證標準 | 狀態 |
|------|------|----------|----------|------|
| 2.1 | 單元測試 | 開發環境 | 測試通過率 ≥ 95% | ⏳/✅ |
| 2.2 | 集成測試 | 測試環境 | 所有接口正常 | ⏳/✅ |
| 2.3 | 性能測試 | 測試環境 | 性能指標達標 | ⏳/✅ |
| 2.4 | 安全測試 | 測試環境 | 安全掃描通過 | ⏳/✅ |
#### 階段 3: 實施部署
| 步驟 | 描述 | 操作命令/腳本 | 回滾方案 | 狀態 |
|------|------|----------------|----------|------|
| 3.1 | 預部署檢查 | ```(檢查命令)``` | (回滾步驟) | ⏳/✅ |
| 3.2 | 備份當前狀態 | ```(備份命令)``` | 使用備份恢復 | ⏳/✅ |
| 3.3 | 實施變更 | ```(變更命令)``` | (回滾命令) | ⏳/✅ |
| 3.4 | 配置更新 | ```(配置命令)``` | 恢復舊配置 | ⏳/✅ |
| 3.5 | 服務重啟 | ```(重啟命令)``` | 停止新服務 | ⏳/✅ |
#### 階段 4: 監控觀察
| 步驟 | 描述 | 監控指標 | 閾值 | 狀態 |
|------|------|----------|------|------|
| 4.1 | 健康檢查 | 服務狀態 | 所有服務正常 | ⏳/✅ |
| 4.2 | 性能監控 | 響應時間 | < 3000ms | ⏳/✅ |
| 4.3 | 錯誤監控 | 錯誤率 | < 1% | ⏳/✅ |
| 4.4 | 業務驗證 | 關鍵流程 | 全部通過 | ⏳/✅ |
### 回滾計畫
| 回滾場景 | 觸發條件 | 回滾步驟 | 預計停機時間 | 負責人 |
|----------|----------|----------|--------------|--------|
| 實施失敗 | 變更步驟失敗 | 1. 停止新服務<br>2. 恢復備份<br>3. 啟動舊服務 | (時間) | (姓名) |
| 性能下降 | 關鍵指標下降 30% | 1. 切換流量到舊版本<br>2. 分析問題<br>3. 修復後重新部署 | (時間) | (姓名) |
| 安全問題 | 發現安全漏洞 | 1. 立即回滾<br>2. 安全修復<br>3. 重新評估 | (時間) | (姓名) |
---
## 資源需求
### 人員需求
| 角色 | 人員 | 投入時間 | 主要職責 |
|------|------|----------|----------|
| 變更負責人 | (姓名) | (時數) | 整體協調和決策 |
| 實施工程師 | (姓名) | (時數) | 具體實施操作 |
| 測試工程師 | (姓名) | (時數) | 測試驗證 |
| 監控工程師 | (姓名) | (時數) | 變更後監控 |
| 溝通協調 | (姓名) | (時數) | 團隊溝通 |
### 系統資源
| 資源類型 | 規格要求 | 數量 | 可用性確認 |
|----------|----------|------|------------|
| 服務器 | (規格) | (數量) | ✅/❌ |
| 存儲空間 | (容量) | (數量) | ✅/❌ |
| 網絡帶寬 | (帶寬) | (數量) | ✅/❌ |
| 授權許可 | (授權類型) | (數量) | ✅/❌ |
### 工具與腳本
| 工具/腳本 | 用途 | 位置/路徑 | 狀態 |
|-----------|------|-----------|------|
| (工具1) | 部署工具 | (路徑) | ✅ 就緒 |
| (工具2) | 監控腳本 | (路徑) | ✅ 就緒 |
| (工具3) | 回滾腳本 | (路徑) | ✅ 就緒 |
---
## 風險管理
### 已識別風險
| 風險編號 | 風險描述 | 可能性 | 影響程度 | 風險等級 | 緩解措施 |
|----------|----------|--------|----------|----------|----------|
| R001 | (風險描述) | 高/中/低 | 高/中/低 | 高/中/低 | (緩解措施) |
| R002 | (風險描述) | 高/中/低 | 高/中/低 | 高/中/低 | (緩解措施) |
### 應急預案
| 應急場景 | 觸發條件 | 應急步驟 | 溝通計劃 | 負責人 |
|----------|----------|----------|----------|--------|
| 服務中斷 | 服務不可用超過 5 分鐘 | 1. 立即通知團隊<br>2. 啟動回滾程序<br>3. 問題分析 | 立即通知所有相關人員 | (姓名) |
| 數據丟失 | 數據不一致或丟失 | 1. 停止變更<br>2. 從備份恢復<br>3. 數據驗證 | 通知數據管理員和受影響用戶 | (姓名) |
| 安全事件 | 發現安全漏洞 | 1. 立即回滾<br>2. 安全評估<br>3. 修復漏洞 | 通知安全團隊和管理層 | (姓名) |
### 溝通計劃
| 溝通時機 | 溝通對象 | 溝通方式 | 溝通內容 | 負責人 |
|----------|----------|----------|----------|--------|
| 變更前 24h | 相關團隊 | 郵件/會議 | 變更通知和影響說明 | (姓名) |
| 變更開始 | 實施團隊 | 即時通訊 | 開始實施通知 | (姓名) |
| 變更完成 | 所有相關方 | 郵件/公告 | 完成通知和驗證結果 | (姓名) |
| 問題發生 | 應急團隊 | 電話/警報 | 問題描述和應急啟動 | (姓名) |
---
## 實施記錄
### 實際時間線
| 時間 | 操作 | 操作人員 | 結果 | 問題/備註 |
|------|------|----------|------|----------|
| (時間) | 開始實施 | (姓名) | ✅ 成功 | (備註) |
| (時間) | 步驟1完成 | (姓名) | ✅ 成功 | (備註) |
| (時間) | 步驟2完成 | (姓名) | ✅ 成功 | (備註) |
| (時間) | 遇到問題 | (姓名) | ⚠️ 警告 | (問題描述) |
| (時間) | 問題解決 | (姓名) | ✅ 成功 | (解決方案) |
| (時間) | 變更完成 | (姓名) | ✅ 成功 | (備註) |
### 問題與解決
| 問題編號 | 問題描述 | 影響 | 解決方案 | 解決時間 | 負責人 |
|----------|----------|------|----------|----------|--------|
| P001 | (問題描述) | (影響程度) | (解決方案) | (時間) | (姓名) |
| P002 | (問題描述) | (影響程度) | (解決方案) | (時間) | (姓名) |
### 變更驗證結果
| 驗證項目 | 預期結果 | 實際結果 | 驗證方法 | 驗證人 | 狀態 |
|----------|----------|----------|----------|--------|------|
| (項目1) | (預期) | (實際) | (方法) | (姓名) | ✅/❌ |
| (項目2) | (預期) | (實際) | (方法) | (姓名) | ✅/❌ |
### 監控數據
| 監控指標 | 變更前 | 變更後 | 變化 | 是否達標 |
|----------|--------|--------|------|----------|
| (指標1) | (數值) | (數值) | (+/-%) | ✅/❌ |
| (指標2) | (數值) | (數值) | (+/-%) | ✅/❌ |
---
## 完成確認
### 成功標準達成情況
| 成功標準 | 達成情況 | 證據/數據 | 確認人 | 日期 |
|----------|----------|------------|--------|------|
| (標準1) | ✅ 達成 / ❌ 未達成 | (證據) | (姓名) | (日期) |
| (標準2) | ✅ 達成 / ❌ 未達成 | (證據) | (姓名) | (日期) |
### 後續行動
| 行動項 | 描述 | 負責人 | 截止日期 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | 清理臨時文件 | (姓名) | (日期) | ⏳/✅ |
| (行動2) | 更新文檔 | (姓名) | (日期) | ⏳/✅ |
| (行動3) | 經驗總結 | (姓名) | (日期) | ⏳/✅ |
### 經驗教訓
| 類別 | 學到的教訓 | 改進建議 |
|------|------------|----------|
| 規劃 | (教訓) | (建議) |
| 實施 | (教訓) | (建議) |
| 溝通 | (教訓) | (建議) |
| 風險管理 | (教訓) | (建議) |
---
## 簽核與批准
### 變更審核
| 審核階段 | 審核人 | 部門 | 審核意見 | 審核狀態 | 日期 |
|----------|--------|------|----------|----------|------|
| 技術審核 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 安全審核 | (姓名) | 安全部 | (意見) | ⏳/✅ | (日期) |
| 業務審核 | (姓名) | 業務部 | (意見) | ⏳/✅ | (日期) |
### 批准實施
| 角色 | 姓名 | 部門 | 批准意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 變更申請人 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 變更委員會 | (姓名) | 變更管理 | (意見) | ⏳/✅ | (日期) |
### 完成確認
| 角色 | 姓名 | 部門 | 確認意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 實施負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 驗證負責人 | (姓名) | 測試部 | (意見) | ⏳/✅ | (日期) |
| 業務負責人 | (姓名) | 業務部 | (意見) | ⏳/✅ | (日期) |
---
## 附件
### 變更文件清單
| 文件類型 | 文件名稱 | 版本 | 存放位置 |
|----------|----------|------|----------|
| 設計文檔 | (文件名) | (版本) | (路徑) |
| 測試報告 | (文件名) | (版本) | (路徑) |
| 部署腳本 | (文件名) | (版本) | (路徑) |
| 監控配置 | (文件名) | (版本) | (路徑) |
### 配置變更詳情
| 配置文件 | 變更前 | 變更後 | 變更原因 |
|----------|--------|--------|----------|
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
### 命令記錄
```bash
# 實施命令記錄
(實際執行的命令)
```
### 監控圖表截圖
| 監控圖表 | 變更前 | 變更後 | 分析 |
|----------|--------|--------|------|
| (圖表1) | (描述) | (描述) | (分析) |
| (圖表2) | (描述) | (描述) | (分析) |
---
## 附錄
### 變更類型定義
| 類型 | 代碼 | 說明 | 審核要求 |
|------|------|------|----------|
| 標準變更 | STANDARD | 低風險，有標準流程 | 技術審核 |
| 正常變更 | NORMAL | 中等風險，需要測試 | 技術+安全審核 |
| 緊急變更 | EMERGENCY | 高風險，緊急修復 | 事後審查 |
| 重大變更 | MAJOR | 高風險，影響廣泛 | 變更委員會 |
### 風險等級定義
| 等級 | 可能性 | 影響 | 處理要求 |
|------|--------|------|----------|
| 低 | < 30% | 輕微 | 標準流程 |
| 中 | 30-70% | 中等 | 額外審核 |
| 高 | > 70% | 嚴重 | 管理層批准 |
| 緊急 | 100% | 災難性 | 立即處理，事後審查 |
### 狀態標記說明
| 狀態 | 標記 | 說明 |
|------|------|------|
| 規劃中 | ⏳ 規劃中 | 變更正在規劃階段 |
| 審核中 | 📋 審核中 | 等待審核批准 |
| 實施中 | 🔧 實施中 | 正在實施變更 |
| 已完成 | ✅ 已完成 | 變更成功完成 |
| 已取消 | ❌ 已取消 | 變更被取消 |
| 已回滾 | ⚠️ 已回滾 | 變更需要回滾 |
---
**文件狀態**: ⏳ 規劃中 / 🔧 實施中 / ✅ 已完成 / ❌ 已取消 / ⚠️ 已回滾
**下次審查日期**: (YYYY-MM-DD)
---
**模板結束** - 請根據實際情況填寫內容

361
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_INCIDENT.md
View File

@@ -1,361 +0,0 @@
# INCIDENT_<服務名稱>_<事件類型>_<日期>.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "incident"
service: "<服務名稱>"
problem: "<事件簡述>"
date: "<YYYY-MM-DD>"
severity: "P0" # P0/P1/P2/P3/P4
status: "active" # active/completed/archived
current_state: "pending" # pending/investigating/resolving/resolved/closed
owner: "<負責人姓名>"
created_by: "<創建者姓名>"
created_at: "<YYYY-MM-DD HH:MM>"
version: "1.0"
incident_type: "服務中斷" # 服務中斷/性能問題/安全事件/數據問題/配置錯誤
detection_method: "監控警報" # 監控警報/用戶報告/系統日誌/例行檢查
impact_level: "高" # 高/中/低
affected_users: "<受影響用戶數量或範圍>"
downtime: "<停機時間(分鐘)>"
tags:
- "incident"
- "<服務標籤>"
- "<事件類型>"
related_documents:
- "RCA_<相關分析>.md"
- "CHANGE_<相關變更>.md"
ai_query_hints:
- "如何查詢所有 P0/P1 級別的事件？"
- "如何找到過去 7 天內未解決的事件？"
- "如何更新事件狀態和時間線？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 報告者 | (填寫報告人員姓名) |
| 報告時間 | (YYYY-MM-DD HH:MM) |
| 嚴重等級 | P0/P1/P2/P3/P4 |
| 當前狀態 | ⏳ 待處理 / 🔍 調查中 / 🔧 處理中 / ✅ 已解決 / 📁 已關閉 |
| 受影響服務 | (服務列表) |
| 負責人 | (指派負責人) |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有 P0/P1 級別的事件
查找: document_type: "incident" AND (severity: "P0" OR severity: "P1")
# 查詢特定服務的未解決事件
查找: document_type: "incident" AND service: "n8n" AND current_state: "investigating"
# 查詢過去 24 小時內的事件
查找: document_type: "incident" AND date: ">=2026-03-26"
```
### 自動化操作
1. **狀態更新**：當事件狀態變更時，更新 `current_state` 和 `status`
2. **目錄移動**：根據狀態自動移動文件到相應目錄 (`_active/`, `_completed/`, `_archived/`)
3. **通知觸發**：根據嚴重等級和影響級別自動發送通知
4. **時間線追蹤**：自動記錄狀態變更時間和操作人員
### 數據提取
```python
# Python 示例：提取事件元數據
import yaml
import re
def extract_incident_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建事件報告 | (姓名) | (工具) |
---
## 事件詳情
### 基本資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | (簡短描述事件) |
| **事件類型** | 服務中斷 / 性能問題 / 安全事件 / 數據問題 / 配置錯誤 |
| **發現時間** | YYYY-MM-DD HH:MM |
| **發現方式** | 監控警報 / 用戶報告 / 系統日誌 / 例行檢查 |
| **影響範圍** | (受影響的用戶數量、服務、功能) |
| **業務影響** | 高/中/低 - (具體影響描述) |
### 事件描述
#### 問題現象
(描述用戶或系統觀察到的具體現象)
#### 預期行為
(正常情況下應有的行為)
#### 實際行為
(實際觀察到的異常行為)
#### 重現步驟
1. (步驟1)
2. (步驟2)
3. (步驟3)
### 影響評估
| 影響維度 | 評估等級 | 詳細說明 |
|----------|----------|----------|
| **服務可用性** | 完全中斷 / 部分中斷 / 降級 | (影響描述) |
| **用戶影響** | 所有用戶 / 部分用戶 / 單一用戶 | (用戶群體) |
| **數據影響** | 數據丟失 / 數據損壞 / 無影響 | (數據影響細節) |
| **財務影響** | 高 / 中 / 低 | (估計損失或成本) |
| **聲譽影響** | 高 / 中 / 低 | (品牌或客戶信任影響) |
---
## 處理進度
### 時間線追蹤
| 時間 | 事件/操作 | 操作人員 | 狀態更新 | 備註 |
|------|----------|----------|----------|------|
| (時間) | 事件發現 | (姓名) | ⏳ 待處理 | (發現方式) |
| (時間) | 初步評估 | (姓名) | 🔍 調查中 | (初步結論) |
| (時間) | 根本原因分析 | (姓名) | 🔍 調查中 | (發現原因) |
| (時間) | 實施修復 | (姓名) | 🔧 處理中 | (修復措施) |
| (時間) | 驗證測試 | (姓名) | ✅ 已解決 | (驗證結果) |
| (時間) | 事件關閉 | (姓名) | 📁 已關閉 | (關閉原因) |
### 當前狀態
| 項目 | 狀態 | 詳細資訊 |
|------|------|----------|
| **調查進度** | 0-100% | (完成百分比) |
| **修復狀態** | 未開始 / 進行中 / 已完成 | (具體狀態) |
| **驗證狀態** | 待驗證 / 驗證中 / 已驗證 | (驗證結果) |
| **溝通狀態** | 內部通知 / 用戶通知 / 公開公告 | (溝通情況) |
### 臨時措施
| 措施 | 描述 | 實施時間 | 效果 | 負責人 |
|------|------|----------|------|--------|
| (措施1) | (詳細描述) | (時間) | ✅/⚠️/❌ | (姓名) |
| (措施2) | (詳細描述) | (時間) | ✅/⚠️/❌ | (姓名) |
### 根本原因分析 (初步)
| 可能原因 | 可能性 | 證據 | 調查方向 |
|----------|--------|------|----------|
| (原因1) | 高/中/低 | (支持證據) | (進一步調查) |
| (原因2) | 高/中/低 | (支持證據) | (進一步調查) |
---
## 溝通記錄
### 內部溝通
| 時間 | 溝通對象 | 溝通方式 | 內容摘要 | 發送人 |
|------|----------|----------|----------|--------|
| (時間) | 技術團隊 | Slack/Email | (摘要) | (姓名) |
| (時間) | 管理層 | 會議/報告 | (摘要) | (姓名) |
### 外部溝通 (如需要)
| 時間 | 溝通對象 | 溝通方式 | 內容摘要 | 狀態 |
|------|----------|----------|----------|------|
| (時間) | 客戶/用戶 | Email/公告 | (摘要) | 已發送/待發送 |
### 升級路徑
| 等級 | 觸發條件 | 通知對象 | 通知時限 |
|------|----------|----------|----------|
| L1 | 事件發現 | 技術團隊 | 立即 |
| L2 | P1/P0 事件 | 技術負責人 | 30分鐘內 |
| L3 | 業務影響重大 | 管理層 | 1小時內 |
| L4 | 公開影響 | 公關團隊 | 2小時內 |
---
## 資源分配
### 人員分配
| 角色 | 人員 | 聯繫方式 | 職責 |
|------|------|----------|------|
| 事件負責人 | (姓名) | (電話/郵件) | 協調處理全過程 |
| 技術調查 | (姓名) | (電話/郵件) | 調查根本原因 |
| 修復實施 | (姓名) | (電話/郵件) | 實施解決方案 |
| 溝通協調 | (姓名) | (電話/郵件) | 內外部溝通 |
| 驗證測試 | (姓名) | (電話/郵件) | 驗證修復效果 |
### 工具與資源
| 資源類型 | 名稱/路徑 | 用途 | 權限 |
|----------|-----------|------|------|
| 監控工具 | (工具名稱) | 問題診斷 | (權限) |
| 日誌系統 | (路徑) | 調查分析 | (權限) |
| 配置管理 | (系統) | 配置檢查 | (權限) |
| 備份系統 | (系統) | 數據恢復 | (權限) |
---
## 後續行動
### 立即行動 (24小時內)
| 行動項 | 描述 | 負責人 | 截止時間 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | (詳細描述) | (姓名) | (時間) | ⏳/✅ |
| (行動2) | (詳細描述) | (姓名) | (時間) | ⏳/✅ |
### 短期行動 (1-7天)
| 行動項 | 描述 | 負責人 | 截止日期 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | (詳細描述) | (姓名) | (日期) | ⏳/✅ |
| (行動2) | (詳細描述) | (姓名) | (日期) | ⏳/✅ |
### RCA 追蹤
| 項目 | 狀態 | 預計完成 | 負責人 |
|------|------|----------|--------|
| 創建 RCA 文件 | ⏳ 待開始 | (日期) | (姓名) |
| 根本原因分析 | ⏳ 待開始 | (日期) | (姓名) |
| 預防措施制定 | ⏳ 待開始 | (日期) | (姓名) |
---
## 附件與參考
### 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| (相關文件1) | (用途) | (路徑) |
| (相關文件2) | (用途) | (路徑) |
### 日誌摘錄
```
(關鍵日誌內容)
```
### 監控圖表
| 指標 | 正常範圍 | 事件期間 | 當前值 |
|------|----------|----------|--------|
| (指標1) | (範圍) | (異常值) | (當前值) |
| (指標2) | (範圍) | (異常值) | (當前值) |
### 配置快照
| 配置項 | 事件前 | 當前值 | 變更原因 |
|--------|--------|--------|----------|
| (配置1) | (值) | (值) | (原因) |
| (配置2) | (值) | (值) | (原因) |
---
## 簽核與批准
### 事件關閉審核
| 審核項目 | 審核標準 | 審核結果 | 審核人 | 日期 |
|----------|----------|----------|--------|------|
| 問題解決 | 根本原因已識別並修復 | ✅/❌ | (姓名) | (日期) |
| 影響消除 | 所有影響已恢復正常 | ✅/❌ | (姓名) | (日期) |
| 驗證通過 | 所有測試用例通過 | ✅/❌ | (姓名) | (日期) |
| 文檔完整 | 所有相關文檔已更新 | ✅/❌ | (姓名) | (日期) |
| 溝通完成 | 所有相關方已通知 | ✅/❌ | (姓名) | (日期) |
### 批准關閉
| 角色 | 姓名 | 部門 | 批准意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 事件負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 受影響方代表 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
---
## 附錄
### 術語定義
| 術語 | 定義 |
|------|------|
| MTTR | 平均修復時間 (Mean Time To Repair) |
| MTBF | 平均故障間隔時間 (Mean Time Between Failures) |
| SLA | 服務水平協議 (Service Level Agreement) |
| SLO | 服務水平目標 (Service Level Objective) |
### 嚴重等級參考
| 等級 | 代碼 | 處理時間目標 | 通知要求 |
|------|------|--------------|----------|
| P0 | 緊急 | 立即處理，1小時內解決 | 立即通知所有相關人員 |
| P1 | 高 | 2小時內開始處理，4小時內解決 | 1小時內通知負責人 |
| P2 | 中 | 4小時內開始處理，8小時內解決 | 2小時內通知負責人 |
| P3 | 低 | 1個工作日內處理 | 工作日內通知 |
| P4 | 資訊 | 3個工作日內回應 | 無需緊急通知 |
### 狀態標記說明
| 狀態 | 標記 | 說明 |
|------|------|------|
| 新報告 | ⏳ 待處理 | 事件剛被報告，尚未分配 |
| 調查中 | 🔍 調查中 | 正在調查根本原因 |
| 處理中 | 🔧 處理中 | 正在實施解決方案 |
| 已解決 | ✅ 已解決 | 問題已解決，待驗證 |
| 已關閉 | 📁 已關閉 | 事件完全關閉 |
| 已歸檔 | 🗄️ 已歸檔 | 事件已歸檔 |
---
**文件狀態**: ⏳ 進行中 / ✅ 已完成 / 📁 已關閉
**下次審查時間**: (YYYY-MM-DD HH:MM)
---
**AI Agent 備註**
**最後更新**: 2026-03-27
**AI 優化版本**: V1.0
**兼容性**: 向後兼容現有模板
**注意**:
- AI Agent 應優先讀取 YAML frontmatter 獲取結構化數據
- 人類用戶可閱讀 Markdown 表格部分
- 兩部分數據應保持同步

361
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_INCIDENT_AI_OPTIMIZED.md
View File

@@ -1,361 +0,0 @@
# INCIDENT_<服務名稱>_<事件類型>_<日期>.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "incident"
service: "<服務名稱>"
problem: "<事件簡述>"
date: "<YYYY-MM-DD>"
severity: "P0" # P0/P1/P2/P3/P4
status: "active" # active/completed/archived
current_state: "pending" # pending/investigating/resolving/resolved/closed
owner: "<負責人姓名>"
created_by: "<創建者姓名>"
created_at: "<YYYY-MM-DD HH:MM>"
version: "1.0"
incident_type: "服務中斷" # 服務中斷/性能問題/安全事件/數據問題/配置錯誤
detection_method: "監控警報" # 監控警報/用戶報告/系統日誌/例行檢查
impact_level: "高" # 高/中/低
affected_users: "<受影響用戶數量或範圍>"
downtime: "<停機時間(分鐘)>"
tags:
- "incident"
- "<服務標籤>"
- "<事件類型>"
related_documents:
- "RCA_<相關分析>.md"
- "CHANGE_<相關變更>.md"
ai_query_hints:
- "如何查詢所有 P0/P1 級別的事件？"
- "如何找到過去 7 天內未解決的事件？"
- "如何更新事件狀態和時間線？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 報告者 | (填寫報告人員姓名) |
| 報告時間 | (YYYY-MM-DD HH:MM) |
| 嚴重等級 | P0/P1/P2/P3/P4 |
| 當前狀態 | ⏳ 待處理 / 🔍 調查中 / 🔧 處理中 / ✅ 已解決 / 📁 已關閉 |
| 受影響服務 | (服務列表) |
| 負責人 | (指派負責人) |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有 P0/P1 級別的事件
查找: document_type: "incident" AND (severity: "P0" OR severity: "P1")
# 查詢特定服務的未解決事件
查找: document_type: "incident" AND service: "n8n" AND current_state: "investigating"
# 查詢過去 24 小時內的事件
查找: document_type: "incident" AND date: ">=2026-03-26"
```
### 自動化操作
1. **狀態更新**：當事件狀態變更時，更新 `current_state` 和 `status`
2. **目錄移動**：根據狀態自動移動文件到相應目錄 (`_active/`, `_completed/`, `_archived/`)
3. **通知觸發**：根據嚴重等級和影響級別自動發送通知
4. **時間線追蹤**：自動記錄狀態變更時間和操作人員
### 數據提取
```python
# Python 示例：提取事件元數據
import yaml
import re
def extract_incident_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建事件報告 | (姓名) | (工具) |
---
## 事件詳情
### 基本資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | (簡短描述事件) |
| **事件類型** | 服務中斷 / 性能問題 / 安全事件 / 數據問題 / 配置錯誤 |
| **發現時間** | YYYY-MM-DD HH:MM |
| **發現方式** | 監控警報 / 用戶報告 / 系統日誌 / 例行檢查 |
| **影響範圍** | (受影響的用戶數量、服務、功能) |
| **業務影響** | 高/中/低 - (具體影響描述) |
### 事件描述
#### 問題現象
(描述用戶或系統觀察到的具體現象)
#### 預期行為
(正常情況下應有的行為)
#### 實際行為
(實際觀察到的異常行為)
#### 重現步驟
1. (步驟1)
2. (步驟2)
3. (步驟3)
### 影響評估
| 影響維度 | 評估等級 | 詳細說明 |
|----------|----------|----------|
| **服務可用性** | 完全中斷 / 部分中斷 / 降級 | (影響描述) |
| **用戶影響** | 所有用戶 / 部分用戶 / 單一用戶 | (用戶群體) |
| **數據影響** | 數據丟失 / 數據損壞 / 無影響 | (數據影響細節) |
| **財務影響** | 高 / 中 / 低 | (估計損失或成本) |
| **聲譽影響** | 高 / 中 / 低 | (品牌或客戶信任影響) |
---
## 處理進度
### 時間線追蹤
| 時間 | 事件/操作 | 操作人員 | 狀態更新 | 備註 |
|------|----------|----------|----------|------|
| (時間) | 事件發現 | (姓名) | ⏳ 待處理 | (發現方式) |
| (時間) | 初步評估 | (姓名) | 🔍 調查中 | (初步結論) |
| (時間) | 根本原因分析 | (姓名) | 🔍 調查中 | (發現原因) |
| (時間) | 實施修復 | (姓名) | 🔧 處理中 | (修復措施) |
| (時間) | 驗證測試 | (姓名) | ✅ 已解決 | (驗證結果) |
| (時間) | 事件關閉 | (姓名) | 📁 已關閉 | (關閉原因) |
### 當前狀態
| 項目 | 狀態 | 詳細資訊 |
|------|------|----------|
| **調查進度** | 0-100% | (完成百分比) |
| **修復狀態** | 未開始 / 進行中 / 已完成 | (具體狀態) |
| **驗證狀態** | 待驗證 / 驗證中 / 已驗證 | (驗證結果) |
| **溝通狀態** | 內部通知 / 用戶通知 / 公開公告 | (溝通情況) |
### 臨時措施
| 措施 | 描述 | 實施時間 | 效果 | 負責人 |
|------|------|----------|------|--------|
| (措施1) | (詳細描述) | (時間) | ✅/⚠️/❌ | (姓名) |
| (措施2) | (詳細描述) | (時間) | ✅/⚠️/❌ | (姓名) |
### 根本原因分析 (初步)
| 可能原因 | 可能性 | 證據 | 調查方向 |
|----------|--------|------|----------|
| (原因1) | 高/中/低 | (支持證據) | (進一步調查) |
| (原因2) | 高/中/低 | (支持證據) | (進一步調查) |
---
## 溝通記錄
### 內部溝通
| 時間 | 溝通對象 | 溝通方式 | 內容摘要 | 發送人 |
|------|----------|----------|----------|--------|
| (時間) | 技術團隊 | Slack/Email | (摘要) | (姓名) |
| (時間) | 管理層 | 會議/報告 | (摘要) | (姓名) |
### 外部溝通 (如需要)
| 時間 | 溝通對象 | 溝通方式 | 內容摘要 | 狀態 |
|------|----------|----------|----------|------|
| (時間) | 客戶/用戶 | Email/公告 | (摘要) | 已發送/待發送 |
### 升級路徑
| 等級 | 觸發條件 | 通知對象 | 通知時限 |
|------|----------|----------|----------|
| L1 | 事件發現 | 技術團隊 | 立即 |
| L2 | P1/P0 事件 | 技術負責人 | 30分鐘內 |
| L3 | 業務影響重大 | 管理層 | 1小時內 |
| L4 | 公開影響 | 公關團隊 | 2小時內 |
---
## 資源分配
### 人員分配
| 角色 | 人員 | 聯繫方式 | 職責 |
|------|------|----------|------|
| 事件負責人 | (姓名) | (電話/郵件) | 協調處理全過程 |
| 技術調查 | (姓名) | (電話/郵件) | 調查根本原因 |
| 修復實施 | (姓名) | (電話/郵件) | 實施解決方案 |
| 溝通協調 | (姓名) | (電話/郵件) | 內外部溝通 |
| 驗證測試 | (姓名) | (電話/郵件) | 驗證修復效果 |
### 工具與資源
| 資源類型 | 名稱/路徑 | 用途 | 權限 |
|----------|-----------|------|------|
| 監控工具 | (工具名稱) | 問題診斷 | (權限) |
| 日誌系統 | (路徑) | 調查分析 | (權限) |
| 配置管理 | (系統) | 配置檢查 | (權限) |
| 備份系統 | (系統) | 數據恢復 | (權限) |
---
## 後續行動
### 立即行動 (24小時內)
| 行動項 | 描述 | 負責人 | 截止時間 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | (詳細描述) | (姓名) | (時間) | ⏳/✅ |
| (行動2) | (詳細描述) | (姓名) | (時間) | ⏳/✅ |
### 短期行動 (1-7天)
| 行動項 | 描述 | 負責人 | 截止日期 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | (詳細描述) | (姓名) | (日期) | ⏳/✅ |
| (行動2) | (詳細描述) | (姓名) | (日期) | ⏳/✅ |
### RCA 追蹤
| 項目 | 狀態 | 預計完成 | 負責人 |
|------|------|----------|--------|
| 創建 RCA 文件 | ⏳ 待開始 | (日期) | (姓名) |
| 根本原因分析 | ⏳ 待開始 | (日期) | (姓名) |
| 預防措施制定 | ⏳ 待開始 | (日期) | (姓名) |
---
## 附件與參考
### 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| (相關文件1) | (用途) | (路徑) |
| (相關文件2) | (用途) | (路徑) |
### 日誌摘錄
```
(關鍵日誌內容)
```
### 監控圖表
| 指標 | 正常範圍 | 事件期間 | 當前值 |
|------|----------|----------|--------|
| (指標1) | (範圍) | (異常值) | (當前值) |
| (指標2) | (範圍) | (異常值) | (當前值) |
### 配置快照
| 配置項 | 事件前 | 當前值 | 變更原因 |
|--------|--------|--------|----------|
| (配置1) | (值) | (值) | (原因) |
| (配置2) | (值) | (值) | (原因) |
---
## 簽核與批准
### 事件關閉審核
| 審核項目 | 審核標準 | 審核結果 | 審核人 | 日期 |
|----------|----------|----------|--------|------|
| 問題解決 | 根本原因已識別並修復 | ✅/❌ | (姓名) | (日期) |
| 影響消除 | 所有影響已恢復正常 | ✅/❌ | (姓名) | (日期) |
| 驗證通過 | 所有測試用例通過 | ✅/❌ | (姓名) | (日期) |
| 文檔完整 | 所有相關文檔已更新 | ✅/❌ | (姓名) | (日期) |
| 溝通完成 | 所有相關方已通知 | ✅/❌ | (姓名) | (日期) |
### 批准關閉
| 角色 | 姓名 | 部門 | 批准意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 事件負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 受影響方代表 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
---
## 附錄
### 術語定義
| 術語 | 定義 |
|------|------|
| MTTR | 平均修復時間 (Mean Time To Repair) |
| MTBF | 平均故障間隔時間 (Mean Time Between Failures) |
| SLA | 服務水平協議 (Service Level Agreement) |
| SLO | 服務水平目標 (Service Level Objective) |
### 嚴重等級參考
| 等級 | 代碼 | 處理時間目標 | 通知要求 |
|------|------|--------------|----------|
| P0 | 緊急 | 立即處理，1小時內解決 | 立即通知所有相關人員 |
| P1 | 高 | 2小時內開始處理，4小時內解決 | 1小時內通知負責人 |
| P2 | 中 | 4小時內開始處理，8小時內解決 | 2小時內通知負責人 |
| P3 | 低 | 1個工作日內處理 | 工作日內通知 |
| P4 | 資訊 | 3個工作日內回應 | 無需緊急通知 |
### 狀態標記說明
| 狀態 | 標記 | 說明 |
|------|------|------|
| 新報告 | ⏳ 待處理 | 事件剛被報告，尚未分配 |
| 調查中 | 🔍 調查中 | 正在調查根本原因 |
| 處理中 | 🔧 處理中 | 正在實施解決方案 |
| 已解決 | ✅ 已解決 | 問題已解決，待驗證 |
| 已關閉 | 📁 已關閉 | 事件完全關閉 |
| 已歸檔 | 🗄️ 已歸檔 | 事件已歸檔 |
---
**文件狀態**: ⏳ 進行中 / ✅ 已完成 / 📁 已關閉
**下次審查時間**: (YYYY-MM-DD HH:MM)
---
**AI Agent 備註**
**最後更新**: 2026-03-27
**AI 優化版本**: V1.0
**兼容性**: 向後兼容現有模板
**注意**:
- AI Agent 應優先讀取 YAML frontmatter 獲取結構化數據
- 人類用戶可閱讀 Markdown 表格部分
- 兩部分數據應保持同步

269
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_INCIDENT_LEGACY.md
View File

@@ -1,269 +0,0 @@
# INCIDENT_<服務名稱>_<事件類型>_<日期>.md
| 項目 | 內容 |
|------|------|
| 報告者 | (填寫報告人員姓名) |
| 報告時間 | (YYYY-MM-DD HH:MM) |
| 嚴重等級 | P0/P1/P2/P3/P4 |
| 當前狀態 | ⏳ 待處理 / 🔍 調查中 / 🔧 處理中 / ✅ 已解決 / 📁 已關閉 |
| 受影響服務 | (服務列表) |
| 負責人 | (指派負責人) |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建事件報告 | (姓名) | (工具) |
---
## 事件詳情
### 基本資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | (簡短描述事件) |
| **事件類型** | 服務中斷 / 性能問題 / 安全事件 / 數據問題 / 配置錯誤 |
| **發現時間** | YYYY-MM-DD HH:MM |
| **發現方式** | 監控警報 / 用戶報告 / 系統日誌 / 例行檢查 |
| **影響範圍** | (受影響的用戶數量、服務、功能) |
| **業務影響** | 高/中/低 - (具體影響描述) |
### 事件描述
#### 問題現象
(描述用戶或系統觀察到的具體現象)
#### 預期行為
(正常情況下應有的行為)
#### 實際行為
(實際觀察到的異常行為)
#### 重現步驟
1. (步驟1)
2. (步驟2)
3. (步驟3)
### 影響評估
| 影響維度 | 評估等級 | 詳細說明 |
|----------|----------|----------|
| **服務可用性** | 完全中斷 / 部分中斷 / 降級 | (影響描述) |
| **用戶影響** | 所有用戶 / 部分用戶 / 單一用戶 | (用戶群體) |
| **數據影響** | 數據丟失 / 數據損壞 / 無影響 | (數據影響細節) |
| **財務影響** | 高 / 中 / 低 | (估計損失或成本) |
| **聲譽影響** | 高 / 中 / 低 | (品牌或客戶信任影響) |
---
## 處理進度
### 時間線追蹤
| 時間 | 事件/操作 | 操作人員 | 狀態更新 | 備註 |
|------|----------|----------|----------|------|
| (時間) | 事件發現 | (姓名) | ⏳ 待處理 | (發現方式) |
| (時間) | 初步評估 | (姓名) | 🔍 調查中 | (初步結論) |
| (時間) | 根本原因分析 | (姓名) | 🔍 調查中 | (發現原因) |
| (時間) | 實施修復 | (姓名) | 🔧 處理中 | (修復措施) |
| (時間) | 驗證測試 | (姓名) | ✅ 已解決 | (驗證結果) |
| (時間) | 事件關閉 | (姓名) | 📁 已關閉 | (關閉原因) |
### 當前狀態
| 項目 | 狀態 | 詳細資訊 |
|------|------|----------|
| **調查進度** | 0-100% | (完成百分比) |
| **修復狀態** | 未開始 / 進行中 / 已完成 | (具體狀態) |
| **驗證狀態** | 待驗證 / 驗證中 / 已驗證 | (驗證結果) |
| **溝通狀態** | 內部通知 / 用戶通知 / 公開公告 | (溝通情況) |
### 臨時措施
| 措施 | 描述 | 實施時間 | 效果 | 負責人 |
|------|------|----------|------|--------|
| (措施1) | (詳細描述) | (時間) | ✅/⚠️/❌ | (姓名) |
| (措施2) | (詳細描述) | (時間) | ✅/⚠️/❌ | (姓名) |
### 根本原因分析 (初步)
| 可能原因 | 可能性 | 證據 | 調查方向 |
|----------|--------|------|----------|
| (原因1) | 高/中/低 | (支持證據) | (進一步調查) |
| (原因2) | 高/中/低 | (支持證據) | (進一步調查) |
---
## 溝通記錄
### 內部溝通
| 時間 | 溝通對象 | 溝通方式 | 內容摘要 | 發送人 |
|------|----------|----------|----------|--------|
| (時間) | 技術團隊 | Slack/Email | (摘要) | (姓名) |
| (時間) | 管理層 | 會議/報告 | (摘要) | (姓名) |
### 外部溝通 (如需要)
| 時間 | 溝通對象 | 溝通方式 | 內容摘要 | 狀態 |
|------|----------|----------|----------|------|
| (時間) | 客戶/用戶 | Email/公告 | (摘要) | 已發送/待發送 |
### 升級路徑
| 等級 | 觸發條件 | 通知對象 | 通知時限 |
|------|----------|----------|----------|
| L1 | 事件發現 | 技術團隊 | 立即 |
| L2 | P1/P0 事件 | 技術負責人 | 30分鐘內 |
| L3 | 業務影響重大 | 管理層 | 1小時內 |
| L4 | 公開影響 | 公關團隊 | 2小時內 |
---
## 資源分配
### 人員分配
| 角色 | 人員 | 聯繫方式 | 職責 |
|------|------|----------|------|
| 事件負責人 | (姓名) | (電話/郵件) | 協調處理全過程 |
| 技術調查 | (姓名) | (電話/郵件) | 調查根本原因 |
| 修復實施 | (姓名) | (電話/郵件) | 實施解決方案 |
| 溝通協調 | (姓名) | (電話/郵件) | 內外部溝通 |
| 驗證測試 | (姓名) | (電話/郵件) | 驗證修復效果 |
### 工具與資源
| 資源類型 | 名稱/路徑 | 用途 | 權限 |
|----------|-----------|------|------|
| 監控工具 | (工具名稱) | 問題診斷 | (權限) |
| 日誌系統 | (路徑) | 調查分析 | (權限) |
| 配置管理 | (系統) | 配置檢查 | (權限) |
| 備份系統 | (系統) | 數據恢復 | (權限) |
---
## 後續行動
### 立即行動 (24小時內)
| 行動項 | 描述 | 負責人 | 截止時間 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | (詳細描述) | (姓名) | (時間) | ⏳/✅ |
| (行動2) | (詳細描述) | (姓名) | (時間) | ⏳/✅ |
### 短期行動 (1-7天)
| 行動項 | 描述 | 負責人 | 截止日期 | 狀態 |
|--------|------|--------|----------|------|
| (行動1) | (詳細描述) | (姓名) | (日期) | ⏳/✅ |
| (行動2) | (詳細描述) | (姓名) | (日期) | ⏳/✅ |
### RCA 追蹤
| 項目 | 狀態 | 預計完成 | 負責人 |
|------|------|----------|--------|
| 創建 RCA 文件 | ⏳ 待開始 | (日期) | (姓名) |
| 根本原因分析 | ⏳ 待開始 | (日期) | (姓名) |
| 預防措施制定 | ⏳ 待開始 | (日期) | (姓名) |
---
## 附件與參考
### 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| (相關文件1) | (用途) | (路徑) |
| (相關文件2) | (用途) | (路徑) |
### 日誌摘錄
```
(關鍵日誌內容)
```
### 監控圖表
| 指標 | 正常範圍 | 事件期間 | 當前值 |
|------|----------|----------|--------|
| (指標1) | (範圍) | (異常值) | (當前值) |
| (指標2) | (範圍) | (異常值) | (當前值) |
### 配置快照
| 配置項 | 事件前 | 當前值 | 變更原因 |
|--------|--------|--------|----------|
| (配置1) | (值) | (值) | (原因) |
| (配置2) | (值) | (值) | (原因) |
---
## 簽核與批准
### 事件關閉審核
| 審核項目 | 審核標準 | 審核結果 | 審核人 | 日期 |
|----------|----------|----------|--------|------|
| 問題解決 | 根本原因已識別並修復 | ✅/❌ | (姓名) | (日期) |
| 影響消除 | 所有影響已恢復正常 | ✅/❌ | (姓名) | (日期) |
| 驗證通過 | 所有測試用例通過 | ✅/❌ | (姓名) | (日期) |
| 文檔完整 | 所有相關文檔已更新 | ✅/❌ | (姓名) | (日期) |
| 溝通完成 | 所有相關方已通知 | ✅/❌ | (姓名) | (日期) |
### 批准關閉
| 角色 | 姓名 | 部門 | 批准意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 事件負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 受影響方代表 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
---
## 附錄
### 術語定義
| 術語 | 定義 |
|------|------|
| MTTR | 平均修復時間 (Mean Time To Repair) |
| MTBF | 平均故障間隔時間 (Mean Time Between Failures) |
| SLA | 服務水平協議 (Service Level Agreement) |
| SLO | 服務水平目標 (Service Level Objective) |
### 嚴重等級參考
| 等級 | 代碼 | 處理時間目標 | 通知要求 |
|------|------|--------------|----------|
| P0 | 緊急 | 立即處理，1小時內解決 | 立即通知所有相關人員 |
| P1 | 高 | 2小時內開始處理，4小時內解決 | 1小時內通知負責人 |
| P2 | 中 | 4小時內開始處理，8小時內解決 | 2小時內通知負責人 |
| P3 | 低 | 1個工作日內處理 | 工作日內通知 |
| P4 | 資訊 | 3個工作日內回應 | 無需緊急通知 |
### 狀態標記說明
| 狀態 | 標記 | 說明 |
|------|------|------|
| 新報告 | ⏳ 待處理 | 事件剛被報告，尚未分配 |
| 調查中 | 🔍 調查中 | 正在調查根本原因 |
| 處理中 | 🔧 處理中 | 正在實施解決方案 |
| 已解決 | ✅ 已解決 | 問題已解決，待驗證 |
| 已關閉 | 📁 已關閉 | 事件完全關閉 |
| 已歸檔 | 🗄️ 已歸檔 | 事件已歸檔 |
---
**文件狀態**: ⏳ 進行中 / ✅ 已完成 / 📁 已關閉
**下次審查時間**: (YYYY-MM-DD HH:MM)
---
**模板結束** - 請根據實際情況填寫內容

593
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_MAINTENANCE.md
View File

@@ -1,593 +0,0 @@
# MAINTENANCE_<服務名稱>_<計畫類型>_<日期>.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "maintenance"
service: "<服務名稱>"
task: "<計畫類型>"
date: "<YYYY-MM-DD>"
severity: "P2" # P0/P1/P2/P3
status: "planning" # planning/active/completed/cancelled
priority: "P2"
owner: "<負責人姓名>"
created_by: "<創建者姓名>"
created_at: "<YYYY-MM-DD HH:MM>"
version: "1.0"
maintenance_type: "routine" # routine/upgrade/architecture/capacity/security
execution_window: "<YYYY-MM-DD HH:MM - HH:MM>"
estimated_duration: "<分鐘>"
affected_systems:
- "<系統1>"
- "<系統2>"
tags:
- "maintenance"
- "<服務標籤>"
- "<計畫類型標籤>"
related_documents:
- "INCIDENT_<相關事件>.md"
- "CHANGE_<相關變更>.md"
ai_query_hints:
- "如何查詢所有 P2 級別的維護計畫？"
- "如何找到與 <服務> 相關的維護計畫？"
- "如何更新維護計畫狀態？"
- "如何查詢正在執行的維護計畫？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 計畫制定人 | (填寫制定人姓名) |
| 制定時間 | (YYYY-MM-DD) |
| 計畫類型 | 例行維護 / 版本升級 / 架構優化 / 容量擴展 / 安全加固 |
| 計畫狀態 | 📅 規劃中 / 🔧 執行中 / ✅ 已完成 / ❌ 已取消 |
| 計畫週期 | 單次 / 每週 / 每月 / 每季 / 每年 |
| 優先級 | P0/P1/P2/P3 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.2 | 2026-03-29 | 加入 FK 依賴圖範例與標準刪除順序 | OpenCode | OpenCode |
| V1.1 | 2026-03-28 | 加入 AI Agent 優化 (YAML Frontmatter) | OpenCode | OpenCode |
| V1.0 | (日期) | 創建維護計畫 | (姓名) | (工具) |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有 P2 級別的維護計畫
查找: document_type: "maintenance" AND severity: "P2"
# 查詢特定服務的活躍維護計畫
查找: document_type: "maintenance" AND service: "MOMENTRY_CORE" AND status: "planning"
# 查詢正在執行的維護計畫
查找: document_type: "maintenance" AND status: "active"
# 查詢即將執行的維護計畫 (未來 7 天)
查找: document_type: "maintenance" AND execution_window: "next_7_days"
```
### 自動化操作
1. **狀態更新**：當計畫狀態變更時，同時更新 YAML frontmatter 中的 `status` 和 Markdown 表格中的狀態
2. **目錄移動**：根據狀態自動移動文件到相應目錄：
- `planning` → `_active/`
- `active` → `_active/`
- `completed` → `_completed/`
- `cancelled` → `_completed/`
3. **通知觸發**：根據優先級和狀態自動發送通知
4. **關聯文件更新**：自動更新相關事件和變更文件的狀態
### 數據提取
```python
# Python 示例：提取維護計畫元數據
import yaml
import re
def extract_maintenance_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
### 狀態同步規則
| YAML status | 表格狀態 | 目錄位置 | 說明 |
|-------------|----------|----------|------|
| planning | 📅 規劃中 | _active/ | 計畫制定中 |
| active | 🔧 執行中 | _active/ | 正在執行 |
| completed | ✅ 已完成 | _completed/ | 執行完成 |
| cancelled | ❌ 已取消 | _completed/ | 計畫取消 |
---
## 計畫概述
### 基本資訊
| 項目 | 內容 |
|------|------|
| **計畫標題** | (簡短描述維護計畫) |
| **計畫目的** | 預防問題 / 性能優化 / 安全性提升 / 合規要求 / 技術債務清理 |
| **業務價值** | (計畫帶來的業務價值) |
| **預期成果** | (具體可衡量成果) |
| **影響服務** | (受影響的服務列表) |
### 背景與動機
#### 當前狀態分析
(描述當前系統狀態、存在的問題或改進機會)
#### 改進機會
- **性能方面**: (性能瓶頸或優化空間)
- **穩定性方面**: (已知問題或風險點)
- **安全性方面**: (安全漏洞或合規缺口)
- **可維護性**: (技術債務或架構問題)
#### 觸發因素
| 因素 | 描述 | 緊迫性 |
|------|------|--------|
| (因素1) | (詳細描述) | 高/中/低 |
| (因素2) | (詳細描述) | 高/中/低 |
### 範圍與約束
#### 範圍定義
- **包含項目**:
- (包含的服務/組件)
- (包含的任務)
- **排除項目**:
- (明確排除的內容)
- (超出範圍的項目)
#### 限制條件
| 限制類型 | 限制條件 | 影響 |
|----------|----------|------|
| 時間限制 | (時間窗口) | (影響說明) |
| 資源限制 | (資源限制) | (影響說明) |
| 技術限制 | (技術限制) | (影響說明) |
| 預算限制 | (預算限制) | (影響說明) |
---
## 資料庫依賴分析
### FK 依賴圖範例
執行資料清理前，必須分析資料表之間的 FK 依賴關係，確保按正確順序刪除。
#### 範例：Momentry Core 影片資料
```
┌─────────────┐
│ videos │ ← 主表 (最終刪除)
└──────┬──────┘
│ (file_id)
┌───────────────┼───────────────┐
│ │ │
┌──────┴──────┐ ┌────┴────┐ ┌──────┴──────┐
│ chunks │ │frames │ │pre_chunks │
└──────┬──────┘ └─────────┘ └─────────────┘
│
┌──────┴──────┐
│chunk_vectors│
└─────────────┘
```
#### 標準刪除順序
| 順序 | 資料表 | 說明 |
|------|--------|------|
| 1 | pre_chunks | 無依賴子表 |
| 2 | chunk_vectors | 無依賴子表 |
| 3 | chunks | 依賴 videos.file_id |
| 4 | frames | 依賴 videos.file_id |
| 5 | monitor_jobs | 依賴 videos.id |
| 6 | processor_results | 依賴 videos.id |
| 7 | videos | 主表 |
#### 查詢 FK 依賴 SQL
```sql
-- 查詢特定表格的所有 FK 依賴
SELECT
tc.constraint_name,
tc.table_name,
kcu.column_name,
ccu.table_name AS foreign_table_name
FROM information_schema.table_constraints AS tc
JOIN information_schema.key_column_usage AS kcu
ON tc.constraint_name = kcu.constraint_name
JOIN information_schema.constraint_column_usage AS ccu
ON ccu.constraint_name = tc.constraint_name
WHERE tc.table_name = '<表格名稱>'
AND tc.constraint_type = 'FOREIGN KEY';
```
#### 關聯資料表清單範本
| 序號 | 資料表 | 主鍵 | 外鍵 | 依賴於 | 刪除順序 |
|------|--------|------|------|--------|----------|
| 1 | videos | id | job_id | monitor_jobs | 7 |
| 2 | chunks | id | file_id | videos | 3 |
| 3 | chunk_vectors | id | file_id | videos | 2 |
| 4 | frames | id | file_id | videos | 4 |
| 5 | pre_chunks | id | file_id | videos | 1 |
| 6 | monitor_jobs | id | video_id | videos | 5 |
| 7 | processor_results | id | video_id | videos | 6 |
---
## 詳細計畫
### 總體時間安排
| 階段 | 開始日期 | 結束日期 | 持續時間 | 里程碑 | 負責人 |
|------|----------|----------|----------|--------|--------|
| 規劃階段 | (日期) | (日期) | (天數) | 計畫批准 | (姓名) |
| 準備階段 | (日期) | (日期) | (天數) | 資源就緒 | (姓名) |
| 實施階段 | (日期) | (日期) | (天數) | 實施完成 | (姓名) |
| 驗證階段 | (日期) | (日期) | (天數) | 驗證通過 | (姓名) |
| 收尾階段 | (日期) | (日期) | (天數) | 計畫關閉 | (姓名) |
### 階段詳情
#### 階段 1: 規劃階段
| 任務編號 | 任務描述 | 交付物 | 負責人 | 預計工時 | 狀態 |
|----------|----------|--------|--------|----------|------|
| 1.1 | 需求分析與收集 | 需求文檔 | (姓名) | (小時) | ⏳/✅ |
| 1.2 | 技術方案設計 | 設計文檔 | (姓名) | (小時) | ⏳/✅ |
| 1.3 | 資源需求評估 | 資源清單 | (姓名) | (小時) | ⏳/✅ |
| 1.4 | 風險評估與緩解 | 風險報告 | (姓名) | (小時) | ⏳/✅ |
| 1.5 | 計畫審核與批准 | 批准文件 | (姓名) | (小時) | ⏳/✅ |
#### 階段 2: 準備階段
| 任務編號 | 任務描述 | 交付物 | 負責人 | 預計工時 | 狀態 |
|----------|----------|--------|--------|----------|------|
| 2.1 | 環境準備 | 環境清單 | (姓名) | (小時) | ⏳/✅ |
| 2.2 | 工具與腳本準備 | 工具包 | (姓名) | (小時) | ⏳/✅ |
| 2.3 | 備份與回滾準備 | 備份驗證報告 | (姓名) | (小時) | ⏳/✅ |
| 2.4 | 團隊培訓與溝通 | 培訓材料 | (姓名) | (小時) | ⏳/✅ |
| 2.5 | 測試計畫制定 | 測試案例 | (姓名) | (小時) | ⏳/✅ |
#### 階段 3: 實施階段
| 任務編號 | 任務描述 | 關鍵操作 | 預計時間 | 負責人 | 狀態 |
|----------|----------|----------|----------|--------|------|
| 3.1 | 預實施檢查 | 系統健康檢查 | (時間) | (姓名) | ⏳/✅ |
| 3.2 | 實施任務1 | ```(操作命令)``` | (時間) | (姓名) | ⏳/✅ |
| 3.3 | 實施任務2 | ```(操作命令)``` | (時間) | (姓名) | ⏳/✅ |
| 3.4 | 實施任務3 | ```(操作命令)``` | (時間) | (姓名) | ⏳/✅ |
| 3.5 | 實施驗證 | 基礎功能驗證 | (時間) | (姓名) | ⏳/✅ |
#### 階段 4: 驗證階段
| 任務編號 | 任務描述 | 驗證標準 | 驗證方法 | 負責人 | 狀態 |
|----------|----------|----------|----------|--------|------|
| 4.1 | 功能驗證 | 所有功能正常 | 測試用例執行 | (姓名) | ⏳/✅ |
| 4.2 | 性能驗證 | 性能指標達標 | 性能測試 | (姓名) | ⏳/✅ |
| 4.3 | 安全驗證 | 安全檢查通過 | 安全掃描 | (姓名) | ⏳/✅ |
| 4.4 | 穩定性驗證 | 系統穩定運行 | 監控觀察 | (姓名) | ⏳/✅ |
#### 階段 5: 收尾階段
| 任務編號 | 任務描述 | 交付物 | 負責人 | 預計工時 | 狀態 |
|----------|----------|--------|--------|----------|------|
| 5.1 | 文檔更新 | 更新後的文檔 | (姓名) | (小時) | ⏳/✅ |
| 5.2 | 經驗總結 | 經驗教訓報告 | (姓名) | (小時) | ⏳/✅ |
| 5.3 | 監控配置更新 | 監控規則更新 | (姓名) | (小時) | ⏳/✅ |
| 5.4 | 計畫評估 | 成果評估報告 | (姓名) | (小時) | ⏳/✅ |
| 5.5 | 計畫關閉 | 關閉確認 | (姓名) | (小時) | ⏳/✅ |
### 關鍵路徑分析
| 路徑 | 關鍵任務 | 依賴關係 | 緩衝時間 | 風險 |
|------|----------|----------|----------|------|
| (路徑1) | (任務列表) | (依賴任務) | (天數) | (風險描述) |
| (路徑2) | (任務列表) | (依賴任務) | (天數) | (風險描述) |
---
## 資源需求
### 人力資源
| 角色 | 人員 | 投入時間 | 主要職責 | 技能要求 |
|------|------|----------|----------|----------|
| 計畫負責人 | (姓名) | (小時) | 整體協調和決策 | 專案管理、技術架構 |
| 技術負責人 | (姓名) | (小時) | 技術方案和實施 | 相關技術專長 |
| 實施工程師 | (姓名) | (小時) | 具體實施操作 | 操作技能 |
| 測試工程師 | (姓名) | (小時) | 測試驗證 | 測試技能 |
| 監控工程師 | (姓名) | (小時) | 監控配置 | 監控技能 |
### 系統資源
| 資源類型 | 規格要求 | 數量 | 使用時間 | 可用性確認 |
|----------|----------|------|----------|------------|
| 測試環境 | (規格) | (數量) | (時間段) | ✅/❌ |
| 備份存儲 | (容量) | (數量) | (時間段) | ✅/❌ |
| 網絡資源 | (帶寬) | (數量) | (時間段) | ✅/❌ |
| 工具許可 | (授權類型) | (數量) | (時間段) | ✅/❌ |
### 預算需求
| 項目 | 預算類別 | 估算金額 | 實際金額 | 備註 |
|------|----------|----------|----------|------|
| (項目1) | 人力成本 | (金額) | (金額) | (備註) |
| (項目2) | 硬件成本 | (金額) | (金額) | (備註) |
| (項目3) | 軟件成本 | (金額) | (金額) | (備註) |
| (項目4) | 其他成本 | (金額) | (金額) | (備註) |
| **總計** | | **(總金額)** | **(總金額)** | |
---
## 風險管理
### 風險識別與評估
| 風險編號 | 風險描述 | 可能性 | 影響程度 | 風險等級 | 觸發條件 |
|----------|----------|--------|----------|----------|----------|
| R001 | (風險描述) | 高/中/低 | 高/中/低 | 高/中/低 | (觸發條件) |
| R002 | (風險描述) | 高/中/低 | 高/中/低 | 高/中/低 | (觸發條件) |
### 風險緩解措施
| 風險編號 | 預防措施 | 應急措施 | 負責人 | 狀態 |
|----------|----------|----------|--------|------|
| R001 | (預防措施) | (應急措施) | (姓名) | ⏳/✅ |
| R002 | (預防措施) | (應急措施) | (姓名) | ⏳/✅ |
### 應急預案
| 應急場景 | 觸發條件 | 應急步驟 | 溝通計劃 | 負責人 |
|----------|----------|----------|----------|--------|
| 實施失敗 | 關鍵任務失敗無法繼續 | 1. 停止實施<br>2. 執行回滾<br>3. 問題分析 | 立即通知計畫負責人和相關人員 | (姓名) |
| 系統中斷 | 服務不可用超過預期時間 | 1. 切換到備用方案<br>2. 優先恢復服務<br>3. 調整計畫 | 通知所有受影響用戶和管理層 | (姓名) |
| 數據問題 | 數據丟失或損壞 | 1. 停止操作<br>2. 從備份恢復<br>3. 數據驗證 | 通知數據管理員和業務負責人 | (姓名) |
### 溝通計劃
| 溝通時機 | 溝通對象 | 溝通方式 | 溝通內容 | 負責人 |
|----------|----------|----------|----------|--------|
| 計畫開始前 | 所有相關方 | 郵件/會議 | 計畫通知、時間安排、影響說明 | (姓名) |
| 每日進度 | 實施團隊 | 站會/報告 | 當日進度、問題、明日計畫 | (姓名) |
| 里程碑達成 | 管理層 | 報告/演示 | 里程碑成果、下一步計畫 | (姓名) |
| 問題發生 | 應急團隊 | 即時通訊/電話 | 問題描述、影響、應急措施 | (姓名) |
| 計畫完成 | 所有相關方 | 郵件/公告 | 計畫總結、成果、經驗教訓 | (姓名) |
---
## 成功標準與衡量指標
### 成功標準
| 標準編號 | 成功標準 | 衡量方法 | 目標值 | 權重 |
|----------|----------|----------|--------|------|
| S001 | (標準描述) | (衡量方法) | (目標值) | (權重%) |
| S002 | (標準描述) | (衡量方法) | (目標值) | (權重%) |
### 關鍵績效指標 (KPI)
| KPI 類別 | 指標名稱 | 當前值 | 目標值 | 衡量頻率 |
|----------|----------|--------|--------|----------|
| 性能指標 | (指標名稱) | (數值) | (數值) | (頻率) |
| 穩定性指標 | (指標名稱) | (數值) | (數值) | (頻率) |
| 安全性指標 | (指標名稱) | (數值) | (數值) | (頻率) |
| 成本指標 | (指標名稱) | (數值) | (數值) | (頻率) |
### 驗收標準
| 驗收項目 | 驗收標準 | 驗證方法 | 驗收人 | 狀態 |
|----------|----------|----------|--------|------|
| (項目1) | (標準描述) | (驗證方法) | (姓名) | ⏳/✅ |
| (項目2) | (標準描述) | (驗證方法) | (姓名) | ⏳/✅ |
---
## 執行記錄
### 實際進度追蹤
| 日期 | 計畫進度 | 實際進度 | 偏差分析 | 問題記錄 | 負責人 |
|------|----------|----------|----------|----------|--------|
| (日期) | (計畫%) | (實際%) | (偏差原因) | (問題) | (姓名) |
| (日期) | (計畫%) | (實際%) | (偏差原因) | (問題) | (姓名) |
### 問題與變更記錄
| 問題編號 | 問題描述 | 影響 | 解決方案 | 解決時間 | 狀態 |
|----------|----------|------|----------|----------|------|
| P001 | (問題描述) | (影響程度) | (解決方案) | (時間) | ✅/❌ |
| P002 | (問題描述) | (影響程度) | (解決方案) | (時間) | ✅/❌ |
| 變更編號 | 變更內容 | 變更原因 | 影響評估 | 批准人 | 日期 |
|----------|----------|----------|----------|--------|------|
| C001 | (變更內容) | (變更原因) | (影響評估) | (姓名) | (日期) |
| C002 | (變更內容) | (變更原因) | (影響評估) | (姓名) | (日期) |
### 資源使用記錄
| 資源類型 | 計畫用量 | 實際用量 | 偏差 | 原因分析 |
|----------|----------|----------|------|----------|
| 人力 (人時) | (數值) | (數值) | (+/-%) | (原因) |
| 硬件成本 | (金額) | (金額) | (+/-%) | (原因) |
| 軟件成本 | (金額) | (金額) | (+/-%) | (原因) |
### 成果記錄
| 成果類別 | 成果描述 | 量化指標 | 達成情況 | 證據 |
|----------|----------|----------|----------|------|
| 技術成果 | (成果描述) | (指標) | ✅/❌ | (證據) |
| 業務成果 | (成果描述) | (指標) | ✅/❌ | (證據) |
| 過程成果 | (成果描述) | (指標) | ✅/❌ | (證據) |
---
## 計畫評估與總結
### 目標達成情況
| 目標 | 計畫值 | 實際值 | 達成率 | 評估 |
|------|--------|--------|--------|------|
| (目標1) | (數值) | (數值) | (%) | (評估) |
| (目標2) | (數值) | (數值) | (%) | (評估) |
### 效益分析
| 效益維度 | 預期效益 | 實際效益 | 差異分析 |
|----------|----------|----------|----------|
| 技術效益 | (預期) | (實際) | (分析) |
| 業務效益 | (預期) | (實際) | (分析) |
| 成本效益 | (預期) | (實際) | (分析) |
| 風險降低 | (預期) | (實際) | (分析) |
### 經驗教訓
#### 成功因素
| 因素 | 具體表現 | 可複用經驗 |
|------|----------|------------|
| (因素1) | (表現) | (經驗) |
| (因素2) | (表現) | (經驗) |
#### 改進機會
| 改進領域 | 問題描述 | 改進建議 | 優先級 |
|----------|----------|----------|--------|
| (領域1) | (問題) | (建議) | 高/中/低 |
| (領域2) | (問題) | (建議) | 高/中/低 |
#### 最佳實踐
| 實踐領域 | 最佳實踐 | 適用場景 |
|----------|----------|----------|
| (領域1) | (實踐) | (場景) |
| (領域2) | (實踐) | (場景) |
### 後續行動建議
| 行動項 | 描述 | 負責人 | 建議完成時間 | 優先級 |
|--------|------|--------|--------------|--------|
| (行動1) | (描述) | (姓名) | (日期) | 高/中/低 |
| (行動2) | (描述) | (姓名) | (日期) | 高/中/低 |
---
## 簽核與批准
### 計畫審核
| 審核階段 | 審核人 | 部門 | 審核意見 | 審核狀態 | 日期 |
|----------|--------|------|----------|----------|------|
| 技術審核 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 資源審核 | (姓名) | 資源部 | (意見) | ⏳/✅ | (日期) |
| 風險審核 | (姓名) | 風險部 | (意見) | ⏳/✅ | (日期) |
### 計畫批准
| 角色 | 姓名 | 部門 | 批准意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 計畫制定人 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 專案負責人 | (姓名) | 管理部 | (意見) | ⏳/✅ | (日期) |
### 完成確認
| 角色 | 姓名 | 部門 | 確認意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 實施負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 驗證負責人 | (姓名) | 測試部 | (意見) | ⏳/✅ | (日期) |
| 業務負責人 | (姓名) | 業務部 | (意見) | ⏳/✅ | (日期) |
---
## 附件
### 參考文件
| 文件 | 用途 | 位置 |
|------|------|------|
| (文件1) | (用途) | (路徑) |
| (文件2) | (用途) | (路徑) |
### 技術文件
| 文件 | 內容 | 版本 |
|------|------|------|
| 設計文檔 | (文件名) | (版本) |
| 測試報告 | (文件名) | (版本) |
| 配置清單 | (文件名) | (版本) |
### 工具與腳本
```bash
# 主要實施腳本
(腳本內容)
```
### 監控數據報告
| 監控指標 | 維護前 | 維護後 | 變化率 | 分析 |
|----------|--------|--------|--------|------|
| (指標1) | (數值) | (數值) | (+/-%) | (分析) |
| (指標2) | (數值) | (數值) | (+/-%) | (分析) |
---
## 附錄
### 計畫類型定義
| 類型 | 代碼 | 說明 | 審核要求 | 執行頻率 |
|------|------|------|----------|----------|
| 例行維護 | ROUTINE | 定期檢查和維護 | 技術審核 | 每週/每月 |
| 版本升級 | UPGRADE | 軟件版本更新 | 技術+安全審核 | 按需 |
| 架構優化 | ARCHITECTURE | 系統架構改進 | 技術+架構審核 | 每季/每年 |
| 容量擴展 | CAPACITY | 資源擴容 | 技術+資源審核 | 按需 |
| 安全加固 | SECURITY | 安全增強 | 安全審核 | 每月/每季 |
### 優先級定義
| 優先級 | 代碼 | 處理時限 | 資源分配 | 審核級別 |
|--------|------|----------|----------|----------|
| 緊急 | P0 | 立即處理 | 最高優先級 | 管理層 |
| 高 | P1 | 1-3天內 | 高優先級 | 技術負責人 |
| 中 | P2 | 1-2週內 | 正常優先級 | 技術審核 |
| 低 | P3 | 1個月內 | 低優先級 | 團隊審核 |
### 狀態標記說明
| 狀態 | 標記 | 說明 |
|------|------|------|
| 規劃中 | 📅 規劃中 | 計畫正在制定階段 |
| 審核中 | 📋 審核中 | 等待審核批准 |
| 執行中 | 🔧 執行中 | 正在執行計畫 |
| 已完成 | ✅ 已完成 | 計畫成功完成 |
| 已取消 | ❌ 已取消 | 計畫被取消 |
| 延期 | ⏰ 延期 | 計畫延期執行 |
---
**計畫狀態**: 📅 規劃中 / 🔧 執行中 / ✅ 已完成 / ❌ 已取消
**下次審查日期**: (YYYY-MM-DD)
---
**模板結束** - 請根據實際情況填寫內容

442
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_RCA.md
View File

@@ -1,442 +0,0 @@
# RCA_<服務名稱>_<問題簡述>_<日期>.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "rca"
service: "<服務名稱>"
problem: "<問題簡述>"
date: "<YYYY-MM-DD>"
severity: "P0" # P0/P1/P2/P3/P4
status: "active" # active/completed/archived
current_state: "investigating" # pending/investigating/resolving/resolved/closed
owner: "<負責人姓名>"
created_by: "<創建者姓名>"
created_at: "<YYYY-MM-DD HH:MM>"
version: "1.0"
rca_type: "technical" # technical/process/human_error
root_cause: "<根本原因描述>"
resolution: "<解決方案描述>"
prevention: "<預防措施>"
tags:
- "rca"
- "<服務標籤>"
- "<問題類型>"
related_documents:
- "INCIDENT_<相關事件>.md"
- "CHANGE_<相關變更>.md"
ai_query_hints:
- "如何查詢所有 P0 級別的 RCA？"
- "如何找到與 n8n 相關的所有 RCA？"
- "如何更新 RCA 狀態？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 建立者 | (填寫分析人員姓名) |
| 建立時間 | (填寫建立日期 YYYY-MM-DD) |
| 文件版本 | V1.0 |
| 嚴重等級 | P0/P1/P2/P3/P4 |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有 P0/P1 級別的 RCA
查找: document_type: "rca" AND (severity: "P0" OR severity: "P1")
# 查詢特定服務的活躍 RCA
查找: document_type: "rca" AND service: "n8n" AND status: "active"
# 查詢需要審核的 RCA
查找: document_type: "rca" AND current_state: "resolved" AND status: "active"
```
### 自動化操作
1. **狀態更新**：當 RCA 完成時，更新 `current_state` 和 `status`
2. **目錄移動**：根據狀態自動移動文件到相應目錄 (`_active/`, `_completed/`, `_archived/`)
3. **通知觸發**：根據嚴重等級自動發送通知
4. **關聯文件更新**：自動更新相關事件和變更文件的狀態
### 數據提取
```python
# Python 示例：提取 RCA 元數據
import yaml
import re
def extract_rca_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建文件 | (姓名) | (工具) |
---
## 概述
(簡要描述問題和影響範圍)
---
## 事件摘要
### 基本資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | (簡短描述事件) |
| **影響服務** | (受影響的服務列表) |
| **嚴重等級** | P0/P1/P2/P3/P4 |
| **發現時間** | (YYYY-MM-DD HH:MM) |
| **解決時間** | (YYYY-MM-DD HH:MM) |
| **影響範圍** | (受影響的用戶、功能、數據等) |
| **停機時間** | (總停機時間) |
### 時間線摘要
| 時間 | 事件 | 操作 |
|------|------|------|
| (時間) | (事件描述) | (採取的操作) |
| (時間) | (事件描述) | (採取的操作) |
---
## 調查過程
### 調查步驟
| 步驟 | 操作 | 結果 | 發現 |
|------|------|------|------|
| 1 | (檢查項目) | (結果) | (重要發現) |
| 2 | (檢查項目) | (結果) | (重要發現) |
| 3 | (檢查項目) | (結果) | (重要發現) |
### 收集證據
| 證據類型 | 檔案/日誌 | 重要內容 |
|----------|-----------|----------|
| 系統日誌 | (檔案路徑) | (關鍵訊息) |
| 應用日誌 | (檔案路徑) | (關鍵訊息) |
| 監控數據 | (監控圖表) | (異常指標) |
| 配置檔案 | (檔案路徑) | (問題配置) |
### 服務狀態檢查
| 服務 | 狀態 | 配置 | 版本 |
|------|------|------|------|
| (服務名稱) | ✅/❌ | (配置摘要) | (版本號) |
| (服務名稱) | ✅/❌ | (配置摘要) | (版本號) |
---
## 根本原因分析
### 主要根本原因
#### 原因 1: (原因標題)
| 項目 | 內容 |
|------|------|
| **原因描述** | (詳細描述原因) |
| **證據** | (支持證據) |
| **影響鏈** | (原因如何導致問題) |
| **根本性** | 根本原因/表面原因 |
**技術細節**:
```代碼或配置示例
```
#### 原因 2: (原因標題)
| 項目 | 內容 |
|------|------|
| **原因描述** | (詳細描述原因) |
| **證據** | (支持證據) |
| **影響鏈** | (原因如何導致問題) |
| **根本性** | 根本原因/表面原因 |
**技術細節**:
```代碼或配置示例
```
### 次要根本原因
| 原因 | 描述 | 影響 | 改進建議 |
|------|------|------|----------|
| (原因) | (描述) | (影響程度) | (建議) |
| (原因) | (描述) | (影響程度) | (建議) |
### 根本原因總結
| 原因類型 | 原因數量 | 影響程度 | 優先級 |
|----------|----------|----------|--------|
| 主要原因 | (數量) | 高/中/低 | 1 |
| 次要原因 | (數量) | 高/中/低 | 2 |
| 系統因素 | (數量) | 高/中/低 | 3 |
---
## 解決方案與實施
### 解決方案設計
#### 方案 1: (方案標題)
| 項目 | 內容 |
|------|------|
| **方案描述** | (詳細解決方案) |
| **實施步驟** | (逐步實施方法) |
| **預期效果** | (解決的問題) |
| **風險評估** | (實施風險) |
| **回滾計畫** | (如果失敗如何回滾) |
**實施命令**:
```bash
# 實施命令示例
```
#### 方案 2: (方案標題) (可選)
| 項目 | 內容 |
|------|------|
| **方案描述** | (詳細解決方案) |
| **實施步驟** | (逐步實施方法) |
| **預期效果** | (解決的問題) |
| **風險評估** | (實施風險) |
| **回滾計畫** | (如果失敗如何回滾) |
### 實施過程
| 時間 | 步驟 | 命令/操作 | 結果 | 驗證 |
|------|------|------------|------|------|
| (時間) | (步驟描述) | (具體命令) | ✅/❌ | (驗證方法) |
| (時間) | (步驟描述) | (具體命令) | ✅/❌ | (驗證方法) |
### 驗證測試
| 測試項目 | 測試方法 | 預期結果 | 實際結果 | 狀態 |
|----------|----------|----------|----------|------|
| (測試1) | (測試步驟) | (預期) | (實際) | ✅/❌ |
| (測試2) | (測試步驟) | (預期) | (實際) | ✅/❌ |
| (測試3) | (測試步驟) | (預期) | (實際) | ✅/❌ |
---
## 預防措施
### 短期措施 (1-7 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
### 中期措施 (8-30 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
### 長期措施 (31-90 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
---
## 影響評估
### 直接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **服務可用性** | ✅/❌/⚠️ | (詳細說明) |
| **數據完整性** | ✅/❌/⚠️ | (詳細說明) |
| **性能影響** | ✅/❌/⚠️ | (詳細說明) |
| **安全性影響** | ✅/❌/⚠️ | (詳細說明) |
### 間接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **用戶體驗** | 高/中/低 | (詳細說明) |
| **業務影響** | 高/中/低 | (詳細說明) |
| **聲譽影響** | 高/中/低 | (詳細說明) |
| **成本影響** | 高/中/低 | (詳細說明) |
### 量化指標
| 指標 | 事件前 | 事件中 | 事件後 | 變化 |
|------|------|------|------|------|
| (指標1) | (數值) | (數值) | (數值) | (+/-%) |
| (指標2) | (數值) | (數值) | (數值) | (+/-%) |
| (指標3) | (數值) | (數值) | (數值) | (+/-%) |
---
## 經驗教訓
### 學到的教訓
| 教訓類別 | 具體教訓 | 改進措施 |
|----------|----------|----------|
| **技術方面** | (技術教訓) | (具體改進) |
| **流程方面** | (流程教訓) | (具體改進) |
| **溝通方面** | (溝通教訓) | (具體改進) |
| **管理方面** | (管理教訓) | (具體改進) |
### 最佳實踐建立
| 實踐領域 | 最佳實踐 | 實施狀態 |
|----------|----------|----------|
| **監控警報** | (監控改進) | ⏳/✅ |
| **容量規劃** | (容量管理) | ⏳/✅ |
| **變更管理** | (變更流程) | ⏳/✅ |
| **災難恢復** | (恢復計畫) | ⏳/✅ |
### 知識庫更新
| 更新項目 | 文件 | 更新內容 | 狀態 |
|----------|------|----------|------|
| (項目1) | (文件名) | (更新摘要) | ⏳/✅ |
| (項目2) | (文件名) | (更新摘要) | ⏳/✅ |
---
## 技術細節
### 服務架構圖
```
(相關服務架構圖或描述)
```
### 配置文件變更
| 文件 | 變更前 | 變更後 | 變更原因 |
|------|------|------|----------|
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
### 關鍵命令
```bash
# 診斷命令
(診斷相關命令)
# 修復命令
(修復相關命令)
# 驗證命令
(驗證相關命令)
```
### 監控指標
| 指標 | 正常範圍 | 事件期間 | 當前狀態 |
|------|----------|----------|----------|
| (指標1) | (範圍) | (異常值) | (當前值) |
| (指標2) | (範圍) | (異常值) | (當前值) |
---
## 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| (相關文件1) | (用途) | (路徑) |
| (相關文件2) | (用途) | (路徑) |
| (相關文件3) | (用途) | (路徑) |
---
## 簽核
### 技術審核
| 角色 | 姓名 | 部門 | 審核意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 問題分析員 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 運維工程師 | (姓名) | 運維部 | (意見) | ⏳/✅ | (日期) |
### 管理確認
| 角色 | 姓名 | 部門 | 確認意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 受影響團隊代表 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
| 專案管理人 | (姓名) | 管理部 | (意見) | ⏳/✅ | (日期) |
---
## 附錄
### 測試腳本詳解
```bash
# 完整測試腳本
(測試腳本內容)
```
### 配置參數說明
| 參數 | 說明 | 建議值 | 計算公式 |
|------|------|--------|----------|
| (參數1) | (說明) | (建議值) | (公式) |
| (參數2) | (說明) | (建議值) | (公式) |
### 監控設定建議
```yaml
# Prometheus 監控規則示例
(監控規則)
```
---
**文件狀態**: ⏳ 進行中 / ✅ 已完成 / 📁 已關閉
**下次審查日期**: (YYYY-MM-DD)
---
**AI Agent 備註**
**最後更新**: 2026-03-27
**AI 優化版本**: V1.0
**兼容性**: 向後兼容現有模板
**注意**:
- AI Agent 應優先讀取 YAML frontmatter 獲取結構化數據
- 人類用戶可閱讀 Markdown 表格部分
- 兩部分數據應保持同步

442
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_RCA_AI_OPTIMIZED.md
View File

@@ -1,442 +0,0 @@
# RCA_<服務名稱>_<問題簡述>_<日期>.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "rca"
service: "<服務名稱>"
problem: "<問題簡述>"
date: "<YYYY-MM-DD>"
severity: "P0" # P0/P1/P2/P3/P4
status: "active" # active/completed/archived
current_state: "investigating" # pending/investigating/resolving/resolved/closed
owner: "<負責人姓名>"
created_by: "<創建者姓名>"
created_at: "<YYYY-MM-DD HH:MM>"
version: "1.0"
rca_type: "technical" # technical/process/human_error
root_cause: "<根本原因描述>"
resolution: "<解決方案描述>"
prevention: "<預防措施>"
tags:
- "rca"
- "<服務標籤>"
- "<問題類型>"
related_documents:
- "INCIDENT_<相關事件>.md"
- "CHANGE_<相關變更>.md"
ai_query_hints:
- "如何查詢所有 P0 級別的 RCA？"
- "如何找到與 n8n 相關的所有 RCA？"
- "如何更新 RCA 狀態？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| 建立者 | (填寫分析人員姓名) |
| 建立時間 | (填寫建立日期 YYYY-MM-DD) |
| 文件版本 | V1.0 |
| 嚴重等級 | P0/P1/P2/P3/P4 |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有 P0/P1 級別的 RCA
查找: document_type: "rca" AND (severity: "P0" OR severity: "P1")
# 查詢特定服務的活躍 RCA
查找: document_type: "rca" AND service: "n8n" AND status: "active"
# 查詢需要審核的 RCA
查找: document_type: "rca" AND current_state: "resolved" AND status: "active"
```
### 自動化操作
1. **狀態更新**：當 RCA 完成時，更新 `current_state` 和 `status`
2. **目錄移動**：根據狀態自動移動文件到相應目錄 (`_active/`, `_completed/`, `_archived/`)
3. **通知觸發**：根據嚴重等級自動發送通知
4. **關聯文件更新**：自動更新相關事件和變更文件的狀態
### 數據提取
```python
# Python 示例：提取 RCA 元數據
import yaml
import re
def extract_rca_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建文件 | (姓名) | (工具) |
---
## 概述
(簡要描述問題和影響範圍)
---
## 事件摘要
### 基本資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | (簡短描述事件) |
| **影響服務** | (受影響的服務列表) |
| **嚴重等級** | P0/P1/P2/P3/P4 |
| **發現時間** | (YYYY-MM-DD HH:MM) |
| **解決時間** | (YYYY-MM-DD HH:MM) |
| **影響範圍** | (受影響的用戶、功能、數據等) |
| **停機時間** | (總停機時間) |
### 時間線摘要
| 時間 | 事件 | 操作 |
|------|------|------|
| (時間) | (事件描述) | (採取的操作) |
| (時間) | (事件描述) | (採取的操作) |
---
## 調查過程
### 調查步驟
| 步驟 | 操作 | 結果 | 發現 |
|------|------|------|------|
| 1 | (檢查項目) | (結果) | (重要發現) |
| 2 | (檢查項目) | (結果) | (重要發現) |
| 3 | (檢查項目) | (結果) | (重要發現) |
### 收集證據
| 證據類型 | 檔案/日誌 | 重要內容 |
|----------|-----------|----------|
| 系統日誌 | (檔案路徑) | (關鍵訊息) |
| 應用日誌 | (檔案路徑) | (關鍵訊息) |
| 監控數據 | (監控圖表) | (異常指標) |
| 配置檔案 | (檔案路徑) | (問題配置) |
### 服務狀態檢查
| 服務 | 狀態 | 配置 | 版本 |
|------|------|------|------|
| (服務名稱) | ✅/❌ | (配置摘要) | (版本號) |
| (服務名稱) | ✅/❌ | (配置摘要) | (版本號) |
---
## 根本原因分析
### 主要根本原因
#### 原因 1: (原因標題)
| 項目 | 內容 |
|------|------|
| **原因描述** | (詳細描述原因) |
| **證據** | (支持證據) |
| **影響鏈** | (原因如何導致問題) |
| **根本性** | 根本原因/表面原因 |
**技術細節**:
```代碼或配置示例
```
#### 原因 2: (原因標題)
| 項目 | 內容 |
|------|------|
| **原因描述** | (詳細描述原因) |
| **證據** | (支持證據) |
| **影響鏈** | (原因如何導致問題) |
| **根本性** | 根本原因/表面原因 |
**技術細節**:
```代碼或配置示例
```
### 次要根本原因
| 原因 | 描述 | 影響 | 改進建議 |
|------|------|------|----------|
| (原因) | (描述) | (影響程度) | (建議) |
| (原因) | (描述) | (影響程度) | (建議) |
### 根本原因總結
| 原因類型 | 原因數量 | 影響程度 | 優先級 |
|----------|----------|----------|--------|
| 主要原因 | (數量) | 高/中/低 | 1 |
| 次要原因 | (數量) | 高/中/低 | 2 |
| 系統因素 | (數量) | 高/中/低 | 3 |
---
## 解決方案與實施
### 解決方案設計
#### 方案 1: (方案標題)
| 項目 | 內容 |
|------|------|
| **方案描述** | (詳細解決方案) |
| **實施步驟** | (逐步實施方法) |
| **預期效果** | (解決的問題) |
| **風險評估** | (實施風險) |
| **回滾計畫** | (如果失敗如何回滾) |
**實施命令**:
```bash
# 實施命令示例
```
#### 方案 2: (方案標題) (可選)
| 項目 | 內容 |
|------|------|
| **方案描述** | (詳細解決方案) |
| **實施步驟** | (逐步實施方法) |
| **預期效果** | (解決的問題) |
| **風險評估** | (實施風險) |
| **回滾計畫** | (如果失敗如何回滾) |
### 實施過程
| 時間 | 步驟 | 命令/操作 | 結果 | 驗證 |
|------|------|------------|------|------|
| (時間) | (步驟描述) | (具體命令) | ✅/❌ | (驗證方法) |
| (時間) | (步驟描述) | (具體命令) | ✅/❌ | (驗證方法) |
### 驗證測試
| 測試項目 | 測試方法 | 預期結果 | 實際結果 | 狀態 |
|----------|----------|----------|----------|------|
| (測試1) | (測試步驟) | (預期) | (實際) | ✅/❌ |
| (測試2) | (測試步驟) | (預期) | (實際) | ✅/❌ |
| (測試3) | (測試步驟) | (預期) | (實際) | ✅/❌ |
---
## 預防措施
### 短期措施 (1-7 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
### 中期措施 (8-30 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
### 長期措施 (31-90 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
---
## 影響評估
### 直接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **服務可用性** | ✅/❌/⚠️ | (詳細說明) |
| **數據完整性** | ✅/❌/⚠️ | (詳細說明) |
| **性能影響** | ✅/❌/⚠️ | (詳細說明) |
| **安全性影響** | ✅/❌/⚠️ | (詳細說明) |
### 間接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **用戶體驗** | 高/中/低 | (詳細說明) |
| **業務影響** | 高/中/低 | (詳細說明) |
| **聲譽影響** | 高/中/低 | (詳細說明) |
| **成本影響** | 高/中/低 | (詳細說明) |
### 量化指標
| 指標 | 事件前 | 事件中 | 事件後 | 變化 |
|------|------|------|------|------|
| (指標1) | (數值) | (數值) | (數值) | (+/-%) |
| (指標2) | (數值) | (數值) | (數值) | (+/-%) |
| (指標3) | (數值) | (數值) | (數值) | (+/-%) |
---
## 經驗教訓
### 學到的教訓
| 教訓類別 | 具體教訓 | 改進措施 |
|----------|----------|----------|
| **技術方面** | (技術教訓) | (具體改進) |
| **流程方面** | (流程教訓) | (具體改進) |
| **溝通方面** | (溝通教訓) | (具體改進) |
| **管理方面** | (管理教訓) | (具體改進) |
### 最佳實踐建立
| 實踐領域 | 最佳實踐 | 實施狀態 |
|----------|----------|----------|
| **監控警報** | (監控改進) | ⏳/✅ |
| **容量規劃** | (容量管理) | ⏳/✅ |
| **變更管理** | (變更流程) | ⏳/✅ |
| **災難恢復** | (恢復計畫) | ⏳/✅ |
### 知識庫更新
| 更新項目 | 文件 | 更新內容 | 狀態 |
|----------|------|----------|------|
| (項目1) | (文件名) | (更新摘要) | ⏳/✅ |
| (項目2) | (文件名) | (更新摘要) | ⏳/✅ |
---
## 技術細節
### 服務架構圖
```
(相關服務架構圖或描述)
```
### 配置文件變更
| 文件 | 變更前 | 變更後 | 變更原因 |
|------|------|------|----------|
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
### 關鍵命令
```bash
# 診斷命令
(診斷相關命令)
# 修復命令
(修復相關命令)
# 驗證命令
(驗證相關命令)
```
### 監控指標
| 指標 | 正常範圍 | 事件期間 | 當前狀態 |
|------|----------|----------|----------|
| (指標1) | (範圍) | (異常值) | (當前值) |
| (指標2) | (範圍) | (異常值) | (當前值) |
---
## 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| (相關文件1) | (用途) | (路徑) |
| (相關文件2) | (用途) | (路徑) |
| (相關文件3) | (用途) | (路徑) |
---
## 簽核
### 技術審核
| 角色 | 姓名 | 部門 | 審核意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 問題分析員 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 運維工程師 | (姓名) | 運維部 | (意見) | ⏳/✅ | (日期) |
### 管理確認
| 角色 | 姓名 | 部門 | 確認意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 受影響團隊代表 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
| 專案管理人 | (姓名) | 管理部 | (意見) | ⏳/✅ | (日期) |
---
## 附錄
### 測試腳本詳解
```bash
# 完整測試腳本
(測試腳本內容)
```
### 配置參數說明
| 參數 | 說明 | 建議值 | 計算公式 |
|------|------|--------|----------|
| (參數1) | (說明) | (建議值) | (公式) |
| (參數2) | (說明) | (建議值) | (公式) |
### 監控設定建議
```yaml
# Prometheus 監控規則示例
(監控規則)
```
---
**文件狀態**: ⏳ 進行中 / ✅ 已完成 / 📁 已關閉
**下次審查日期**: (YYYY-MM-DD)
---
**AI Agent 備註**
**最後更新**: 2026-03-27
**AI 優化版本**: V1.0
**兼容性**: 向後兼容現有模板
**注意**:
- AI Agent 應優先讀取 YAML frontmatter 獲取結構化數據
- 人類用戶可閱讀 Markdown 表格部分
- 兩部分數據應保持同步

144
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_RCA_AI_OPTIMIZED_SIMPLE.md
View File

@@ -1,144 +0,0 @@
# RCA_<服務名稱>_<問題簡述>_<日期>.md
<!--
AI AGENT METADATA (YAML Frontmatter)
AI Agent 應優先讀取此區塊的結構化數據
-->
---
document_type: "rca"
service: "<服務名稱>"
problem: "<問題簡述>"
date: "<YYYY-MM-DD>"
severity: "P0" # P0/P1/P2/P3/P4
status: "active" # active/completed/archived
current_state: "investigating" # pending/investigating/resolving/resolved/closed
owner: "<負責人姓名>"
created_by: "<創建者姓名>"
created_at: "<YYYY-MM-DD HH:MM>"
version: "1.0"
tags:
- "incident"
- "<服務標籤>"
- "<問題類型>"
related_documents:
- "INCIDENT_<相關事件>.md"
- "CHANGE_<相關變更>.md"
ai_query_hints:
- "如何查詢所有 P0 級別的 RCA？"
- "如何找到與 n8n 相關的所有 RCA？"
- "如何更新 RCA 狀態？"
---
<!--
HUMAN READABLE SECTION (Markdown Tables)
人類可讀的表格部分，AI Agent 也可解析但優先使用上述 YAML
-->
| 項目 | 內容 |
|------|------|
| **文件類型** | 根本原因分析 (RCA) |
| **相關服務** | <服務列表> |
| **嚴重等級** | P0/P1/P2/P3/P4 |
| **當前狀態** | ⏳ 待處理 / 🔍 調查中 / 🔧 處理中 / ✅ 已解決 / 📁 已關閉 |
| **創建日期** | YYYY-MM-DD |
| **完成日期** | YYYY-MM-DD |
| **負責人** | <姓名> |
| **文件版本** | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建文件 | (姓名) | (工具) |
---
## AI Agent 操作指南
### 快速查詢示例
```yaml
# 查詢所有 P0/P1 級別的 RCA
查找: document_type: "rca" AND (severity: "P0" OR severity: "P1")
# 查詢特定服務的活躍 RCA
查找: document_type: "rca" AND service: "n8n" AND status: "active"
# 查詢需要審核的 RCA
查找: document_type: "rca" AND current_state: "resolved" AND status: "active"
```
### 自動化操作
1. **狀態更新**：當 RCA 完成時，更新 `current_state` 和 `status`
2. **目錄移動**：根據狀態自動移動文件到相應目錄 (`_active/`, `_completed/`, `_archived/`)
3. **通知觸發**：根據嚴重等級自動發送通知
### 數據提取
```python
# Python 示例：提取 RCA 元數據
import yaml
import re
def extract_rca_metadata(file_path):
with open(file_path, 'r') as f:
content = f.read()
# 提取 YAML frontmatter
yaml_match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
if yaml_match:
metadata = yaml.safe_load(yaml_match.group(1))
return metadata
# 備用：解析 Markdown 表格
# ... 表格解析邏輯
```
---
## 概述
(簡要描述問題和影響範圍)
---
## 事件摘要
### 基本資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | (簡短描述事件) |
| **影響服務** | (受影響的服務列表) |
| **嚴重等級** | P0/P1/P2/P3/P4 |
| **發現時間** | (YYYY-MM-DD HH:MM) |
| **解決時間** | (YYYY-MM-DD HH:MM) |
| **影響範圍** | (受影響的用戶、功能、數據等) |
| **停機時間** | (總停機時間) |
### 時間線摘要
| 時間 | 事件 | 操作 |
|------|------|------|
| (時間) | (事件描述) | (採取的操作) |
---
## 調查過程
<!-- 標準調查過程內容 -->
---
## AI Agent 備註
**最後更新**: 2026-03-27
**AI 優化版本**: V1.0
**兼容性**: 向後兼容現有模板
**注意**:
- AI Agent 應優先讀取 YAML frontmatter 獲取結構化數據
- 人類用戶可閱讀 Markdown 表格部分
- 兩部分數據應保持同步

351
docs_v1.0/OPERATIONS/maintenance_records/templates/TEMPLATE_RCA_LEGACY.md
View File

@@ -1,351 +0,0 @@
# RCA_<服務名稱>_<問題簡述>_<日期>.md
| 項目 | 內容 |
|------|------|
| 建立者 | (填寫分析人員姓名) |
| 建立時間 | (填寫建立日期 YYYY-MM-DD) |
| 文件版本 | V1.0 |
| 嚴重等級 | P0/P1/P2/P3/P4 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | (日期) | 創建文件 | (姓名) | (工具) |
---
## 概述
(簡要描述問題和影響範圍)
---
## 事件摘要
### 基本資訊
| 項目 | 內容 |
|------|------|
| **事件標題** | (簡短描述事件) |
| **影響服務** | (受影響的服務列表) |
| **嚴重等級** | P0/P1/P2/P3/P4 |
| **發現時間** | (YYYY-MM-DD HH:MM) |
| **解決時間** | (YYYY-MM-DD HH:MM) |
| **影響範圍** | (受影響的用戶、功能、數據等) |
| **停機時間** | (總停機時間) |
### 時間線摘要
| 時間 | 事件 | 操作 |
|------|------|------|
| (時間) | (事件描述) | (採取的操作) |
| (時間) | (事件描述) | (採取的操作) |
---
## 調查過程
### 調查步驟
| 步驟 | 操作 | 結果 | 發現 |
|------|------|------|------|
| 1 | (檢查項目) | (結果) | (重要發現) |
| 2 | (檢查項目) | (結果) | (重要發現) |
| 3 | (檢查項目) | (結果) | (重要發現) |
### 收集證據
| 證據類型 | 檔案/日誌 | 重要內容 |
|----------|-----------|----------|
| 系統日誌 | (檔案路徑) | (關鍵訊息) |
| 應用日誌 | (檔案路徑) | (關鍵訊息) |
| 監控數據 | (監控圖表) | (異常指標) |
| 配置檔案 | (檔案路徑) | (問題配置) |
### 服務狀態檢查
| 服務 | 狀態 | 配置 | 版本 |
|------|------|------|------|
| (服務名稱) | ✅/❌ | (配置摘要) | (版本號) |
| (服務名稱) | ✅/❌ | (配置摘要) | (版本號) |
---
## 根本原因分析
### 主要根本原因
#### 原因 1: (原因標題)
| 項目 | 內容 |
|------|------|
| **原因描述** | (詳細描述原因) |
| **證據** | (支持證據) |
| **影響鏈** | (原因如何導致問題) |
| **根本性** | 根本原因/表面原因 |
**技術細節**:
```代碼或配置示例
```
#### 原因 2: (原因標題)
| 項目 | 內容 |
|------|------|
| **原因描述** | (詳細描述原因) |
| **證據** | (支持證據) |
| **影響鏈** | (原因如何導致問題) |
| **根本性** | 根本原因/表面原因 |
**技術細節**:
```代碼或配置示例
```
### 次要根本原因
| 原因 | 描述 | 影響 | 改進建議 |
|------|------|------|----------|
| (原因) | (描述) | (影響程度) | (建議) |
| (原因) | (描述) | (影響程度) | (建議) |
### 根本原因總結
| 原因類型 | 原因數量 | 影響程度 | 優先級 |
|----------|----------|----------|--------|
| 主要原因 | (數量) | 高/中/低 | 1 |
| 次要原因 | (數量) | 高/中/低 | 2 |
| 系統因素 | (數量) | 高/中/低 | 3 |
---
## 解決方案與實施
### 解決方案設計
#### 方案 1: (方案標題)
| 項目 | 內容 |
|------|------|
| **方案描述** | (詳細解決方案) |
| **實施步驟** | (逐步實施方法) |
| **預期效果** | (解決的問題) |
| **風險評估** | (實施風險) |
| **回滾計畫** | (如果失敗如何回滾) |
**實施命令**:
```bash
# 實施命令示例
```
#### 方案 2: (方案標題) (可選)
| 項目 | 內容 |
|------|------|
| **方案描述** | (詳細解決方案) |
| **實施步驟** | (逐步實施方法) |
| **預期效果** | (解決的問題) |
| **風險評估** | (實施風險) |
| **回滾計畫** | (如果失敗如何回滾) |
### 實施過程
| 時間 | 步驟 | 命令/操作 | 結果 | 驗證 |
|------|------|------------|------|------|
| (時間) | (步驟描述) | (具體命令) | ✅/❌ | (驗證方法) |
| (時間) | (步驟描述) | (具體命令) | ✅/❌ | (驗證方法) |
### 驗證測試
| 測試項目 | 測試方法 | 預期結果 | 實際結果 | 狀態 |
|----------|----------|----------|----------|------|
| (測試1) | (測試步驟) | (預期) | (實際) | ✅/❌ |
| (測試2) | (測試步驟) | (預期) | (實際) | ✅/❌ |
| (測試3) | (測試步驟) | (預期) | (實際) | ✅/❌ |
---
## 預防措施
### 短期措施 (1-7 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
### 中期措施 (8-30 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
### 長期措施 (31-90 天)
| 措施 | 描述 | 負責人 | 截止日期 | 狀態 |
|------|------|--------|----------|------|
| (措施1) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
| (措施2) | (詳細描述) | (負責人) | (日期) | ⏳/✅ |
---
## 影響評估
### 直接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **服務可用性** | ✅/❌/⚠️ | (詳細說明) |
| **數據完整性** | ✅/❌/⚠️ | (詳細說明) |
| **性能影響** | ✅/❌/⚠️ | (詳細說明) |
| **安全性影響** | ✅/❌/⚠️ | (詳細說明) |
### 間接影響
| 影響維度 | 評估 | 說明 |
|----------|------|------|
| **用戶體驗** | 高/中/低 | (詳細說明) |
| **業務影響** | 高/中/低 | (詳細說明) |
| **聲譽影響** | 高/中/低 | (詳細說明) |
| **成本影響** | 高/中/低 | (詳細說明) |
### 量化指標
| 指標 | 事件前 | 事件中 | 事件後 | 變化 |
|------|------|------|------|------|
| (指標1) | (數值) | (數值) | (數值) | (+/-%) |
| (指標2) | (數值) | (數值) | (數值) | (+/-%) |
| (指標3) | (數值) | (數值) | (數值) | (+/-%) |
---
## 經驗教訓
### 學到的教訓
| 教訓類別 | 具體教訓 | 改進措施 |
|----------|----------|----------|
| **技術方面** | (技術教訓) | (具體改進) |
| **流程方面** | (流程教訓) | (具體改進) |
| **溝通方面** | (溝通教訓) | (具體改進) |
| **管理方面** | (管理教訓) | (具體改進) |
### 最佳實踐建立
| 實踐領域 | 最佳實踐 | 實施狀態 |
|----------|----------|----------|
| **監控警報** | (監控改進) | ⏳/✅ |
| **容量規劃** | (容量管理) | ⏳/✅ |
| **變更管理** | (變更流程) | ⏳/✅ |
| **災難恢復** | (恢復計畫) | ⏳/✅ |
### 知識庫更新
| 更新項目 | 文件 | 更新內容 | 狀態 |
|----------|------|----------|------|
| (項目1) | (文件名) | (更新摘要) | ⏳/✅ |
| (項目2) | (文件名) | (更新摘要) | ⏳/✅ |
---
## 技術細節
### 服務架構圖
```
(相關服務架構圖或描述)
```
### 配置文件變更
| 文件 | 變更前 | 變更後 | 變更原因 |
|------|------|------|----------|
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
| (文件路徑) | ```(舊配置)``` | ```(新配置)``` | (原因) |
### 關鍵命令
```bash
# 診斷命令
(診斷相關命令)
# 修復命令
(修復相關命令)
# 驗證命令
(驗證相關命令)
```
### 監控指標
| 指標 | 正常範圍 | 事件期間 | 當前狀態 |
|------|----------|----------|----------|
| (指標1) | (範圍) | (異常值) | (當前值) |
| (指標2) | (範圍) | (異常值) | (當前值) |
---
## 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| (相關文件1) | (用途) | (路徑) |
| (相關文件2) | (用途) | (路徑) |
| (相關文件3) | (用途) | (路徑) |
---
## 簽核
### 技術審核
| 角色 | 姓名 | 部門 | 審核意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 問題分析員 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 技術負責人 | (姓名) | 技術部 | (意見) | ⏳/✅ | (日期) |
| 運維工程師 | (姓名) | 運維部 | (意見) | ⏳/✅ | (日期) |
### 管理確認
| 角色 | 姓名 | 部門 | 確認意見 | 簽核狀態 | 日期 |
|------|------|------|----------|----------|------|
| 受影響團隊代表 | (姓名) | (部門) | (意見) | ⏳/✅ | (日期) |
| 專案管理人 | (姓名) | 管理部 | (意見) | ⏳/✅ | (日期) |
---
## 附錄
### 測試腳本詳解
```bash
# 完整測試腳本
(測試腳本內容)
```
### 配置參數說明
| 參數 | 說明 | 建議值 | 計算公式 |
|------|------|--------|----------|
| (參數1) | (說明) | (建議值) | (公式) |
| (參數2) | (說明) | (建議值) | (公式) |
### 監控設定建議
```yaml
# Prometheus 監控規則示例
(監控規則)
```
---
**文件狀態**: ⏳ 進行中 / ✅ 已完成 / 📁 已關閉
**下次審查日期**: (YYYY-MM-DD)
---
**模板結束** - 請根據實際情況填寫內容