# Nâng cấp, sao lưu và khôi phục

> Nâng cấp bản tự host bằng helm upgrade (Job migrate chạy trước), lùi bản, sao lưu hằng ngày bằng worker hoặc CronJob, diễn tập khôi phục và khôi phục thật bằng lệnh backup-restore.

Các lệnh dưới đây giả định tên bản cài `dataxland` trong namespace `dataxland`. Lệnh vận hành chạy trong pod `worker`:

```bash
kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli <lệnh>
```

## Nâng cấp

1. **Đọc ghi chú phát hành** của bản mới: có đổi schema không, có lùi bản được không, có bước nào phải làm tay không.
2. **Sao lưu ngay** và kiểm bản vừa tạo có trạng thái `ok`:

   ```bash
   kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli backup
   kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli backup-list
   ```

3. Mạng kín: [chép ảnh của bản mới](/vi/docs/self-host/airgapped#7-chép-ảnh-vào-registry-nội-bộ) vào registry nội bộ trước.
4. **Nâng cấp**:

   ```bash
   helm upgrade dataxland <đường dẫn chart mới> -n dataxland -f values-prod.yaml
   ```

   Helm chạy Job `migrate` trước (`python -m pipelines.cli db-migrate`): tạo bảng, cột, chỉ mục còn thiếu trong Postgres. Job
   chạy lại được nhiều lần; giới hạn thời gian đặt ở `migrations.activeDeadlineSeconds` (mặc định 600 giây). Job xong thì
   `api`, `web`, `mcp` được thay dần, còn `worker` dừng rồi chạy bản mới: việc nền (build, lịch làm mới, sao lưu) ngừng vài phút,
   dashboard và hỏi Si vẫn chạy.
5. **Kiểm tra**: `kubectl -n dataxland get pods`, gọi `/readyz` của `api` như lúc [cài](/vi/docs/self-host/helm#6-kiểm-tra-và-đăng-nhập),
   mở một dashboard, xem **Quản trị → Vận hành**.

Job `migrate` lỗi thì Helm dừng và các thành phần đang chạy giữ bản cũ. Xem log bằng `kubectl -n dataxland logs job/dataxland-migrate`.

### Lùi bản

`helm rollback dataxland <revision>` chỉ an toàn khi bản mới **chưa đổi schema theo cách bản cũ không đọc được**; ghi chú phát
hành nói rõ điều này. Nếu không chắc, cách mặc định là cài lại bản cũ rồi khôi phục bản sao lưu đã tạo ở bước 2.

## Sao lưu

Một bản sao lưu gồm Postgres metadata, tệp của từng workspace (tệp tải lên, cấu hình, bản duyệt, bí mật đã mã hóa) và kho dữ
liệu của mọi workspace. Mọi tệp được **mã hóa bằng `DX_BACKUP_ENCRYPTION_KEY`** trước khi ghi vào bucket sao lưu. Dữ liệu kho chỉ
được tải lên một lần rồi các bản sau tham chiếu lại, nên các lượt sau nhỏ hơn lượt đầu.

### Lịch

Mặc định `worker` tự sao lưu mỗi ngày:

```yaml
deployment:
  timezone: Asia/Ho_Chi_Minh
objectStorage:
  backup:
    enabled: true
    bucket: dx-backups
    prefix: ""
    endpoint: ""        # trống = cùng endpoint với kho
    at: "02:00"         # giờ theo deployment.timezone
    keep: "7,4,6"       # giữ 7 bản ngày, 4 bản tuần, 6 bản tháng
```

Muốn Kubernetes quản lịch, bật CronJob. Khi đó chart tự tắt lịch của `worker`:

```yaml
backupCronJob:
  enabled: true
  schedule: "0 19 * * *"          # 02:00 giờ Việt Nam nếu cụm dùng UTC
  restoreDrill:
    enabled: true
    schedule: "0 21 * * 0"        # diễn tập hằng tuần
```

Khuyến nghị:

- Đặt bucket sao lưu ở vùng hoặc hệ thống khác với bucket kho. Có thể dùng khóa riêng (`DX_BACKUP_S3_KEY_ID`,
  `DX_BACKUP_S3_SECRET`) và endpoint riêng (`objectStorage.backup.endpoint`).
- Bật versioning và khóa ghi một lần (Object Lock, retention, immutability) cho bucket sao lưu.
- Không xóa tay thư mục `_objects/` trong bucket sao lưu: mọi bản sao lưu cần nó để khôi phục kho.
- Vẫn giữ sao lưu của dịch vụ Postgres có quản lý; hai lớp bổ sung cho nhau.

### Giữ hai khóa ở hai nơi

Hai khóa sau **không nằm trong bản sao lưu** và không có cách lấy lại:

- `DX_SECRET_KEY`: giải mã mật khẩu nguồn, token đã lưu. Mất thì phải nối lại mọi nguồn dữ liệu.
- `DX_BACKUP_ENCRYPTION_KEY`: giải mã bản sao lưu. Mất thì **mọi bản sao lưu đã mã hóa bằng nó không dùng được**.

Giữ mỗi khóa ở hai nơi: kho bí mật của công ty và một bản ngoại tuyến (bản in hoặc USB mã hóa cất két). Giữ hai khóa tách nhau,
do người khác nhau quản lý nếu được.

## Diễn tập khôi phục

```bash
kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli restore-drill
kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli restore-drill --backup <mã bản sao lưu>
```

Lệnh khôi phục bản mới nhất (hoặc bản chỉ định) vào một database tạm và một vùng lưu tạm, so số dòng và tổng các cột số với lúc
sao lưu, kiểm tổng băm các tệp, rồi xóa phần tạm. **Không đụng dữ liệu đang chạy.** User Postgres cần quyền tạo database.

Chạy ít nhất hằng tuần (hoặc bật `backupCronJob.restoreDrill`). Lần diễn tập thành công cũng chứng minh `DX_BACKUP_ENCRYPTION_KEY`
đang giữ là đúng. Chỉ số `dx_backup_last_success_timestamp_seconds` (nhãn `kind`) cho biết lần sao lưu và diễn tập thành công gần
nhất.

## Khôi phục thật

`backup-restore` ghi đè dữ liệu. Chọn bản trước:

```bash
kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli backup-list
```

Tham số của `backup-restore`:

| Tham số | Việc |
| --- | --- |
| `--backup <mã>` | Bản sao lưu, bắt buộc |
| `--meta` | Nạp Postgres metadata; mọi bảng của database đích phải chưa có dữ liệu |
| `--tenant <mã workspace>` | Khôi phục tệp và kho của workspace này; lặp lại được |
| `--all-tenants` | Mọi workspace có trong bản sao lưu |
| `--force` | Ghi đè tệp và thay kho đang có |

### Một workspace hỏng

Metadata còn nguyên, chỉ kho hoặc tệp của một workspace hỏng:

```bash
kubectl -n dataxland exec deploy/dataxland-worker -- \
  python -m pipelines.cli backup-restore --backup <mã> --tenant <mã workspace> --force
```

Sau đó chạy một lần làm mới cho workspace đó để nạp dữ liệu nguồn mới hơn thời điểm sao lưu.

### Khôi phục toàn phần

Khi mất Postgres metadata, mất bucket kho hoặc dựng lại trên cụm mới:

1. Tạo Postgres mới với database `dx` và `dx_lake` trống.
2. Cài chart **cùng phiên bản** với bản cài lúc sao lưu, dùng **cùng** `DX_SECRET_KEY`, `DX_BACKUP_ENCRYPTION_KEY` và cùng nơi lưu
   sao lưu. Chưa cho ai đăng nhập: `kubectl -n dataxland scale deploy/dataxland-web --replicas=0` (tắt `web.autoscaling` nếu đang
   bật).
3. Nạp metadata:

   ```bash
   kubectl -n dataxland exec deploy/dataxland-worker -- \
     python -m pipelines.cli backup-restore --backup <mã> --meta
   ```

4. Nạp tệp và kho của mọi workspace:

   ```bash
   kubectl -n dataxland exec deploy/dataxland-worker -- \
     python -m pipelines.cli backup-restore --backup <mã> --all-tenants
   ```

   Dữ liệu kho được lấy từ bucket sao lưu, nên bucket kho mới có thể trống.
5. Khởi động lại các thành phần (`kubectl -n dataxland rollout restart deploy`), gọi `/readyz`, mở dashboard của một workspace
   và so với số trước sự cố. Có thể chạy thêm `restore-drill --backup <mã>`.
6. Mở lại `web` (`kubectl -n dataxland scale deploy/dataxland-web --replicas=2`). Lần làm mới theo lịch kế tiếp nạp lại dữ liệu
   nguồn sau thời điểm sao lưu; tệp Excel tải lên sau thời điểm đó phải tải lại.

Nếu `--meta` báo database đích đã có dữ liệu, hoặc bạn không chắc nên chọn bản nào, liên hệ DataxLand trước khi chạy tiếp.

## Liên quan

- [Cài bằng Helm](/vi/docs/self-host/helm)
- [Giấy phép](/vi/docs/self-host/license)
- [Bảo mật và quyền riêng tư](/vi/docs/security-privacy)
