From c6e57a81011100a48198d88f233622e534a0d8de Mon Sep 17 00:00:00 2001
From: root <root@Sora39.localdomain>
Date: Sun, 26 Apr 2026 19:54:46 +0800
Subject: [PATCH] docs: add task tracking record for backup feature

---
 .../2026-04-26-database-backup-snapshot.md    | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/Tasktracking/2026-04-26-database-backup-snapshot.md

diff --git a/docs/Tasktracking/2026-04-26-database-backup-snapshot.md b/docs/Tasktracking/2026-04-26-database-backup-snapshot.md
new file mode 100644
index 00000000..8edf2e50
--- /dev/null
+++ b/docs/Tasktracking/2026-04-26-database-backup-snapshot.md
@@ -0,0 +1,53 @@
+# Task Record
+
+Date: 2026-04-26
+Related Module: database, web, x-ui.sh
+Change Type: Feature
+
+## Background
+
+MariaDB has no backup or snapshot functionality. Users need to create backups, schedule automatic snapshots, export/download backup files, and restore from backups — all operable from the panel UI and x-ui.sh CLI.
+
+## Changes
+
+- Added backup config fields to `AllSetting` entity and `SettingService` (backupEnabled, backupFrequency, backupHour, backupMaxCount)
+- Created `web/service/backup.go` — BackupService with mysqldump/sqlite3 dump, tar.gz archiving, restore with safety backup, retention policy, node role check
+- Created `web/controller/backup.go` — BackupController with 5 API endpoints (create, restore, delete, list, download)
+- Created `web/job/backup_job.go` — BackupJob for scheduled snapshots (hourly/every12h/daily/weekly)
+- Wired up routes in `web/controller/server.go` and job scheduling in `web/web.go`
+- Created `web/html/settings/backup.html` — Backup tab UI with config, manual backup, backup list table
+- Added backup tab to `web/html/settings.html` with Vue.js data/methods
+- Added backup fields to `web/assets/js/model/setting.js`
+- Added `backup` and `restore` CLI subcommands to `main.go`
+- Added `backup`/`restore`/`list-backups` subcommands and db_menu items 17-19 to `x-ui.sh`
+- Added filename validation (regex) to prevent path traversal in backup file operations
+- Exported ValidateBackupFilename for consistent validation across service and controller
+
+## Impact
+
+- New files: web/service/backup.go, web/controller/backup.go, web/job/backup_job.go, web/html/settings/backup.html
+- Modified: web/entity/entity.go, web/service/setting.go, web/controller/server.go, web/web.go, web/html/settings.html, web/assets/js/model/setting.js, main.go, x-ui.sh
+- Database schema: no changes (backup settings stored via existing settings key-value table)
+- API: 5 new endpoints under /panel/api/server/
+- CLI: 2 new subcommands (backup, restore)
+- x-ui.sh: 3 new subcommands, 4 new db_menu items
+- Build: requires CGO_ENABLED=1, go run ./cmd/genassets first
+
+## Verification
+
+- go build ./... — PASS
+- go vet ./... — PASS
+- gofmt -l -w . — PASS
+- go test -race ./database/... — PASS
+- go test -race ./web/service/... — PASS
+- go test -race ./config/... — PASS
+- CGO_ENABLED=1 go build -ldflags "-w -s" -o /tmp/x-ui ./main.go — PASS
+
+## Risks And Follow-Up
+
+- mysqldump/sqlite3 must be installed on target system; x-ui.sh install_mariadb_client can install MariaDB client
+- Large DB backups may be slow; UI has no progress indicator (uses default HTTP timeout)
+- Node role check prevents worker nodes from backup/restore — correct behavior
+- Restore requires panel downtime (systemctl stop/start) — communicated via UI confirmation dialog
+- Safety backups (pre-restore-*.tar.gz) are now visible in backup list and included in retention count
+- exec.Command calls lack timeout; consider adding context.WithTimeout in future iteration