---
title: 更換儲存後端——客戶手冊警語章素材
feature: FR-065.5
card: CM-1278 (T-5.3)
date: 2026-08-18
status: 完成（素材，待 T-4.1 收進客戶手冊）
---

# 更換儲存後端——客戶手冊警語章素材

> **用途**：客戶手冊（T-4.1）「更換儲存後端」章節的素材草稿。本檔是**給寫手冊的人用的**，
> 已按客戶讀得懂的語氣寫；收進手冊時可直接採用，或依手冊整體行文調整措辭，
> 但**三條核心警語與其順序不可刪改**——它們對應的是三種不同的資料遺失情境。
>
> 相關：D14（`design.md`）、遷移工具 follow-up CM-1279。

---

## 背景：出廠預設是什麼

系統出廠時，檔案（證據、報告、附件、合規框架 PDF）全部存放在**隨系統內建的物件儲存**
（SeaweedFS）裡。這是安裝程式自動設定好的，客戶不需要做任何事。

有些客戶會想改用自己既有的儲存設備（例如公司已有的 S3 相容儲存、NAS 或雲端儲存桶）。
系統支援這件事——但**切換的方式與後果**必須先讀完本章再動手。

---

## 三條核心警語

### ① 切換只影響「之後」上傳的檔案；舊檔仍留在原本的儲存

切換儲存後端之後，**新上傳**的檔案會進到新的儲存；**先前已經上傳**的檔案仍然躺在
原本的儲存裡，系統也**仍然讀得到**它們——因為每個檔案在資料庫裡都記著「我當初存在
哪一種儲存」，讀取時會依此找到對應的設定。

所以切換當下不會有任何東西壞掉，畫面上也看不出差別。這是好事，但也正是下一條警語
容易被忽略的原因。

### ② 舊的儲存要下線之前，**必須先把檔案搬過去**，否則永久遺失

承上：舊檔還在舊儲存裡。如果客戶在切換之後把舊的儲存設備關機、刪除、或回收，
那些檔案就**永久消失**了——資料庫裡的紀錄還在（檔名、上傳者、時間都看得到），
但點下去下載不到任何東西。

**正確順序**：
1. 先設定新的儲存後端
2. 把舊儲存內的檔案**完整搬移**到新儲存（保持相同的檔案路徑／key）
3. 驗證：隨機挑幾個較舊的檔案，實際點開下載確認讀得到
4. 確認無誤後，才可以將舊儲存下線

> 目前系統**沒有內建**的一鍵搬移工具（規劃中）。需要搬移時請聯繫原廠協助，
> 或由貴公司的維運人員以儲存設備自身的同步工具（如 S3 相容儲存的 mirror／sync 指令）
> 執行，**務必保持檔案路徑不變**。

### ③ 🔴 系統內建檔案（合規框架 PDF）切換後**立即**不可用

這一條與前兩條的行為**不同**，也是最容易出事的一條。

一般使用者上傳的檔案，系統是「看檔案自己記的儲存位置」去讀（所以切換後舊檔照樣讀得到，
見警語 ①）。但**系統內建的檔案**——最典型的就是合規框架的 PDF 原文——走的是另一條路徑：
它們讀的是「**當下**設定的儲存後端」，不看檔案自己記的位置。

結果是：**切換儲存後端的那一刻，合規框架的 PDF 預覽立刻打不開**（顯示空白頁，
沒有錯誤訊息）。不需要等到舊儲存下線，切換完成當下就會發生。

**因此，切換前必須先把系統內建檔案搬到新儲存**。這些檔案在系統出廠時就隨安裝包一起
附上並灌入內建儲存，若不確定有哪些、放在哪裡，請聯繫原廠取得清單。

---

## 給手冊撰寫者的補充說明（此段不進客戶手冊）

- 警語 ③ 的技術成因：`storage_scope=system` 的檔案，讀取端走
  `_load_system_config()` → 「root tenant 當下的 STORAGE_CONFIG」建 adapter，
  **不經過** customer-scope 那條「依檔案自記 storage_type 挑同型設定」的邏輯
  （`ManagedFileUploadService._adapter_for_uid` 的分岔）。這是設計上的取捨而非缺陷
  ——系統檔本來就該有單一權威來源——但對客戶而言後果是「切換即斷」，故必須警語。
- 警語 ② 提到的「搬移工具」＝ follow-up **CM-1279**。該卡完成後，本章應改寫成
  指向該工具的操作步驟，並把「聯繫原廠」降為備援說明。
- 三條警語的排序有意義：① 建立「切換不會立刻壞」的正確預期 → ② 點出這個預期的陷阱
  （不壞不代表可以丟）→ ③ 打破預期的例外（有一類東西是會立刻壞的）。
  順序調換會讓 ③ 看起來像 ② 的重複而被讀者略過。