Chuyển đến nội dung chính
Ayakaleaf Pro hỗ trợ mở rộng theo chiều ngang (horizontal scaling). Chúng tôi đã kiểm thử và xác nhận rằng nó chạy đúng với nhiều bản sao (replica).
Tài liệu này liệt kê các yêu cầu kỹ thuật và cung cấp hướng dẫn để chạy Ayakaleaf Pro trên nhiều hơn một node. Việc thiết lập mở rộng theo chiều ngang đòi hỏi rất nhiều công sức. Chúng tôi khuyên bạn chỉ nên cân nhắc mở rộng theo chiều ngang khi đạt đến một quy mô nhất định. Ví dụ, Overleaf đã báo cáo một bản cài đặt on-premises cho tổng cộng 1.000 người dùng chạy thành công trên một máy chủ duy nhất được trang bị hai bộ xử lý 4 nhân và 32GB bộ nhớ hệ thống. Xem tài liệu yêu cầu phần cứng để biết các khuyến nghị. Một bản triển khai Ayakaleaf Pro với mở rộng theo chiều ngang bao gồm một tập hợp các thành phần bên ngoài, chẳng hạn như Load Balancer và một hệ thống lưu trữ tương thích S3.

Yêu cầu

Lưu trữ dữ liệu tập trung, bên ngoài

Việc lưu trữ dữ liệu trong Ayakaleaf Pro có thể được chia thành bốn kho dữ liệu:
  • MongoDB
    • Phần lớn dữ liệu được lưu trữ bền vững trong MongoDB.
    • Chúng tôi hỗ trợ cả phiên bản cục bộ lẫn phiên bản bên ngoài, chẳng hạn như MongoDB Atlas (một dịch vụ MongoDB được quản lý hoàn toàn, chạy trên hạ tầng AWS).
    Lưu ý: Rất tiếc, hiện tại chưa có hỗ trợ chính thức cho các cơ sở dữ liệu tương thích MongoDB như CosmoDB/DocumentDB, vì chúng tôi chưa kiểm thử Ayakaleaf Pro với chúng. Mặc dù việc triển khai Ayakaleaf Pro với các cơ sở dữ liệu tương thích có thể khả thi, chúng tôi chỉ hỗ trợ chính thức các bản triển khai sử dụng MongoDB.
  • Redis
    • Redis lưu trữ dữ liệu tạm thời, chẳng hạn như các cập nhật tài liệu đang chờ trước khi được ghi xuống MongoDB.
    • Redis được dùng để truyền các cập nhật tài liệu giữa các dịch vụ khác nhau và thông báo cho trình soạn thảo về các thay đổi trạng thái trong một dự án nhất định.
    • Redis được dùng để lưu trữ phiên của người dùng.
    • Chúng tôi hỗ trợ cả phiên bản cục bộ lẫn phiên bản bên ngoài.
    Lưu ý: Rất tiếc, hiện tại chưa có hỗ trợ chính thức cho các kho key/value tương thích Redis như KeyDB/Valkey, vì chúng tôi chưa kiểm thử Ayakaleaf Pro với chúng. Mặc dù việc triển khai Ayakaleaf Pro với các kho tương thích có thể khả thi, chúng tôi chỉ hỗ trợ chính thức các bản triển khai sử dụng Redis.
  • Tệp dự án và tệp lịch sử
    • Các tệp dự án không thể chỉnh sửa được lưu trữ bên ngoài MongoDB. Hệ thống lịch sử dự án cũng lưu trữ lịch sử bên ngoài MongoDB.
    • Đối với các phiên bản đơn lẻ nhỏ, chúng tôi hỗ trợ cả hệ thống tệp cục bộ (có thể dựa trên SSD cục bộ, NFS hoặc EBS) lẫn hệ thống lưu trữ dữ liệu tương thích S3.
    • Đối với mở rộng theo chiều ngang, chúng tôi chỉ hỗ trợ các hệ thống lưu trữ dữ liệu tương thích S3.
    Quan trọng: NFS/Amazon EFS/Amazon EBS không được hỗ trợ cho mở rộng theo chiều ngang. Vui lòng xem phần yêu cầu lưu trữ phần cứng về việc mở rộng lưu trữ trong Ayakaleaf Pro để biết thêm chi tiết.
  • Tệp tạm thời (ephemeral)
    • Việc biên dịch LaTeX cần chạy trên đĩa cục bộ tốc độ cao để đạt hiệu năng tối ưu. Kết quả đầu ra của quá trình biên dịch không cần được lưu trữ bền vững hay sao lưu.
    • Việc đệm các tệp mới được tải lên và tạo tệp zip của dự án cũng được hưởng lợi từ việc sử dụng đĩa cục bộ.
Chúng tôi đặc biệt khuyên bạn nên sử dụng đĩa cục bộ. Việc sử dụng bất kỳ loại đĩa mạng nào (chẳng hạn như NFS hoặc EBS) có thể dẫn đến các lỗi biên dịch không mong muốn và các vấn đề hiệu năng khác.

Git-bridge

Các kho git được lưu trữ cục bộ trên đĩa. Không có tùy chọn sao chép (replication) nào. Git-bridge nên được chạy dưới dạng singleton (một phiên bản duy nhất). Để đạt hiệu năng tối ưu, chúng tôi khuyên bạn nên sử dụng đĩa cục bộ cho dữ liệu git-bridge. Đĩa dữ liệu git-bridge nên được sao lưu thường xuyên. Để lưu trữ dữ liệu với mở rộng theo chiều ngang, bạn cần:
  • một phiên bản MongoDB tập trung mà tất cả các phiên bản Ayakaleaf Pro đều có thể truy cập
  • một phiên bản Redis tập trung mà tất cả các phiên bản Ayakaleaf Pro đều có thể truy cập
  • một hệ thống lưu trữ tương thích S3 tập trung cho các tệp dự án và tệp lịch sử
  • một đĩa cục bộ trên mỗi phiên bản cho các tệp tạm thời
  • một đĩa cục bộ trên phiên bản chứa container git-bridge để lưu dữ liệu git-bridge

Yêu cầu đối với Load balancer

  • Định tuyến cố định (persistent routing), ví dụ: sử dụng cookie Yêu cầu này xuất phát từ các thành phần sau:
    • Khả năng chỉnh sửa thời gian thực trong Ayakaleaf Pro sử dụng WebSocket với phương án dự phòng là XHR polling. Mỗi phiên chỉnh sửa có trạng thái cục bộ ở phía máy chủ, và các yêu cầu của một phiên chỉnh sửa nhất định luôn cần được định tuyến đến cùng một phiên bản Ayakaleaf Pro. Tính năng cộng tác sử dụng Redis Pub/Sub để chia sẻ cập nhật giữa nhiều phiên bản Ayakaleaf Pro.
    • Quá trình biên dịch LaTeX giữ kết quả đầu ra và bộ nhớ đệm biên dịch ở cục bộ để tối ưu hiệu năng. Khi gửi một yêu cầu biên dịch đến một phiên bản Ayakaleaf Pro, các yêu cầu tải xuống PDF/log tiếp theo cần được định tuyến đến cùng phiên bản Ayakaleaf Pro đó.
  • Thời gian chờ yêu cầu dài để hỗ trợ biên dịch các tài liệu LaTeX lớn
  • Hỗ trợ WebSocket để đạt hiệu năng tối ưu
  • Kích thước payload POST 50MB
  • Thời gian chờ keep-alive phải thấp hơn thời gian chờ keep-alive của Ayakaleaf Pro Thời gian chờ keep-alive trong Ayakaleaf Pro có thể được cấu hình bằng biến môi trường NGINX_KEEPALIVE_TIMEOUT. Giá trị mặc định là 65s. Với giá trị mặc định, thời gian chờ keep-alive 60s trên load balancer sẽ hoạt động tốt. Với NGINX_KEEPALIVE_TIMEOUT=120, load balancer có thể chọn 115s.
  • IP của client Đặt header yêu cầu X-Forwarded-For thành IP của client.
  • Khi kết thúc SSL (SSL termination) Load balancer cần thêm header yêu cầu X-Forwarded-Proto: https.

Cấu hình Ayakaleaf Pro

Secret Các phiên bản Ayakaleaf Pro cần thống nhất về các secret dùng chung:
  • WEB_API_PASSWORD (xác thực web api)
  • STAGING_PASSWORD và V1_HISTORY_PASSWORD có cùng giá trị (xác thực lịch sử)
  • CRYPTO_RANDOM (cho cookie phiên)
  • OT_JWT_AUTH_KEY (xác thực lịch sử)
  • OVERLEAF_INVITE_TOKEN_SECRET (token chia sẻ qua liên kết, bắt buộc: nếu thiếu, Ayakaleaf Pro sẽ từ chối khởi động)
Tất cả các secret này cần được cấu hình với giá trị duy nhất riêng và được chia sẻ giữa các phiên bản. Nếu không được cấu hình và các yêu cầu của người dùng được định tuyến đến các phiên bản Ayakaleaf Pro khác nhau, yêu cầu của họ sẽ không vượt qua được các bước kiểm tra xác thực, và họ sẽ thường xuyên bị chuyển hướng về trang đăng nhập hoặc các thao tác của họ trên giao diện sẽ thất bại theo những cách không mong muốn. Khi không được cấu hình, Ayakaleaf Pro sẽ dùng một giá trị ngẫu nhiên mới cho mỗi secret dựa trên 32 byte ngẫu nhiên từ /dev/urandom (256 bit ngẫu nhiên).
MongoDB Trỏ OVERLEAF_MONGO_URL đến phiên bản MongoDB tập trung. Redis Trỏ OVERLEAF_REDIS_HOST và REDIS_HOST đến phiên bản Redis tập trung. Lưu trữ tương thích S3 cho tệp dự án và tệp lịch sử Vui lòng xem tài liệu về lưu trữ tương thích S3 để biết chi tiết. Tệp tạm thời (ephemeral) Bind-mount mặc định của một SSD cục bộ vào /var/lib/overleaf là đủ. Hãy đảm bảo trỏ SANDBOXED_COMPILES_HOST_DIR đến điểm mount trên máy chủ.
Chúng tôi đặc biệt khuyên bạn nên sử dụng đĩa cục bộ. Việc sử dụng bất kỳ loại đĩa mạng nào (chẳng hạn như NFS hoặc EBS) có thể dẫn đến các lỗi biên dịch không mong muốn và các vấn đề hiệu năng khác.
Cấu hình proxy
  • Đặt OVERLEAF_TRUSTED_PROXY_IPS thành loopback cộng với IP của các load balancer, ví dụ loopback,198.18.0.1, để có IP client chính xác. Có thể chỉ định nhiều IP hoặc CIDR, phân tách bằng dấu phẩy.
Tích hợp Git-bridge Container git-bridge cần một container Ayakaleaf Pro “anh em” (sibling) để xử lý các yêu cầu git gửi đến. Container sibling này cũng có thể phục vụ lưu lượng người dùng thông thường. Trong cấu hình mẫu, phiên bản đầu tiên đóng vai trò container sibling cho git-bridge, nhưng thực tế bất kỳ phiên bản nào cũng có thể đảm nhận vai trò đó. Tại sao chúng ta cần chỉ định một container Ayakaleaf Pro làm sibling cho git-bridge? Ayakaleaf Pro cung cấp các URL tải xuống của dịch vụ lịch sử cho git-bridge. Chúng ta cần cấu hình để các URL lịch sử này có thể truy cập được từ container git-bridge. Cấu hình container Ayakaleaf Pro:
  • Đặt GIT_BRIDGE_ENABLED thành 'true'
  • Đặt GIT_BRIDGE_HOST thành <git-bridge container name>, ví dụ: git-bridge
  • Đặt GIT_BRIDGE_PORT thành 8000
  • Đặt V1_HISTORY_URL thành http://<server-pro sibling container name>:3100/api. Lưu ý: Điều này chỉ cần thiết trên container sibling của container git-bridge. Các phiên bản khác có thể dùng URL localhost, vốn là giá trị mặc định.
Cấu hình container git-bridge:
  • Đặt GIT_BRIDGE_API_BASE_URL thành http://<server-pro sibling container name>/api/v0, ví dụ: http://server-pro-ha-1/api/v0
  • Đặt GIT_BRIDGE_OAUTH2_SERVER thành http://<server-pro sibling container name>, ví dụ: http://server-pro-ha-1
  • Đặt GIT_BRIDGE_POSTBACK_BASE_URL thành http://<git-bridge container name>:8000, ví dụ: http://git-bridge:8000
  • Đặt GIT_BRIDGE_ROOT_DIR thành đĩa dữ liệu git-bridge được bind-mount, ví dụ: /data/git-bridge
Cấu hình sau đây minh họa một thiết lập độc lập (self-contained). Để bản demo hoạt động, bạn cần cung cấp khóa/chứng chỉ SSL hợp lệ và điều chỉnh OVERLEAF_SITE_URL. Đối với thiết lập thực tế, bạn phải thay các secret giả bằng secret thật như được ghi chú trong cấu hình. Đối với thiết lập thực tế, bạn cần chuyển từng container lên các node chuyên dụng và điều chỉnh địa chỉ IP cho phù hợp với cấu hình mạng cục bộ của bạn.Các lần biên dịch chạy trong các container TeX Live bên cạnh mỗi phiên bản Ayakaleaf Pro. Trước tiên hãy pull TeX Live image trên mọi máy chủ Ayakaleaf Pro, ví dụ docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

Phần cứng

Chúng tôi khuyến nghị sử dụng cùng thông số phần cứng cho tất cả các phiên bản Ayakaleaf Pro tham gia vào việc mở rộng theo chiều ngang. Các khuyến nghị chung về thông số phần cứng cho các phiên bản Ayakaleaf Pro vẫn được áp dụng.

Nâng cấp Ayakaleaf Pro

Trong quá trình nâng cấp, Ayakaleaf Pro tự động chạy các bước di chuyển (migration) cơ sở dữ liệu. Các bước di chuyển này không được thiết kế để chạy song song từ nhiều phiên bản. Các bước di chuyển cần hoàn tất trước khi ứng dụng web thực sự được khởi động. Bạn có thể kiểm tra nhật ký để tìm mục Finished migrations hoặc chờ cho đến khi ứng dụng bắt đầu nhận lưu lượng. Quy trình nâng cấp như sau:
  1. Lên lịch một khung thời gian bảo trì
  2. Dừng tất cả các phiên bản Ayakaleaf Pro
  3. Tạo một bản sao lưu nhất quán như được mô tả trong tài liệu
  4. Khởi động một phiên bản Ayakaleaf Pro duy nhất với phiên bản mới
  5. Xác nhận rằng phiên bản mới hoạt động như mong đợi
  6. Khởi động các phiên bản còn lại với phiên bản mới
Lần sửa đổi cuối 2 tháng 11, 2026