# Khởi động NCV DCIMS sau khi NAS khởi động lại NCV DCIMS — NCV Dental Clinical Image Management System. Ứng dụng 0.2.30, cấu trúc NAS Volume 2. Tài liệu cập nhật cho bộ cài r2 ngày 30/09/2026. ## Khi nào dùng hướng dẫn này? NAS đã chạy 0.2.30; giữ nguyên ba credential database runtime/migration/backup và credential quản trị riêng. Không sinh lại credential, provision role hoặc chạy migration khi reboot bình thường. Dùng sau khi NAS reboot bình thường hoặc trở lại sau mất điện, khi không có cập nhật/migration đang dang dở. Đây là hướng dẫn cho người vận hành NAS, không phải thao tác của Bác sĩ/LABO. Nếu DCIMS đã mở được, đăng nhập và xem ảnh/hợp đồng bình thường thì không cần khởi động lại container. Chuyển đến bước kiểm tra cuối. Nếu NAS bị ngắt giữa update/migration hoặc chưa rõ vì sao ứng dụng dừng, đọc mục Xử lý lỗi; không tự start bản cũ. Trình tự: **kiểm NAS → mở khóa dữ liệu → kiểm lưu trữ → chạy PostgreSQL → chạy ứng dụng/tunnel → thử website**. Không build, cài lại, update hoặc bootstrap chỉ vì NAS reboot. ## Bước 1 — Kiểm tra NAS trong DSM 1. Đăng nhập DSM bằng tài khoản quản trị NAS. 2. Mở Storage Manager. Kiểm Volume 1 và Volume 2 đang sẵn sàng, không có cảnh báo khiến volume không truy cập được. Nếu có lỗi ổ đĩa/filesystem, dừng và xử lý lưu trữ trước. 3. Mở Package Center hoặc Container Manager, kiểm gói Container Manager đang chạy. Nếu gói đang dừng sau reboot, khởi động gói bằng giao diện DSM rồi chờ phản hồi. 4. Không di chuyển Docker Root. Cấu hình hiện tại chủ ý giữ Docker Root và Container Manager trên Volume 1; source và dữ liệu DCIMS ở Volume 2. Nếu DSM/Docker phản hồi rất chậm, không chạy docker system df, prune, build hoặc lặp lệnh restart để thử. Chưa có bằng chứng những thao tác đó sẽ khắc phục sự cố. ## Bước 2 — Mở khóa shared folder mã hóa Trong DSM: **Control Panel → Shared Folder → chọn ncv-dcims trên Volume 2 → Encryption → Mount**, nếu share đang khóa. Tên nút có thể hiển thị theo ngôn ngữ DSM. Nếu đã mount thì không unmount/mount lại. Nhập mật khẩu mã hóa hoặc dùng file khóa qua giao diện DSM. Không gửi mật khẩu/file khóa, không gõ mật khẩu vào cửa sổ PowerShell và không đưa khóa vào tài liệu bàn giao. Dữ liệu cần truy cập được: | Thành phần | Đường dẫn hiện tại | |---|---| | Media | /volume2/ncv-dcims/media | | Backup repository | /volume2/ncv-dcims/backup/repository | | Backup receipts | /volume2/ncv-dcims/backup/receipts | | Ledger WriteOnce | /volume2/ncv-dcims-ledger-v2 | | PostgreSQL | /volume2/docker-v2/ncv-dcims-postgres-data-v2 | Không tạo thư mục trống, sentinel mới hoặc đổi quyền ledger để vượt lỗi. Share mã hóa đã từng cần mount thủ công sau reboot; **chưa có bằng chứng đã cấu hình tự mở khóa**. Hướng dẫn này không bật auto-mount hay thay cách lưu khóa. ## Bước 3 — Đăng nhập SSH và xem trạng thái Trên máy Windows, mở PowerShell. Thay tên tài khoản và IP trong dấu <> bằng giá trị hiện tại; không gõ nguyên dấu <>: ```powershell ssh @ ``` Chỉ nhập mật khẩu khi xuất hiện password: hoặc Password:. Lúc nhập không hiện ký tự là bình thường. Nếu SSH chưa bật, quản trị NAS kiểm trong Control Panel → Terminal & SNMP; không mở SSH ra Internet chỉ để làm bước này. Khi đã vào NAS, chạy từng dòng: ```sh sudo -i export PATH=/var/packages/ContainerManager/target/usr/bin:$PATH docker ps -a --filter name=ncv-dcims \ --format 'table {{.Names}}\t{{.Status}}' ``` Phải thấy năm container hiện có: ncv-dcims-postgres, ncv-dcims-api, ncv-dcims-web, ncv-dcims-gateway và ncv-dcims-cloudflared. Nếu thiếu container, dừng để đối chiếu; không tự tạo mới bằng Compose chỉ có file base. Nếu lệnh đứng im bất thường quá khoảng 15 giây, Ctrl+C để ngắt lệnh phía SSH; không coi đó là đã dừng tiến trình bên Docker. Không tiếp tục các lệnh start liên tiếp. Nếu báo docker: command not found, kiểm đã chạy export PATH ở trên; đường dẫn Docker đã dùng được là /var/packages/ContainerManager/target/usr/bin/docker. ## Bước 4 — Kiểm đúng dữ liệu trước khi start Chạy preflight từ bộ công cụ đã cài, với môi trường lệnh sạch để lấy đúng giá trị trong .env của project: ```sh env -i PATH=/usr/local/bin:/usr/bin:/bin \ /bin/sh /volume2/docker-v2/ncv-tools/dcims-v1/storage-preflight.sh \ --env-file /volume2/docker-v2/ncv-dcims-production/.env ``` Chỉ tiếp tục khi có **NCV_DCIMS_STORAGE_PREFLIGHT_OK**. Lệnh kiểm bốn storage root và marker; tạo/xóa file thử nhỏ trong media/backup để kiểm quyền, không thử ghi vào ledger. Không thêm --initialize. Nếu file công cụ bị thiếu hoặc preflight báo lỗi, dừng tại đây. Kiểm PostgreSQL data version và cấu hình volume/container hiện có: ```sh cat /volume2/docker-v2/ncv-dcims-postgres-data-v2/PG_VERSION docker volume inspect ncv-dcims-postgres-data-v2 \ --format '{{.Driver}}|{{index .Options "type"}}|{{index .Options "o"}}|{{index .Options "device"}}' docker inspect ncv-dcims-postgres \ --format '{{range .Mounts}}{{if eq .Destination "/var/lib/postgresql/data"}}{{.Type}}|{{.Name}}{{end}}{{end}}' ``` Ba kết quả phải lần lượt là: ```text 17 local|none|bind|/volume2/docker-v2/ncv-dcims-postgres-data-v2 volume|ncv-dcims-postgres-data-v2 ``` Nếu khác hoặc không đọc được, không start và không tạo database/volume thay thế. Mountpoint dưới /volume1/@docker không tự chứng minh database nằm ở Volume 1; đối chiếu Options.device như trên. ## Bước 5 — Khởi động PostgreSQL trước Nếu PostgreSQL chưa chạy, dùng: ```sh docker start ncv-dcims-postgres ``` Sau khoảng 30 giây, kiểm: ```sh docker inspect ncv-dcims-postgres \ --format '{{.State.Running}}|{{if .State.Health}}{{.State.Health.Status}}{{end}}' ``` Chỉ tiếp tục khi kết quả là **true|healthy**. Nếu starting, chờ thêm rồi kiểm lại; không restart liên tục. Nếu unhealthy hoặc vẫn không sẵn sàng sau vài phút, dừng và kiểm lỗi database. Nếu đã true|healthy từ đầu thì không cần chạy start lại. ## Bước 6 — Khởi động ứng dụng và đường truy cập Sau khi PostgreSQL healthy và lưu trữ đã đạt preflight: ```sh docker start ncv-dcims-api ncv-dcims-web \ ncv-dcims-gateway ncv-dcims-cloudflared ``` Đây là start container hiện có, không build/recreate và không chạy migration. Nếu các container đã chạy nhưng unhealthy, lệnh start không phải biện pháp sửa lỗi; kiểm nguyên nhân trước khi quyết định restart. Chờ khoảng 30–60 giây rồi kiểm: ```sh docker ps -a --filter name=ncv-dcims \ --format 'table {{.Names}}\t{{.Status}}' ``` | Container | Kết quả cần có | |---|---| | ncv-dcims-postgres | Up, healthy | | ncv-dcims-api | Up, healthy | | ncv-dcims-web | Up, healthy | | ncv-dcims-gateway | Up, healthy | | ncv-dcims-cloudflared | Up/running; không yêu cầu nhãn healthy nếu không có healthcheck | ## Bước 7 — Xác nhận sử dụng được 1. Mở địa chỉ HTTPS DCIMS đang dùng, đăng nhập bằng tài khoản của mình. Nếu thấy giao diện cũ, dùng Ctrl+F5 trên máy tính. 2. Mở hồ sơ có sẵn, xem một ảnh và một hợp đồng theo quyền. Không đưa nội dung thật vào ảnh chụp hỗ trợ. 3. Nếu cần thử thao tác ghi, dùng dữ liệu giả theo quy trình kiểm thử; nếu nhận HTTP 500 thì kiểm bản ghi đã tạo chưa trước khi thử lại. 4. Khi cả bốn container đã healthy, có thể kiểm adapter một lần: ```sh sh /volume2/docker-v2/ncv-tools/dcims-v1/dcims.sh check ``` Kết quả kỳ vọng với bản hiện tại: **NCV_VOLUME2_READY version=0.2.30**. Check không update/build, nhưng có thể tạo/xóa file thử trong media/backup; không dùng khi hệ thống đang dừng hoặc Docker treo. Nếu cần đối chiếu DSM sau khi bốn service đã healthy, kiểm helper đã cài: ```sh sh /volume2/docker-v2/ncv-tools/dcims-v1/sync-dsm-compose.sh check ``` Kỳ vọng **DSM_COMPOSE_SYNC_CHECK_OK**. Lỗi sync không phải lý do chạy lại migration/update; ghi lỗi và đối chiếu riêng cấu hình DSM. Nếu website và dữ liệu hoạt động bình thường, kết thúc. Không cần chạy update 0.2.30, cài lại công cụ hoặc bấm Build trong DSM. Trạng thái project xanh/healthy là một dấu hiệu, không thay thế kiểm truy cập thực tế. ## Xử lý lỗi — biết lúc nào cần dừng | Hiện tượng | Việc cần làm | |---|---| | ncv-dcims còn khóa / thiếu marker | Mount đúng share trong DSM; không tạo lại thư mục hoặc marker | | Docker không tìm thấy | Kiểm PATH hoặc đường dẫn Docker đầy đủ; không cài lại ứng dụng | | Docker không phản hồi | Ngắt kiểm tra, xem tình trạng Container Manager/NAS; không lặp start/build/prune | | Database sai volume hoặc PG_VERSION | Dừng; đối chiếu volume hiện có và hồ sơ triển khai | | Container thiếu hoặc unhealthy | Kiểm trạng thái và log đúng service; không dựng database mới hoặc dùng Compose base | | Container healthy nhưng web không vào | Kiểm gateway, tunnel Cloudflare, hostname/TLS và DNS; không đổi dữ liệu để sửa đường truy cập | | Lỗi sau update/migration | Xem stage và backup của updater. Không tự start image cũ/restore nếu schema có thể đã đổi | Để xem log của một service gặp lỗi, thay TEN_CONTAINER bằng đúng tên trong bảng trên: ```sh docker logs --since 10m --tail 80 TEN_CONTAINER ``` Chỉ xem nội bộ; trước khi gửi hỗ trợ, che mật khẩu, token, đường dẫn nhạy cảm và thông tin bệnh nhân. Ghi thời điểm reboot, trạng thái share, tên container, lỗi ngắn và bước đã làm. Không cần gửi .env, khóa hoặc toàn bộ log. Không dùng down -v, Clean/Delete project, prune volume, chạy lại prepare-volume2 hoặc sửa retention/ledger để xử lý reboot. Nếu NAS đã tự chạy lại bình thường thì chỉ cần kiểm tra, không chạy thêm. ## Phiếu xác nhận sau reboot Ngày/giờ: __________________ Người thực hiện: __________________ - [ ] Volume 1/2 sẵn sàng; Container Manager phản hồi. - [ ] Share ncv-dcims đã mount; storage preflight đạt. - [ ] PostgreSQL dùng đúng external volume V2, PG_VERSION 17 và healthy. - [ ] API/Web/Gateway healthy; tunnel running. - [ ] Đăng nhập và mở ảnh/hợp đồng được. - [ ] Ghi nhận lỗi còn lại hoặc kết thúc kiểm tra. Đây là phiếu trống. Chưa chạy thử reboot NAS trong đợt cập nhật tài liệu này. Tự mở khóa sau reboot, task enabled và backup ngoài NAS vẫn cần xác nhận riêng.