Chuyển website từ WordPress sang KDIGI CMS

KDIGI CMS chuyển nội dung từ bất kỳ site WordPress nào bằng một pipeline 8 phase có thể chạy lại: tải bản chụp qua REST hoặc WPGraphQL, chuẩn hóa thành JSON để bạn duyệt, khóa cổng review rồi mới ghi vào CMS. Bài viết, trang, media, menu, SEO Yoast/RankMath và redirect 301 được mang sang.

Tóm tắt nhanh

• Dữ liệu đi theo đường WordPress → raw/ (bản sao bất biến) → staged/ (JSON sửa được) → cổng review → Payload.
• Không có gì được ghi vào database trước khi bạn khóa dữ liệu bằng --gate lock.
• Database không phải local luôn được pg_dump trước khi ghi, không có cờ bỏ qua.
• Yoast và RankMath đều được đọc và quy về một schema SEO thống nhất; JSON-LD do CMS sinh lại.
• Mọi lệnh idempotent: chạy lại không tạo bản trùng, có --dry-run để xem trước.
• Không di chuyển theme, plugin, form, tài khoản đăng nhập WordPress và dữ liệu page builder lưu ngoài post_content.

Trang này tóm tắt cách pipeline hoạt động, những gì được mang sang, những gì phải làm tay và checklist nghiệm thu. Lệnh chi tiết từng bước nằm trong runbook trên GitHub; trang Thực hành tốt gom các quy tắc SEO nên áp dụng khi cutover.

Những gì được di chuyển

Bảng dưới đây lấy từ tài liệu pipeline của KDIGI CMS (phạm vi di chuyển, bản 1.1.0).

Không di chuyển: theme và giao diện, plugin, cấu hình form, người dùng đăng nhập WordPress, widget/sidebar, custom fields ACF/meta box, redirect nằm trong plugin (RankMath Redirections, Yoast Premium), sitemap và robots.txt (frontend của bạn sinh lại).

Pipeline hoạt động thế nào

Pipeline gồm bốn bước lớn, điều phối bởi src/importers/run-wp-migration.ts:

1. Archive. Tải bản chụp site nguồn. Ưu tiên WPGraphQL nếu site có; nếu không, dựng từ REST API chuẩn của WordPress nên chạy được trên mọi site. Thư mục raw/ là bản sao nguồn, không sửa tay.
2. Normalize. Chuyển raw/ thành staged/: HTML thành Markdown, SEO Yoast/RankMath thành một schema thống nhất, cùng taxonomy, menu, tác giả, media và bình luận. Bước này không ghi database và không gọi mạng.
3. Review gate. Con người rà soát và sửa các file JSON trong staged/. --gate lint phải sạch lỗi, --gate lock ghi hash nội dung vào .gate-lock. Sửa staged/ sau khi khóa sẽ làm khóa mất hiệu lực.
4. Import. Ghi vào Payload, mỗi phase kiểm lại khóa trước khi chạy.

8 phase ghi dữ liệu

Phase schema chuẩn bị database (chạy pnpm payload migrate và kiểm các giá trị enum cần thiết). Tám phase ghi dữ liệu là seed đến redirects:

6 giai đoạn từ đầu đến cutover

1. Baseline nguồn. Lưu sitemap, canonical và status code của toàn bộ URL WordPress hiện tại; đóng băng nội dung từ lúc archive cuối đến cutover.
2. Archive. Tải bản chụp REST hoặc WPGraphQL vào wp-archive/<site>/raw/ (kèm binary media).
3. Normalize. Sinh staged/ gồm JSON mỗi tài liệu, SEO đã thống nhất, taxonomy, menu, tác giả, media, bình luận.
4. Review và khóa. Sửa tay staged/, --gate lint sạch rồi --gate lock.
5. Import. --dry-run trước, sau đó --from schema --to redirects với sao lưu pg_dump bắt buộc khi database không phải local.
6. Nghiệm thu và cutover. Duyệt checklist, so sánh lại URL, chuyển DNS, theo dõi Search Console 2-4 tuần rồi mới tắt WordPress.

Cảnh báo KDIGI CMS không phải bản sao WordPress: theme, plugin, form, ACF/meta box và layout của page builder không được chuyển. Phần nào cần giữ hãy dựng lại ở frontend hoặc bằng collection landings.

Chạy di chuyển từng bước

Dưới đây là luồng rút gọn từ runbook, chạy ở thư mục gốc của repo kdigi-cms-open (Node ≥ 20, pnpm, PostgreSQL đích đã migrate, DATABASE_URI trong .env).

1. Đặt biến và kiểm tra nguồn

SITE=my-site                       # siteKey: a-z, 0-9, dấu -
WP_URL=https://wp.example.com      # backend WordPress (REST/GraphQL)
DOMAIN=example.com                 # domain công khai MỚI trên KDIGI CMS

mig() { node --env-file=.env --import tsx src/importers/run-wp-migration.ts \
  --site "$SITE" --wp-url "$WP_URL" --domain "$DOMAIN" "$@"; }

curl -s -o /dev/null -w '%{http_code}\n' "$WP_URL/wp-json/wp/v2/posts?per_page=1"   # mong đợi 200

Nếu REST trả 401/403 cho mọi thứ, thường là plugin bảo mật hoặc WAF đang chặn; tạo Application Password và đặt WP_AUTH_USER, WP_AUTH_PASSWORD.

2. Archive và normalize

mig        # lần đầu: archive → normalize → dừng ở review gate (exit khác 0 là bình thường)

Đặt WP_UTC_OFFSET=+07:00 (hoặc múi giờ đúng của WordPress) trước khi normalize để publishedAt không lệch giờ; không đặt thì giá trị được coi là UTC. Kết quả nằm trong wp-archive/<site>/raw/ và wp-archive/<site>/staged/. Thư mục wp-archive/ đã nằm trong .gitignore, đừng commit dữ liệu WordPress.

3. Review, lint, lock

mig --gate lint     # lỗi (chặn lock) và cảnh báo (không chặn)
mig --gate lock     # lint sạch thì ghi staged/.gate-lock {approver, timestamp, contentHash}
mig --gate status   # khóa còn hiệu lực không

Tối thiểu hãy rà các mục sau trong staged/:

• contentMd của vài bài mẫu mỗi loại: heading, bảng, ảnh, shortcode còn sót dạng [xyz].
• seo.canonical phải trỏ về domain mới, không phải host WordPress. Lint báo lỗi nếu còn trỏ host cũ.
• Cây taxonomy và menu; term thừa xóa bằng file .delete-<tên>.json.
• Alt của media (xem media-alt-fallback-report.md); ảnh nhạy cảm đưa vào denylist.json.

4. Dry-run rồi import thật

mig --from schema --to redirects --dry-run   # xem trước, không ghi Payload
mig --from schema --to redirects             # import thật

Dry-run vẫn kết nối database để kiểm enum. Với lần ghi thật vào database không phải local, CMS hỏi xác nhận rồi chạy pg_dump -Fc vào backups-local/. Hãy ghi lại tên file dump, đó là điểm rollback. Bạn cần pg_dump (gói postgresql-client) khớp phiên bản server.

Dùng KDIGI CMS từ phiên bản 1.0.1 trở lên. Bản 1.0.1 sửa lỗi phase media thiếu khóa idempotency sourceMediaId khiến ảnh đại diện, slider và ảnh trong thân bài không được nhập. Bản hiện hành là 1.1.0, xem lịch sử phát hành.

5. Kiểm tra sau import

Sau khi site mới đã có dữ liệu, bạn cấu hình theme, footer, thông tin liên hệ và SEO mặc định trong admin ở mục Sites. Xem thêm quản lý nhiều website.

Quyết định theo từng loại site WordPress

Yoast SEO hay RankMath

Cả hai được quy về cùng một cấu trúc: title, description, canonicalOverride, robots, focusKeywords, Open Graph, twitter meta và ngày xuất bản/sửa. JSON-LD không được nhập mà được CMS sinh lại từ dữ liệu tài liệu và knowledge graph của site (SEO và JSON-LD).

Một lưu ý hay bị bỏ sót: nhiều site WordPress đặt canonical tùy biến trong database mà không phát ra ở frontend. Nếu mang nguyên sang, CMS sẽ áp dụng và có thể de-index nhầm trang đích. Trước khi lock, hãy curl trang thật và so với seo.canonicalOverride trong staged/.

Gutenberg, Classic hay page builder

Importer chỉ đọc HTML đã render của post_content rồi chuyển thành GitHub-flavoured Markdown.

Trang Elementor hay Divi bị rỗng thường do nội dung nằm trong meta (_elementor_data) còn post_content gần như trống; --gate lint sẽ cảnh báo contentMd empty.

WooCommerce

Tùy chọn. Sản phẩm trở thành Products của KDIGI CMS (trang sản phẩm/dịch vụ) với một mức giá, tiền tệ trong VND, USD, EUR, GBP, JPY. Biến thể, thuộc tính, tồn kho, giỏ hàng, thanh toán, đơn hàng, coupon và khách hàng không chuyển. Nếu bạn cần bán hàng online, KDIGI CMS không thay thế WooCommerce: hãy giữ WooCommerce làm backend bán hàng và chỉ dùng pipeline để chuyển nội dung và SEO. Với website chỉ giới thiệu catalog, Products là đủ; xem thêm giải pháp website bán hàng.

Thư viện media lớn

• Script archive tải song song (--concurrency=N, mặc định 8), bỏ qua file đã có và ghi file lỗi vào raw/media/failed.json; bị ngắt thì chạy lại để tải tiếp.
• Phase media tạo một media cho mỗi ảnh gốc trong inventory, không phải từng kích thước thumbnail, và nhận lại ảnh đã upload qua sourceMediaId.
• Cấu hình storage (local-disk hoặc Cloudflare R2) trước khi import để file đi thẳng vào nơi cuối cùng, xem thư viện media.
• Đặt PAYLOAD_PUBLIC_SERVER_URL về URL thật trước phase media, nếu không URL localhost sẽ bị ghi vào thân bài (sửa bằng cách chạy lại --from content --to media).

Redirect và cutover

Phase redirects sinh 301 từ permalink WordPress (ví dụ /2024/05/ten-bai/) sang đường dẫn mới cho mọi tài liệu đã published. Quy tắc cần nhớ:

• Không tự sinh redirect cho trang lưu trữ taxonomy (/category/<slug>/, /tag/<slug>/), trang tác giả, phân trang, feed, ?p=123 và attachment. Lấy danh sách URL có traffic/backlink từ Search Console hoặc log, rồi thêm vào staged/redirects/*.json với statusCode 301 hoặc 302.
• Không tạo chuỗi A → B → C; to luôn là đích cuối.
• Nội dung đã xóa nên để draft (trả 404) thay vì redirect về trang chủ, vì soft-404 gây hại SEO.
• Thử vài URL cũ: curl -sI https://example.com/2024/05/old-post/ | grep -iE '^(HTTP|location)'.

Ba kịch bản cutover được tài liệu mô tả:

1. Đổi domain: --wp-url https://old.example.com --domain example.com. Canonical và og:url được viết lại sang domain mới, link nội bộ trong bài trở thành đường dẫn tương đối.
2. Backend WordPress tách khỏi site công khai: thêm --public-url https://example.com để link nội bộ trỏ về đường dẫn tương đối.
3. Thay thế tại chỗ (cùng host): bắt buộc có redirect cho mọi URL thay đổi và kiểm robots/canonical trên bản staging trước khi chuyển DNS.

Quy trình khuyến nghị: baseline site nguồn (sitemap, canonical, status code toàn bộ URL) → import vào database local/staging → duyệt checklist → import production (có backup) → so sánh lại URL → chuyển DNS → theo dõi Search Console 2-4 tuần → tắt WordPress. Giữ WordPress chạy ít nhất 2-4 tuần sau cutover.

Checklist nghiệm thu

1. Số lượng posts, pages, products, taxonomies, media, menus, comments trong CMS khớp staged/ (trừ phần cố ý bỏ).
2. Chạy lại toàn bộ --from schema --to redirects không làm đổi số tài liệu, log created: 0.
3. 10 URL ngẫu nhiên cùng toàn bộ URL trong sitemap WordPress cũ mở được hoặc redirect 301 đúng đích.
4. Thân bài không còn Markdown thô, [shortcode] hay chữ dính nhau; bảng và ảnh hiển thị đủ.
5. Canonical, OG, robots đúng domain mới; không có noindex ngoài ý muốn.
6. Ngày xuất bản và sửa đúng nguồn, không phải ngày import.
7. Menu header, footer, mobile đúng; link nội bộ không 404.
8. Logo, favicon, knowledge graph, social đã đúng; theme, footer, contact đã cấu hình trong admin.
9. Đã lưu file pg_dump và thư mục wp-archive/<site>/ (raw, staged, .gate-lock).

Rollback

Đừng xóa wp-archive/<site>/raw/ hay file dump trước khi cutover ổn định.

Sau khi chuyển xong

Bạn có một site KDIGI CMS để hiển thị nội dung qua REST và GraphQL API trên frontend tự chọn. Nếu muốn tự vận hành máy chủ, xem hướng dẫn tự host và sao lưu, nâng cấp. Muốn thử giao diện biên tập trước khi di chuyển thật, vào bản demo trực tiếp. Nếu còn cân nhắc giữa hai hệ thống, so sánh KDIGI CMS và WordPress nêu rõ khi nào nên giữ WordPress; sau cutover, áp dụng SEO on-page cho nội dung mới.

Nguồn

• Tài liệu di chuyển WordPress của KDIGI CMS (README, runbook, playbook): https://github.com/kdigivn/kdigi-cms-open/tree/main/docs/wordpress-migration
• Bản hosted trên docs: https://docs.opencms.kdigi.vn/wordpress/di-chuyen-tu-wordpress/
• CHANGELOG (1.0.1 sửa phase media): https://github.com/kdigivn/kdigi-cms-open/blob/main/CHANGELOG.md