Cài đặt Access Hub
Trang này hướng dẫn dựng một Access Hub mới trên Linux với nginx và PHP-FPM. Sau khi làm xong, bạn có một hub chạy được với giao diện web, hàng đợi, lịch chạy lệnh và kênh thời gian thực.
Trước khi bắt đầu
DB_*Yêu cầu hệ thống
| Thành phần | Yêu cầu |
|---|---|
| PHP | 8.4 (composer.json cho phép từ 8.3, bản triển khai chạy 8.4) với PHP-FPM |
| CSDL | MySQL |
| Node.js | Đủ mới để chạy Vite 8, dùng để build giao diện |
| Web server | nginx (ví dụ bên dưới) |
| Tiến trình nền | systemd hoặc trình quản lý tiến trình tương đương |
Mẹo: Redis là tùy chọn
Tệp .env.example mặc định dùng MySQL cho session (SESSION_DRIVER=database), cache (CACHE_STORE=database) và queue (QUEUE_CONNECTION=database). Bạn không cần Redis để chạy hub. Nếu muốn dùng Redis, đổi các biến này và cài phpredis (REDIS_CLIENT=phpredis).
Bước 1: Lấy mã nguồn và cài phụ thuộc
cd /var/www/access-hub
composer install --no-dev --optimize-autoloader
npm ciBước 2: Cấu hình môi trường
Sao chép tệp mẫu rồi sửa các giá trị kết nối.
cp .env.example .env
php artisan key:generateCác nhóm biến cần điền:
| Nhóm | Biến chính |
|---|---|
| Ứng dụng | APP_URL, APP_ENV, APP_DEBUG |
| CSDL | DB_CONNECTION=mysql, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD |
| Hàng đợi | QUEUE_CONNECTION |
| Thời gian thực | BROADCAST_CONNECTION, REVERB_*, VITE_REVERB_* |
| Giám sát | MONITORING_COLLECTOR_PUBLIC_URL, MONITORING_COLLECTOR_ADMIN_URL, MONITORING_COLLECTOR_ADMIN_TOKEN |
Cảnh báo: Không commit tệp .env
Tệp .env chứa khóa ứng dụng và mật khẩu CSDL. Giữ nó ngoài hệ thống quản lý mã nguồn.
Bước 3: Tạo bảng dữ liệu
php artisan migrate --forceLệnh này cũng tạo bảng scheduled_commands dùng cho lịch chạy lệnh (xem Vận hành).
Bước 4: Build giao diện
npm run buildLệnh build cũng sinh lại các hàm Wayfinder cho route. Nếu bạn gọi trực tiếp wayfinder:generate, hãy truyền --with-form, nếu không các hàm .form() sẽ biến mất khỏi mã giao diện.
Bước 5: Tạo super admin đầu tiên
Hub không có lệnh artisan riêng để tạo quản trị viên đầu tiên. Có hai cách:
Chạy seeder, nó tạo các quyền, vai trò chuẩn và một tài khoản super admin dùng cho demo.
bashphp artisan db:seed --forceSau khi đăng nhập, đổi mật khẩu hoặc xóa tài khoản demo ngay.
Tạo người dùng bằng tinker rồi gán vai trò
super-admin.bashphp artisan tinker
Cảnh báo: Đổi tài khoản demo
Không để tài khoản demo do seeder tạo ở môi trường thật. Đăng nhập, tạo tài khoản quản trị của bạn, bật xác thực hai lớp rồi xóa tài khoản demo.
Bước 6: Cấu hình nginx
Ví dụ dưới đây phục vụ Laravel qua PHP-FPM và chuyển tiếp WebSocket của Reverb. Thay <your-hub-host> bằng tên miền của bạn, thêm khối TLS theo chuẩn của tổ chức.
server {
listen 80;
server_name <your-hub-host>;
root /var/www/access-hub/public;
index index.php;
client_max_body_size 100M;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
# WebSocket của Reverb
location ~ ^/apps?(/|$) {
proxy_http_version 1.1;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:8080;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
}
# Chặn tệp ẩn, trừ .well-known
location ~ /\.(?!well-known).* {
deny all;
}
# Không thực thi PHP trong thư mục dữ liệu
location ~ ^/(storage|bootstrap/cache)/.*\.php$ {
deny all;
}
}Kiểm tra và nạp lại cấu hình:
sudo nginx -t && sudo systemctl reload nginxBước 7: Scheduler (cron)
Hub chạy các lệnh định kỳ qua scheduler của Laravel. Hệ điều hành chỉ cần gọi schedule:run mỗi phút, còn lịch chi tiết của từng lệnh nằm trong bảng scheduled_commands và chỉnh được trong giao diện.
* * * * * www-data cd /var/www/access-hub && php artisan schedule:run >> /dev/null 2>&1Thiếu dòng cron này, các lệnh như dọn thùng rác, nhắc phê duyệt hay đồng bộ máy chủ sẽ không bao giờ chạy.
Bước 8: Queue worker
Hub chia hàng đợi thành nhiều lane: default, emails, exports, iac, notifications, webhooks. Mỗi lane là một tiến trình riêng. Với systemd, dùng một unit mẫu có tham số lane:
# /etc/systemd/system/[email protected]
[Unit]
Description=Access Hub Laravel Queue Worker (%i lane)
After=network.target php8.4-fpm.service
[Service]
User=www-data
Group=www-data
Restart=always
RestartSec=3
WorkingDirectory=/var/www/access-hub
ExecStart=/usr/bin/php /var/www/access-hub/artisan queue:work --queue=%i --sleep=3 --tries=3 --max-time=3600
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
for lane in default emails exports iac notifications webhooks; do
sudo systemctl enable --now access-hub-queue@$lane
doneMẹo: Restart sau mỗi lần đổi mã
Worker giữ mã trong bộ nhớ. Sau khi triển khai mã mới, chạy php artisan queue:restart để các worker nạp lại mã. Bỏ qua bước này, một job có thể chạy bằng mã cũ và thất bại.
Bước 9: Reverb (thời gian thực)
Reverb phục vụ WebSocket cho thông báo và cập nhật trực tiếp trên giao diện. Đặt BROADCAST_CONNECTION=reverb trong .env (mặc định của tệp mẫu là log), điền REVERB_* rồi chạy Reverb như một dịch vụ riêng:
# /etc/systemd/system/access-hub-reverb.service
[Unit]
Description=Access Hub Reverb websocket server
After=network.target
[Service]
User=www-data
Group=www-data
Restart=always
RestartSec=3
WorkingDirectory=/var/www/access-hub
ExecStart=/usr/bin/php /var/www/access-hub/artisan reverb:start --host=127.0.0.1 --port=8080
LimitNOFILE=10000
[Install]
WantedBy=multi-user.targetsudo systemctl enable --now access-hub-reverbReverb chỉ lắng nghe trên 127.0.0.1:8080. nginx chuyển tiếp các đường dẫn /app và /apps tới đó như ở bước 6, nên trình duyệt không cần mở thêm cổng.
Cập nhật phiên bản
Chạy tuần tự trên máy chủ hub:
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:restartCảnh báo: Hub đang chạy là bản triển khai thật
Nếu bạn sửa mã trực tiếp trên thư mục phục vụ web, thay đổi có hiệu lực ngay lập tức. Hãy sao lưu CSDL trước khi chạy migration trên môi trường thật.