🌐 Ngôn ngữ: 🇻🇳 Tiếng Việt (hiện tại) · 🇬🇧 English · 🇯🇵 日本語
Lệnh kiểm tra và chẩn đoán
Giới thiệu
Trang này mô tả các lệnh giúp bạn biết site đang ở trạng thái nào: gp247:doctor kiểm máy chủ, cài đặt và cấu hình bảo
mật; gp247:info và gp247:core-info cho biết phiên bản; gp247:cache-rebuild dựng lại cache. Tất cả đều chỉ đọc
(trừ việc dựng cache) nên chạy bất cứ lúc nào, kể cả trên site đang bán hàng. Tài liệu dành cho chủ site và người vận hành
máy chủ. Đọc xong, bạn hiểu từng dòng gp247:doctor báo và biết cách sửa.
Nhìn nhanh
Dùng gp247:doctor ở ba thời điểm:
flowchart LR
A["Trước khi cài<br/>máy chủ đủ chưa?"] --> B["Sau khi cài / cập nhật<br/>còn gì cần dọn?"]
B --> C["Định kỳ<br/>cấu hình còn an toàn?"]
- Ba trạng thái: PASS ổn · WARN nên dọn nhưng không chặn · FAIL phải sửa.
- Có FAIL thì lệnh thoát khác 0 — dùng làm cổng chặn trong CI hoặc trước khi cài. WARN không làm thoát khác 0.
- Site đã cài thì doctor kiểm thêm cấu hình bảo mật — cùng các mục mà trang Cảnh báo hệ thống hiện cho quản trị viên.
- Cần biết phiên bản để báo lỗi hoặc kiểm bản vá →
gp247:info.
gp247:doctor — kiểm tra sức khoẻ site
-
Tại thư mục site, gõ:
php artisan gp247:doctor -
Đọc bảng kết quả: mỗi dòng có tên mục, trạng thái và ghi chú (đường dẫn, số lượng, lệnh gợi ý sửa).
-
Sửa mọi dòng FAIL trước, rồi tới WARN. Chạy lại tới khi không còn FAIL.
Doctor đọc cấu hình và database, không mở site qua mạng (trừ khi thêm --probe-headers — xem
Kiểm header bảo mật thật sự tới trình duyệt). Việc http:// có tự chuyển sang https:// hay .env có bị tải
được từ ngoài không vẫn phải tự kiểm — xem Cấu hình production an toàn trong bộ
tài liệu Bảo mật.
Máy chủ và cài đặt
| Mục | Kiểm gì | Không đạt thì |
|---|---|---|
php_version |
PHP từ 8.3 trở lên | FAIL — nâng PHP |
ext_pdo, ext_mbstring, ext_openssl, ext_tokenizer, ext_ctype, ext_json |
Extension PHP bắt buộc | FAIL — bật extension |
ext_zip, ext_curl, ext_gd, ext_fileinfo |
Extension PHP khuyến nghị | WARN — một số tính năng (cài .zip, ảnh) không chạy |
env_file |
Có file .env |
FAIL |
writable_storage, writable_bootstrap_cache |
Ghi được storage/, bootstrap/cache/ |
FAIL — sửa quyền thư mục |
writable_app_gp247, writable_public_gp247 |
Ghi được app/GP247, public/GP247 |
WARN — không cài / cập nhật extension được |
db_connection |
Kết nối được database | FAIL — kiểm DB_* trong .env |
installed |
Site đã cài chưa | WARN khi chưa cài (bình thường trước lần cài đầu) |
Khoá mã hoá và bí mật
| Mục | Kiểm gì |
|---|---|
encryption_key_dedicated |
Đã đặt khoá riêng GP247_ENCRYPTION_KEY cho bí mật, hay đang dùng chung APP_KEY — xem Mã hoá dữ liệu |
secret_decryptable |
Bí mật đã mã hoá trong cấu hình còn giải mã được (không được: dấu hiệu khoá bị đổi mà không giữ khoá cũ) |
backup_post_incident_pending |
Còn việc chưa làm sau một lần phục hồi "sau sự cố bảo mật" (đổi khoá, cài lại mã, đổi mật khẩu database / hosting) |
Extension và giao diện
| Mục | Kiểm gì | Lệnh sửa |
|---|---|---|
extension_assets |
Extension đã cài thiếu CSS/JS/ảnh trong public/GP247/..., hoặc (từ core 3.14.3) có file cũ hơn bản trong app/ |
gp247:ext-publish |
extension_data_pending |
Extension có file mới hơn phiên bản GP247 ghi nhớ (vừa git pull, chép đè) mà chưa chạy phần cập nhật dữ liệu |
gp247:ext-update --local --all |
template_source |
Số file template đã publish nhưng giống hệt package — sẽ không nhận bản vá | gp247:template-prune |
file_bom |
File .php / .blade.php bắt đầu bằng BOM UTF-8 |
Lưu lại file dạng UTF-8 không BOM |
raw_output_scan |
(WARN, từ core 3.12.0) Template / plugin của site (app/GP247/Templates, app/GP247/Plugins) in biến bằng {!! … !!} ngoài các dạng an toàn, nên chữ người dùng gõ được in nguyên dạng HTML; --json liệt kê từng file:dòng |
Đổi sang {{ }} |
REST API
| Mục | Kiểm gì |
|---|---|
api_config_legacy_names |
.env còn dùng tên biến API cũ đã đổi tên (bỏ qua khi cấu hình đang được cache) |
api_route_gate |
Khi route đang được cache: mọi route REST API đều đi qua lớp bảo vệ chung của API |
api_event_retention |
Bảng sự kiện đồng bộ của API có sự kiện quá hạn giữ (dọn tự động khi có request API; giảm GP247_API_EVENT_DAYS nếu cần) |
Cấu hình bảo mật (khi site đã cài)
Các mục này chỉ PASS hoặc WARN — kể cả khi trang quản trị xếp mức nghiêm trọng — nên không đổi mã thoát.
| Mục | WARN khi |
|---|---|
app_debug |
APP_DEBUG đang bật |
https |
APP_URL không bắt đầu bằng https:// hoặc SESSION_SECURE_COOKIE chưa bật (chỉ WARN khi APP_ENV=production) |
trusted_proxies |
TRUSTED_PROXIES tin mọi nguồn (*, REMOTE_ADDR…) — ai cũng tự đặt được IP của mình, giới hạn đăng nhập và quy tắc IP mất tác dụng |
default_admin_password |
Tài khoản admin đang hoạt động vẫn dùng mật khẩu mặc định |
password_policy |
Độ dài mật khẩu tối thiểu của quản trị viên dưới 12 ký tự |
mfa_enabled |
Plugin xác thực hai lớp MFA chưa cài hoặc chưa bật |
api_exposure |
(Chỉ để biết, PASS) REST API / MCP đang bật |
support_line |
Dòng phiên bản đang dùng còn dưới 6 tháng hỗ trợ bảo mật, hoặc đã hết |
security_headers |
(Từ core 3.16.0) Công tắc khẩn cấp GP247_SECURITY_HEADERS=0 đang tắt mọi header bảo mật, HSTS bật trên site chưa chạy HTTPS, hoặc có header bị tắt |
login_failures |
(Từ core 3.11.0) Có dấu hiệu dò mật khẩu quản trị trong 24 giờ qua, hoặc đăng nhập sai của quản trị viên không được ghi lại |
backup_vault_exposed |
(Từ core 3.11.0) Thư mục chứa bản sao lưu tải được qua web |
Mục của gp247/front (khi site có front)
Package và plugin đăng ký thêm mục vào cùng danh sách Cảnh báo hệ thống; doctor in luôn các mục đó, cũng chỉ PASS hoặc WARN.
| Mục | WARN khi |
|---|---|
seo_audit |
(Từ front 3.11.0) Lần Kiểm tra SEO gần nhất của cửa hàng còn lỗi cần sửa — doctor chỉ đọc kết quả đã lưu, không quét lại |
tracking_consent |
(Từ front 3.12.0) Mã đo lường đang chạy khi banner cookie tắt, hoặc template của cửa hàng không gọi meta-head nên mã đo lường không chạy |
Kiểm header bảo mật thật sự tới trình duyệt
Thêm --probe-headers thì doctor mở trang chủ (APP_URL) đúng một lần và so header bảo mật trình duyệt thật sự nhận
với cài đặt trên màn Header bảo mật:
php artisan gp247:doctor --probe-headers
Dòng security_headers_live báo WARN khi có header thiếu, header bị gửi hai lần (web server và GP247 cùng gửi), hoặc header
đã tắt mà vẫn tới. Không mở được trang (chưa có tên miền, mạng chặn) thì dòng này PASS kèm ghi chú could not check. Chi
tiết: Header bảo mật.
ℹ️ Có từ: gp247/core 3.16.0
Vì sao file_bom đáng kiểm
BOM là 3 byte vô hình mà nhiều trình soạn thảo trên Windows tự thêm vào đầu file khi lưu "UTF-8". PHP in chúng ra
trước mọi thứ khác, gây lỗi "headers already sent", JSON/XML/CSV hỏng ngay ký tự đầu, hay HTML mở đầu bằng một ký tự lạ.
Mở file lên trông hoàn toàn bình thường, nên chỉ máy phát hiện được. Doctor quét app/GP247/** và mã nguồn các package
gp247/*.
Cách sửa: mở file bằng trình soạn thảo và lưu lại dạng UTF-8 without BOM (VS Code: bấm UTF-8 with BOM ở thanh dưới
bên phải → Save with Encoding → UTF-8). Chạy lại gp247:doctor để thấy mục trở về PASS.
gp247:info và gp247:core-info — xem phiên bản
| Lệnh | In ra |
|---|---|
gp247:info |
Phiên bản từng package đã cài (core, front, shop, mcp), site đã cài chưa, số plugin / template, địa chỉ thư viện extension |
gp247:core-info |
Tên, phiên bản core và phiên bản con, trang chủ, kho mã nguồn |
php artisan gp247:info
💡 Mẹo: muốn biết site đã có bản vá bảo mật chưa, so phiên bản package
gp247:infoin ra với bảng ở Ghi chú phát hành. Số phiên bản S-Cart ở chân trang quản trị không đáng tin sau lầncomposer updateđầu tiên — luôn dựa vào phiên bản package.
gp247:cache-rebuild — dựng lại cache
Xoá rồi dựng lại cache route và cấu hình. GP247 tự gọi lệnh này sau khi cài, bật, cập nhật extension và ở cuối
gp247:update. Chạy tay khi bạn vừa sửa .env hay route mà site chưa nhận.
php artisan gp247:cache-rebuild
Hỏi & Đáp (Q&A)
Câu 1: Doctor có WARN thì site có chạy được không?
→ Có. WARN là việc nên dọn (bảo mật, file thừa), không chặn site. Chỉ FAIL mới là thứ phải sửa ngay.
Câu 2: Tôi chạy doctor trước khi cài thì có ý nghĩa không?
→ Có — đó là một công dụng chính. Doctor có ngay sau composer require, kể cả khi chưa cài; các mục cần database đã cài sẽ
được bỏ qua.
Câu 3: Doctor báo secret_decryptable không đạt?
→ Khoá mã hoá đã đổi mà khoá cũ không còn. Đưa khoá cũ vào GP247_ENCRYPTION_PREVIOUS_KEYS rồi chạy
gp247:encryption-key-rotate — xem Mã hoá dữ liệu.
Câu 4: Doctor báo https WARN trên máy dev?
→ Chỉ WARN khi APP_ENV=production; môi trường khác hiện PASS kèm ghi chú. Nếu thấy WARN, kiểm lại APP_ENV của bạn.
Câu 5: Dùng doctor trong CI thế nào?
→ php artisan gp247:doctor --json: lệnh thoát khác 0 khi có FAIL, nên bước CI tự dừng. Xem Script, CI & Docker.
Câu 6: Doctor kiểm bảo mật có thay được việc rà soát bảo mật không?
→ Không. Doctor chỉ đọc cấu hình. Rà đủ theo Danh sách kiểm tra bảo mật.
Lịch sử thay đổi
| Ngày | Phiên bản GP247 | Thay đổi |
|---|---|---|
| 2026-11-22 | gp247/core 3.11.0–3.16.0, gp247/front 3.11.0–3.12.0 | Liệt kê thêm các mục doctor in từ Cảnh báo hệ thống: security_headers, login_failures, backup_vault_exposed, raw_output_scan, seo_audit, tracking_consent; thêm --probe-headers (dòng security_headers_live) |
| 2026-11-17 | gp247/core 3.14.3 | extension_assets báo cả file tĩnh cũ (khác nội dung bản trong app/), không chỉ file thiếu |
📅 Cập nhật lần cuối: 2026-11-22 · ✍️ Tác giả (Author): GP247