473 lines
9.4 KiB
Markdown
473 lines
9.4 KiB
Markdown
# Troubleshooting Guide
|
|
|
|
This guide covers common issues and their solutions for the Torrent Gateway native installation.
|
|
|
|
## Service Issues
|
|
|
|
#### Gateway Won't Start
|
|
|
|
**Symptoms:** Service exits immediately or health checks fail
|
|
|
|
**Diagnostic Steps:**
|
|
```bash
|
|
# Check service status
|
|
sudo systemctl status torrent-gateway
|
|
|
|
# Check detailed logs
|
|
sudo journalctl -u torrent-gateway -f
|
|
|
|
# Check database file
|
|
ls -la /opt/torrent-gateway/data/metadata.db
|
|
|
|
# Test database connection
|
|
sqlite3 /opt/torrent-gateway/data/metadata.db "SELECT COUNT(*) FROM files;"
|
|
```
|
|
|
|
**Solutions:**
|
|
1. **Fix permissions:**
|
|
```bash
|
|
sudo chown -R torrent-gateway:torrent-gateway /opt/torrent-gateway/data
|
|
```
|
|
|
|
2. **Check disk space:**
|
|
```bash
|
|
df -h /opt/torrent-gateway/
|
|
```
|
|
|
|
3. **Reset database (last resort):**
|
|
```bash
|
|
sudo systemctl stop torrent-gateway
|
|
sudo mv /opt/torrent-gateway/data/metadata.db /opt/torrent-gateway/data/metadata.db.backup
|
|
sudo systemctl start torrent-gateway
|
|
```
|
|
|
|
#### Redis Connection Issues
|
|
|
|
**Symptoms:** Gateway logs show Redis connection errors
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Check Redis service
|
|
sudo systemctl status redis-server
|
|
|
|
# Test Redis connection
|
|
redis-cli ping
|
|
|
|
# Restart Redis
|
|
sudo systemctl restart redis-server
|
|
```
|
|
|
|
### Performance Issues
|
|
|
|
#### High CPU Usage
|
|
|
|
**Diagnostic:**
|
|
```bash
|
|
# Check service resources
|
|
systemctl status torrent-gateway
|
|
htop
|
|
|
|
# Check system resources
|
|
top
|
|
```
|
|
|
|
**Solutions:**
|
|
1. **Check for resource leaks:**
|
|
```bash
|
|
sudo journalctl -u torrent-gateway | grep -i "memory\|leak"
|
|
```
|
|
|
|
2. **Optimize database:**
|
|
```bash
|
|
/opt/torrent-gateway/scripts/migrate.sh # Runs VACUUM and ANALYZE
|
|
```
|
|
|
|
3. **Add resource limits:**
|
|
Edit systemd service limits in `/etc/systemd/system/torrent-gateway.service`
|
|
|
|
#### High Memory Usage
|
|
|
|
**Diagnostic:**
|
|
```bash
|
|
# Check memory usage
|
|
free -h
|
|
ps aux | grep gateway
|
|
|
|
# Check for memory leaks in logs
|
|
sudo journalctl -u torrent-gateway | grep -i "memory\|leak\|oom"
|
|
```
|
|
|
|
**Solutions:**
|
|
1. **Restart service:**
|
|
```bash
|
|
sudo systemctl restart torrent-gateway
|
|
```
|
|
|
|
2. **Implement stricter memory limits:**
|
|
```ini
|
|
# In /etc/systemd/system/torrent-gateway.service
|
|
[Service]
|
|
MemoryMax=1G
|
|
```
|
|
|
|
#### Slow File Operations
|
|
|
|
**Common Causes:**
|
|
- Disk I/O bottleneck
|
|
- Database fragmentation
|
|
- Too many concurrent operations
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Check disk I/O
|
|
iostat -x 1
|
|
|
|
# Optimize database
|
|
sqlite3 /opt/torrent-gateway/data/metadata.db "VACUUM; ANALYZE;"
|
|
|
|
# Check file system
|
|
df -h
|
|
find /opt/torrent-gateway/data -name "*.tmp" -delete
|
|
```
|
|
|
|
## Database Issues
|
|
|
|
#### Database Locked Errors
|
|
|
|
**Symptoms:** "database is locked" errors
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Find processes using database
|
|
lsof /opt/torrent-gateway/data/metadata.db
|
|
|
|
# Stop service and clean up (if safe)
|
|
sudo systemctl stop torrent-gateway
|
|
rm -f /opt/torrent-gateway/data/metadata.db-wal /opt/torrent-gateway/data/metadata.db-shm
|
|
sudo systemctl start torrent-gateway
|
|
```
|
|
|
|
#### Database Corruption
|
|
|
|
**Symptoms:** SQL errors, integrity check failures
|
|
|
|
**Diagnostic:**
|
|
```bash
|
|
# Check database integrity
|
|
sqlite3 /opt/torrent-gateway/data/metadata.db "PRAGMA integrity_check;"
|
|
```
|
|
|
|
**Solutions:**
|
|
1. **Try repair:**
|
|
```bash
|
|
sudo systemctl stop torrent-gateway
|
|
sqlite3 /opt/torrent-gateway/data/metadata.db ".recover" > /tmp/recovered.sql
|
|
sqlite3 /opt/torrent-gateway/data/metadata_new.db < /tmp/recovered.sql
|
|
```
|
|
|
|
2. **Restore from backup:**
|
|
```bash
|
|
sudo /opt/torrent-gateway/scripts/restore.sh BACKUP_TIMESTAMP
|
|
```
|
|
|
|
### Storage Issues
|
|
|
|
#### Disk Space Full
|
|
|
|
**Diagnostic:**
|
|
```bash
|
|
# Check disk usage
|
|
df -h /opt/torrent-gateway/
|
|
du -sh /opt/torrent-gateway/data/*
|
|
```
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Run cleanup script
|
|
sudo /opt/torrent-gateway/scripts/cleanup.sh
|
|
|
|
# Manual cleanup
|
|
find /opt/torrent-gateway/data/chunks -type f -mtime +30 -delete
|
|
find /opt/torrent-gateway/logs -name "*.log" -mtime +7 -delete
|
|
```
|
|
|
|
#### File Upload Failures
|
|
|
|
**Common Issues:**
|
|
- Nginx client_max_body_size too small
|
|
- Disk space insufficient
|
|
- Permissions problems
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Check nginx configuration
|
|
sudo nginx -t
|
|
sudo systemctl reload nginx
|
|
|
|
# Check upload directory permissions
|
|
ls -la /opt/torrent-gateway/data/
|
|
|
|
# Increase nginx limits
|
|
sudo vim /etc/nginx/sites-available/torrent-gateway
|
|
# Update: client_max_body_size 50G;
|
|
```
|
|
|
|
## Network Issues
|
|
|
|
#### Connection Timeouts
|
|
|
|
**Symptoms:** API requests timeout, health checks fail
|
|
|
|
**Diagnostic:**
|
|
```bash
|
|
# Test local connectivity
|
|
curl -v http://localhost:9877/api/health
|
|
|
|
# Check network configuration
|
|
ss -tulpn | grep 9877
|
|
```
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Restart nginx
|
|
sudo systemctl restart nginx
|
|
|
|
# Check firewall
|
|
sudo ufw status
|
|
|
|
# Increase timeouts
|
|
curl --connect-timeout 30 --max-time 60 http://localhost:9877/api/health
|
|
```
|
|
|
|
#### Port Binding Issues
|
|
|
|
**Symptoms:** "Port already in use" errors
|
|
|
|
**Diagnostic:**
|
|
```bash
|
|
# Check what's using the port
|
|
sudo lsof -i :9877
|
|
sudo netstat -tulpn | grep 9877
|
|
```
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Kill conflicting process
|
|
sudo kill $(sudo lsof -t -i:9877)
|
|
|
|
# Or change port in configuration
|
|
sudo vim /opt/torrent-gateway/configs/config.yaml
|
|
```
|
|
|
|
### SSL/HTTPS Issues
|
|
|
|
#### Certificate Errors
|
|
|
|
**Symptoms:** SSL warnings, certificate expired
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Check certificate status
|
|
sudo certbot certificates
|
|
|
|
# Renew certificates
|
|
sudo certbot renew
|
|
|
|
# Test renewal
|
|
sudo certbot renew --dry-run
|
|
```
|
|
|
|
#### Mixed Content Warnings
|
|
|
|
**Causes:** HTTP resources loaded on HTTPS page
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Check nginx configuration
|
|
sudo vim /etc/nginx/sites-available/torrent-gateway
|
|
# Ensure all proxy_set_header X-Forwarded-Proto $scheme;
|
|
```
|
|
|
|
### Monitoring Issues
|
|
|
|
#### Prometheus Not Scraping
|
|
|
|
**Diagnostic:**
|
|
```bash
|
|
# Check Prometheus service
|
|
sudo systemctl status prometheus
|
|
|
|
# Check metrics endpoint
|
|
curl -s http://localhost:9877/metrics
|
|
```
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Restart Prometheus
|
|
sudo systemctl restart prometheus
|
|
|
|
# Check configuration
|
|
sudo vim /opt/prometheus/prometheus.yml
|
|
```
|
|
|
|
#### Grafana Dashboard Issues
|
|
|
|
**Common Problems:**
|
|
1. **No data in dashboards:**
|
|
- Check Prometheus data source configuration
|
|
- Verify metrics are being collected: `curl http://localhost:9877/metrics`
|
|
|
|
2. **Dashboard import errors:**
|
|
- Verify dashboard version compatibility
|
|
|
|
## Video Transcoding Issues
|
|
|
|
#### FFmpeg Errors
|
|
|
|
**Symptoms:** Transcoding fails, codec errors
|
|
|
|
**Diagnostic:**
|
|
```bash
|
|
# Check FFmpeg installation
|
|
ffmpeg -version
|
|
|
|
# Check logs for transcoding errors
|
|
sudo journalctl -u torrent-gateway | grep -i "transcode\|ffmpeg"
|
|
```
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Install/update FFmpeg
|
|
sudo apt update
|
|
sudo apt install -y ffmpeg
|
|
|
|
# Check disk space for temp files
|
|
df -h /opt/torrent-gateway/data/transcoded/
|
|
```
|
|
|
|
## Log Analysis
|
|
|
|
#### Finding Specific Errors
|
|
|
|
```bash
|
|
# Gateway application logs
|
|
sudo journalctl -u torrent-gateway --since "1 hour ago"
|
|
|
|
# System logs with timestamps
|
|
sudo journalctl --since "1 hour ago" | grep gateway
|
|
|
|
# Follow logs in real-time
|
|
sudo journalctl -u torrent-gateway -f
|
|
```
|
|
|
|
#### Log Rotation Issues
|
|
|
|
```bash
|
|
# Check log sizes
|
|
sudo du -sh /opt/torrent-gateway/logs/*
|
|
|
|
# Manually rotate logs
|
|
sudo logrotate -f /etc/logrotate.d/torrent-gateway
|
|
```
|
|
|
|
## Emergency Procedures
|
|
|
|
### Complete Service Failure
|
|
|
|
1. **Stop all services:**
|
|
```bash
|
|
sudo systemctl stop torrent-gateway nginx redis-server
|
|
```
|
|
|
|
2. **Check system resources:**
|
|
```bash
|
|
df -h
|
|
free -h
|
|
top
|
|
```
|
|
|
|
3. **Restore from backup:**
|
|
```bash
|
|
sudo /opt/torrent-gateway/scripts/restore.sh LATEST_BACKUP
|
|
```
|
|
|
|
4. **Restart services:**
|
|
```bash
|
|
sudo systemctl start redis-server nginx torrent-gateway
|
|
```
|
|
|
|
### Data Recovery
|
|
|
|
```bash
|
|
# Create emergency backup
|
|
sudo tar -czf /tmp/gateway_emergency_$(date +%Y%m%d_%H%M%S).tar.gz /opt/torrent-gateway/data/
|
|
|
|
# Check database
|
|
sqlite3 /opt/torrent-gateway/data/metadata.db ".schema"
|
|
```
|
|
|
|
## Diagnostic Information Collection
|
|
|
|
### Log Collection
|
|
|
|
Before reporting issues, collect relevant logs:
|
|
|
|
```bash
|
|
# Create diagnostics package
|
|
mkdir -p diagnostics
|
|
sudo journalctl -u torrent-gateway --since "1 day ago" > diagnostics/service_logs.txt
|
|
sudo /opt/torrent-gateway/scripts/health_check.sh > diagnostics/health_check.txt 2>&1
|
|
cp /opt/torrent-gateway/data/metadata.db diagnostics/ 2>/dev/null || echo "Database not accessible"
|
|
tar -czf diagnostics_$(date +%Y%m%d_%H%M%S).tar.gz diagnostics/
|
|
```
|
|
|
|
### Health Check Output
|
|
|
|
Always include health check results:
|
|
```bash
|
|
sudo /opt/torrent-gateway/scripts/health_check.sh | tee health_status.txt
|
|
```
|
|
|
|
### System Information
|
|
|
|
```bash
|
|
# Collect system info
|
|
echo "System: $(uname -a)" > system_info.txt
|
|
echo "Memory: $(free -h)" >> system_info.txt
|
|
echo "Disk: $(df -h)" >> system_info.txt
|
|
echo "FFmpeg: $(ffmpeg -version 2>/dev/null | head -1 || echo 'Not installed')" >> system_info.txt
|
|
echo "Go version: $(go version 2>/dev/null || echo 'Not installed')" >> system_info.txt
|
|
```
|
|
|
|
## Getting Help
|
|
|
|
### Information to Include
|
|
|
|
When reporting issues, always include:
|
|
1. System information (OS, version, architecture)
|
|
2. Installation method and version
|
|
3. Error messages and logs
|
|
4. Steps to reproduce
|
|
5. Expected vs actual behavior
|
|
|
|
### Log Locations
|
|
|
|
- **Application logs:** `sudo journalctl -u torrent-gateway`
|
|
- **Nginx logs:** `/var/log/nginx/error.log`
|
|
- **System logs:** `/var/log/syslog`
|
|
- **Health check logs:** `/var/log/torrent-gateway-health.log`
|
|
|
|
### Useful Commands
|
|
|
|
```bash
|
|
# Full system status
|
|
sudo /opt/torrent-gateway/scripts/health_check.sh
|
|
|
|
# Service overview
|
|
sudo systemctl status torrent-gateway nginx redis-server
|
|
|
|
# Resource usage
|
|
htop
|
|
df -h
|
|
free -h
|
|
``` |