69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 維運：備份、還原與資料庫升級
|
||
|
||
## 備份
|
||
|
||
在專案根目錄執行：
|
||
|
||
```bash
|
||
./scripts/backup.sh
|
||
```
|
||
|
||
腳本會在 `data/backups/YYYYMMDD-HHMMSS/` 建立兩個檔案：
|
||
|
||
- `hub.db`：由正在執行的 SQLite 資料庫建立的一致性備份。
|
||
- `uploads.tar.gz`：Hub 本機上傳的附件。
|
||
|
||
每次備份都會執行 SQLite `integrity_check`、驗證附件壓縮檔，並在 `SHA256SUMS` 記錄雜湊。`data/backups/` 已由 Git 排除。
|
||
|
||
可設定保留與異地複製（例如掛載的 NAS、加密磁碟或 rclone 掛載點）：
|
||
|
||
```bash
|
||
BACKUP_RETENTION_DAYS=30 BACKUP_OFFSITE_DIR=/mnt/nas/mebbling ./scripts/backup.sh
|
||
```
|
||
|
||
在 WSL 主機安裝每日 03:15 排程：
|
||
|
||
```bash
|
||
./scripts/install-backup-cron.sh
|
||
```
|
||
|
||
## 還原
|
||
|
||
先在非正式環境執行還原演練；腳本會驗證雜湊、停止服務、保留原本資料庫副本、還原資料庫與附件後重新啟動：
|
||
|
||
```bash
|
||
CONFIRM_RESTORE=YES ./scripts/restore.sh data/backups/<時間>
|
||
```
|
||
|
||
請始終一起還原資料庫與附件，否則貼文中的附件連結可能失效。
|
||
|
||
## 健康檢查與日誌
|
||
|
||
反向代理或監控服務可呼叫 `GET /api/health`。收到 `200` 且 JSON 的 `ok: true` 表示 Web 與 SQLite 可用；`failedJobs` 可用於設定同步異常告警。
|
||
|
||
容器日誌為 JSON 事件。管理員頁會保留最近的同步錯誤；請定期備份 SQLite，因為錯誤事件和限流狀態同樣位於資料庫。
|
||
|
||
## 附件掃毒
|
||
|
||
Hub 原生附件預設只接受圖片、PDF、純文字與 Markdown。若要串接掃毒服務，設定 `VIRUS_SCAN_URL`；服務應接受檔案內容的 HTTP POST，並回覆 JSON `{ "clean": true }`。設為 `VIRUS_SCAN_REQUIRED=1` 後，掃毒服務逾時或不可用時會拒絕上傳。
|
||
|
||
## Schema migration
|
||
|
||
資料庫 schema 由 `lib/db.ts` 管理。每個欄位 migration 在 `schema_migrations` 表中記錄版本與套用時間，啟動 Web 或 Worker 時會自動執行尚未套用的安全 migration。
|
||
|
||
升級 Mebbling 前請先執行備份。若新版本在測試環境正常運作，再升級正式資料；不支援直接以舊程式碼讀取已升級 schema 的保證。
|
||
|
||
## 資料保存與刪除
|
||
|
||
`NOTIFICATION_RETENTION_DAYS`、`READING_HISTORY_RETENTION_DAYS` 與 `AUDIT_RETENTION_DAYS` 可設定保存天數；`0` 代表無限期保存。Worker 每日清理一次。到期或已使用的邀請連結會自動移除。
|
||
|
||
使用者可在「帳號設定」以目前密碼與 `DELETE` 文字確認刪除帳號及個人資料。若帳號仍擁有來源，必須先轉移或刪除來源，避免誤刪共享內容。
|
||
|
||
## 外部告警
|
||
|
||
設定 `ALERT_WEBHOOK_URL` 後，Worker 會在同步重試耗盡、或簽章 Webhook 超過 7 天未收到事件時發送告警。支援 Discord incoming webhook 或 ntfy topic URL；同一事件每小時最多通知一次。
|
||
|
||
## 監控指標與健康檢查
|
||
|
||
`GET /api/health?probe=live` 只確認程序存活；預設的 `GET /api/health` 是 readiness 檢查，會確認 SQLite 可讀取。Prometheus 格式的 `GET /api/metrics` 提供來源、公開貼文、同步佇列、Webhook 與附件快取的聚合指標。若設定 `METRICS_TOKEN`，請以 `Authorization: Bearer <token>` 抓取。
|