WordPress WP-CLI Runbook: Quản Trị, Backup Và Xử Lý Sự Cố Production Nhanh Hơn

WordPress WP-CLI runbook là tài liệu nên có trong mọi hệ thống WordPress nghiêm túc. Khi website production gặp lỗi trắng trang, plugin xung đột, cron không chạy, database phình to hoặc cần đổi domain sau migration, thao tác qua giao diện admin thường chậm, dễ timeout và đôi khi không vào được. WP-CLI giúp quản trị WordPress bằng dòng lệnh: nhanh, lặp lại được, ghi log được và phù hợp với quy trình vận hành của sysadmin/DevOps.

Bài viết này đi theo hướng thực chiến: dựng môi trường lab/production, cài WP-CLI, backup trước khi đụng hệ thống, update an toàn, kiểm tra plugin/theme, thao tác database, search-replace, xử lý cron, user, transient, lỗi thường gặp, troubleshooting và checklist nghiệm thu. Các lệnh có giải thích để bạn đưa thẳng vào runbook nội bộ.

1. WP-CLI giải quyết vấn đề gì trong production?

Trong production, thời gian khôi phục quan trọng hơn việc “click đúng chỗ” trong wp-admin. WP-CLI cho phép bạn kiểm tra phiên bản, tắt plugin lỗi, export database, flush cache, tạo user khẩn cấp, chạy cron thủ công hoặc search-replace URL mà không cần mở trình duyệt. Quan trọng hơn, mọi lệnh đều có thể ghi vào ticket, audit log hoặc pipeline deploy.

Tắt plugin gây lỗi ngay cả khi wp-admin không truy cập được.
Backup database trước khi update core/plugin/theme.
Kiểm tra trạng thái cron, option, rewrite rule và site URL.
Chạy search-replace an toàn sau khi đổi domain hoặc migration.
Tự động hóa health check sau deploy mà không cần hook tùy biến trong WordPress.

2. Bối cảnh lab/production mẫu

Giả sử website chạy trên Linux với Nginx/Apache, PHP-FPM và MariaDB/MySQL. Document root là /var/www/site/public, user hệ thống chạy web là www-data, và bạn có SSH vào server. Nếu dùng hosting shared không có SSH, WP-CLI có thể không khả dụng; lúc đó cần staging hoặc control panel hỗ trợ terminal.

cd /var/www/site/public
sudo -u www-data php -v
sudo -u www-data wp --info

# Output mẫu
PHP binary: /usr/bin/php8.2
WP-CLI version: 2.10.0

Luôn chạy WP-CLI bằng đúng user sở hữu file WordPress, thường là www-data, nginx hoặc user deploy riêng. Chạy bằng root có thể tạo file cache/log sai quyền và gây lỗi ghi file sau này.

3. Cài đặt WP-CLI an toàn

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
php wp-cli.phar --info
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
wp --info

Sau khi cài, kiểm tra wp --info để biết PHP binary, path và version. Nếu server có nhiều phiên bản PHP, cần chắc chắn WP-CLI dùng đúng PHP với extension cần thiết như mysqli, mbstring, curl, zip, imagick/gd.

4. Nguyên tắc vàng: backup trước khi thay đổi

Mọi thao tác update, search-replace, xóa transient lớn hoặc sửa option đều phải bắt đầu bằng backup. Ít nhất cần backup database; tốt hơn là backup cả thư mục wp-content.

mkdir -p ~/wp-backups/$(date +%F)
cd /var/www/site/public
sudo -u www-data wp db export ~/wp-backups/$(date +%F)/db-before-change.sql
sudo tar -czf ~/wp-backups/$(date +%F)/wp-content-before-change.tar.gz wp-content
ls -lh ~/wp-backups/$(date +%F)/

Output kỳ vọng là file SQL và file tar.gz có kích thước hợp lý. Nếu file SQL chỉ vài KB trong khi site lớn, phải kiểm tra lại quyền database hoặc cấu hình wp-config.php.

5. Health check nhanh bằng WP-CLI

sudo -u www-data wp core version
sudo -u www-data wp plugin list --fields=name,status,update,version --format=table
sudo -u www-data wp theme list --fields=name,status,update,version --format=table
sudo -u www-data wp option get siteurl
sudo -u www-data wp option get home

Các lệnh này giúp trả lời nhanh: WordPress đang chạy version nào, plugin/theme nào active, có update hay không, siteurl/home có lệch domain không. Đây là nhóm lệnh nên chạy trước và sau deploy.

6. Update core/plugin/theme có kiểm soát

Không nên update production kiểu “bấm tất cả”. Quy trình an toàn là backup, kiểm tra update, update từng nhóm, flush cache/rewrite, sau đó verify public URL. Nếu có staging, hãy chạy ở staging trước.

sudo -u www-data wp core check-update
sudo -u www-data wp plugin list --update=available
sudo -u www-data wp theme list --update=available

# Update một plugin cụ thể
sudo -u www-data wp plugin update wordpress-seo

# Update core minor/patch nếu phù hợp chính sách
sudo -u www-data wp core update
sudo -u www-data wp core update-db

Sau update database, chạy thêm wp rewrite flush --hard nếu có thay đổi permalink hoặc plugin routing. Với website có cache, flush cache ở plugin hoặc layer ngoài như Redis/Nginx/CDN.

7. Tắt plugin gây lỗi khi wp-admin không vào được

Một trong những tình huống WP-CLI cứu production tốt nhất là lỗi trắng trang sau khi cập nhật plugin. Nếu log PHP chỉ ra plugin nghi ngờ, tắt plugin đó bằng CLI.

sudo -u www-data wp plugin list --status=active
sudo -u www-data wp plugin deactivate ten-plugin-loi
sudo -u www-data wp cache flush

# Nếu cần cô lập nhanh toàn bộ plugin
sudo -u www-data wp plugin deactivate --all

Nếu tắt toàn bộ plugin làm site hoạt động lại, bật từng plugin theo nhóm để tìm nguyên nhân. Trong production, nên ưu tiên khôi phục dịch vụ trước, sau đó phân tích root cause ở staging.

8. Search-replace khi đổi domain hoặc migration

Search-replace là lệnh mạnh nhưng nguy hiểm nếu chạy sai. Luôn dùng --dry-run trước để xem số dòng sẽ thay đổi. WP-CLI xử lý dữ liệu serialized tốt hơn thao tác SQL replace thủ công.

sudo -u www-data wp search-replace "https://old.example.com" "https://new.example.com" --all-tables --dry-run
sudo -u www-data wp search-replace "https://old.example.com" "https://new.example.com" --all-tables
sudo -u www-data wp rewrite flush --hard

Nếu website multisite, cần cân nhắc thêm --network và kiểm tra từng site. Không chạy search-replace mù trên production khi chưa có backup database cùng ngày.

9. Làm việc với database, option và transient

9.1. Kiểm tra kích thước table

sudo -u www-data wp db query "SELECT table_name, ROUND((data_length+index_length)/1024/1024,2) AS mb FROM information_schema.tables WHERE table_schema=DATABASE() ORDER BY mb DESC LIMIT 10;"

Lệnh này giúp phát hiện table log, session, action scheduler hoặc plugin analytics phình bất thường. Khi table quá lớn, cần backup rồi mới dọn theo tài liệu plugin.

9.2. Xóa transient hết hạn

sudo -u www-data wp transient delete --expired
sudo -u www-data wp cache flush

Transient hết hạn có thể làm bảng options phình to. Tuy nhiên, nếu site dùng object cache, cần hiểu cache backend trước khi dọn hàng loạt.

10. Kiểm tra và xử lý WP-Cron

WP-Cron phụ thuộc traffic nếu chưa cấu hình cron hệ thống. Website ít traffic có thể bị chậm scheduled post, backup, email hoặc tác vụ plugin. WP-CLI cho phép liệt kê và chạy event thủ công.

sudo -u www-data wp cron event list
sudo -u www-data wp cron event run --due-now

# Cron hệ thống mẫu, chạy mỗi 5 phút
*/5 * * * * www-data cd /var/www/site/public && wp cron event run --due-now --quiet

Nếu dùng cron hệ thống, thường đặt DISABLE_WP_CRON trong wp-config.php để tránh cron chạy theo request người dùng. Sau đó theo dõi log để chắc chắn cron không bị lỗi quyền hoặc thiếu PHP extension.

11. Quản trị user và tình huống khẩn cấp

Khi cần tạo tài khoản admin tạm thời cho incident response, WP-CLI có thể làm nhanh. Nhưng đây là thao tác nhạy cảm: phải ghi ticket, đặt mật khẩu mạnh, bật 2FA nếu có và xóa/giảm quyền sau khi xử lý.

sudo -u www-data wp user list --role=administrator
sudo -u www-data wp user create incident-admin incident-admin@example.com --role=administrator --user_pass="CHANGE_ME_STRONG_PASSWORD"
sudo -u www-data wp user update incident-admin --display_name="Incident Admin"

Không lưu mật khẩu thật trong runbook. Dùng password manager hoặc cơ chế secret nội bộ. Sau incident, kiểm tra lại danh sách admin để tránh tài khoản tạm tồn tại lâu dài.

12. Troubleshooting lỗi thường gặp

12.1. Error establishing a database connection

sudo -u www-data wp config get DB_NAME
sudo -u www-data wp config get DB_USER
sudo -u www-data wp db check
mysqladmin ping

Kiểm tra service MySQL/MariaDB, thông tin DB trong wp-config.php, quyền user database và dung lượng disk. Nếu disk đầy, database có thể từ chối ghi và làm site lỗi dây chuyền.

12.2. WP-CLI báo “This does not seem to be a WordPress installation”

pwd
ls -la wp-config.php wp-load.php
sudo -u www-data wp --path=/var/www/site/public core version

Bạn đang đứng sai thư mục hoặc WordPress nằm trong subdirectory. Dùng --path để chỉ rõ document root.

12.3. Permission denied sau khi chạy lệnh

find wp-content -maxdepth 2 -type f -user root | head
sudo chown -R www-data:www-data wp-content/cache wp-content/uploads

Nguyên nhân thường do chạy WP-CLI bằng root hoặc user sai. Sửa quyền cẩn thận, tránh chown toàn bộ hệ thống nếu không hiểu layout deploy.

13. Checklist nghiệm thu production

WP-CLI cài đặt đúng PHP version và chạy được bằng user web/deploy.
Có thư mục backup riêng, kiểm tra được file SQL sau mỗi lần export.
Runbook update có bước backup, update, flush cache, verify public URL và rollback.
Có lệnh tắt plugin/theme gây lỗi khi wp-admin không vào được.
Search-replace luôn chạy dry-run trước và có backup database.
WP-Cron được kiểm tra định kỳ, tác vụ due-now không tồn đọng bất thường.
Danh sách admin được audit, không còn user tạm sau incident.
Các lệnh quan trọng được ghi vào ticket hoặc log vận hành.

14. Bài lab cuối bài

Dựng một site WordPress lab bằng Docker hoặc VPS nhỏ.
Cài WP-CLI và chạy wp --info, wp core version.
Tạo backup database bằng wp db export rồi import lại vào database lab khác.
Cài một plugin thử nghiệm, deactivate/activate bằng WP-CLI.
Tạo search-replace dry-run từ domain cũ sang domain mới.
Liệt kê cron event và chạy --due-now.
Viết lại các lệnh thành runbook 1 trang cho team trực sự cố.

Kết luận

WordPress WP-CLI runbook không làm website tự động an toàn, nhưng nó biến các thao tác vận hành quan trọng thành quy trình rõ ràng, nhanh và có thể kiểm chứng. Với production, hãy coi WP-CLI như bộ dụng cụ khẩn cấp: backup trước, thay đổi có kiểm soát, ghi log, verify ngoài site và luôn có đường rollback. Khi wp-admin chậm hoặc không vào được, một runbook WP-CLI tốt có thể rút thời gian xử lý sự cố từ hàng giờ xuống còn vài phút.