Biên dịch trong sandbox

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 Server 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

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

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

Bắt đầu từ Overleaf CE/Server Pro 5.0.3, các biến môi trường đã được đổi tên từ SHARELATEX_* thành OVERLEAF_*.

Nếu bạn đang dùng phiên bản 4.x (hoặc cũ hơn), hãy đảm bảo các biến có tiền tố phù hợp (ví dụ: SHARELATEX_MONGO_URL thay vì OVERLEAF_MONGO_URL).

version: '2'
services:
    sharelatex:
        #...
        volumes:
            - /data/overleaf_data:/var/lib/overleaf
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            #...
            DOCKER_RUNNER: "true"
            SANDBOXED_COMPILES: "true"
            SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"
            #...
        #...

​

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ể thay ghcr.io bằng ghcr.nju.edu.cn để tăng tốc độ tải xuống. Nhưng KHÔNG sử dụng trực tiếp ghcr.nju.edu.cn trong các thiết lập biến môi trường của toolkit. Bạn nên giữ ghcr.io là lựa chọn duy nhất.

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 (bắt buộc), TeX Live image mặc định dùng để biên dịch các dự án mới. Image này phải nằm trong ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (bắt buộc), Danh sách tên thân thiện của các image, phân tách bằng dấu phẩy, được dùng cho các tùy chọn ở frontend.
• 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ài đặt tối thiểu

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

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1, ghcr.io/ayaka-notes/texlive-full:2025.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026, Texlive 2025
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

Cài đặt đầy đủ

Cấu hình sau cài đặt tất cả các TeX Live Docker image đầy đủ từ 2020 đến 2026. Chúng tôi khuyến nghị có ít nhất 150 GB dung lượng lưu trữ trống trước khi sử dụng cấu hình này.

config/variables.env

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1,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
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026,Texlive 2025,Texlive 2024,Texlive 2023,Texlive 2022,Texlive 2021,Texlive 2020
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

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

IMAGE_ROOT=hub.your.com/your-repo

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

if (process.env.SANDBOXED_COMPILES === 'true') {
  // Set default image root if not provided
  let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes";
  // Export imageRoot to Settings
  Settings.imageRoot = imageRootPath

  // allowedImageNames should be:
  // [
  //  { imageName: "texlive-2023:latest", imageDesc: "TeX Live 2023" },
  //  { imageName: "texlive-2022:latest", imageDesc: "TeX Live 2022" },
  // ]
  Settings.allowedImageNames = parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGES)
    .map((texImage, index) => ({
      imageName: texImage.split("/")[texImage.split("/").length - 1],
      imageDesc: parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES)[index]
        || texImage.split(':')[1],
    }))
  
  // In the end, imageName will be put together with imageRoot to form the full image path
  // The full name will be like: ghcr.io/ayaka-notes/texlive-2023:latest

  // Set default image name if not provided
  if(!process.env.TEX_LIVE_DOCKER_IMAGE) {
    process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName
  }

  // Export currentImageName to Settings
  // This is the new created projects' image name
  Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE
}

​

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:

TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full

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:

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15
ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15

Trong log, tôi thấy như sau:

{"name":"clsi","level":50,"err":{"message":"(HTTP code 404) no such container - No such image: texlive/texlive:latest-full ","name":"Error","stack":"Error: (HTTP code 404) no such container - No such image: texlive/texlive:latest-full ... 

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

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

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.

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

Đ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:

bin/logs clsi

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.