日誌與診斷
AppPorts 內置日誌系統，記錄應用運行期間的關鍵事件、遷移操作、系統信息和錯誤詳情。當遇到問題時，可導出診斷包並提交至項目 Issues 以協助排查。
日誌記錄內容
啓動會話信息
應用每次啓動時記錄以下信息：
| 項目 | 說明 |
|---|---|
| 會話 ID | 本次運行的唯一標識（8 位 UUID 前綴） |
| 進程 ID | 系統進程標識 |
| Bundle ID | 應用標識符 |
| 應用語言 | 當前選擇的語言代碼 |
| 系統區域 | 系統區域設置標識 |
| 時區 | 當前時區標識 |
| 首選語言列表 | 系統首選語言順序 |
系統診斷信息
| 項目 | 說明 |
|---|---|
| 應用版本 | 版本號與構建號 |
| macOS 版本 | 系統版本及營銷名稱（如 "macOS Sequoia 15.x"） |
| 設備型號 | 型號及友好名稱（如 "MacBook Pro (14-inch, M3 Pro, 2023)"） |
| 處理器信息 | 品牌字符串、核心數、活躍核心數 |
| 物理內存 | 內存總量 |
外部存儲信息
選擇外部存儲卷時記錄：
| 項目 | 說明 |
|---|---|
| 卷名稱 | 存儲卷名稱 |
| 總容量 / 可用空間 | 存儲空間信息 |
| 文件系統格式 | 如 APFS、HFS+、exFAT 等 |
| 接口協議 | USB、Thunderbolt、NVMe/SATA |
| 設備速度 | 傳輸速率信息 |
| 塊大小 | 存儲塊大小 |
| 卷 UUID | 存儲卷唯一標識 |
遷移操作事件
每次遷移操作生成唯一的操作 ID（如 data-migrate-ABCD1234），記錄：
- 操作開始與結束
- 每個步驟的進度（複製、刪除原始目錄、創建符號鏈接、回滾）
- 步驟前後的路徑狀態快照（存在性、權限、大小、符號鏈接目標、不可變標誌）
- 殘留遷移數據檢測與自動恢復
- 文件複製進度、錯誤與重試
遷移性能報告
| 項目 | 說明 |
|---|---|
| 應用名稱 | 遷移的應用名 |
| 數據大小 | 遷移數據量 |
| 耗時 | 遷移持續時間（秒） |
| 傳輸速度 | 傳輸速率（MB/s） |
| 源路徑 / 目標路徑 | 遷移起止路徑 |
錯誤詳情
錯誤日誌包含結構化信息：
| 字段 | 說明 |
|---|---|
| 錯誤描述 | 人類可讀的錯誤說明 |
| 錯誤類型 / 域 / 碼 | NSError 結構化信息 |
| 失敗原因 | 詳細失敗原因 |
| 恢復建議 | 系統提供的恢復建議 |
| 文件路徑 | 涉及的文件路徑 |
| 底層錯誤 | 嵌套錯誤遞歸記錄 |
操作摘要
每個遷移操作生成 OperationSummaryRecord 記錄，保留最近 100 條：
| 字段 | 說明 |
|---|---|
operationID | 操作唯一標識 |
category | 操作類別（app_move、data-migrate、file-copy 等） |
result | 結果（success、failed、rolled_back、success_with_warning） |
errorCode | 錯誤碼（如有） |
startedAt / endedAt | 起止時間 |
durationMs | 耗時（毫秒） |
日誌配置
存儲位置
默認日誌路徑：
text
~/Library/Application Support/AppPorts/AppPorts_Log.txt可通過以下方式自定義：
- 菜單欄 → 日誌 → 設置日誌位置
- 設置 → 日誌設置 → 自定義路徑
日誌格式
text
[2026-05-08 09:30:00] [INFO] [session:a1b2c3d4] [pid:12345] 應用啓動
[2026-05-08 09:30:01] [DIAG] [session:a1b2c3d4] [pid:12345] app_version: 1.6.1 (123)
[2026-05-08 09:30:05] [PERF] [session:a1b2c3d4] [pid:12345] 遷移完成: 2.3 GB, 45.2 MB/s, 52.1s日誌級別
| 級別 | 說明 |
|---|---|
INFO | 一般信息 |
ERROR | 錯誤信息（含結構化錯誤詳情） |
DIAG | 系統診斷信息 |
DISK | 外部存儲卷信息 |
PERF | 遷移性能報告 |
TRACE | 底層路徑狀態與文件夾監控 |
DEBUG | 調試信息（大小計算、嵌套目錄檢查） |
WARN | 警告（殘留遷移數據、恢復模式） |
日誌輪轉
- 默認最大大小：2 MB（可配置：1 MB、5 MB、10 MB、50 MB、100 MB）
- 超出時自動截斷：丟棄較舊的一半行，保留較新的一半
導出診斷包
當遇到問題需要反饋時，請導出診斷包並附帶在 Issue 中。
導出方式
方式一：菜單欄
- 點擊菜單欄 → 日誌 → 導出診斷包
- 選擇保存位置
- 系統自動生成
.zip文件並在 Finder 中打開
方式二：設置頁面
- 打開 AppPorts → 右上角設置
- 找到「日誌設置」區域
- 點擊「導出診斷包」按鈕
- 選擇保存位置
診斷包內容
導出的 AppPorts-Diagnostic-<日期時間>.zip 包含：
| 文件 | 格式 | 說明 |
|---|---|---|
diagnostic-summary.json | JSON | 元數據（會話 ID、版本、區域、時區等） |
diagnostic-summary.txt | 純文本 | 人類可讀的診斷摘要 |
recent-operations.json | JSON | 最近 100 條操作記錄 |
recent-failures.json | JSON | 最近 20 條失敗/警告操作 |
AppPorts_Log.share-safe.txt | 純文本 | 完整日誌（已脫敏） |
隱私保護
診斷包中的日誌文件經過脫敏處理：
| 原始內容 | 替換爲 |
|---|---|
用戶主目錄路徑（如 /Users/john） | /Users/<redacted-user> |
外部存儲卷名（如 /Volumes/MyDrive） | /Volumes/<redacted-volume> |
$HOME 完整路徑 | ~ |
提交 Issue
獲取診斷包後，請按以下步驟提交：
- 訪問項目 Issues 頁面
- 點擊「New Issue」，選擇 Bug 報告模板
- 描述問題現象和復現步驟
- 將診斷包
.zip文件拖拽至附件區域上傳 - 提交 Issue
💡 提高反饋效率
提交 Issue 時附帶診斷包，可顯著加快問題定位速度。診斷包包含完整的操作歷史、錯誤詳情和系統環境信息，開發者無需反覆溝通即可復現和分析問題。