1. Tổng quan cài đặt nhanh
2. Yêu cầu hệ thống
3. Tải xuống và giải nén
4. MariaDB/MySQL và Redis
5. Cấu hình file .env
6. Khởi chạy vGocms
7. Đăng nhập trang quản trị
8. Kiểm tra sau khi cài đặt
9. Kiểm tra đường truyền
10. Xử lý lỗi thường gặp
11. Khuyến nghị bảo mật

0. Tổng quan cài đặt nhanh

Quy trình cài đặt gồm 6 bước. Hãy hoàn thành theo đúng thứ tự để tránh lỗi kết nối database, Redis hoặc phiên đăng nhập.

The installation has 6 steps. Complete them in order to avoid database, Redis, or session errors.

Thông tin truy cập mặc định / Default access information

1. Yêu cầu hệ thống

2. Tải xuống và giải nén

Tải bộ cài chính thức dành cho Windows 64-bit từ website vgo.codes. Tên gói cài đặt: vGocms-windows.zip.

Download the official Windows 64-bit package from vgo.codes. Package name: vGocms-windows.zip.

Tạo thư mục riêng, ví dụ C:\vGocms, rồi giải nén toàn bộ file ZIP vào thư mục đó.

Create a dedicated folder such as C:\vGocms, then extract the entire ZIP package into it.

C:\vGocms├── .env
└── vgocms_windows_amd64.exe

3. Chuẩn bị MariaDB/MySQL và Redis

3.1 MariaDB hoặc MySQL / MariaDB or MySQL

Mở Laragon và khởi động MariaDB. MariaDB được ưu tiên; MySQL vẫn có thể sử dụng nếu hệ thống của bạn đang chạy MySQL.

Open Laragon and start MariaDB. MariaDB is recommended; MySQL can also be used if it is already installed.

Tạo database có tên videogo bằng HeidiSQL, phpMyAdmin hoặc cửa sổ SQL:

Create a database named videogo using HeidiSQL, phpMyAdmin, or an SQL console:

CREATE DATABASE videogo
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;

3.2 Redis bắt buộc / Required Redis service

Khởi động Redis trong Laragon và giữ địa chỉ mặc định localhost:6379.

Start Redis in Laragon and use the default address localhost:6379.

Kiểm tra Redis bằng PowerShell:

redis-cli ping

# Kết quả đúng / Expected result
PONG

4. Cấu hình file .env

Mở .env bằng VS Code, Notepad++ hoặc trình soạn thảo văn bản. Cập nhật thông tin database, Redis, cổng ứng dụng và khóa bảo mật theo môi trường của bạn.

Open .env with VS Code, Notepad++, or another text editor. Update database, Redis, application port, and security settings for your environment.

# --- Database ---
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASS=123456
DB_NAME=videogo

# --- Redis ---
REDIS_ADDR=localhost:6379
REDIS_PASS=
REDIS_DB=0

USER_SERVICE_BASE_URL=http://localhost:8081
USER_SERVICE_WEBHOOK_ENABLED=1
USER_SERVICE_WEBHOOK_SECRET=vui-long-doi

# --- Session ---
SESSION_SECRET=vui-long-doi

# --- Application ---
APP_PORT=8000
# release mode: release, debug mode: debug
GIN_MODE=release
ENABLE_HSTS=1

# --- Cloud integrations security ---
# Generate once with: openssl rand -base64 48
# IMPORTANT: Do not change this after saving Cloudflare/Google credentials.
INTEGRATION_ENCRYPTION_KEY=

# --- Portable & secure database backup ---
# auto: prefer mariadb-dump/mysqldump, otherwise use the built-in Go exporter
# native: require mariadb-dump/mysqldump
# go: always use the built-in Go exporter
# BACKUP_METHOD=auto
# Optional absolute path when the dump tool is not in PATH, especially on Windows.
DB_DUMP_PATH=
# Keep backups outside the public ./static directory.
BACKUP_DIR=./data/backups
BACKUP_TIMEOUT_MINUTES=120

# ISP/network reachability monitor
NETWORK_CHECK_SCHEDULER=1
NETWORK_CHECK_HISTORY_DAYS=30

# --- Performance and security ---
# Exact public/admin hostnames, comma separated. Required in production.
# ALLOWED_HOSTS=admin.example.com,api.example.com
# Only reverse proxies allowed to supply X-Forwarded-* / client IP headers.
TRUSTED_PROXIES=127.0.0.1,::1
CSRF_ENABLED=1
# Enable when the admin panel is served through HTTPS.
SESSION_SECURE=0

# MariaDB driver timeout and connection pool.
DB_CONNECT_TIMEOUT=5s
DB_READ_TIMEOUT=10s
DB_WRITE_TIMEOUT=10s
DB_MAX_OPEN_CONNS=40
DB_MAX_IDLE_CONNS=10
DB_CONN_MAX_LIFETIME=30m
DB_CONN_MAX_IDLE_TIME=5m

# Redis fail-soft cache/pool settings.
REDIS_DIAL_TIMEOUT=3s
REDIS_READ_TIMEOUT=2s
REDIS_WRITE_TIMEOUT=2s
REDIS_POOL_SIZE=20
REDIS_MIN_IDLE_CONNS=2

# HTTP server protection.
HTTP_READ_HEADER_TIMEOUT=10s
HTTP_READ_TIMEOUT=30s
HTTP_WRITE_TIMEOUT=60s
HTTP_IDLE_TIMEOUT=120s
ADMIN_REQUEST_MAX_BYTES=134217728

# Upload and remote-image safety limits (bytes/pixels).
FILE_UPLOAD_MAX_BYTES=52428800
FILE_IMAGE_MAX_BYTES=15728640
REMOTE_IMAGE_MAX_BYTES=15728640
REMOTE_IMAGE_MAX_PIXELS=40000000

Các biến quan trọng / Important variables

Tạo khóa bảo mật bằng PowerShell / Generate security keys with PowerShell

Tạo khóa 48 byte cho INTEGRATION_ENCRYPTION_KEY:

$bytes = New-Object byte[] 48
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
[Convert]::ToBase64String($bytes)

Tạo khóa 32 byte cho SESSION_SECRET hoặc USER_SERVICE_WEBHOOK_SECRET:

$bytes = New-Object byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
[Convert]::ToBase64String($bytes)

Local và production / Local and production settings

5. Khởi chạy vGocms

Trước khi chạy, xác nhận MariaDB/MySQL và Redis đang hoạt động. Sau đó nhấp đúp vgocms_windows_amd64.exe hoặc chạy bằng PowerShell.

Before starting, confirm that MariaDB/MySQL and Redis are running. Then double-click vgocms_windows_amd64.exe or launch it from PowerShell.

cd C:\vGocms
.\vgocms_windows_amd64.exe

Windows SmartScreen

Windows có thể cảnh báo đối với file mới tải về. Chỉ tiếp tục khi file được tải từ liên kết chính thức. Chọn More info rồi Run anyway khi bạn đã xác minh nguồn.

Windows may warn about a newly downloaded executable. Continue only when it came from the official download link. Select More info and then Run anyway after verifying the source.

6. Đăng nhập trang quản trị

Mở trình duyệt và truy cập:

http://localhost:8000/admin/login

7. Kiểm tra sau khi cài đặt

Sau khi đăng nhập, mở Dashboard và xác nhận trạng thái database, Redis, tài nguyên hệ thống và các cảnh báo bảo mật.

After signing in, open the Dashboard and verify database, Redis, system resources, and security status.

8. Kiểm tra đường truyền và nhà mạng

Khi NETWORK_CHECK_SCHEDULER=1, vGocms sẽ định kỳ kiểm tra khả năng truy cập website qua các proxy nhà mạng đã cấu hình.

When NETWORK_CHECK_SCHEDULER=1, vGocms periodically tests website reachability through configured ISP proxies.

9. Xử lý lỗi thường gặp

Không truy cập được localhost:8000 / Cannot open localhost:8000

Kiểm tra file .exe có đang chạy, APP_PORT=8000, Windows Firewall và xung đột cổng.

Check whether the .exe is running, confirm APP_PORT=8000, and inspect Windows Firewall or port conflicts.

Get-NetTCPConnection -LocalPort 8000 -ErrorAction SilentlyContinue
netstat -ano | findstr :8000

Lỗi kết nối database / Database connection error

Kiểm tra MariaDB/MySQL đã chạy, database videogo đã tồn tại, đúng host/port/user/password.

Confirm MariaDB/MySQL is running, the videogo database exists, and host/port/user/password are correct.

mysql -h localhost -P 3306 -u root -p

Lỗi kết nối Redis / Redis connection error

Kiểm tra REDIS_ADDR=localhost:6379, mật khẩu Redis và dịch vụ Redis trong Laragon.

Check REDIS_ADDR=localhost:6379, the Redis password, and the Redis service in Laragon.

redis-cli -h localhost -p 6379 ping

File .exe chạy rồi tự đóng / The .exe opens and immediately closes

Chạy ứng dụng từ PowerShell để xem lỗi khởi động thay vì nhấp đúp.

cd C:\vGocms
.\vgocms_windows_amd64.exe

Không tạo được backup database / Database backup fails

Đặt BACKUP_METHOD=auto. Nếu công cụ dump không có trong PATH, cấu hình đường dẫn tuyệt đối trong DB_DUMP_PATH.

Use BACKUP_METHOD=auto. If the dump tool is not in PATH, set its absolute path in DB_DUMP_PATH.

DB_DUMP_PATH=C:\laragon\bin\mysql\mariadb-11.x.x-winx64\bin\mariadb-dump.exe

Lỗi webhook dịch vụ người dùng / User service webhook error

Nếu backend người dùng chưa chạy ở cổng 8081, tạm đặt USER_SERVICE_WEBHOOK_ENABLED=0. Khi bật, secret của hai hệ thống phải giống nhau.

If the user backend is not running on port 8081, temporarily set USER_SERVICE_WEBHOOK_ENABLED=0. When enabled, both systems must use the same secret.

USER_SERVICE_WEBHOOK_ENABLED=0

Không giữ được phiên đăng nhập khi chạy local / Login session does not persist locally

Khi truy cập bằng HTTP local, đặt SESSION_SECURE=0. Chỉ dùng SESSION_SECURE=1 khi chạy HTTPS.

For local HTTP access, use SESSION_SECURE=0. Use SESSION_SECURE=1 only behind HTTPS.

SESSION_SECURE=0

10. Khuyến nghị bảo mật

• Đổi mật khẩu tài khoản admin ngay lập tức.
  Change the admin account password immediately.
• Không dùng giá trị vui-long-doi trong production.
  Do not use vui-long-doi in production.
• Tạo riêng SESSION_SECRET, USER_SERVICE_WEBHOOK_SECRET và INTEGRATION_ENCRYPTION_KEY.
  Generate unique values for all secret and encryption keys.
• Chỉ công khai vGocms sau khi đã cấu hình HTTPS và reverse proxy.
  Expose vGocms publicly only after configuring HTTPS and a reverse proxy.
• Cấu hình chính xác ALLOWED_HOSTS và TRUSTED_PROXIES.
  Configure ALLOWED_HOSTS and TRUSTED_PROXIES precisely.
• Không lưu backup trong thư mục public hoặc static.
  Do not store backups in a public or static directory.
• Không đưa file .env lên GitHub công khai.
  Never commit .env to a public GitHub repository.
• Sao lưu khóa mã hóa ở nơi an toàn.
  Back up encryption keys in a secure location.
• Chỉ tải và cập nhật phần mềm từ nguồn chính thức.
  Download and update software only from official sources.