Chuyển đến nội dung chính
Ayakaleaf Pro đi kèm tùy chọn chạy biên dịch trong môi trường sandbox an toàn nhằm đáp ứng yêu cầu bảo mật của doanh nghiệp. Điều này được thực hiện bằng cách chạy mỗi dự án trong môi trường docker an toàn riêng của nó.

Cải thiện bảo mật

Biên dịch trong sandbox (Sandboxed Compiles) là cách tiếp cận được khuyến nghị cho Ayakaleaf Pro, vì nhiều tài liệu LaTeX yêu cầu/có khả năng thực thi các lệnh shell tùy ý trong quá trình biên dịch PDF. Nếu bạn sử dụng Sandboxed Compiles, mỗi lần biên dịch sẽ chạy trong một Docker container riêng biệt với các quyền hạn chế, không chia sẻ với bất kỳ người dùng hay dự án nào khác và không có quyền truy cập vào các tài nguyên bên ngoài như mạng của máy chủ host.
Nếu bạn chạy Ayakaleaf Pro không có Sandboxed Compiles, quá trình biên dịch sẽ chạy song song với các lần biên dịch đồng thời khác bên trong Docker container chính, và người dùng có toàn quyền đọc và ghi vào tài nguyên của container sharelatex (hệ thống tệp, mạng và biến môi trường) khi chạy biên dịch LaTeX.

Quản lý gói dễ dàng hơn

Để tránh phải cài đặt gói thủ công, chúng tôi khuyến nghị bật Sandboxed Compiles. Đây là một thiết lập có thể cấu hình trong Ayakaleaf Pro, cho phép người dùng của bạn truy cập cùng môi trường TeX Live như trên overleaf.com nhưng nằm trong bản cài đặt on-premise của riêng bạn. Các TeX Live image được Sandboxed Compiles sử dụng chứa những gói và phông chữ phổ biến nhất đã được kiểm thử với các mẫu trong thư viện của chúng tôi, đảm bảo khả năng tương thích tối đa với các dự án on-premise. Bật Sandboxed Compiles cho phép bạn cấu hình những phiên bản TeX Live mà người dùng có thể chọn trong dự án của họ, đồng thời thiết lập phiên bản TeX Live image mặc định cho các dự án mới.
Nếu bạn chạy Ayakaleaf Pro mà không có Sandboxed Compiles, phiên bản của bạn sẽ mặc định sử dụng một phiên bản TeX Live với scheme cơ bản để biên dịch. Phiên bản cơ bản này nhẹ và chỉ chứa một tập con rất hạn chế các gói LaTeX, điều này rất có thể sẽ dẫn đến lỗi thiếu gói cho người dùng, đặc biệt nếu họ dùng các mẫu dựng sẵn.
Vì Ayakaleaf Pro được thiết kế để hoạt động ngoại tuyến, không có cách tự động nào để tích hợp các mẫu trong thư viện của overleaf.com vào bản cài đặt on-premise của bạn; tuy nhiên, có thể thực hiện việc này thủ công cho từng mẫu. Để biết thêm thông tin về cách thực hiện, vui lòng xem hướng dẫn chuyển mẫu từ overleaf.com của chúng tôi: #transferring-templates-from-overleaf.com.
Sandboxed Compiles yêu cầu container sharelatex có quyền truy cập vào Docker socket trên máy chủ host (thông qua bind mount) để có thể quản lý các container biên dịch anh em (sibling) này.

Cách hoạt động

Khi Sandboxed Compiles được bật, Docker socket sẽ được mount từ máy chủ host vào container sharelatex, để dịch vụ biên dịch trong container có thể tạo các Docker container mới trên host. Sau đó, với mỗi lần chạy trình biên dịch trong mỗi dự án, dịch vụ biên dịch LaTeX (CLSI) sẽ thực hiện các bước sau:
  • Ghi các tệp của dự án ra một vị trí bên trong OVERLEAF_DATA_PATH.
  • Sử dụng Docker socket đã được mount để tạo một container texlive mới cho lần biên dịch.
  • Để container texlive đọc dữ liệu dự án từ vị trí trong OVERLEAF_DATA_PATH.
  • Biên dịch dự án bên trong container texlive.

Bật Sandboxed Compiles

Dành cho người dùng Toolkit

Để bật biên dịch trong sandbox (còn gọi là Sibling containers), hãy đặt các tùy chọn cấu hình sau trong overleaf-toolkit/config/overleaf.rc:
config/overleaf.rc
Để tắt chúng, đặt SIBLING_CONTAINERS_ENABLED=false và chạy bin/up. Khi đó việc biên dịch chạy bên trong container sharelatex với TeX Live cơ bản của nó.

Dành cho người dùng Docker Compose

Thiết lập TexLive Image

Đối với người dùng tại Trung Quốc đại lục, bạn có thể kéo các image từ mirror ghcr.nju.edu.cn để tăng tốc độ tải xuống, sau đó gắn tag cho chúng bằng tên ghcr.io:
KHÔNG sử dụng ghcr.nju.edu.cn trong các thiết lập biến môi trường của toolkit: hãy giữ các tên ghcr.io ở đó. Để ngăn bin/up kéo lại các image từ ghcr.io, hãy đặt SIBLING_CONTAINERS_PULL=false trong config/overleaf.rc. Để giữ các image luôn được cập nhật thông qua mirror, xem Tự động cập nhật TeX Live Full Image.
Ayakaleaf Pro sử dụng ba biến môi trường để xác định các TeX Live image được dùng cho Sandboxed Compiles:
  • TEX_LIVE_DOCKER_IMAGE (tùy chọn), TeX Live image được dùng cho các dự án mới. Image này phải là một trong các image trong ALL_TEX_LIVE_DOCKER_IMAGES. Nếu không được đặt, các dự án mới sẽ dùng image đầu tiên trong ALL_TEX_LIVE_DOCKER_IMAGES.
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (tùy chọn), Danh sách tên của các image, phân tách bằng dấu phẩy, theo cùng thứ tự, được hiển thị trong cài đặt trình biên dịch. Nếu không được đặt, hoặc ngắn hơn danh sách image, một image sẽ được hiển thị bằng tag của nó, ví dụ 2026.1.
  • ALL_TEX_LIVE_DOCKER_IMAGES (bắt buộc), Danh sách các TeX Live image sẽ sử dụng, phân tách bằng dấu phẩy. Nếu Overleaf Toolkit được dùng để triển khai, các image này sẽ được tải xuống hoặc cập nhật. Để bỏ qua việc tải xuống, hãy đặt SIBLING_CONTAINERS_PULL=false trong config/overleaf.rc.
Khi khởi động phiên bản Ayakaleaf Pro bằng lệnh bin/up, Toolkit sẽ tự động pull tất cả các image được liệt kê trong ALL_TEX_LIVE_DOCKER_IMAGES. Dưới đây là một ví dụ trong đó chúng tôi mặc định dùng TeX Live 2026 cho các dự án mới, và giữ lại 2025 cho các dự án cũ.
Cấu hình sau cài đặt tất cả các TeX Live Docker image đầy đủ từ 2025 đến 2026. Chúng tôi khuyến nghị có ít nhất 64 GB dung lượng lưu trữ trống trước khi sử dụng cấu hình này.
config/variables.env
Chúng tôi đặc biệt khuyến nghị thiết lập ít nhất 2 image texlive-full. Để biết lý do chi tiết, xem #known-issues

Các TeX Live image có sẵn

Đây là một loạt TeX Live image được tối ưu hóa đặc biệt cho Overleaf, cũng có thể được thêm vào TEX_LIVE_DOCKER_IMAGE và ALL_TEX_LIVE_DOCKER_IMAGES:
  • ghcr.io/ayaka-notes/texlive-full:2026.1 (cũng là tag latest)
  • ghcr.io/ayaka-notes/texlive-full:2025.1
  • ghcr.io/ayaka-notes/texlive-full:2024.1
  • ghcr.io/ayaka-notes/texlive-full:2023.1
  • ghcr.io/ayaka-notes/texlive-full:2022.1
  • ghcr.io/ayaka-notes/texlive-full:2021.1
  • ghcr.io/ayaka-notes/texlive-full:2020.1
Có một quy tắc nghiêm ngặt về cách image bắt buộc phải được gắn tag (áp dụng regex ^[0-9]+.[0-9]+, trong đó số đầu tiên xác định năm của TeX Live và số thứ hai là phiên bản bản vá).

Tôi có thể sử dụng Image Registry khác không

Một số người có thể thắc mắc liệu có thể thay ghcr.io bằng một trang mirror khác, hoặc chuyển texlive sang image khác từ docker hub không?
Không, chúng tôi không khuyến nghị điều này vì cấu hình tương đối phức tạp. Nếu bạn tải xuống từ một trang mirror, bạn có thể đổi tên image của mình thành ghcr.io/ayaka-notes/texlive-full. Tuy nhiên, nếu bạn thực sự muốn sử dụng Image Registry của riêng mình, hãy thêm:
config/variables.env
Sau đó, bạn cần đảm bảo tất cả các image texlive đều nằm trong your-repo, ví dụ
  • hub.your.com/your-repo/texlive-full:2025.1
  • hub.your.com/your-repo/texlive-full:2024.1
Để biết thông tin chi tiết, hãy đọc mã nguồn dưới đây để hiểu cách chúng tôi phân tích biến môi trường của bạn:
sandboxed-compiles/index.mjs

Tự động đồng bộ TeX Live Image

Để tránh phải cập nhật thủ công phiên bản của bạn bằng bin/up mỗi lần, bạn có thể tự động hóa việc cập nhật TeX Live image. Xem updating-tex-live-full-images-automatically.md.

Các vấn đề đã biết

Đây là một trường hợp thực tế từ cộng đồng Overleaf:
Khi dùng 6.0.1-ext-v3.3, tôi có các thiết lập sau trong variables.env:
Cấu hình này hoạt động tốt với texlive/texlive:latest-full. Tuy nhiên, tôi đã pull một texlive image khác là danteev/texlive:2025-10-15 và đổi cả hai biến này sang tên image mới nhưng nó không hoạt động:
Trong log, tôi thấy như sau:
Có vẻ như các thiết lập đã cập nhật trong variables.env không có hiệu lực. Quá trình biên dịch vẫn cố chạy image texlive/texlive:latest-full, chứ không phải image mới. Tôi đã thử khởi động lại, xóa các container và chạy lại, nhưng vẫn gặp vấn đề tương tự. Có giải pháp nào không?
Do một số hạn chế kỹ thuật, nếu bạn chỉ thiết lập một Docker TeXLive image duy nhất, chẳng hạn như texlive-fullA:latest
Và sau khi chạy phiên bản Overleaf của bạn một thời gian, bạn có thể muốn đổi TeXLive image thành texlive-fullB:latest. Khi đó, bạn sẽ thấy người dùng của mình không thể biên dịch bất kỳ dự án nào.
Điều này là do tên của TeXLive-Full image (dùng cho biên dịch trong sandbox) của mỗi dự án được lưu cố định trong cơ sở dữ liệu. Chỉ khi người dùng chuyển phiên bản TeXLive của dự án, ví dụ từ 2024 sang 2025, thì tên image mới được thay đổi trong cơ sở dữ liệu. Khi CLSI biên dịch một dự án, nó sử dụng tên container image tìm thấy trong cơ sở dữ liệu để biên dịch dự án trực tiếp. Nếu bạn chỉ cung cấp một Docker image, người dùng sẽ không thể thay đổi image dùng để biên dịch dự án. Trong trường hợp này, bạn cần viết một script để sửa thủ công TeXLive image cho tất cả các dự án của người dùng trong mongoDB.

Gỡ lỗi và báo cáo

Chạy lệnh sau để kiểm tra log clsi từ toolkit:
Nếu bạn gặp bất kỳ vấn đề nào khi biên dịch với các TeX Live image, vui lòng gửi issue tại đây: https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml Để giúp chúng tôi tái hiện và khắc phục sự cố, bạn có thể được yêu cầu tải dự án của mình lên Overleaf. Sau đó, chúng tôi sẽ pull dự án và chạy thử nghiệm biên dịch bằng GitHub Action.

Hỏi & Đáp

Trả lời: Các container và tệp biên dịch sẽ được xóa sau một khoảng thời gian; các TeX Live image thì không.
  • Container biên dịch (project-<project id>-<hash>) được tái sử dụng qua các lần biên dịch của cùng một dự án, vì vậy chúng vẫn tồn tại sau khi biên dịch. Một tác vụ kiểm tra chạy mỗi giờ và xóa những container cũ hơn một giờ mà dự án của chúng không được biên dịch trong giờ vừa qua. Một container thường biến mất sau một đến hai giờ kể từ lần biên dịch cuối cùng. Khởi động lại Overleaf không xóa chúng; lần kiểm tra hằng giờ tiếp theo mới xóa.
  • Container đếm từ, SyncTeX và chuyển đổi được xóa ngay khi chúng hoàn tất.
  • Tệp biên dịch (data/overleaf/data/compiles và output) được xóa khi một dự án không được sử dụng trong một ngày, được kiểm tra mỗi 10 phút. Khi đĩa sắp hết dung lượng, khoảng thời gian này được rút ngắn dần, xuống tối thiểu nửa ngày.
  • TeX Live image không bao giờ bị xóa, vì mọi lần biên dịch đều cần chúng. Để giải phóng dung lượng sau khi xóa một image khỏi ALL_TEX_LIVE_DOCKER_IMAGES, hãy xóa nó bằng docker image rm <image>.
Không cần xóa các container này bằng tay.
Trả lời: Không. Mỗi container biên dịch chỉ mount thư mục biên dịch của chính dự án đó, tại /compile, và không có mạng, đồng thời không có thiết lập nào để mount các thư mục khác của máy chủ vào đó. Thay vào đó, hãy tải các tệp mà dự án cần lên dự án.
Trả lời: Có. ghcr.io/ayaka-notes/texlive-basic:<year>.1 (từ 2020.1 đến 2026.1) chứa scheme basic của TeX Live cùng một vài gói như latexmk, xetex và fontspec, nhưng không có bộ phông chữ đầy đủ. Image này nhỏ hơn nhiều so với texlive-full, nhưng các dự án sử dụng gói khác sẽ gặp lỗi thiếu gói. Đối với TeX Live 2025 basic:
config/variables.env
ghcr.io/ayaka-notes/texlive-full:base không phải là một image basic: nó không có TeX Live và không thể biên dịch.
Trả lời: Trình soạn thảo không hiển thị thông tin này, và log của clsi chỉ ghi lại nó ở mức debug. Tuy nhiên, mọi yêu cầu biên dịch đều trả về thông tin này: mở công cụ dành cho nhà phát triển của trình duyệt, chuyển đến tab Network, biên dịch lại và chọn yêu cầu compile. Phản hồi JSON của nó có timings tính bằng mili giây, trong đó compileE2E là toàn bộ quá trình biên dịch trong dịch vụ biên dịch và compile là chính lần chạy LaTeX.
Lần sửa đổi cuối 13 tháng 11, 2026