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.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.
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 containersharelatex, để 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
texlivemới cho lần biên dịch. - Để container
texliveđọc dữ liệu dự án từ vị trí trongOVERLEAF_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 trongoverleaf-toolkit/config/overleaf.rc:
config/overleaf.rc
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 KHÔNG sử dụng
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: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.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 trongALL_TEX_LIVE_DOCKER_IMAGES. Nếu không được đặt, các dự án mới sẽ dùng image đầu tiên trongALL_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 đặtSIBLING_CONTAINERS_PULL=falsetrongconfig/overleaf.rc.
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ài đặt tối thiểu
- Cài đặt đầy đủ
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àoTEX_LIVE_DOCKER_IMAGE và ALL_TEX_LIVE_DOCKER_IMAGES:
ghcr.io/ayaka-notes/texlive-full:2026.1(cũng là taglatest)ghcr.io/ayaka-notes/texlive-full:2025.1ghcr.io/ayaka-notes/texlive-full:2024.1ghcr.io/ayaka-notes/texlive-full:2023.1ghcr.io/ayaka-notes/texlive-full:2022.1ghcr.io/ayaka-notes/texlive-full:2021.1ghcr.io/ayaka-notes/texlive-full:2020.1
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
your-repo, ví dụ
hub.your.com/your-repo/texlive-full:2025.1hub.your.com/your-repo/texlive-full:2024.1
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ằngbin/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ùng6.0.1-ext-v3.3, tôi có các thiết lập sau trongvariables.env:Cấu hình này hoạt động tốt vớitexlive/texlive:latest-full. Tuy nhiên, tôi đã pull một texlive image khác làdanteev/texlive:2025-10-15và đổ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 trongDo 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ưvariables.envkhông có hiệu lực. Quá trình biên dịch vẫn cố chạy imagetexlive/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?
texlive-fullA:latest
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.
Gỡ lỗi và báo cáo
Chạy lệnh sau để kiểm tra log clsi từ toolkit:Hỏi & Đáp
Các container sandbox, tệp biên dịch và TeX Live image có được tự động xóa không?
Các container sandbox, tệp biên dịch và TeX Live image có được tự động xóa không?
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/compilesvà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ằngdocker image rm <image>.
Một dự án có thể đọc tệp từ thư mục trên máy chủ (host) hoặc NAS không?
Một dự án có thể đọc tệp từ thư mục trên máy chủ (host) hoặc NAS không?
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.Có TeX Live image bản basic không, và cấu hình nó như thế nào?
Có TeX Live image bản basic không, và cấu hình nó như thế nào?
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.Tôi có thể xem một lần biên dịch mất bao lâu ở đâu?
Tôi có thể xem một lần biên dịch mất bao lâu ở đâu?
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.
