CPPAI × EzyPlatform

Loạt bài · Bài 1

Hướng dẫn sử dụng bộ công cụ của CPPAI cho EzyPlatform

Đi từ máy tính trống đến lần publish đầu tiên: cài lệnh ezy, cài Claude Code và plugin ezyplatform, dựng EzyPlatform chạy local bằng Docker, lấy access token, rồi kéo nội dung, chỉnh sửa và publish có sao lưu.

Trong bài mở đầu, chúng ta đã biết bộ giải pháp của CPPAI gồm ba phần: plugin ezyplatform cho các coding agent, lệnh ezy và image Docker. Bài này hướng dẫn cài đặt và dùng chúng theo đúng thứ tự. Các ảnh chụp màn hình được lấy trên macOS; Linux làm giống hệt, Windows chỉ khác lệnh cài đặt.

Chuẩn bị

• Một máy macOS, Linux hoặc Windows có kết nối Internet.
• Một tài khoản Claude (hoặc một coding agent khác được hỗ trợ: Codex, GitHub Copilot CLI, Cursor, oh-my-pi).
• Nếu muốn chạy EzyPlatform ngay trên máy: Docker. Không có cũng không sao, ezy new sẽ đề nghị cài giúp.
• Nếu muốn làm việc với site thật: một tài khoản admin của site đó.

Bạn không cần cài Python trước: trình cài đặt của ezy tự lo phần này.

Bước 1: Cài lệnh ezy

Chỉ cần một dòng lệnh. Trình cài đặt sẽ cài uv và cả Python 3.9+ nếu máy chưa có.

macOS / Linux

curl -LsSf https://raw.githubusercontent.com/cppai-vn/ezyplatform-cli/main/install.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/cppai-vn/ezyplatform-cli/main/install.ps1 | iex"

Cài xong, mở một terminal mới rồi kiểm tra:

ezy --version

Sau này, cập nhật bằng ezy update và gỡ bằng ezy uninstall. Các thư mục dự án site của bạn luôn được giữ lại.

Bước 2: Cài coding agent và plugin ezyplatform

Lệnh ezy init chỉ cần chạy một lần cho mỗi máy. Nó tìm các coding agent đang có trên máy, cài plugin ezyplatform@cppai vào từng agent, rồi chạy ezy doctor để kiểm tra.

ezy init

Nếu máy chưa có coding agent nào, bạn sẽ thấy kết quả như sau:

Cài Claude Code bản dòng lệnh:

curl -fsSL https://claude.ai/install.sh | bash

Mở terminal mới, gõ claude một lần để đăng nhập, rồi chạy lại ezy init. Lần này plugin được cài vào Claude Code:

Cách khác, không cần qua ezy init: gõ trực tiếp trong khung chat của Claude Code

/plugin marketplace add cppai-vn/agents-plugins
/plugin install ezyplatform@cppai

Dù cài theo cách nào, hãy mở một phiên Claude mới để các skill được nạp.

Bước 3: Tạo dự án site

Mỗi site là một thư mục dự án trên máy. Lệnh ezy new tạo thư mục đó và hỏi site chạy ở đâu:

Với người mới, nên bắt đầu bằng local để không ảnh hưởng đến site thật:

ezy new my-site --mode local
cd my-site

Với chế độ local, ezy new làm tiếp các việc sau:

1. Kiểm tra Docker. Nếu thiếu, nó đề nghị cài: OrbStack trên macOS, Docker Engine trên Linux, Docker Desktop trên Windows.
2. Tạo docker-compose.yml và file .env (đã được git bỏ qua) với tên dự án Docker riêng, cổng còn trống và mật khẩu database ngẫu nhiên, rồi khởi động.
3. Chờ trang admin và website sẵn sàng, rồi thêm môi trường local vào environment.json.

Lần chạy đầu tiên tải khoảng 1 GB và mất vài phút. Trên máy Mac chip Apple, image chạy qua giả lập nên sẽ chậm hơn một chút.

Nếu bạn đã có site thật, thay bằng:

ezy new my-site --mode live --admin-url https://admin.example.com

Bước 4: Tạo admin và lấy access token

Các lệnh ezy và AI agent làm việc với site thông qua access token của tài khoản admin.

1. Với bản local, mở http://127.0.0.1:9090/setup-admin và tạo tài khoản super admin đầu tiên. Với site thật, đăng nhập bằng tài khoản admin sẵn có.

   

2. Mở trang /admins/me trên trang admin, bấm hiện Access Token (nhập lại mật khẩu để xác nhận), rồi bấm Sao chép.

   

3. Tự dán token vào environment.json, đúng mục môi trường bạn dùng (local hoặc mục có "default": true), ở trường admin_access_token.

Riêng bản local: cài plugin EzyArticle

Bản EzyPlatform mà ezy new --mode local dựng lên chỉ có phần lõi, chưa có EzyArticle, trong khi các lệnh ezy làm việc với trang, bài viết và fragment qua API của EzyArticle. Vì vậy cần cài EzyArticle trước khi sang bước 5:

1. Đăng nhập trang admin http://127.0.0.1:9090 bằng tài khoản super admin vừa tạo.
2. Vào Modules → Add (/modules/add), tìm ezyarticle và cài cả Admin Plugin lẫn Web Plugin.
3. Nếu trang admin yêu cầu khởi động lại, chạy docker compose restart ezyplatform trong thư mục dự án.

Với site thật đang chạy EzyArticle, bạn bỏ qua phần này.

Bước 5: Kiểm tra kết nối và bắt đầu làm việc

ezy check

ezy check xác nhận token hợp lệ, cho biết bạn đang đăng nhập với vai trò gì và địa chỉ website là gì. Từ đây có hai cách làm việc, dùng xen kẽ được.

Cách 1: Trò chuyện với AI agent

Mở Claude Code trong thư mục dự án và nói bằng ngôn ngữ tự nhiên, ví dụ:

• "Kiểm tra cấu hình EzyPlatform giúp tôi"
• "Kéo toàn bộ nội dung site về, cả tiếng Việt và tiếng Anh"
• "Thiết kế lại trang chủ theo phong cách tối giản, giữ hai ngôn ngữ đồng bộ"
• "Publish trang chủ"

Skill ezy-guide sẽ chọn đúng skill cho từng việc. Agent luôn xem trước thay đổi và hỏi bạn trước khi ghi lên site.

Cách 2: Tự gõ lệnh

ezy pull-all --langs vi,en          # chạy thử: xem sẽ kéo những gì
ezy pull-all --langs vi,en --write  # kéo nội dung về máy
ezy status                          # so sánh bản trên máy với server
ezy publish plan page:home          # xem trước những gì sẽ thay đổi
ezy publish apply page:home --yes   # sao lưu → publish → kiểm tra

Đích của lệnh có dạng page:<slug> hoặc fragment:<page_name>/<fragment_name>. Sau khi publish, lệnh in sẵn câu lệnh khôi phục để bạn quay lại bản cũ nếu cần. Xem toàn bộ lệnh bằng ezy --help.

Quy trình chuẩn cho mỗi thay đổi:

sync status → sửa → media / i18n → verify preview
→ người duyệt → publish apply (sao lưu trước) → verify live

Những quy tắc an toàn cần nhớ

Xử lý sự cố thường gặp

Quản lý bản local trong thư mục dự án:

docker compose stop                  # tạm dừng
docker compose up -d                 # chạy lại
docker compose logs -f ezyplatform   # xem log
docker compose down -v               # xóa hẳn, kể cả dữ liệu

Tiếp theo

Bạn đã có một dự án site kết nối được với EzyPlatform và một AI agent biết cách làm việc với nó. Các bài tiếp theo trong loạt bài sẽ đi sâu vào từng việc cụ thể. Xem danh sách đầy đủ tại mục lục loạt bài.