diff --git a/README.md b/README.md index a9732d3..b35dfcf 100644 --- a/README.md +++ b/README.md @@ -2,506 +2,197 @@ English | äž­æ–‡

-

🛡 BackupX

+

BackupX

- Self-hosted Server Backup Management Platform with Web UI -

-

- Features • - Quick Start • - Configuration • - Architecture • - Cluster • - Development • - API + 自托管服务噚倇仜管理平台
+ 䞀䞪二进制䞀条呜什管奜䜠所有服务噚的倇仜。

Stars Release - Go + Go React - TypeScript SQLite License - Issues

--- -BackupX 是䞀䞪面向 **Linux / macOS 服务噚**的自托管倇仜管理平台。通过䌁䞚级 Web 控制台蜻束配眮目圕倇仜、数据库倇仜并将倇仜文件安党存傚到阿里云 OSS、腟讯云 COS、䞃牛云 Kodo、Google Drive、S3 兌容存傚、WebDAV、FTP/FTPS 或本地磁盘。 + + + + + + + + + +
仪衚盘倇仜任务
存傚目标倇仜记圕
-支持 **倚节点集矀管理**可统䞀管控分垃圚䞍同服务噚䞊的倇仜任务。 +## 功胜亮点 -> **适甚人矀**拥有 Linux 服务噚的䞪人匀发者 / 小团队 / 䌁䞚运绎 - -## Screenshots - -### 登圕页面 -![登圕页面](screenshots/login.png) - -### 仪衚盘 -![仪衚盘](screenshots/dashboard.png) - -### 倇仜任务 -![倇仜任务](screenshots/backup-tasks.png) - -### 倇仜记圕 -![倇仜记圕](screenshots/backup-records.png) - -### 存傚目标 -![存傚目标](screenshots/storage-targets.png) - -### 节点管理 -![节点管理](screenshots/nodes.png) - -### 通知配眮 -![通知配眮](screenshots/notifications.png) - -### 系统讟眮 -![系统讟眮](screenshots/settings.png) - -## Features - -### 📊 倚种倇仜类型 -- **文件/目圕** — 支持倚源路埄倇仜自定义排陀规则劂 `node_modules`、`*.log` -- **MySQL** — 通过 `mysqldump` 原生工具 -- **SQLite** — 安党文件拷莝 -- **PostgreSQL** — 通过 `pg_dump` 原生工具 -- **SAP HANA** — 通过 `hdbsql+backint` 支持倚租户数据库 - -### ☁ 倚云存傚后端 -| 厂商 | 类型 | 诎明 | -|------|------|------| -| 🇚🇳 **阿里云 OSS** | `aliyun_oss` | 自劚组装 Endpoint支持内眑䌠蟓 | -| 🇚🇳 **腟讯云 COS** | `tencent_cos` | 自劚组装 Endpoint | -| 🇚🇳 **䞃牛云 Kodo** | `qiniu_kodo` | 6 倧区域粟确映射 | -| 🌍 **S3 Compatible** | `s3` | AWS S3 / MinIO / Cloudflare R2 等 | -| 🌍 **Google Drive** | `google_drive` | 完敎 OAuth 2.0 授权流皋 | -| 🌍 **WebDAV** | `webdav` | 坚果云 / Nextcloud 等 | -| 🌍 **FTP / FTPS** | `ftp` | 标准 FTP 协议支持 Explicit TLS 加密 | -| 💟 **本地磁盘** | `local_disk` | 倇仜到服务噚本地目圕 | - -> 囜内云厂商仅需填写 **Region** 和 **AccessKey**系统自劚完成 Endpoint 组装底层倍甚 S3 匕擎零额倖䟝赖。 - -### 🖥 集矀管理 (Master-Agent) -- **节点管理** — 泚册远皋服务噚节点Token 讀证 -- **本机节点** — 自劚创建单机甚户零感知升级 -- **目圕浏览** — 可视化文件树选择倇仜源路埄告别手劚蟓入 -- **Agent 心跳** — 节点圚线状态实时监控 -- **任务标筟** — 按标筟/节点分类管理倇仜任务 - -### ⏰ 自劚化䞎调床 -- Cron 衚蟟匏定时调床 -- 可视化 Cron 猖蟑噚 -- 自劚保留策略按倩数 / 按仜数过期枅理 -- 最倧并发倇仜数限制 - -### 🔐 安党 -- JWT 讀证 + bcrypt 密码存傚 -- AES-256-GCM 加密存傚敏感配眮数据库密码、OAuth Token -- 可选倇仜文件加密 -- 登圕限流防暎力砎解 -- 节点 Token 讀证䞀次性星瀺安党䌠蟓 -- CLI 密码重眮Docker 甚户通过 `docker exec` 执行无需邮件扟回 - -### 📊 监控䞎通知 -- 仪衚盘统计成功率、存傚甚量、倇仜趋势囟衚 -- 邮件 / Webhook / Telegram 通知 -- 实时倇仜执行日志 (SSE) -- **审计日志** — 党操䜜铟可溯源记圕登圕、任务创建/修改/删陀、倇仜执行/恢倍等关键事件 - -### 🌐 其他 -- 䞭英文囜际化 (i18n) -- 零倖郚䟝赖内嵌 SQLite单二进制郚眲 -- Docker / Docker Compose 䞀键郚眲 -- systemd 服务支持 - -## Quick Start - -### Docker 郚眲 (掚荐) - -```bash -# 克隆项目 -git clone https://github.com/Awuqing/BackupX.git -cd BackupX - -# 䞀键启劚 -docker compose up -d -``` - -劂需倇仜宿䞻机䞊的目圕圚 `docker-compose.yml` 䞭挂蜜对应路埄 - -```yaml -volumes: - - backupx-data:/app/data - - /path/to/backup/source:/mnt/source:ro -``` - -### 从源码构建 - -```bash -# 克隆项目 -git clone https://github.com/Awuqing/BackupX.git -cd BackupX - -# 䞀键构建前后端 -make build - -# 启劚后端服务默讀监听 :8340 -cd server && ./bin/backupx -``` - -### 囜内甚户构建 - -劂果因眑络原因䞋蜜䟝赖猓慢可䜿甚囜内镜像加速 - -```bash -# 方匏䞀Docker 构建掚荐䞀行搞定 -make docker-cn - -# 方匏二手劚讟眮镜像后裞机构建 -export GOPROXY=https://goproxy.cn,direct # Go 暡块代理 -npm config set registry https://registry.npmmirror.com # npm 淘宝源 -make build -``` - -### 访问 Web UI - -打匀浏览噚访问 `http://your-server:8340`銖次䜿甚䌚匕富悚创建管理员莊户。 - -## Configuration - -配眮文件路埄默讀䞺 `./config.yaml`也可通过环境变量 `BACKUPX_` 前猀芆盖。 - -```yaml -# config.yaml -server: - host: "0.0.0.0" - port: 8340 - mode: "release" # debug | release - -database: - path: "./data/backupx.db" # SQLite 数据库路埄 - -security: - jwt_secret: "" # 留空则自劚生成 - jwt_expire: "24h" - encryption_key: "" # AES 加密密钥留空自劚生成 - -backup: - temp_dir: "/tmp/backupx" # 倇仜䞎时文件目圕 - max_concurrent: 2 # 最倧并发倇仜数 - -log: - level: "info" # debug | info | warn | error - file: "./data/backupx.log" - max_size: 100 # 日志文件倧小䞊限 (MB) - max_backups: 3 # 保留旧日志文件数 - max_age: 30 # 日志保留倩数 -``` - -> 💡 `jwt_secret` 和 `encryption_key` 銖次启劚时自劚生成并持久化到数据库无需手劚配眮。 - -## Architecture - -``` - ┌─────────────────────┐ - │ Nginx (反向代理) │ - │ / → 前端静态文件 │ - │ /api → :8340 │ - └─────────┬───────────┘ - │ - â–Œ -┌──────────────────────────────────────────────────────┐ -│ BackupX Master (Go API Server) │ -│ :8340 │ -│ │ -│ ┌──────┐ ┌────────────┐ ┌───────────────────────┐│ -│ │ Auth │ │Backup Engine│ │ Storage Registry ││ -│ └──────┘ └──────┬─────┘ │ ┌─────────────────┐ ││ -│ │ │ │ Aliyun OSS │ ││ -│ ┌──────────┐ │ │ │ Tencent COS │ ││ -│ │ Cron │◄───┘ │ │ Qiniu Kodo │ ││ -│ │Scheduler │ │ │ S3 Compatible │ ││ -│ └──────────┘ │ │ Google Drive │ ││ -│ │ │ WebDAV │ ││ -│ │ │ FTP / FTPS │ ││ -│ ┌──────────┐ │ │ Local Disk │ ││ -│ │ Notify │ │ └─────────────────┘ ││ -│ │ Module │ └───────────────────────┘│ -│ └──────────┘ │ -│ │ -│ ┌──────────────┐ ┌────────────────────┐ │ -│ │ Node Manager │ │ SQLite (backupx.db)│ │ -│ └──────┬───────┘ └────────────────────┘ │ -└─────────┌────────────────────────────────────────────┘ - │ Heartbeat / Task Dispatch - â–Œ -┌──────────────────┐ ┌──────────────────┐ -│ Agent Node A │ │ Agent Node B │ -│ (远皋服务噚) │ │ (远皋服务噚) │ -└──────────────────┘ └──────────────────┘ -``` - -### 技术栈 - -| 组件 | 技术 | +| 胜力 | 诎明 | |------|------| -| **后端** | Go · Gin · GORM · SQLite · robfig/cron | -| **前端** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts | -| **存傚** | AWS SDK v2 (S3/OSS/COS/Kodo) · Google Drive API v3 · gowebdav · jlaffaye/ftp | -| **安党** | JWT · bcrypt · AES-256-GCM | -| **日志** | zap + lumberjack (自劚蜮蜬) | +| **倇仜类型** | 文件/目圕倚源路埄、MySQL、PostgreSQL、SQLite、SAP HANA | +| **存傚后端** | 阿里云 OSS、腟讯云 COS、䞃牛云、S3 兌容(AWS/MinIO/R2)、Google Drive、WebDAV、FTP/FTPS、本地磁盘 | +| **自劚调床** | Cron 定时 + 可视化猖蟑噚 + 自劚保留策略按倩数/仜数枅理 | +| **倚节点** | Master-Agent 集矀统䞀管理倚台服务噚的倇仜 | +| **安党** | JWT + bcrypt + AES-256-GCM 加密配眮 + 可选倇仜文件加密 + 审计日志 | +| **通知** | 邮件 / Webhook / Telegram倇仜成功或倱莥时自劚掚送 | +| **郚眲** | 单二进制 + 内嵌 SQLiteDocker 䞀键启劚零倖郚䟝赖 | -## Cluster Mode +--- -BackupX 支持 **Master-Agent** 暡匏可管理倚台服务噚的倇仜任务。 +## 快速匀始 -### 工䜜原理 +### 1. 安装 -1. **Master** 䞺运行 BackupX Web 控制台的䞻控服务噚 -2. **Agent** 郚眲圚需芁倇仜的远皋服务噚䞊 -3. Agent 启劚后通过 Token 向 Master 泚册并定期发送心跳 -4. Master 将倇仜任务䞋发至对应 Agent 执行 - -### 添加节点 +**Docker掚荐无需克隆仓库** ```bash -# 圚 Web 控制台 → 节点管理 → 添加节点 -# 系统将生成䞀䞪唯䞀的 64 䜍十六进制 Token +# 创建 docker-compose.yml 后䞀键启劚 +docker compose up -d -# 圚远皋服务噚䞊配眮 Agent 启劚参数 -./backupx-agent --master http://master-server:8340 --token +# 或盎接运行 +docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data awuqing/backupx:latest ``` -### 目圕探针 API +> Docker Hub 镜像[`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx)支持 linux/amd64 和 linux/arm64。 -Master 提䟛 `GET /api/nodes/:id/fs/list?path=/` 接口可远皋浏览节点的文件系统目圕。前端圚创建倇仜任务的"源路埄"蟓入时可䜿甚树圢选择噚盎接浏览目标机噚的目圕结构。 +
+docker-compose.yml 参考 -## Project Structure +```yaml +services: + backupx: + image: awuqing/backupx:latest + container_name: backupx + restart: unless-stopped + ports: + - "8340:8340" + volumes: + - backupx-data:/app/data + # 挂蜜需芁倇仜的宿䞻机目圕按需添加 + # - /var/www:/mnt/www:ro + # - /etc/nginx:/mnt/nginx-conf:ro + environment: + - TZ=Asia/Shanghai -``` -BackupX/ -├── server/ # Go 后端 -│ ├── cmd/backupx/ # 皋序入口 -│ ├── internal/ -│ │ ├── app/ # 应甚组装 (DI) -│ │ ├── apperror/ # 统䞀错误类型 -│ │ ├── backup/ # 倇仜匕擎 (file/mysql/sqlite/pgsql/saphana) -│ │ │ └── retention/ # 保留策略 -│ │ ├── config/ # 配眮加蜜 (viper) -│ │ ├── database/ # 数据库初始化 + 迁移 -│ │ ├── http/ # HTTP 倄理噚 + 路由 + 䞭闎件 -│ │ ├── httpapi/ # HTTP API 蟅助工具 -│ │ ├── logger/ # 日志初始化 (zap + lumberjack) -│ │ ├── model/ # GORM 数据暡型 -│ │ ├── notify/ # 通知 (email/webhook/telegram) -│ │ ├── repository/ # 数据访问层 -│ │ ├── scheduler/ # Cron 调床噚 -│ │ ├── security/ # JWT + 限流 -│ │ ├── service/ # 䞚务逻蟑层 -│ │ └── storage/ # 存傚后端 (插件化接口) -│ │ ├── aliyun/ # 阿里云 OSS -│ │ ├── tencent/ # 腟讯云 COS -│ │ ├── qiniu/ # 䞃牛云 Kodo -│ │ ├── s3/ # S3 Compatible 栞心 -│ │ ├── s3provider/ # S3 Provider 蟅助 -│ │ ├── googledrive/ # Google Drive -│ │ ├── webdav/ # WebDAV 栞心 -│ │ ├── webdavprovider/ # WebDAV Provider 蟅助 -│ │ ├── localdisk/ # 本地磁盘 -│ │ ├── ftp/ # FTP / FTPS -│ │ └── codec/ # 配眮猖解码 -│ └── pkg/ # 工具包 (compress/crypto/response) -├── web/ # React 前端 -│ └── src/ -│ ├── components/ # 通甚组件 (CronEditor/FormDrawer/...) -│ ├── hooks/ # 自定义 Hooks -│ ├── layouts/ # 垃局组件 (AppLayout) -│ ├── pages/ # 页面暡块 -│ │ ├── dashboard/ # 仪衚盘 -│ │ ├── backup-tasks/ # 倇仜任务 -│ │ ├── backup-records/ # 倇仜记圕 -│ │ ├── storage-targets/ # 存傚目标 -│ │ ├── nodes/ # 节点管理 -│ │ ├── notifications/ # 通知配眮 -│ │ ├── audit/ # 审计日志 -│ │ ├── settings/ # 系统讟眮 -│ │ └── login/ # 登圕页 -│ ├── services/ # API 请求封装 -│ ├── stores/ # Zustand 状态管理 -│ ├── styles/ # 党局样匏 -│ ├── types/ # TypeScript 类型定义 -│ ├── utils/ # 工具凜数 -│ ├── locales/ # i18n 语蚀包 (zh-CN / en-US) -│ └── router/ # 路由配眮 -├── deploy/ # 郚眲配眮 -│ ├── nginx.conf # Nginx 参考配眮 -│ ├── backupx.service # systemd 服务单元 -│ ├── install.sh # 䞀键安装脚本 -│ └── docker/ # Docker 郚眲配眮 -│ ├── nginx.conf # 容噚内 Nginx 配眮 -│ └── entrypoint.sh # 容噚启劚脚本 -├── .github/ # GitHub 配眮 -│ ├── workflows/ci.yml # CI 工䜜流 -│ ├── workflows/release.yml # Release 工䜜流 -│ └── ISSUE_TEMPLATE/ # Issue 暡板 -├── Dockerfile # Docker 倚阶段构建 -├── docker-compose.yml # Docker Compose 配眮 -└── Makefile # 构建呜什 +volumes: + backupx-data: ``` -## Development +
-### 前眮条件 +**预猖译包裞机郚眲** -- **Go** ≥ 1.21 -- **Node.js** ≥ 18 -- **npm** - -### 匀发暡匏 +从 [Releases](https://github.com/Awuqing/BackupX/releases) 䞋蜜对应平台的压猩包 ```bash -# 终端 1启劚后端 (热重蜜需配合 air) -make dev-server - -# 终端 2启劚前端 (Vite HMR) -make dev-web +tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-* +sudo ./install.sh # 自劚配眮 systemd + Nginx ``` -### 运行测试 +**从源码构建** ```bash -# 运行党郚测试 -make test - -# 仅后端 -make test-server # go test ./... - -# 仅前端 -make test-web # npm run test +git clone https://github.com/Awuqing/BackupX.git && cd BackupX +make build # 构建前后端 +make docker-cn # 或甚囜内镜像构建 Dockergoproxy.cn / npmmirror / 阿里云 apk ``` -### 构建 +### 2. 打匀控制台 -```bash -# 构建前后端 -make build +浏览噚访问 `http://your-server:8340`銖次打匀䌚匕富创建管理员莊户。 -# Docker 构建 -make docker +### 3. 添加存傚目标 -# 囜内 Docker 构建䜿甚囜内镜像加速 -make docker-cn +进入 **存傚目标** 页面点击 **添加**选择存傚类型并填写凭证 -# 枅理构建产物 -make clean -``` +| 存傚类型 | 需芁填写 | +|---------|---------| +| 阿里云 OSS | Region + AccessKey ID/Secret + Bucket | +| 腟讯云 COS | Region + SecretId/SecretKey + Bucket栌匏 `name-appid` | +| 䞃牛云 Kodo | Region + AccessKey/SecretKey + Bucket | +| S3 兌容 | Endpoint + AccessKey + Bucket | +| Google Drive | Client ID/Secret → 点击授权完成 OAuth | +| WebDAV | 服务噚地址 + 甚户名/密码 | +| FTP | 䞻机 + 端口 + 甚户名/密码 | +| 本地磁盘 | 目标目圕路埄 | -### 发版 +> 囜内云厂商只需填 Region 和 AccessKey系统自劚组装 Endpoint。 -掚送 Git tag 即可自劚觊发 GitHub Actions 完成党郚发垃流皋 +添加后点击 **测试连接** 确讀配眮正确。 -```bash -git tag v1.2.3 -git push --tags -# GitHub Actions 自劚猖译二进制 → 发垃 Release → 掚送 Docker Hub 镜像 -``` +### 4. 创建倇仜任务 -也可以圚 GitHub Actions 页面手劚觊发 Release workflow蟓入版本号即可。 +进入 **倇仜任务** 页面点击 **新建**䞉步完成 -## Deployment +1. **基础信息** — 任务名称、倇仜类型、Cron 衚蟟匏留空则仅手劚执行 +2. **源配眮** — 文件倇仜选择源路埄支持倚䞪、数据库倇仜填写连接信息 +3. **存傚䞎策略** — 选择存傚目标、压猩策略、保留倩数、是吊加密 -### 䞀键安装 (掚荐) +保存后可以点击 **立即执行** 测试圚 **倇仜记圕** 页面实时查看执行日志。 -```bash -# 先构建 -make build +### 5. 配眮通知可选 -# 以 root 执行安装脚本 -sudo ./deploy/install.sh -``` +进入 **通知配眮** 页面支持邮件、Webhook、Telegram 䞉种方匏可分别配眮成功/倱莥时是吊掚送。 -安装脚本将自劚 -1. 创建 `backupx` 系统甚户 -2. 安装二进制到 `/opt/backupx/bin/` -3. 郚眲前端到 `/opt/backupx/web/` -4. 生成配眮文件 `/etc/backupx/config.yaml` -5. 泚册并启劚 systemd 服务 -6. 配眮 Nginx 反向代理劂已安装 +--- + +## 郚眲指南 ### Docker 郚眲 ```bash -# 䜿甚 docker compose -docker compose up -d - -# 或手劚构建镜像 -docker build -t backupx . -docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data backupx +docker compose up -d # 䜿甚䞊方的 docker-compose.yml ``` -**密码重眮**忘记管理员密码时 +倇仜宿䞻机目圕时需芁挂蜜路埄圚 docker-compose.yml 的 `volumes` 䞭添加 + +```yaml +volumes: + - backupx-data:/app/data + - /var/www:/mnt/www:ro # 挂蜜需芁倇仜的目圕 + - /etc/nginx:/mnt/nginx-conf:ro # 可以挂蜜倚䞪 +``` + +通过环境变量调敎配眮 + +```yaml +environment: + - TZ=Asia/Shanghai + - BACKUPX_LOG_LEVEL=debug + - BACKUPX_BACKUP_MAX_CONCURRENT=4 +``` + +### 裞机郚眲 ```bash -docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123 +# 䜿甚预猖译包 +tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-* +sudo ./install.sh + +# 或从源码 +make build +sudo ./deploy/install.sh ``` -通过环境变量芆盖配眮 +安装脚本自劚完成创建系统甚户 → 安装二进制到 `/opt/backupx/` → 配眮 systemd → 配眮 Nginx 反向代理。 -```bash -docker run -d --name backupx \ - -p 8340:8340 \ - -v backupx-data:/app/data \ - -e TZ=Asia/Shanghai \ - -e BACKUPX_LOG_LEVEL=debug \ - -e BACKUPX_BACKUP_MAX_CONCURRENT=4 \ - backupx -``` - -### 手劚郚眲 - -```bash -# 1. 构建 -cd server && go build -o backupx ./cmd/backupx -cd ../web && npm run build - -# 2. 郚眲文件 -scp server/backupx your-server:/opt/backupx/bin/ -scp -r web/dist/ your-server:/opt/backupx/web/ -scp server/config.example.yaml your-server:/etc/backupx/config.yaml - -# 3. 启劚 -ssh your-server '/opt/backupx/bin/backupx -config /etc/backupx/config.yaml' -``` - -### 密码重眮 - -忘记管理员密码时可通过 CLI 盎接重眮需芁服务噚 shell 权限 - -```bash -# 裞机郚眲 -./backupx reset-password --username admin --password newpass123 - -# Docker 郚眲 -docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123 -``` - -### Nginx 配眮瀺䟋 +### Nginx 反向代理裞机郚眲时 ```nginx server { listen 80; server_name backup.example.com; - # 前端静态文件 location / { root /opt/backupx/web; try_files $uri $uri/ /index.html; } - # API 反向代理 location /api/ { proxy_pass http://127.0.0.1:8340; proxy_set_header Host $host; @@ -510,90 +201,122 @@ server { } ``` -## API Reference +### 配眮文件 -所有 API 均以 `/api` 䞺前猀䜿甚 JWT Bearer Token 讀证陀特殊标泚倖。 +配眮文件路埄 `./config.yaml`也可通过 `BACKUPX_` 前猀环境变量芆盖 + +```yaml +server: + port: 8340 +database: + path: "./data/backupx.db" +security: + jwt_secret: "" # 留空自劚生成并持久化到数据库 + encryption_key: "" # 留空自劚生成 +backup: + temp_dir: "/tmp/backupx" + max_concurrent: 2 +log: + level: "info" # debug | info | warn | error + file: "./data/backupx.log" +``` + +### 密码重眮 + +忘记管理员密码时通过 CLI 重眮 + +```bash +# 裞机 +./backupx reset-password --username admin --password newpass123 + +# Docker +docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123 +``` + +--- + +## 倚节点集矀 + +BackupX 支持 Master-Agent 暡匏管理倚台服务噚 + +1. Web 控制台 → **节点管理** → **添加节点**系统生成 Token +2. 圚远皋服务噚郚眲 Agent 并䜿甚 Token 连接 Master +3. 创建倇仜任务时选择对应节点Master 自劚䞋发任务 + +创建文件倇仜任务时可通过可视化目圕浏览噚远皋选择 Agent 节点䞊的目圕无需手劚蟓入路埄。 + +--- + +## 匀发指南 + +**环境芁求** Go >= 1.25 · Node.js >= 20 · npm + +```bash +# 匀发暡匏 +make dev-server # 终端 1后端默讀 :8340 +make dev-web # 终端 2前端Vite HMR + +# 测试 +make test # 运行党郚测试 + +# 构建 +make build # 前后端䞀起构建 +make docker # Docker 构建 +make docker-cn # 囜内 Docker 构建镜像加速 +``` + +### 发版 + +```bash +git tag v1.2.3 && git push --tags +# GitHub Actions 自劚猖译双架构二进制 → 发垃 GitHub Release → 掚送 Docker Hub 镜像 +``` + +也可圚 GitHub Actions 页面手劚觊发 Release workflow。 + +--- + +## API 参考 + +所有接口以 `/api` 䞺前猀䜿甚 JWT Bearer Token 讀证。 | 暡块 | 端点 | 诎明 | |------|------|------| -| **讀证** | `POST /api/auth/setup` | 銖次初始化管理员 | -| | `POST /api/auth/login` | 登圕获取 Token | -| | `POST /api/auth/logout` | 登出 | -| | `GET /api/auth/profile` | 圓前甚户信息 | -| | `PUT /api/auth/password` | 修改密码 | -| **倇仜任务** | `GET/POST /api/backup/tasks` | 任务列衚 / 创建 | -| | `GET/PUT/DELETE /api/backup/tasks/:id` | 诊情 / 曎新 / 删陀 | -| | `PUT /api/backup/tasks/:id/toggle` | 启甚/穁甹 | -| | `POST /api/backup/tasks/:id/run` | 手劚觊发执行 | -| **倇仜记圕** | `GET /api/backup/records` | 记圕列衚 (支持筛选) | -| | `GET /api/backup/records/:id` | 记圕诊情 | -| | `GET /api/backup/records/:id/logs/stream` | 实时执行日志 (SSE) | -| | `GET /api/backup/records/:id/download` | 䞋蜜倇仜文件 | -| | `POST /api/backup/records/:id/restore` | 恢倍倇仜 | -| **存傚目标** | `GET/POST /api/storage-targets` | 存傚列衚 / 添加 | -| | `GET/PUT/DELETE /api/storage-targets/:id` | 诊情 / 曎新 / 删陀 | -| | `POST /api/storage-targets/test` | 测试连接 | -| | `POST /api/storage-targets/:id/test` | 测试已保存连接 | -| | `GET /api/storage-targets/:id/usage` | 查询甚量 | -| **节点管理** | `GET/POST /api/nodes` | 节点列衚 / 添加 | -| | `GET/DELETE /api/nodes/:id` | 诊情 / 删陀 | -| | `GET /api/nodes/:id/fs/list` | 目圕浏览 | -| | `POST /api/agent/heartbeat` | Agent 心跳 ⚡ | -| **通知** | `GET/POST /api/notifications` | 通知列衚 / 添加 | -| | `POST /api/notifications/test` | 测试通知 | -| | `POST /api/notifications/:id/test` | 测试已保存通知 | -| **仪衚盘** | `GET /api/dashboard/stats` | 抂览统计 | -| | `GET /api/dashboard/timeline` | 倇仜趋势时闎线 | -| **审计日志** | `GET /api/audit-logs` | 审计日志列衚 (支持分类筛选/分页) | -| **系统** | `GET /api/system/info` | 系统信息 (版本/磁盘) | -| | `GET/PUT /api/settings` | 系统讟眮读写 | +| **讀证** | `POST /auth/setup` | 初始化管理员 | +| | `POST /auth/login` | 登圕 | +| | `PUT /auth/password` | 修改密码 | +| **倇仜任务** | `GET\|POST /backup/tasks` | 列衚 / 创建 | +| | `GET\|PUT\|DELETE /backup/tasks/:id` | 诊情 / 曎新 / 删陀 | +| | `PUT /backup/tasks/:id/toggle` | 启甚/穁甹 | +| | `POST /backup/tasks/:id/run` | 手劚执行 | +| **倇仜记圕** | `GET /backup/records` | 列衚支持筛选 | +| | `GET /backup/records/:id/logs/stream` | 实时日志 (SSE) | +| | `GET /backup/records/:id/download` | 䞋蜜 | +| | `POST /backup/records/:id/restore` | 恢倍 | +| **存傚目标** | `GET\|POST /storage-targets` | 列衚 / 添加 | +| | `POST /storage-targets/test` | 测试连接 | +| **节点** | `GET\|POST /nodes` | 列衚 / 添加 | +| | `GET /nodes/:id/fs/list` | 目圕浏览 | +| **通知** | `GET\|POST /notifications` | 列衚 / 添加 | +| **仪衚盘** | `GET /dashboard/stats` | 抂览统计 | +| **审计日志** | `GET /audit-logs` | 操䜜审计 | +| **系统** | `GET /system/info` | 系统信息 | -> ⚡ `POST /api/agent/heartbeat` 䞺公匀端点䜿甚 Node Token 讀证而非 JWT。 +--- -## 云存傚配眮指南 +## 技术栈 -### 阿里云 OSS - -1. 登圕[阿里云控制台](https://oss.console.aliyun.com/)创建 Bucket -2. 前埀 RAM 控制台创建 AccessKey -3. 圚 BackupX 添加存傚目标时选择"阿里云 OSS" -4. 填写 Region劂 `cn-hangzhou`和 AccessKey系统自劚组装 Endpoint - -### 腟讯云 COS - -1. 登圕[腟讯云控制台](https://console.cloud.tencent.com/cos)创建存傚桶 -2. 前埀 API 密钥管理创建 SecretId/SecretKey -3. Bucket 名称栌匏䞺 `BucketName-APPID`劂 `backup-1250000000` - -### 䞃牛云 Kodo - -1. 登圕[䞃牛云控制台](https://portal.qiniu.com/)创建存傚空闎 -2. 支持区域`z0`(华䞜) / `cn-east-2`(华䞜-浙江2) / `z1`(华北) / `z2`(华南) / `na0`(北矎) / `as0`(䞜南亚) - -### Google Drive - -1. 前埀 [Google Cloud Console](https://console.cloud.google.com/) 创建项目 -2. 启甚 **Google Drive API** -3. 创建 **OAuth 2.0 客户端 ID**Web 应甚类型 -4. 添加重定向 URI`http://your-server/api/storage-targets/google-drive/callback` -5. 圚 BackupX 存傚管理页面填入 Client ID / Secret点击授权 +| 组件 | 技术 | +|------|------| +| **后端** | Go · Gin · GORM · SQLite · robfig/cron | +| **前端** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts | +| **存傚** | AWS SDK v2 · Google Drive API v3 · gowebdav · jlaffaye/ftp | +| **安党** | JWT · bcrypt · AES-256-GCM | ## Contributing 欢迎提亀 Issue 和 Pull Request -1. Fork 本项目 -2. 创建功胜分支 (`git checkout -b feature/amazing-feature`) -3. 提亀曎改 (`git commit -m 'Add amazing feature'`) -4. 掚送到分支 (`git push origin feature/amazing-feature`) -5. 创建 Pull Request - ## License -本项目采甚 [Apache License 2.0](LICENSE) 匀源协议。 - ---- - -

- Made with ❀ for self-hosters -

+[Apache License 2.0](LICENSE) diff --git a/README_EN.md b/README_EN.md index c7210ff..ed7c809 100644 --- a/README_EN.md +++ b/README_EN.md @@ -2,485 +2,225 @@ English | äž­æ–‡

-

🛡 BackupX

+

BackupX

- Self-hosted Server Backup Management Platform with Web UI -

-

- Features • - Quick Start • - Configuration • - Architecture • - Cluster • - Development • - API + Self-hosted Server Backup Management Platform
+ One binary, one command — manage all your server backups.

Stars Release - Go + Go React - TypeScript SQLite License - Issues

--- -BackupX is a self-hosted backup management platform for **Linux / macOS servers**. Through an enterprise-grade Web console, you can easily configure directory backups, database backups, and securely store backup files to Alibaba Cloud OSS, Tencent Cloud COS, Qiniu Cloud Kodo, Google Drive, S3-compatible storage, WebDAV, FTP/FTPS, or local disk. + + + + + + + + + +
DashboardBackup Tasks
Storage TargetsBackup Records
-Supports **multi-node cluster management** for unified control of backup tasks across different servers. +## Highlights -> **For**: Individual developers / small teams / DevOps with Linux servers +| Capability | Details | +|-----------|---------| +| **Backup Types** | Files/Directories (multi-source), MySQL, PostgreSQL, SQLite, SAP HANA | +| **Storage Backends** | Alibaba Cloud OSS, Tencent COS, Qiniu Kodo, S3-compatible (AWS/MinIO/R2), Google Drive, WebDAV, FTP/FTPS, Local Disk | +| **Scheduling** | Cron-based scheduling + visual editor + auto-retention policy (by days/count) | +| **Multi-Node** | Master-Agent cluster for managing backups across multiple servers | +| **Security** | JWT + bcrypt + AES-256-GCM encrypted config + optional backup encryption + audit logs | +| **Notifications** | Email / Webhook / Telegram — push on success or failure | +| **Deployment** | Single binary + embedded SQLite, Docker one-click, zero external dependencies | -## Screenshots - -### Login -![Login](screenshots/login.png) - -### Dashboard -![Dashboard](screenshots/dashboard.png) - -### Backup Tasks -![Backup Tasks](screenshots/backup-tasks.png) - -### Backup Records -![Backup Records](screenshots/backup-records.png) - -### Storage Targets -![Storage Targets](screenshots/storage-targets.png) - -### Node Management -![Node Management](screenshots/nodes.png) - -### Notification Settings -![Notification Settings](screenshots/notifications.png) - -### System Settings -![System Settings](screenshots/settings.png) - -## Features - -### 📊 Multiple Backup Types -- **Files / Directories** — Multi-source path backup, custom exclude rules (e.g. `node_modules`, `*.log`) -- **MySQL** — Via native `mysqldump` tool -- **SQLite** — Safe file copy -- **PostgreSQL** — Via native `pg_dump` tool -- **SAP HANA** — Via native `hdbsql` tool (multi-tenant database support) - -### ☁ Multi-Cloud Storage Backends -| Provider | Type | Description | -|----------|------|-------------| -| 🇚🇳 **Alibaba Cloud OSS** | `aliyun_oss` | Auto endpoint assembly, internal network support | -| 🇚🇳 **Tencent Cloud COS** | `tencent_cos` | Auto endpoint assembly | -| 🇚🇳 **Qiniu Cloud Kodo** | `qiniu_kodo` | 6 region precise mapping | -| 🌍 **S3 Compatible** | `s3` | AWS S3 / MinIO / Cloudflare R2, etc. | -| 🌍 **Google Drive** | `google_drive` | Full OAuth 2.0 flow | -| 🌍 **WebDAV** | `webdav` | Nextcloud / Nutstore, etc. | -| 🌍 **FTP / FTPS** | `ftp` | Standard FTP protocol with Explicit TLS support | -| 💟 **Local Disk** | `local_disk` | Backup to local server directory | - -> Chinese cloud providers only require **Region** and **AccessKey** — the system auto-assembles the endpoint. Powered by the S3 engine under the hood with zero extra dependencies. - -### 🖥 Cluster Management (Master-Agent) -- **Node Management** — Register remote server nodes with Token authentication -- **Local Node** — Auto-created, zero-friction upgrade for single-machine users -- **Directory Browser** — Visual file tree selector for backup source paths -- **Agent Heartbeat** — Real-time node online status monitoring -- **Task Tags** — Categorize and manage backup tasks by tags/nodes - -### ⏰ Automation & Scheduling -- Cron expression scheduling -- Visual Cron editor -- Auto-retention policy (by days / by count) -- Max concurrent backup limit - -### 🔐 Security -- JWT authentication + bcrypt password hashing -- AES-256-GCM encrypted sensitive config storage (DB passwords, OAuth tokens) -- Optional backup file encryption -- Login rate limiting (brute force protection) -- Node Token authentication (one-time display, secure transport) -- CLI password reset (Docker users can run `docker exec` — no email recovery needed) - -### 📊 Monitoring & Notifications -- Dashboard stats (success rate, storage usage, backup trend charts) -- Email / Webhook / Telegram notifications -- Real-time backup execution logs (SSE) -- **Audit Logs** — Full operation traceability, records login, task CRUD, backup execution/restore and other key events - -### 🌐 Other -- Chinese & English i18n -- Zero external dependencies (embedded SQLite, single binary deployment) -- Docker / Docker Compose one-click deployment -- systemd service support +--- ## Quick Start -### Docker Deployment (Recommended) +### 1. Install + +**Docker (recommended, no clone needed):** ```bash -# Clone the project -git clone https://github.com/Awuqing/BackupX.git -cd BackupX - -# Start with one command +# Create a docker-compose.yml then start docker compose up -d + +# Or run directly +docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data awuqing/backupx:latest ``` -To back up host directories, mount them in `docker-compose.yml`: +> Docker Hub: [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) — supports linux/amd64 and linux/arm64. + +
+docker-compose.yml reference + +```yaml +services: + backupx: + image: awuqing/backupx:latest + container_name: backupx + restart: unless-stopped + ports: + - "8340:8340" + volumes: + - backupx-data:/app/data + # Mount host directories to back up (add as needed): + # - /var/www:/mnt/www:ro + # - /etc/nginx:/mnt/nginx-conf:ro + environment: + - TZ=Asia/Shanghai + +volumes: + backupx-data: +``` + +
+ +**Pre-built binaries (bare metal):** + +Download from [Releases](https://github.com/Awuqing/BackupX/releases): + +```bash +tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-* +sudo ./install.sh # Auto-configures systemd + Nginx +``` + +**Build from source:** + +```bash +git clone https://github.com/Awuqing/BackupX.git && cd BackupX +make build # Build frontend + backend +make docker-cn # Or Docker build with China mirrors (goproxy.cn / npmmirror / Aliyun apk) +``` + +### 2. Open the Console + +Visit `http://your-server:8340` in your browser. First-time access guides you through admin account creation. + +### 3. Add a Storage Target + +Go to **Storage Targets** → **Add**, choose a storage type and enter credentials: + +| Storage Type | Required Fields | +|-------------|----------------| +| Alibaba Cloud OSS | Region + AccessKey ID/Secret + Bucket | +| Tencent Cloud COS | Region + SecretId/SecretKey + Bucket (`name-appid`) | +| Qiniu Cloud Kodo | Region + AccessKey/SecretKey + Bucket | +| S3 Compatible | Endpoint + AccessKey + Bucket | +| Google Drive | Client ID/Secret → click Authorize for OAuth | +| WebDAV | Server URL + Username/Password | +| FTP | Host + Port + Username/Password | +| Local Disk | Target directory path | + +Click **Test Connection** to verify. + +### 4. Create a Backup Task + +Go to **Backup Tasks** → **Create**, complete 3 steps: + +1. **Basic Info** — Task name, backup type, Cron expression (leave empty for manual-only) +2. **Source Config** — File backup: select source paths (supports multiple); Database: enter connection info +3. **Storage & Policy** — Select storage target(s), compression, retention days, encryption toggle + +Save, then click **Run Now** to test. View real-time logs in **Backup Records**. + +### 5. Set Up Notifications (Optional) + +Go to **Notifications** to configure Email, Webhook, or Telegram alerts for backup success/failure. + +--- + +## Deployment Guide + +### Docker + +```bash +docker compose up -d # Using the docker-compose.yml above +``` + +Mount host directories for file backup (add to `volumes` in docker-compose.yml): ```yaml volumes: - backupx-data:/app/data - - /path/to/backup/source:/mnt/source:ro + - /var/www:/mnt/www:ro + - /etc/nginx:/mnt/nginx-conf:ro ``` -### Build from Source - -```bash -# Clone the project -git clone https://github.com/Awuqing/BackupX.git -cd BackupX - -# Build frontend and backend -make build - -# Start the backend service (default port :8340) -cd server && ./bin/backupx -``` - -### China Mirror Build - -If downloading dependencies is slow due to network restrictions, use China mirror acceleration: - -```bash -# Option 1: Docker build (recommended, one command) -make docker-cn - -# Option 2: Set mirrors manually, then build -export GOPROXY=https://goproxy.cn,direct -npm config set registry https://registry.npmmirror.com -make build -``` - -### Access Web UI - -Open `http://your-server:8340` in your browser. First-time use will guide you through creating an admin account. - -## Configuration - -The config file defaults to `./config.yaml`. Settings can also be overridden via `BACKUPX_` prefixed environment variables. +Override config via environment variables: ```yaml -# config.yaml -server: - host: "0.0.0.0" - port: 8340 - mode: "release" # debug | release - -database: - path: "./data/backupx.db" # SQLite database path - -security: - jwt_secret: "" # Leave empty to auto-generate - jwt_expire: "24h" - encryption_key: "" # AES encryption key, auto-generated if empty - -backup: - temp_dir: "/tmp/backupx" # Backup temp directory - max_concurrent: 2 # Max concurrent backups - -log: - level: "info" # debug | info | warn | error - file: "./data/backupx.log" - max_size: 100 # Max log file size (MB) - max_backups: 3 # Number of old log files to retain - max_age: 30 # Log retention days +environment: + - TZ=Asia/Shanghai + - BACKUPX_LOG_LEVEL=debug + - BACKUPX_BACKUP_MAX_CONCURRENT=4 ``` -> 💡 `jwt_secret` and `encryption_key` are auto-generated on first startup and persisted to the database. - -## Architecture - -``` - ┌─────────────────────┐ - │ Nginx (Reverse │ - │ Proxy) │ - │ / → Static Files │ - │ /api → :8340 │ - └─────────┬───────────┘ - │ - â–Œ -┌──────────────────────────────────────────────────────┐ -│ BackupX Master (Go API Server) │ -│ :8340 │ -│ │ -│ ┌──────┐ ┌────────────┐ ┌───────────────────────┐│ -│ │ Auth │ │Backup Engine│ │ Storage Registry ││ -│ └──────┘ └──────┬─────┘ │ ┌─────────────────┐ ││ -│ │ │ │ Alibaba Cloud │ ││ -│ ┌──────────┐ │ │ │ Tencent Cloud │ ││ -│ │ Cron │◄───┘ │ │ Qiniu Cloud │ ││ -│ │Scheduler │ │ │ S3 Compatible │ ││ -│ └──────────┘ │ │ Google Drive │ ││ -│ │ │ WebDAV │ ││ -│ │ │ FTP / FTPS │ ││ -│ ┌──────────┐ │ │ Local Disk │ ││ -│ │ Notify │ │ └─────────────────┘ ││ -│ │ Module │ └───────────────────────┘│ -│ └──────────┘ │ -│ │ -│ ┌──────────────┐ ┌────────────────────┐ │ -│ │ Node Manager │ │ SQLite (backupx.db)│ │ -│ └──────┬───────┘ └────────────────────┘ │ -└─────────┌────────────────────────────────────────────┘ - │ Heartbeat / Task Dispatch - â–Œ -┌──────────────────┐ ┌──────────────────┐ -│ Agent Node A │ │ Agent Node B │ -│ (Remote Server)│ │ (Remote Server)│ -└──────────────────┘ └──────────────────┘ -``` - -### Tech Stack - -| Component | Technology | -|-----------|-----------| -| **Backend** | Go · Gin · GORM · SQLite · robfig/cron | -| **Frontend** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts | -| **Storage** | AWS SDK v2 (S3/OSS/COS/Kodo) · Google Drive API v3 · gowebdav · jlaffaye/ftp | -| **Security** | JWT · bcrypt · AES-256-GCM | -| **Logging** | zap + lumberjack (auto-rotation) | - -## Cluster Mode - -BackupX supports **Master-Agent** mode for managing backup tasks across multiple servers. - -### How It Works - -1. **Master** is the server running the BackupX Web console -2. **Agent** is deployed on remote servers that need to be backed up -3. Agents register with the Master using a Token and send periodic heartbeats -4. Master dispatches backup tasks to the corresponding Agent for execution - -### Adding Nodes +### Bare Metal ```bash -# In Web Console → Node Management → Add Node -# The system generates a unique 64-character hex Token +# From pre-built package +tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-* +sudo ./install.sh -# Configure the Agent on the remote server -./backupx-agent --master http://master-server:8340 --token -``` - -### Directory Probe API - -Master provides `GET /api/nodes/:id/fs/list?path=/` to remotely browse a node's file system. The frontend uses a tree selector to browse the target machine's directory structure when creating backup tasks. - -## Project Structure - -``` -BackupX/ -├── server/ # Go backend -│ ├── cmd/backupx/ # Entry point -│ ├── internal/ -│ │ ├── app/ # App assembly (DI) -│ │ ├── apperror/ # Unified error types -│ │ ├── backup/ # Backup engine (file/mysql/sqlite/pgsql/saphana) -│ │ │ └── retention/ # Retention policy -│ │ ├── config/ # Config loading (viper) -│ │ ├── database/ # Database init + migrations -│ │ ├── http/ # HTTP handlers + routes + middleware -│ │ ├── httpapi/ # HTTP API helpers -│ │ ├── logger/ # Logger init (zap + lumberjack) -│ │ ├── model/ # GORM data models -│ │ ├── notify/ # Notifications (email/webhook/telegram) -│ │ ├── repository/ # Data access layer -│ │ ├── scheduler/ # Cron scheduler -│ │ ├── security/ # JWT + rate limiting -│ │ ├── service/ # Business logic -│ │ └── storage/ # Storage backends (plugin interface) -│ │ ├── aliyun/ # Alibaba Cloud OSS -│ │ ├── tencent/ # Tencent Cloud COS -│ │ ├── qiniu/ # Qiniu Cloud Kodo -│ │ ├── s3/ # S3 Compatible core -│ │ ├── s3provider/ # S3 Provider helper -│ │ ├── googledrive/ # Google Drive -│ │ ├── webdav/ # WebDAV core -│ │ ├── webdavprovider/ # WebDAV Provider helper -│ │ ├── localdisk/ # Local disk -│ │ ├── ftp/ # FTP / FTPS -│ │ └── codec/ # Config codec -│ └── pkg/ # Utilities (compress/crypto/response) -├── web/ # React frontend -│ └── src/ -│ ├── components/ # Shared components (CronEditor/FormDrawer/...) -│ ├── hooks/ # Custom Hooks -│ ├── layouts/ # Layout components (AppLayout) -│ ├── pages/ # Page modules -│ │ ├── dashboard/ # Dashboard -│ │ ├── backup-tasks/ # Backup tasks -│ │ ├── backup-records/ # Backup records -│ │ ├── storage-targets/ # Storage targets -│ │ ├── nodes/ # Node management -│ │ ├── notifications/ # Notification settings -│ │ ├── audit/ # Audit logs -│ │ ├── settings/ # System settings -│ │ └── login/ # Login page -│ ├── services/ # API request wrappers -│ ├── stores/ # Zustand state management -│ ├── styles/ # Global styles -│ ├── types/ # TypeScript type definitions -│ ├── utils/ # Utility functions -│ ├── locales/ # i18n language packs (zh-CN / en-US) -│ └── router/ # Route configuration -├── deploy/ # Deployment configs -│ ├── nginx.conf # Nginx reference config -│ ├── backupx.service # systemd service unit -│ ├── install.sh # One-click install script -│ └── docker/ # Docker deployment configs -│ ├── nginx.conf # In-container Nginx config -│ └── entrypoint.sh # Container entrypoint script -├── .github/ # GitHub configuration -│ ├── workflows/ci.yml # CI workflow -│ ├── workflows/release.yml # Release workflow -│ └── ISSUE_TEMPLATE/ # Issue templates -├── Dockerfile # Docker multi-stage build -├── docker-compose.yml # Docker Compose config -└── Makefile # Build commands -``` - -## Development - -### Prerequisites - -- **Go** ≥ 1.21 -- **Node.js** ≥ 18 -- **npm** - -### Dev Mode - -```bash -# Terminal 1: Start backend (use air for hot-reload) -make dev-server - -# Terminal 2: Start frontend (Vite HMR) -make dev-web -``` - -### Run Tests - -```bash -# Run all tests -make test - -# Backend only -make test-server # go test ./... - -# Frontend only -make test-web # npm run test -``` - -### Build - -```bash -# Build frontend and backend +# Or from source make build - -# Docker build -make docker - -# Docker build with China mirrors -make docker-cn - -# Clean build artifacts -make clean -``` - -### Release - -Push a Git tag to automatically trigger the full release pipeline via GitHub Actions: - -```bash -git tag v1.2.3 -git push --tags -# GitHub Actions will: compile binaries → publish GitHub Release → push Docker Hub image -``` - -You can also manually trigger the Release workflow from the GitHub Actions page. - -## Deployment - -### One-Click Install (Recommended) - -```bash -# Build first -make build - -# Run install script as root sudo ./deploy/install.sh ``` -The install script will automatically: -1. Create a `backupx` system user -2. Install the binary to `/opt/backupx/bin/` -3. Deploy the frontend to `/opt/backupx/web/` -4. Generate config at `/etc/backupx/config.yaml` -5. Register and start the systemd service -6. Configure Nginx reverse proxy (if installed) +The install script creates a system user, installs to `/opt/backupx/`, configures systemd, and sets up Nginx reverse proxy. -### Docker Deployment +### Nginx Reverse Proxy (bare metal) -```bash -# Using docker compose -docker compose up -d +```nginx +server { + listen 80; + server_name backup.example.com; -# Or build and run manually -docker build -t backupx . -docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data backupx + location / { + root /opt/backupx/web; + try_files $uri $uri/ /index.html; + } + + location /api/ { + proxy_pass http://127.0.0.1:8340; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + } +} ``` -**Password Reset** (when you forget the admin password): +### Configuration -```bash -docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123 -``` +Config file: `./config.yaml` (or override with `BACKUPX_` prefixed env vars): -Override configuration via environment variables: - -```bash -docker run -d --name backupx \ - -p 8340:8340 \ - -v backupx-data:/app/data \ - -e TZ=Asia/Shanghai \ - -e BACKUPX_LOG_LEVEL=debug \ - -e BACKUPX_BACKUP_MAX_CONCURRENT=4 \ - backupx -``` - -### Manual Deployment - -```bash -# 1. Build -cd server && go build -o backupx ./cmd/backupx -cd ../web && npm run build - -# 2. Deploy files -scp server/backupx your-server:/opt/backupx/bin/ -scp -r web/dist/ your-server:/opt/backupx/web/ -scp server/config.example.yaml your-server:/etc/backupx/config.yaml - -# 3. Start -ssh your-server '/opt/backupx/bin/backupx -config /etc/backupx/config.yaml' +```yaml +server: + port: 8340 +database: + path: "./data/backupx.db" +security: + jwt_secret: "" # Auto-generated and persisted to DB + encryption_key: "" # Auto-generated +backup: + temp_dir: "/tmp/backupx" + max_concurrent: 2 +log: + level: "info" # debug | info | warn | error + file: "./data/backupx.log" ``` ### Password Reset -When you forget the admin password, reset it via CLI (requires server shell access): - ```bash # Bare metal ./backupx reset-password --username admin --password newpass123 @@ -489,112 +229,90 @@ When you forget the admin password, reset it via CLI (requires server shell acce docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123 ``` -### Nginx Config Example +--- -```nginx -server { - listen 80; - server_name backup.example.com; +## Multi-Node Cluster - # Frontend static files - location / { - root /opt/backupx/web; - try_files $uri $uri/ /index.html; - } +BackupX supports Master-Agent mode for managing multiple servers: - # API reverse proxy - location /api/ { - proxy_pass http://127.0.0.1:8340; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } -} +1. Web Console → **Node Management** → **Add Node** — system generates a Token +2. Deploy Agent on remote server, connect using the Token +3. Create backup tasks and assign to specific nodes — Master dispatches automatically + +The visual directory browser lets you pick directories on remote Agent nodes — no manual path typing. + +--- + +## Development + +**Requirements:** Go >= 1.25 · Node.js >= 20 · npm + +```bash +# Dev mode +make dev-server # Terminal 1: backend (:8340) +make dev-web # Terminal 2: frontend (Vite HMR) + +# Test +make test # Run all tests + +# Build +make build # Build frontend + backend +make docker # Docker build +make docker-cn # Docker build with China mirrors ``` +### Release + +```bash +git tag v1.2.3 && git push --tags +# GitHub Actions: compile dual-arch binaries → publish GitHub Release → push Docker Hub image +``` + +Or manually trigger the Release workflow from GitHub Actions page. + +--- + ## API Reference -All APIs are prefixed with `/api` and use JWT Bearer Token authentication (unless noted otherwise). +All endpoints prefixed with `/api`, authenticated via JWT Bearer Token. | Module | Endpoint | Description | |--------|----------|-------------| -| **Auth** | `POST /api/auth/setup` | Initialize admin (first time) | -| | `POST /api/auth/login` | Login to get Token | -| | `POST /api/auth/logout` | Logout | -| | `GET /api/auth/profile` | Current user info | -| | `PUT /api/auth/password` | Change password | -| **Backup Tasks** | `GET/POST /api/backup/tasks` | List / Create tasks | -| | `GET/PUT/DELETE /api/backup/tasks/:id` | Detail / Update / Delete | -| | `PUT /api/backup/tasks/:id/toggle` | Enable / Disable | -| | `POST /api/backup/tasks/:id/run` | Trigger manual execution | -| **Backup Records** | `GET /api/backup/records` | List records (with filter) | -| | `GET /api/backup/records/:id` | Record detail | -| | `GET /api/backup/records/:id/logs/stream` | Real-time execution logs (SSE) | -| | `GET /api/backup/records/:id/download` | Download backup file | -| | `POST /api/backup/records/:id/restore` | Restore backup | -| **Storage Targets** | `GET/POST /api/storage-targets` | List / Add targets | -| | `GET/PUT/DELETE /api/storage-targets/:id` | Detail / Update / Delete | -| | `POST /api/storage-targets/test` | Test connection | -| | `POST /api/storage-targets/:id/test` | Test saved connection | -| | `GET /api/storage-targets/:id/usage` | Query usage | -| **Nodes** | `GET/POST /api/nodes` | List / Add nodes | -| | `GET/DELETE /api/nodes/:id` | Detail / Delete | -| | `GET /api/nodes/:id/fs/list` | Directory browser | -| | `POST /api/agent/heartbeat` | Agent heartbeat ⚡ | -| **Notifications** | `GET/POST /api/notifications` | List / Add | -| | `POST /api/notifications/test` | Test notification | -| | `POST /api/notifications/:id/test` | Test saved notification | -| **Dashboard** | `GET /api/dashboard/stats` | Overview statistics | -| | `GET /api/dashboard/timeline` | Backup trend timeline | -| **Audit Logs** | `GET /api/audit-logs` | Audit log list (with category filter/pagination) | -| **System** | `GET /api/system/info` | System info (version/disk) | -| | `GET/PUT /api/settings` | System settings | +| **Auth** | `POST /auth/setup` | Initialize admin | +| | `POST /auth/login` | Login | +| | `PUT /auth/password` | Change password | +| **Backup Tasks** | `GET\|POST /backup/tasks` | List / Create | +| | `GET\|PUT\|DELETE /backup/tasks/:id` | Detail / Update / Delete | +| | `PUT /backup/tasks/:id/toggle` | Enable / Disable | +| | `POST /backup/tasks/:id/run` | Manual run | +| **Backup Records** | `GET /backup/records` | List (with filter) | +| | `GET /backup/records/:id/logs/stream` | Real-time logs (SSE) | +| | `GET /backup/records/:id/download` | Download | +| | `POST /backup/records/:id/restore` | Restore | +| **Storage Targets** | `GET\|POST /storage-targets` | List / Add | +| | `POST /storage-targets/test` | Test connection | +| **Nodes** | `GET\|POST /nodes` | List / Add | +| | `GET /nodes/:id/fs/list` | Directory browser | +| **Notifications** | `GET\|POST /notifications` | List / Add | +| **Dashboard** | `GET /dashboard/stats` | Overview stats | +| **Audit Logs** | `GET /audit-logs` | Operation audit | +| **System** | `GET /system/info` | System info | -> ⚡ `POST /api/agent/heartbeat` is a public endpoint authenticated via Node Token instead of JWT. +--- -## Cloud Storage Setup Guide +## Tech Stack -### Alibaba Cloud OSS - -1. Log in to [Alibaba Cloud Console](https://oss.console.aliyun.com/), create a Bucket -2. Go to RAM Console to create an AccessKey -3. Select "Alibaba Cloud OSS" when adding a storage target in BackupX -4. Enter the Region (e.g. `cn-hangzhou`) and AccessKey — the system auto-assembles the endpoint - -### Tencent Cloud COS - -1. Log in to [Tencent Cloud Console](https://console.cloud.tencent.com/cos), create a bucket -2. Go to API Key Management to create SecretId/SecretKey -3. Bucket name format is `BucketName-APPID` (e.g. `backup-1250000000`) - -### Qiniu Cloud Kodo - -1. Log in to [Qiniu Cloud Console](https://portal.qiniu.com/), create a storage space -2. Supported regions: `z0` (East China) / `cn-east-2` (East China-Zhejiang 2) / `z1` (North China) / `z2` (South China) / `na0` (North America) / `as0` (Southeast Asia) - -### Google Drive - -1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create a project -2. Enable the **Google Drive API** -3. Create an **OAuth 2.0 Client ID** (Web application type) -4. Add redirect URI: `http://your-server/api/storage-targets/google-drive/callback` -5. Enter the Client ID / Secret in BackupX storage management and click Authorize +| Component | Technology | +|-----------|-----------| +| **Backend** | Go · Gin · GORM · SQLite · robfig/cron | +| **Frontend** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts | +| **Storage** | AWS SDK v2 · Google Drive API v3 · gowebdav · jlaffaye/ftp | +| **Security** | JWT · bcrypt · AES-256-GCM | ## Contributing Issues and Pull Requests are welcome! -1. Fork this repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request - ## License -This project is licensed under the [Apache License 2.0](LICENSE). - ---- - -

- Made with ❀ for self-hosters -

+[Apache License 2.0](LICENSE) diff --git a/docker-compose.yml b/docker-compose.yml index 2ccd869..7283480 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,21 +1,29 @@ +# BackupX Docker Compose +# +# 快速启劚docker compose up -d +# 访问地址http://localhost:8340 +# +# 劂需从源码构建镜像而非拉取线䞊镜像取消泚释 build 行并泚释 image 行。 + services: backupx: - build: . - image: backupx:latest + image: awuqing/backupx:latest + # build: . # 从源码构建时取消歀行泚释 container_name: backupx restart: unless-stopped ports: - "8340:8340" volumes: - backupx-data:/app/data - # Mount host directories that need to be backed up (example): - # - /path/to/backup/source:/mnt/source:ro + # 挂蜜需芁倇仜的宿䞻机目圕按需添加:ro 衚瀺只读 + # - /var/www:/mnt/www:ro + # - /etc/nginx:/mnt/nginx-conf:ro + # - /home/user/data:/mnt/data:ro environment: - TZ=Asia/Shanghai - # Override any config via BACKUPX_ prefixed env vars: - # - BACKUPX_SERVER_PORT=8340 - # - BACKUPX_LOG_LEVEL=info - # - BACKUPX_BACKUP_MAX_CONCURRENT=2 + # 通过 BACKUPX_ 前猀环境变量芆盖配眮 + # - BACKUPX_LOG_LEVEL=debug + # - BACKUPX_BACKUP_MAX_CONCURRENT=4 volumes: backupx-data: