Hướng dẫn cài đặt và cập nhật

================================================================================ YELLOWDUCK — HƯỚNG DẪN CÀI ĐẶT VÀ CẬP NHẬT ================================================================================ File này là BẢN GỐC duy nhất của hướng dẫn: trang tải trên mạng và file đi kèm trong gói cài đều đọc từ đây, nên hai nơi không bao giờ lệch nhau. Bộ cài tên là yd-setup. Nó làm cả hai việc: cài lần đầu, và áp dụng gói cập nhật cho những lần sau. Chỉ một file, không có file thứ hai. -------------------------------------------------------------------------------- 1. CHUẨN BỊ -------------------------------------------------------------------------------- Cần có sẵn trên máy chủ bệnh viện: - PostgreSQL đang chạy, và biết mật khẩu của người dùng postgres - Khoảng 5 GB trống ổ đĩa Phần mềm còn lại tuỳ theo NỀN TẢNG: - Linux (Ubuntu 24.04 x64): libicu74 (thư viện ngôn ngữ — Ubuntu 24.04 chuẩn thường có sẵn) nginx (web server) - Windows x64: IIS (web server) ASP.NET Core Hosting Bundle (cần module aspnetcorev2.dll) Không cần .NET runtime: yd-setup và gói cài là bản TỰ CHỨA (đã gói sẵn .NET bên trong). Trên Windows/IIS, thứ máy cần là ASP.NET Core Hosting Bundle ở trên — một thứ KHÁC hẳn .NET runtime thường. Không cần URL Rewrite Module: ứng dụng đã bỏ phần cấu hình rewrite (khối đó từng làm lỗi 500.19 trên máy Windows thật). Đừng cài thêm. Bộ cài SẼ TỰ CÀI phần còn thiếu: PostgreSQL, libicu74, nginx (Linux), hoặc bật IIS và cài Hosting Bundle (Windows). Không phải tự đi cài. Điều kiện duy nhất: máy CHƯA CÓ thì phải chép sẵn GÓI TIỀN ĐỀ vào máy — xem mục "MÁY CHƯA CÓ GÌ" ngay dưới. Các file cần tải về: - yd-setup bộ cài (chọn đúng nền tảng: win-x64 hoặc linux-x64) - yellowduck-<phiên-bản>-<nền-tảng>.zip gói cài Máy trắng (chưa có đủ phần mềm kể trên) còn phải tải thêm GÓI TIỀN ĐỀ — xem mục ngay dưới. Máy không có internet: tải các file này ở máy khác rồi chép sang bằng USB. Toàn bộ quá trình cài KHÔNG cần mạng. ---------------------------------------- MÁY CHƯA CÓ GÌ: TẢI THÊM GÓI TIỀN ĐỀ ---------------------------------------- Máy đã có đủ PostgreSQL và web server (nginx/IIS) thì BỎ QUA mục này. Máy trắng (chưa có gì) thì gói tiền đề là file BẮT BUỘC phải tải kèm: thiếu nó, bộ cài báo thiếu từng thứ rồi dừng — không tự cài được gì. Tên file theo khuôn: yd-prereq-<hệ-điều-hành>-<phiên-bản>-<nền-tảng>-<ngày>.zip - Linux: yd-prereq-ubuntu-24.04-linux-x64-20260903.zip - Windows: yd-prereq-windows-2022-win-x64-20260903.zip (ngày là ngày phát hành — cứ lấy đúng file trang tải đưa, đừng đổi tên) Dung lượng: - Linux: khoảng 53 MB (16 file .deb) — đo 03/09/2026 - Windows: 449,3 MB (471.123.816 byte) — đo 04/09/2026 gồm bộ cài PostgreSQL 16.10-1 và ASP.NET Core Hosting Bundle 10.0.11, kèm prereq.json + SOURCES.txt + chữ ký. Số của bản Windows là dung lượng gói ĐÃ KÝ đo được, không phải ước lượng. Nén gần như không giảm được gì (hai file bên trong vốn đã là bộ cài nén sẵn), nên gói phát hành sau chỉ xê dịch khi Mio đổi phiên bản thành phần. Gói Windows to hơn Linux gần chín lần là bình thường, không phải tải nhầm file: bên Linux là các thư viện nhỏ, còn bên Windows phải mang trọn bộ cài PostgreSQL. Trang tải in mã SHA256 của gói tiền đề. Đối chiếu bằng đúng lệnh ở mục 2 (sha256sum / certutil -hashfile), thay tên yd-setup bằng tên file .zip. Đặt file .zip vào một trong ba chỗ sau — theo đúng thứ tự — bộ cài TỰ TÌM, không cần gõ đường dẫn: 1. cạnh file yd-setup (cùng một thư mục) 2. thư mục đang chạy lệnh 3. ổ USB cắm vào máy Không thấy ở chỗ nào, bộ cài in ra tên file cần tải và địa chỉ trang tải rồi dừng. Gói tiền đề phát hành theo nhịp RIÊNG với bộ cài và gói cài: nâng bản gói cài không bắt buộc phải tải lại gói tiền đề, trừ khi trang tải nói rõ. Gói Linux chứa các file .deb của bên thứ ba theo giấy phép GPL. Trong gói có file SOURCES.txt ghi rõ nguồn tải và cách xin mã nguồn — khách có quyền yêu cầu mã nguồn theo đúng hướng dẫn trong file đó. Muốn chạy RIÊNG phần cài tiền đề (kiểm - cài - kiểm lại) thì dùng lệnh: Linux: sudo ./yd-setup --prereq Windows: yd-setup.exe --prereq Đường dẫn gói là TUỲ CHỌN: không ghi thì bộ cài tự dò các chỗ kể trên. Lệnh in ra mã kết thúc: 0 = đủ điều kiện; 3 = còn điều kiện chặn (đọc bảng in ra để biết thứ còn thiếu); mã khác = thất bại. -------------------------------------------------------------------------------- 2. KIỂM FILE TẢI VỀ CÓ NGUYÊN VẸN KHÔNG -------------------------------------------------------------------------------- Trang tải có in mã SHA256 của yd-setup. Đối chiếu trước khi chạy: Linux: sha256sum yd-setup Windows: certutil -hashfile yd-setup.exe SHA256 Mã in ra phải TRÙNG với mã trên trang tải. Không trùng thì đừng chạy, tải lại. Vì sao phải làm thủ công: yd-setup chính là công cụ đi kiểm chữ ký của gói cài, nên bản thân nó không có chữ ký nào để tự kiểm. Gói .zip thì khác — nó có chữ ký và yd-setup tự kiểm, không cần làm gì thêm. -------------------------------------------------------------------------------- 3. LINUX: CẤP QUYỀN CHẠY CHO BỘ CÀI -------------------------------------------------------------------------------- chmod +x yd-setup BƯỚC NÀY BẮT BUỘC và phải làm BẰNG TAY. Quyền chạy bị mất khi file đi qua scp hoặc qua file .zip, và bộ cài không thể tự cấp quyền cho chính nó. Quên bước này thì lệnh ở mục 4 báo "Permission denied". Windows không cần bước này. -------------------------------------------------------------------------------- 4. CÀI LẦN ĐẦU -------------------------------------------------------------------------------- Linux: sudo ./yd-setup Windows: chạy yd-setup.exe với quyền Administrator Màn hình sẽ hỏi lần lượt. Cứ đọc và trả lời: - Thư mục cài đặt (mặc định /opt/yellowduck) - Thông tin kết nối PostgreSQL - Đường dẫn tới file .zip gói cài - Mã kích hoạt (xem mục 5) Trước khi làm gì, bộ cài chạy một lượt KIỂM TRA TRƯỚC KHI CHẠY: đủ đĩa, đúng phiên bản PostgreSQL, có quyền ghi, cổng còn trống. Thiếu thứ gì nó nói thẳng thiếu thứ đó và cách sửa, không làm nửa chừng rồi bỏ dở. -------------------------------------------------------------------------------- 5. XIN MÃ KÍCH HOẠT -------------------------------------------------------------------------------- Bộ cài sẽ in ra MÃ MÁY — một chuỗi ký tự dài. Gửi chuỗi đó cho Mio, Mio gửi lại mã kích hoạt, dán vào là xong. Mã kích hoạt gắn chặt với một máy. Đổi máy (hỏng ổ cứng, đổi main, cài lại) thì phải xin CẤP LẠI MÃ — mã cũ chết, mã mới không cộng thêm ngày sử dụng. Máy còn chạy được thì chạy lệnh này trước khi bỏ máy: ./yd-setup surrender Lệnh này TRẢ LẠI GIẤY PHÉP: nó tắt giấy phép trên máy cũ và in ra một mã trả lại. Gửi mã đó cho Mio thì được cấp lại ngay, không cần ai duyệt. Máy đã chết hẳn thì báo Mio, nhưng đường này chậm hơn vì cần người duyệt. -------------------------------------------------------------------------------- 6. CẬP NHẬT LÊN BẢN MỚI -------------------------------------------------------------------------------- Linux: sudo ./yd-setup --apply /đường/dẫn/tới/gói.zip Windows: yd-setup.exe --apply D:\đường\dẫn\tới\gói.zip Bộ cài sẽ: kiểm chữ ký gói → sao lưu dữ liệu và cơ sở dữ liệu → tạm dừng site → tráo thư mục app → chạy migration → bật site lên → kiểm site chạy được. Hỏng ở bất kỳ bước nào thì nó TỰ QUAY VỀ BẢN CŨ. Dữ liệu của bệnh viện nằm ngoài thư mục app nên không bị đụng tới. Ba thứ dưới đây KHÔNG bị ghi đè khi cập nhật: config/ cấu hình, giấy phép data/ file người dùng tải lên, kết xuất, log backups/ bản sao lưu Nghĩa là: cấu hình đã khai một lần thì giữ nguyên qua mọi lần cập nhật. -------------------------------------------------------------------------------- 7. QUAY VỀ BẢN CŨ -------------------------------------------------------------------------------- Cập nhật xong, chạy vài hôm mới phát hiện vấn đề: sudo ./yd-setup rollback Lệnh này đưa cả thư mục app lẫn cơ sở dữ liệu về bản sao lưu gần nhất. Dữ liệu người dùng nhập SAU khi cập nhật sẽ mất theo — cân nhắc trước khi chạy. -------------------------------------------------------------------------------- 8. GẶP LỖI THÌ LÀM GÌ -------------------------------------------------------------------------------- Bộ cài không bao giờ báo lỗi cụt ngủn. Mọi thông báo đều nói rõ ba điều: cái gì hỏng, ở đâu, và sửa bằng cách nào. Đọc hết thông báo trước khi gọi hỗ trợ. Cần gọi hỗ trợ thì chuẩn bị sẵn: - Ảnh chụp màn hình của thông báo lỗi - Kết quả của lệnh: ./yd-setup --version - File log trong thư mục: data/logs/ ================================================================================