Vận hành Access Hub
Trang này dành cho người vận hành hub sau khi đã cài đặt. Nội dung gồm các tiến trình nền cần giữ chạy, cách quản lý lịch chạy lệnh, log, sao lưu, nâng cấp và cách khoanh vùng khi có sự cố.
Các tiến trình cần chạy
| Thành phần | Dịch vụ | Ghi chú |
|---|---|---|
| Web | nginx và PHP-FPM | Phục vụ giao diện và API |
| Queue worker | access-hub-queue@<lane> | Một tiến trình cho mỗi lane |
| Reverb | access-hub-reverb | WebSocket cho thông báo thời gian thực, nghe 127.0.0.1:8080 |
| Scheduler | cron gọi schedule:run mỗi phút | Chạy các lệnh theo lịch |
Kiểm tra nhanh trạng thái:
systemctl status 'access-hub-queue@*' access-hub-reverbHàng đợi
Hub chia công việc nền thành các lane, mỗi lane có một worker riêng để việc nặng không chặn việc nhẹ:
| Lane | Công việc điển hình |
|---|---|
default | Việc chung |
emails | Gửi email |
exports | Tạo tệp xuất (Excel...) |
iac | Lập kế hoạch và áp dụng yêu cầu IaC |
notifications | Thông báo trong ứng dụng |
webhooks | Gửi webhook |
Mỗi worker chạy queue:work với --tries=3 và --max-time=3600, nên tự khởi động lại mỗi giờ và thử tối đa 3 lần cho mỗi job. Trang Hàng đợi trong giao diện cho xem trạng thái các lane, dừng hoặc tiếp tục một lane, thử lại hoặc xóa job thất bại.
Cảnh báo: Restart worker sau khi đổi mã
Worker giữ mã trong bộ nhớ. Sau khi sửa job, notification hoặc exporter, chạy php artisan queue:restart. Bỏ qua bước này có thể làm một job chạy bằng mã cũ và thất bại.
php artisan queue:restart
php artisan queue:failed
php artisan queue:retry allLệnh chạy theo lịch
Lịch chạy lệnh nằm trong bảng scheduled_commands, không nằm trong mã. Nhờ đó quản trị viên đổi lịch trong giao diện mà không cần triển khai lại.
- Chỉ các lệnh có trong danh sách cho phép
config/commands.phpmới được lên lịch hoặc chạy tay. Không ai gõ được một chuỗi lệnh tùy ý. - Khi khởi động,
routes/console.phpđọc các dòng đang bật trongscheduled_commandsvà đăng ký vào scheduler của Laravel với biểu thức cron của từng dòng. - OS cron vẫn phải gọi
php artisan schedule:runmỗi phút, xem Cài đặt. - Quản lý ở trang Lệnh chạy nền (quyền
commands.view,commands.manage,commands.run).
| Lệnh | Mục đích |
|---|---|
trash:purge | Xóa vĩnh viễn bản ghi đã nằm trong thùng rác quá thời hạn lưu |
approvals:remind | Gửi thông báo SLA (trước hạn, quá hạn, lặp, leo thang) cho bước phê duyệt đang chờ |
users:lock-missing-two-factor | Khóa tài khoản chưa bật 2FA sau thời gian ân hạn |
iac:detect-drift | Đánh dấu tài nguyên do IaC quản lý bị sửa tay ngoài luồng IaC |
notifications:expiring-resources | Báo công ty về tài nguyên vừa bước vào cửa sổ 30 ngày trước khi hết hạn |
notifications:two-factor-lockout-warning | Cảnh báo người dùng sắp bị khóa vì chưa bật 2FA |
audit-log:purge | Xóa vĩnh viễn nhật ký kiểm toán quá thời hạn lưu |
api-request-logs:purge | Xóa log request API quá thời hạn lưu, tôn trọng cờ giữ vĩnh viễn của từng token |
job-runs:purge | Xóa lịch sử job quá thời hạn lưu |
monitoring-alerts:purge | Xóa lịch sử cảnh báo giám sát quá thời hạn lưu của từng công ty |
exports:purge | Xóa tệp xuất đã tạo quá thời hạn lưu |
monitoring:sync-registry | Đẩy toàn bộ agent sang collector để registry khớp với hub |
monitoring:sync-server-facts | Điền ô trống của máy chủ từ số liệu agent báo, mặc định chạy mỗi giờ (phút 15) |
Chạy tay một lệnh để thử:
php artisan monitoring:sync-server-facts --dry-run
php artisan schedule:listReverb
Reverb là WebSocket server phục vụ thông báo thời gian thực. Nó nghe trên 127.0.0.1:8080 và nginx chuyển tiếp /app và /apps tới đó. Khi chỉnh REVERB_* hoặc VITE_REVERB_* trong .env, khởi động lại dịch vụ và build lại giao diện vì các biến VITE_* được nhúng lúc build.
sudo systemctl restart access-hub-reverb
npm run buildNếu thông báo không tự hiện mà phải tải lại trang, kiểm tra theo thứ tự: BROADCAST_CONNECTION=reverb, dịch vụ Reverb đang chạy, nginx có khối chuyển tiếp WebSocket, và queue worker lane notifications đang chạy.
Log
| Nguồn | Vị trí hoặc lệnh |
|---|---|
| Log ứng dụng | storage/logs/laravel.log |
| Queue worker | journalctl -u 'access-hub-queue@*' |
| Reverb | journalctl -u access-hub-reverb |
| nginx | /var/log/nginx/error.log và log truy cập của site |
| Job thất bại | php artisan queue:failed |
Ngoài log hệ thống, hub có nhật ký kiểm toán (ai đổi gì), log request API theo token và lịch sử chạy lệnh. Các bảng này được dọn tự động bởi các lệnh *:purge ở trên.
Sao lưu
Dữ liệu của hub nằm trong MySQL, và tệp tải lên (đính kèm, tệp xuất) nằm trong storage/. Hub không kèm công cụ sao lưu riêng, hãy dùng quy trình của tổ chức bạn. Tối thiểu nên có:
mysqldump --single-transaction --routines <database> > access-hub-$(date +%F).sql
tar czf access-hub-storage-$(date +%F).tgz storage/appCảnh báo: Sao lưu trước khi migrate
Luôn sao lưu CSDL trước khi chạy php artisan migrate --force trên môi trường thật. Giữ .env ở nơi an toàn riêng, vì mất APP_KEY làm dữ liệu mã hóa không đọc lại được.
Nâng cấp
cd /var/www/access-hub
composer install --no-dev --optimize-autoloader
php artisan migrate --force
npm ci && npm run build
php artisan optimize:clear
php artisan queue:restartSau khi nâng cấp, mở lại trang Lệnh chạy nền để chắc các lệnh mới (nếu có) đã được thêm vào scheduled_commands và đang bật.
Danh sách kiểm tra khi có sự cố
| Triệu chứng | Kiểm tra |
|---|---|
| Trang trắng hoặc lỗi 500 | storage/logs/laravel.log, quyền ghi của storage và bootstrap/cache cho user của PHP-FPM |
| Lỗi "Unable to locate file in Vite manifest" | Chưa build giao diện, chạy npm run build |
| Email, xuất Excel, áp dụng IaC mãi không xong | Worker của lane tương ứng có đang chạy không, php artisan queue:failed |
| Job chạy bằng hành vi cũ sau khi triển khai | Quên php artisan queue:restart |
| Lệnh theo lịch không chạy | Có dòng cron schedule:run chưa, dòng trong scheduled_commands có bật không, php artisan schedule:list |
| Thông báo thời gian thực không đến | Mục Reverb ở trên |
| Giám sát hiện "chưa có dữ liệu" | MONITORING_COLLECTOR_ADMIN_URL và MONITORING_COLLECTOR_ADMIN_TOKEN, cầu dao của collector đang mở (đặt lại ở trang chi tiết collector) |
| Agent hiện offline dù đang chạy | Collector có heartbeat không, ngưỡng online (mặc định 180 giây), agent có bị thu hồi không |
Enroll thất bại với binding_failed | Máy chủ chưa có trong hub cùng công ty với license, hoặc IP khớp nhiều máy chủ |
Dữ liệu sai sau khi sửa .env | php artisan config:clear, rồi php artisan queue:restart |
Mẹo: Sửa trực tiếp trên bản đang chạy
Nếu thư mục mã chính là bản đang phục vụ người dùng, mọi thay đổi cấu hình có hiệu lực ngay. Ghi lại thay đổi và kiểm tra bằng php artisan config:show <khóa> thay vì đọc .env.