Tham chiếu API — Backups

Tổng quan Resources

Resource	Mô tả	Quyền
backups	Quản lý backup files	Admin
backupSchedule	Cấu hình lịch trình tự động	Admin
backupDestinations	Cấu hình nơi lưu trữ (S3, local)	Admin

Tạo backup thủ công

await agent.resource('backups').create({
  values: {
    type: 'full',               // 'full' | 'database'
    description: 'Backup trước khi cập nhật phiên bản',
  },
});

Lấy danh sách backups

const response = await agent.resource('backups').list({
  sort: ['-createdAt'],
  pageSize: 20,
});
// response.body.data = [{ id, type, status, size, description, createdAt, ... }]

Tải backup

// Download file backup (stream response)
const file = await agent.resource('backups').download({
  filterByTk: backupId,
});

Restore từ backup

await agent.resource('backups').restore({
  filterByTk: backupId,
  values: {
    confirm: true,  // Bắt buộc xác nhận
  },
});
// ⚠️ Server sẽ restart sau khi restore hoàn tất

Xoá backup

await agent.resource('backups').destroy({
  filterByTk: backupId,
});
// Xoá file backup khỏi storage (local + cloud)

Cấu hình lịch trình tự động

await agent.resource('backupSchedule').update({
  values: {
    enabled: true,
    cron: '0 2 * * *',         // 2h sáng mỗi ngày
    type: 'full',               // 'full' | 'database'
    retention: 30,              // Giữ backup 30 ngày
    maxBackups: 10,             // Tối đa 10 backups
    notifyOnFailure: true,      // Thông báo khi lỗi
  },
});

Cấu hình destination (nơi lưu trữ)

Thêm S3 destination

await agent.resource('backupDestinations').create({
  values: {
    type: 's3',
    name: 'AWS S3 Production',
    config: {
      bucket: 'my-backups',
      region: 'ap-southeast-1',
      accessKeyId: 'AKIA...',
      secretAccessKey: '...',
      prefix: 'digiforce/backups/',
    },
  },
});

Thêm Local destination

await agent.resource('backupDestinations').create({
  values: {
    type: 'local',
    name: 'Server Local',
    config: {
      directory: './storage/backups',
      maxBackups: 10,
    },
  },
});

Backup Object

Trường	Kiểu	Mô tả
id	bigint	ID backup
type	string	full hoặc database
status	string	pending, running, completed, failed
size	bigint	Kích thước file (bytes)
description	string	Mô tả do user nhập
checksum	string	SHA-256 hash để xác minh tính toàn vẹn
encrypted	boolean	File có được mã hoá không
destinations	json	Danh sách nơi đã lưu
createdAt	datetime	Thời gian tạo
completedAt	datetime	Thời gian hoàn tất
error	text	Thông báo lỗi (nếu failed)

Database Collections

Bảng	Mô tả
backups	Metadata backup (timestamp, size, checksum, status)
backupSchedules	Lịch trình backup (cron expression, type, retention)
backupDestinations	Cấu hình đích lưu trữ (type, credentials, bucket)

Giới hạn kỹ thuật

Tham số	Giá trị	Ghi chú
Đồng thời	1 backup/restore tại một thời điểm	Tránh xung đột database
Mã hoá	AES-256	Tự động khi upload lên cloud
Nén	gzip	Giảm 60–80% kích thước
Restore	Ghi đè toàn bộ database	Cần xác nhận confirm: true
S3 upload	Multipart cho file > 5MB	Tự động