Xử lý sự cố White-Label System

Troubleshooting

Hướng dẫn chi tiết về cách chẩn đoán và khắc phục các vấn đề thường gặp khi triển khai và vận hành hệ thống White-Label OV-Panel.

Vấn đề: Instance không khởi động

Triệu chứng

Service status hiển thị failed hoặc inactive

systemctl status ov-panel-instance@<uuid>
# Output: Active: failed (Result: exit-code)

Các bước chẩn đoán

1. Kiểm tra logs chi tiết

# Xem logs từ journalctl
journalctl -u ov-panel-instance@<uuid> -n 100

# Xem error log file
tail -n 50 /opt/ov-panel-instances/instance-<uuid>/logs/error.log

2. Kiểm tra port conflict

# Kiểm tra port đã được sử dụng chưa
netstat -tulpn | grep <port>

# Hoặc
lsof -i :<port>

# Nếu có output = port đã bị chiếm

Giải pháp: Đổi port trong file .env và database, sau đó restart instance.

3. Kiểm tra file .env

# Xem nội dung .env
cat /opt/ov-panel-instances/instance-<uuid>/.env.<uuid>

# Kiểm tra:
# - Có đầy đủ variables không?
# - Format đúng không? (KEY=VALUE)
# - Port có đúng không?

4. Kiểm tra database file

# Kiểm tra file tồn tại và permissions
ls -la /opt/ov-panel-instances/instance-<uuid>/data/ov-panel.db

# Output mong đợi:
-rw-r--r-- 1 root root 245760 Nov 17 10:30 ov-panel.db

5. Test start manually

cd /opt/ov-panel
export INSTANCE_ID=<uuid>
source /opt/ov-panel-instances/instance-<uuid>/.env.<uuid>
/opt/ov-panel/venv/bin/python main.py

# Xem error trực tiếp nếu có

Giải pháp phổ biến

Port conflict

# 1. Edit .env và đổi port
nano /opt/ov-panel-instances/instance-<uuid>/.env.<uuid>
# PORT=9005

# 2. Update database
cd /opt/ov-panel
python3 -c "
from backend.db.engine import sessionLocal
from backend.db.models import WhiteLabelInstance
db = sessionLocal()
instance = db.query(WhiteLabelInstance).filter_by(instance_id='<uuid>').first()
instance.port = 9005
db.commit()
print('Port updated to 9005')
"

# 3. Restart instance
systemctl restart ov-panel-instance@<uuid>

Database corruption

# 1. Backup old database
mv /opt/ov-panel-instances/instance-<uuid>/data/ov-panel.db \
   /opt/ov-panel-instances/instance-<uuid>/data/ov-panel.db.bak

# 2. Copy fresh sample
cp /opt/ov-panel/data/ov-panel-sample.db \
   /opt/ov-panel-instances/instance-<uuid>/data/ov-panel.db

# 3. Restart instance
systemctl restart ov-panel-instance@<uuid>

Lưu ý: Thao tác này sẽ mất dữ liệu. Chỉ sử dụng khi database bị lỗi nghiêm trọng.

Vấn đề: Instance chạy nhưng không truy cập được

Triệu chứng

Service = active nhưng không mở được trong browser

systemctl status ov-panel-instance@<uuid>
# Output: Active: active (running)

# Nhưng trình duyệt báo: Connection refused / Timeout

Các bước kiểm tra

1. Verify port listening

netstat -tulpn | grep <port>

# Phải thấy python process listening trên port đó
tcp        0      0 0.0.0.0:9001       0.0.0.0:*       LISTEN      12345/python

2. Test local connection

# Test từ localhost
curl http://localhost:<port>/dashboard

# Nếu thành công = instance đang chạy OK
# Nếu failed = vấn đề ở application

3. Kiểm tra firewall

# Check UFW status
ufw status

# Check iptables
iptables -L -n -v | grep <port>

Giải pháp

Firewall blocking

# Mở port trong UFW
ufw allow <port>/tcp

# Hoặc mở range ports
ufw allow 9001:9999/tcp

# Reload firewall
ufw reload

Wrong HOST binding

# Nếu HOST=127.0.0.1 thì chỉ access từ localhost
# Edit .env
nano /opt/ov-panel-instances/instance-<uuid>/.env.<uuid>

# Đổi thành:
HOST=0.0.0.0

# Restart
systemctl restart ov-panel-instance@<uuid>

Vấn đề: Database Migration Failed

Triệu chứng

Lỗi migration khi update code hoặc database

alembic.util.exc.CommandError: Target database is not up to date

Giải pháp

Migration Fix

# 1. Kiểm tra migration version hiện tại
cd /opt/ov-panel/backend
export INSTANCE_ID=<uuid>
alembic current

# 2. Force upgrade
alembic upgrade head

# 3. Nếu vẫn lỗi, stamp version
alembic stamp head

# 4. Restart instance
systemctl restart ov-panel-instance@<uuid>

Vấn đề: Super Admin Panel không show instances

Triệu chứng

Web UI không hiển thị instances hoặc API trả về empty list

Các bước kiểm tra

1. Verify database

sqlite3 /opt/ov-panel/data/ov-panel.db "SELECT * FROM whitelabel_instances;"

# Phải thấy instances nếu đã tạo

2. Test API endpoint

# Get JWT token
TOKEN=$(curl -X POST http://localhost:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"superadmin","password":"yourpassword"}' \
  | jq -r '.data.access_token')

# List instances via API
curl http://localhost:9000/api/whitelabel/list \
  -H "Authorization: Bearer $TOKEN" | jq

3. Check logs

journalctl -u ov-panel -n 100 | grep -i "error|exception"

Vấn đề: Shared symlinks broken

Triệu chứng

Symlinks màu đỏ hoặc broken khi list

ls -la /opt/ov-panel-instances/shared/
# Symlinks hiển thị màu đỏ (broken)

Giải pháp

Fix Symlinks

# Re-initialize shared directory
python3 /opt/ov-panel/whitelabel_cli.py init

# Hoặc manual fix
cd /opt/ov-panel-instances/shared
rm -f backend frontend main.py pyproject.toml

ln -s /opt/ov-panel/backend backend
ln -s /opt/ov-panel/frontend frontend
ln -s /opt/ov-panel/main.py main.py
ln -s /opt/ov-panel/pyproject.toml pyproject.toml

# Restart tất cả instances
systemctl restart ov-panel-instance@*.service

Vấn đề hiệu suất

Triệu chứng

Instances chậm, high CPU/Memory usage

Monitoring & Solutions

Monitor resources

# Top processes
top -u root | grep python

# Instance-specific
systemctl status ov-panel-instance@<uuid> | grep -E 'Memory|CPU'

# All instances
for svc in $(systemctl list-units 'ov-panel-instance@*' --no-legend | awk '{print $1}'); do
    echo "=== $svc ==="
    systemctl status $svc | grep -E 'Memory|CPU'
done

Solutions

Too many connections:

# Check connection count
netstat -an | grep <port> | wc -l

# Consider adding connection pooling or rate limiting

Memory leak:

# Restart instance để free memory
systemctl restart ov-panel-instance@<uuid>

# Schedule periodic restarts (weekly)
# Crontab: 0 4 * * 0 systemctl restart ov-panel-instance@<uuid>

Disk full:

# Check disk space
df -h

# Clean old logs
find /opt/ov-panel-instances/instance-*/logs/ -name "*.log" -mtime +30 -delete

# Rotate logs
logrotate -f /etc/logrotate.d/ov-panel-instances

Best Practices để tránh vấn đề

Regular Monitoring

• Setup health check scripts (5 phút)

• Monitor resource usage daily

• Check logs for errors/warnings

• Track disk space growth

Backup Strategy

• Daily database backups

• Keep backups 30+ days

• Test restore procedures

• Backup configuration files

Security Measures

• Strong passwords (>12 chars)

• Firewall properly configured

• Regular security updates

• Monitor suspicious activities

Documentation

• Document instance configurations

• Keep port assignment list

• Record maintenance history

• Share knowledge with team

Liên hệ hỗ trợ

Cần thêm hỗ trợ?

Telegram Community:

@vouuvhb

GitHub Issues:

TinyActive/OpenVpn-Panel/issues

Documentation:

Quay lại trang giới thiệu để xem lại tài liệu

Pro tip: Khi báo cáo vấn đề, hãy include: instance ID, logs, system info (OS, RAM, CPU) và các bước bạn đã thử để dễ dàng nhận được hỗ trợ nhanh hơn.