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

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

用途:客戶手冊(T-4.1)「更換儲存後端」章節的素材草稿。本檔是給寫手冊的人用的, 已按客戶讀得懂的語氣寫;收進手冊時可直接採用,或依手冊整體行文調整措辭, 但三條核心警語與其順序不可刪改——它們對應的是三種不同的資料遺失情境。

相關:D14(design.md)、遷移工具 follow-up CM-1279。


§1

背景:出廠預設是什麼

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

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


§2

三條核心警語

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

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

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

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

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

正確順序

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

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

③ 🔴 系統內建檔案(合規框架 PDF)切換後立即不可用

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

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

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

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


§3

給手冊撰寫者的補充說明(此段不進客戶手冊)

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