Fi1osof · Nikolai Lanets
kỹ sư nghiên cứu · nhật ký công khai
bộ đếm thời gian không chạy
🇷🇺Русский🇬🇧English🇻🇳Tiếng Việt

Nhật ký công việc cho nhiệm vụ "Thêm tính năng để chạy các trang web MODX"

4 сент. 2026 г., 21:18:14

Nghiên cứu định hướng MODX runtime và khả năng tái tạo legacy

Đã tiến hành phân tích kho lưu trữ hiện tại https://github.com/MODX-Club/modx-docker, các tác vụ của dự án và thảo luận trong Cộng đồng MODX: https://community.modx.com/t/an-open-letter-to-modx-leadership-and-the-modx-revolution-team/9247.

Động lực chính của dự án

Đã xác nhận rằng giá trị cốt lõi của modx-docker không chỉ là một Docker stack cục bộ dành cho MODX, mà là khả năng tái tạo các cấu hình lịch sử cụ thể của các dự án MODX.

Đối với một dự án MODX legacy thực tế, tính tương thích thường không chỉ được quyết định bởi phiên bản core, mà là sự kết hợp của:

  • Phiên bản MODX Revolution;
  • Phiên bản PHP;
  • Phiên bản MySQL/MariaDB;
  • Các phiên bản cụ thể của Extras;
  • Các component tùy chỉnh và các bản vá (patches);
  • Trạng thái cơ sở dữ liệu;
  • Trạng thái hệ thống tệp của dự án.

Do đó, định hướng của dự án nên được coi là một runtime để nghiên cứu, hỗ trợ và di dời (migrate) các trang web MODX legacy, cũng như tiềm năng kiểm thử chính MODX trên các môi trường lịch sử khác nhau.

Những gì đã có trong modx-docker

Việc triển khai hiện tại thiết lập stack nginx + php-fpm + mysql + phpMyAdmin và thực hiện cài đặt tự động (unattended) MODX từ GitHub.

Điểm mạnh của cách tiếp cận hiện tại là MODX được lấy trực tiếp từ git repository và có thể chọn một ref/branch/phiên bản cụ thể, trong khi mã nguồn có sẵn trong bind mount. Điều này cho phép sử dụng môi trường không chỉ để phát triển trang web, mà còn để tái tạo lỗi (bugs), kiểm tra các commit cụ thể và phát triển chính MODX.

Quá trình cài đặt được chia thành các giai đoạn shell riêng biệt: chuẩn bị thư mục, clone, tạo cơ sở dữ liệu, cài đặt composer, build core transport, thiết lập CLI, vá cấu hình (patch configuration). Đây là nền tảng tốt cho việc cài đặt có thể lập trình trong tương lai.

Kết luận kiến trúc

modx-docker nên được xem xét như một runtime adapter chuyên dụng chứ không phải là một hệ thống quản lý dự án độc lập.

Việc quản lý dự án, thư mục, trạng thái git, môi trường dev/stage/prod và các kịch bản tác nhân (agent scenarios) nên nằm ở cấp độ nền tảng chung. modx-docker nên chịu trách nhiệm về MODX runtime có thể tái tạo.

Về lâu dài, mô hình trông sẽ đại loại như sau:

Agent
  -> Project management
  -> Git / filesystem
  -> Code analysis
  -> Knowledge / worklogs
  -> Runtime
       -> MODX adapter
            -> modx-docker

Tại sao việc hỗ trợ legacy trở thành tính năng trung tâm

Thảo luận trong Cộng đồng MODX đã xác nhận rằng Revolution thực tế đang dịch chuyển theo hướng trở thành nền tảng legacy/maintenance lâu đời: ưu tiên là sự ổn định, bảo mật và tính tương thích, trong khi việc hiện đại hóa đáng kể được kỳ vọng sẽ nằm trong một giải pháp tương lai riêng biệt.

Điều này có nghĩa là cơ sở cài đặt MODX Revolution lớn sẽ tiếp tục tồn tại trong nhiều năm tới dưới dạng vô số sự kết hợp lịch sử giữa core, PHP, cơ sở dữ liệu và Extras.

Do đó, các phiên bản PHP/MySQL cũ trong modx-docker nên được coi không phải là kỹ thuật nợ (technical debt) của chính công cụ này, mà là các tham số được hỗ trợ có ý thức của môi trường phòng thí nghiệm.

Nên dần tham số hóa tối thiểu:

MODX_REF
PHP_VERSION
DB_ENGINE
DB_VERSION
COMPOSER_VERSION

Cũng nên sử dụng khái niệm git ref thay vì chỉ branch, để có thể chạy một tag, branch hoặc một commit MODX cụ thể.

Dự án MODX thực tế không thể khôi phục chỉ từ Git

Giới hạn kiến trúc quan trọng: một phần đáng kể trạng thái của MODX được lưu trữ trong cơ sở dữ liệu:

  • resources;
  • templates;
  • chunks;
  • snippets;
  • TVs;
  • system settings;
  • package state;
  • các thực thể cấu hình khác.

Đồng thời, một phần đáng kể của dự án nằm trong hệ thống tệp:

  • assets;
  • components;
  • mã nguồn tùy chỉnh;
  • tệp Extras;
  • đôi khi là chính core và các chỉnh sửa cục bộ bên trong nó.

Do đó, để tái tạo hoàn chỉnh một dự án thực tế, cần phải có khả năng khôi phục cơ sở dữ liệu và hệ thống tệp một cách độc lập hoặc đồng thời.

Giải pháp: Hỗ trợ snapshot/restore

Dựa trên kết quả thảo luận, một tác vụ riêng biệt đã được đưa ra: /tasks/cmtngfoe204qdpf0qab6spl66 — "Thêm tính năng khôi phục dự án MODX từ các bản dump và tệp".

Trong đó đã xác định bốn kịch bản cơ bản:

  1. cài đặt MODX sạch;
  2. chỉ khôi phục cơ sở dữ liệu;
  3. chỉ khôi phục tệp;
  4. snapshot đầy đủ: tệp + cơ sở dữ liệu.

Đối với chế độ snapshot, điều quan trọng là không sửa đổi các tệp lưu trữ/dump gốc, mà làm việc với bản sao của chúng và sau đó chuẩn hóa dữ liệu dành riêng cho môi trường ngay bên trong môi trường làm việc.

Sau khi khôi phục, có thể cần tự động chuẩn hóa:

  • các tham số kết nối cơ sở dữ liệu;
  • domain/hostname;
  • đường dẫn tuyệt đối (absolute paths);
  • đường dẫn cache/session;
  • URL context/connector;
  • các cài đặt khác gắn liền với máy chủ cũ.

Quy trình làm việc tiềm năng của Agent

Mô hình mục tiêu có thể trông như sau:

Người dùng cung cấp trang web MODX cũ
        -> agent xác định phiên bản MODX và các phần phụ thuộc (dependencies)
        -> chọn PHP/DB runtime
        -> khôi phục tệp và cơ sở dữ liệu
        -> chuẩn hóa môi trường
        -> chạy trang web
        -> phân tích lỗi và sự không tương thích
        -> dần cập nhật runtime/mã nguồn
        -> ghi lại kết quả vào worklogs/knowledge

Điều này biến modx-docker thành một phòng thí nghiệm không chỉ để chạy, mà còn để di dời các dự án legacy.

Ví dụ, một agent có tiềm năng kiểm tra tuần tự tính tương thích với các phiên bản PHP/MySQL, tìm ra điểm lỗi, sửa mã nguồn và tiếp tục tiến tới một runtime hiện đại hơn.

Góc nhìn bổ sung: Kiểm thử MODX Revolution

Cơ sở hạ tầng tương tự có tiềm năng phù hợp để kiểm thử các PR core của MODX trên các môi trường khác nhau và các snapshot dự án thực tế.

Thay vì chỉ kiểm tra một tập hợp hiện đại duy nhất, các thay đổi có thể được chạy qua ma trận các cấu hình lịch sử để phát hiện các sự hồi quy (regressions). Điều này đặc biệt phù hợp đối với Revolution, nơi tính tương thích ngược (backward compatibility) là một trong những giá trị cốt lõi và đồng thời là nguồn gây tốn kém cao cho việc kiểm tra thủ công.

Tổng kết

Mục đích đã được làm rõ của modx-docker:

Một MODX runtime có thể tái tạo cho hệ thống quản lý dự án dựa trên agent, được thiết kế chủ yếu để chạy, nghiên cứu, hỗ trợ và di dời các cấu hình legacy với các phiên bản cụ thể của MODX, PHP, cơ sở dữ liệu, Extras và trạng thái dự án.

Ưu tiên kiến trúc trước mắt là không làm phức tạp modx-docker bằng hệ thống quản lý dự án của riêng nó, mà biến nó thành một nguyên thủy runtime (runtime primitive) có thể tham số hóa tốt với các giai đoạn dự đoán được build -> install/restore -> normalize -> ready/failed và hỗ trợ các snapshot thực tế.

Nhiệm vụ: Thêm tính năng để chạy các trang web MODX

25.06.2026