(Di chuyển v3.5.13) Di chuyển toàn bộ lịch sử dự án

​

Di chuyển toàn bộ lịch sử dự án

Bản phát hành 3.5.x của Community Edition bao gồm tính năng Full Project History vốn đã có trong dịch vụ SaaS của chúng tôi, overleaf.com

Sau khi nâng cấp phiên bản của bạn lên Overleaf CE 3.5.13, tất cả các dự án mới sẽ sử dụng Full Project History theo mặc định. Các dự án hiện có sẽ tiếp tục sử dụng hệ thống History cũ cho đến khi được di chuyển.

Nếu bạn nâng cấp lên 3.5.13 rồi quyết định hạ cấp xuống một phiên bản cũ hơn, bạn nên khôi phục từ một bản sao lưu toàn bộ hệ thống. Lịch sử của các dự án được tạo trong 3.5.13 không tương thích với các phiên bản Overleaf CE cũ hơn.

Full Project History mới mang lại một số cải tiến cho người dùng:

• Theo dõi các thay đổi trong tệp nhị phân, điều mà hệ thống cũ không hỗ trợ.
• Hỗ trợ các phiên bản được gắn nhãn.
• Hệ thống nhìn chung ổn định hơn, ít có nguy cơ mất dữ liệu hơn.

Xem tài liệu Full Project History để biết thêm thông tin về toàn bộ lịch sử dự án.

​

Di chuyển các dự án hiện có

1. Tạo bản sao lưu

   Tạo một bản sao lưu đầy đủ cho phiên bản của bạn với một snapshot nhất quán của các thư mục mongo, redis và sharelatex.

2. Cập nhật

   Cập nhật phiên bản image sharelatex/sharelatex lên 3.5.13.

   Toolkit: Dùng script $ bin/upgrade để nâng cấp toolkit lên phiên bản mới nhất và chỉnh sửa config/version thành 3.5.13.

3. Khởi động phiên bản

   Lý tưởng nhất là bạn nên ngăn người dùng truy cập vào phiên bản của mình trong khi quá trình di chuyển diễn ra, để tránh mất dữ liệu trong trường hợp bạn cần khôi phục bản sao lưu. Xem Di chuyển ngoại tuyến để biết thêm thông tin về cách thực hiện.

4. Chờ cho đến khi tất cả dịch vụ hoạt động

   Chờ cho đến khi tất cả dịch vụ đã khởi động và đang chạy (xem lệnh bên dưới)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Chạy script di chuyển

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   
   # legacy docker-compose.yml users:
   $ docker exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   

   --force-clean xóa dữ liệu lịch sử dự án đã được di chuyển một phần trong hệ thống mới, cho phép thử lại việc di chuyển đối với từng dự án đã thất bại trong các lần thử trước;

   --fix-invalid-characters thay thế các ký tự không in được mà hệ thống lịch sử mới không hỗ trợ;

   --convert-large-docs-to-file chuyển đổi các tài liệu vượt quá ngưỡng kích thước có thể chỉnh sửa 2MB thành tệp không thể chỉnh sửa)

   Kết quả đầu ra sẽ trông như sau:

   Migrated Projects  :  1
   Total Projects     :  51
   Remaining Projects :  51
   Total history records to migrate: 98
   Starting migration...
   Migrating project: 63d29b5772dd80015a81bffe
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   Migrating project: 63d29c2e72dd80015a81c0a2
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   
   // …
   
   Migration complete
   ==================
   Projects migrated:  51
   Projects failed:  0
   Done.
   

   Nếu quá trình di chuyển thành công, bạn sẽ nhận được mã thoát 0, và các dòng cuối cùng cho biết không có lỗi nào:

   Projects failed:  0
   Done.
   

   Bạn có thể mở lại quyền truy cập cho người dùng (xem bước tiếp theo). Nếu có lỗi, vui lòng xem phần khắc phục sự cố bên dưới. Bạn vẫn có thể mở lại trang nếu các vấn đề chưa được khắc phục ngay, và các dự án chưa được di chuyển sẽ vẫn ở trên hệ thống lịch sử cũ.

6. Mở lại trang

   Nếu bạn đã chọn thực hiện di chuyển ngoại tuyến thì bạn sẽ cần mở lại trang. Nếu bạn vẫn đang đăng nhập, bạn cần:

   1. Nhấp vào nút Admin và chọn Manage Site
   2. Nhấp vào tab Open/Close Editor
   3. Nhấp vào nút Reopen Editor

   Nếu bạn đã đóng trình duyệt thì bạn cần khởi động lại trang bằng $ bin/up.

​

Di chuyển ngoại tuyến

Để ngăn người dùng đăng nhập trong khi script di chuyển lịch sử đang chạy, vui lòng làm theo các bước sau:

• Đăng nhập vào phiên bản Overleaf của bạn bằng tài khoản quản trị viên
• Nhấp vào nút Admin và chọn Manage Site
• Nhấp vào tab Open/Close Editor
• Nhấp vào nút Close Editor
• Nhấp vào nút Disconnect all users

Sau khi thực hiện xong, mọi người dùng đang đăng nhập sẽ bị chuyển hướng đến trang bảo trì, và mọi người dùng mới truy cập trang đăng nhập sẽ thấy trang bảo trì và không thể đăng nhập.

​

Di chuyển trực tuyến

Có thể chạy các script di chuyển trong khi ứng dụng vẫn đang chạy. Có một vài điểm cần cân nhắc:

• Quá trình di chuyển tiêu tốn nhiều CPU, bạn nên theo dõi mức sử dụng tài nguyên trong khi script đang chạy.
• Với giá trị --concurrency cao, vòng lặp sự kiện (event loop) trong một số dịch vụ (đặc biệt là track-changes) có thể bị chặn, dẫn đến trải nghiệm người dùng bị suy giảm. Chúng tôi khuyến nghị bắt đầu với giá trị mặc định --concurrency=1.
• Bạn có thể dừng script bất cứ lúc nào. Khi khởi động lại, quá trình di chuyển sẽ tiếp tục từ chỗ bạn đã dừng. Điều này hữu ích nếu bạn muốn chạy việc di chuyển vào những giờ ít bận rộn hơn (ví dụ: ban đêm).

Khuyến nghị của chúng tôi là đóng trang và chạy di chuyển ngoại tuyến trong một khung thời gian bảo trì khi số lượng dự án của bạn ít hơn 1000 dự án (db.projects.count()). Nếu số lượng dự án lớn, bạn có thể chạy script và theo dõi tiến trình, sau đó quyết định tiếp tục chạy trực tuyến hay ngoại tuyến tùy theo trường hợp cụ thể của bạn.

​

Dọn dẹp dữ liệu lịch sử cũ

Một script để dọn dẹp dữ liệu lịch sử cũ đã được thêm vào Server Pro 3.5.6, 4.0.6 và 4.1.0.

bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"

Script này có thể được chạy sau khi tất cả các dự án đã được di chuyển. Nó cũng có thể được dùng để giải phóng một phần dung lượng trong khi thực hiện di chuyển trực tuyến.

Trong Server Pro trước phiên bản 3.5.13, script này xóa nội dung của các collection docHistory và docHistoryIndex. MongoDB không giải phóng dung lượng đĩa sau khi bạn xóa tài liệu; thay vào đó, nó sẽ tái sử dụng dung lượng đó cho các tài liệu sau này trong cùng collection. Sau khi di chuyển lịch sử, sẽ không có gì ghi vào các collection này nữa, vì vậy dung lượng đĩa sẽ vẫn không được sử dụng.

Nếu bạn muốn giải phóng lại dung lượng đĩa, bạn có thể nâng cấp lên Server Pro 3.5.13 (khi vẫn dùng bản phát hành 3.x) hoặc Server Pro 4.2.5 (khi dùng bản phát hành 4.x) và chạy lại script dọn dẹp.

Script dọn dẹp đi kèm trong các bản vá mới nhất của Server Pro 3.5.x và 4.x.x mới nhất sẽ xóa bỏ (drop) các collection ở bước cuối cùng.

Chạy lại script dọn dẹp là an toàn.

​

Khắc phục sự cố

Chúng tôi sẽ bổ sung các lời khuyên khắc phục sự cố tại đây. Xin lưu ý rằng mặc dù thông thường chúng tôi chỉ hỗ trợ khách hàng Server Pro, nhưng do tính chất của đợt di chuyển này, chúng tôi cũng sẽ cố gắng hết sức để hỗ trợ người dùng CE gặp các vấn đề cụ thể liên quan đến việc di chuyển toàn bộ lịch sử dự án.

Nếu script di chuyển toàn bộ lịch sử dự án thất bại (tức là thoát với lỗi hoặc in ra số dự án thất bại khác 0), vui lòng gửi các thông tin sau đến đội ngũ hỗ trợ của chúng tôi qua email [e-mail], bao gồm chi tiết:

Tiêu đề: Full project history migration problem

• Loại phiên bản: CE hoặc Server Pro (xóa mục không phù hợp)
• Kiểu cài đặt: Overleaf toolkit hoặc docker-compose.yml hoặc khác (xóa mục không phù hợp)
• Phiên bản: 3.5.x (toolkit: $ cat config/version)
• Kết quả đầu ra của script di chuyển (nằm trong container tại /overleaf/services/web)
• Migrated Projects: (theo kết quả đầu ra của script di chuyển)
• Total Projects: (theo kết quả đầu ra của script di chuyển)
• Remaining Projects: (theo kết quả đầu ra của script di chuyển)
• Thời lượng di chuyển:
• Kết quả đầu ra của bin/doctor (khi dùng toolkit)
• Phiên bản Toolkit: $ git rev-parse HEAD (khi dùng Toolkit)

Hãy cân nhắc đính kèm các tệp nhật ký của các dịch vụ history-v1, project-history và track-changes vào email. Bạn có thể tìm thấy chúng tại /var/log/sharelatex bên trong container sharelatex và xuất chúng ra như sau:

$ docker cp sharelatex:/var/log/sharelatex/history-v1.log history-v1.log
$ docker cp sharelatex:/var/log/sharelatex/project-history.log project-history.log
$ docker cp sharelatex:/var/log/sharelatex/track-changes.log track-changes.log

Vui lòng loại bỏ mọi thông tin nhạy cảm khỏi các tệp nhật ký trước khi đính kèm.

​

Tìm các cây tệp bị hỏng

Việc di chuyển có thể thất bại đối với các dự án có cây tệp bị lỗi định dạng (ví dụ: tên tệp bị trống). Bạn có thể tìm danh sách các vấn đề này bằng script find_malformed_filetrees, script này kiểm tra tất cả các dự án trong cơ sở dữ liệu:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/find_malformed_filetrees.js"
BAD PATH: 123456789012345678901234 rootFolder.0.1.2.3
BAD PATH: 123456789012345678901234 rootFolder.0.4.5.6
...

Để sửa các đường dẫn không hợp lệ, hãy dùng script fix_malformed_filetree, chạy lệnh một lần cho mỗi đường dẫn bị lỗi:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.1.2.3"
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.4.5.6"
...

​

Hạ cấp dự án từ Full Project History về lịch sử cũ

Nếu có một dự án đã được di chuyển sang Full Project History nhưng bạn muốn quay lại lịch sử cũ, hãy dùng script downgrade_project như sau:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR