# Bảo vệ vùng lưu trữ khi Synology khởi động

Tài liệu này áp dụng cho **NCV DCIMS — NCV Dental Clinical Image Management System** chạy bằng Container Manager trên Synology DSM.

## Mục tiêu

Shared folder mã hóa có thể chưa được mount ngay sau khi NAS khởi động. Nếu Docker chạy trước thời điểm đó, bind mount có thể trỏ vào một thư mục rỗng trên volume. Hiện tượng này trông giống như dữ liệu biến mất dù dữ liệu thật vẫn nằm trong shared folder chưa được mount.

Cơ chế bảo vệ dùng bốn sentinel riêng biệt. Hệ thống chỉ khởi động khi đúng sentinel xuất hiện tại cả media, backup repository, backup receipts và WriteOnce ledger. Kiểm tra bình thường không tự tạo thư mục hay sentinel.

## 1. Khởi tạo sentinel một lần

Chỉ thực hiện sau khi đã mở DSM và xác nhận thủ công cả `ncv-dcims` lẫn `ncv-dcims-ledger` đang được mount đúng.

Chạy với quyền `root` trong Task Scheduler hoặc SSH:

```sh
cd /volume1/docker/ncv-dcims-production
sh scripts/synology/ncv-dcims-initialize-storage-sentinels.sh --env-file .env
```

Kết quả hợp lệ:

```text
NCV_DCIMS_STORAGE_SENTINELS_INITIALIZED
```

Lệnh không ghi sentinel nếu thư mục gốc chưa tồn tại và không ghi đè sentinel có nội dung sai.

## 2. Kiểm tra độc lập

```sh
cd /volume1/docker/ncv-dcims-production
sh scripts/synology/ncv-dcims-storage-preflight.sh --env-file .env
```

Kết quả hợp lệ:

```text
NCV_DCIMS_STORAGE_PREFLIGHT_OK
```

Mã thoát `20` nghĩa là storage chưa sẵn sàng; mã `64` nghĩa là cấu hình không hợp lệ.

## 3. Thay auto-start bằng guarded start

Trong Container Manager, tắt auto-start của project `ncv-dcims-production`. Sau đó tạo Task Scheduler:

- User: `root`
- Event: Boot-up
- Tên: `NCV DCIMS guarded start`
- User-defined script:

```sh
cd /volume1/docker/ncv-dcims-production
sh scripts/synology/ncv-dcims-guarded-start.sh
```

Script chờ tối đa 300 giây theo mặc định. Nếu storage vẫn chưa sẵn sàng, project bị dừng và script thoát lỗi; Docker không được phép chạy trên thư mục rỗng thay thế.

## 4. Watchdog định kỳ

Tạo thêm task chạy mỗi 5 phút:

- User: `root`
- Tên: `NCV DCIMS storage watchdog`
- User-defined script:

```sh
cd /volume1/docker/ncv-dcims-production
sh scripts/synology/ncv-dcims-storage-watchdog.sh
```

Watchdog không tự khởi động project. Khi một root hoặc sentinel biến mất, nó dừng project theo nguyên tắc fail-closed.

## 5. Kiểm tra sau khi cấu hình

```sh
cd /volume1/docker/ncv-dcims-production
sh scripts/synology/ncv-dcims-storage-guard-self-test.sh
```

Sau đó khởi động lại NAS có kiểm soát và xác nhận:

1. Hai shared folder đã mount.
2. Task guarded start báo thành công.
3. Sáu container production có trạng thái mong đợi; container migration được phép dừng sau khi hoàn tất.
4. Upload thử chỉ dùng dữ liệu giả, rồi xác nhận file nằm trong media root thật.
5. Backup thử tạo point và receipt trong đúng root.

## Khôi phục khi guard chặn hệ thống

Không tạo thủ công các thư mục media, backup hoặc ledger để vượt qua guard. Hãy mount lại shared folder mã hóa trong DSM, chạy preflight, rồi chạy guarded start. Nếu sentinel sai hoặc mất trong khi share chắc chắn đã mount, điều tra nguyên nhân trước khi khởi tạo lại.

Các đường dẫn, project name và thời gian chờ đều lấy từ `.env` hoặc biến môi trường; tài liệu không yêu cầu hard-code IP, domain hay credential.