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).
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).
-
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.
-
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.
-
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ớiNGINX_KEEPALIVE_TIMEOUT=120, load balancer có thể chọn 115s. -
IP của client
Đặt header yêu cầu
X-Forwarded-Forthà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 HAProxy mẫu
Cấu hình HAProxy mẫu
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_PASSWORDvàV1_HISTORY_PASSWORDcó 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)
/dev/urandom (256 bit ngẫu nhiên).
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.
- Đặt
OVERLEAF_TRUSTED_PROXY_IPSthànhloopbackcộ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
GIT_BRIDGE_ENABLEDthành'true' -
Đặt
GIT_BRIDGE_HOSTthành<git-bridge container name>, ví dụ:git-bridge -
Đặt
GIT_BRIDGE_PORTthành8000 -
Đặt
V1_HISTORY_URLthànhhttp://<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.
- Đặt
GIT_BRIDGE_API_BASE_URLthànhhttp://<server-pro sibling container name>/api/v0, ví dụ:http://server-pro-ha-1/api/v0 - Đặt
GIT_BRIDGE_OAUTH2_SERVERthànhhttp://<server-pro sibling container name>, ví dụ:http://server-pro-ha-1 - Đặt
GIT_BRIDGE_POSTBACK_BASE_URLthànhhttp://<git-bridge container name>:8000, ví dụ:http://git-bridge:8000 - Đặt
GIT_BRIDGE_ROOT_DIRthành đĩa dữ liệu git-bridge được bind-mount, ví dụ:/data/git-bridge
Cấu hình docker-compose.yml mẫu
Cấu hình docker-compose.yml mẫu
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ụcFinished 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:
- Lên lịch một khung thời gian bảo trì
- Dừng tất cả các phiên bản Ayakaleaf Pro
- Tạo một bản sao lưu nhất quán như được mô tả trong tài liệu
- Khởi động một phiên bản Ayakaleaf Pro duy nhất với phiên bản mới
- Xác nhận rằng phiên bản mới hoạt động như mong đợi
- Khởi động các phiên bản còn lại với phiên bản mới

