Implement comprehensive rate limiting system and item spawn configuration
Major Features Added: - Complete token bucket rate limiting for IRC commands and web interface - Per-user rate tracking with category-based limits (Basic, Gameplay, Management, Admin, Web) - Admin commands for rate limit management (\!rate_stats, \!rate_user, \!rate_unban, \!rate_reset) - Automatic violation tracking and temporary bans with cleanup - Global item spawn multiplier system with 75% spawn rate reduction - Central admin configuration system (config.py) - One-command bot startup script (start_petbot.sh) Rate Limiting: - Token bucket algorithm with burst capacity and refill rates - Category limits: Basic (20/min), Gameplay (10/min), Management (5/min), Web (60/min) - Graceful violation handling with user-friendly error messages - Admin exemption and override capabilities - Background cleanup of old violations and expired bans Item Spawn System: - Added global_spawn_multiplier to config/items.json for easy adjustment - Reduced all individual spawn rates by 75% (multiplied by 0.25) - Admins can fine-tune both global multiplier and individual item rates - Game engine integration applies multiplier to all spawn calculations Infrastructure: - Single admin user configuration in config.py - Enhanced startup script with dependency management and verification - Updated documentation and help system with rate limiting guide - Comprehensive test suite for rate limiting functionality Security: - Rate limiting protects against command spam and abuse - IP-based tracking for web interface requests - Proper error handling and status codes (429 for rate limits) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
megaproxy
parent
f8ac661cd1
commit
915aa00bea
28 changed files with 5730 additions and 57 deletions
369
TROUBLESHOOTING.md
Normal file
369
TROUBLESHOOTING.md
Normal file
|
|
@ -0,0 +1,369 @@
|
|||
# PetBot Troubleshooting Guide
|
||||
|
||||
## Common Installation Issues
|
||||
|
||||
### Issue 1: externally-managed-environment Error
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
error: externally-managed-environment
|
||||
|
||||
× This environment is externally managed
|
||||
╰─> To install Python packages system-wide, try apt install
|
||||
python3-xyz, where xyz is the package you are trying to
|
||||
install.
|
||||
```
|
||||
|
||||
**Cause:** Modern Python installations (3.11+) prevent direct pip installations to avoid conflicts with system packages.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
#### Solution A: Use Fixed Installation Script (Recommended)
|
||||
```bash
|
||||
./install_prerequisites_simple.sh
|
||||
```
|
||||
|
||||
This creates a virtual environment and installs packages there.
|
||||
|
||||
#### Solution B: Manual Virtual Environment Setup
|
||||
```bash
|
||||
# Create virtual environment
|
||||
python3 -m venv venv
|
||||
|
||||
# Activate virtual environment
|
||||
source venv/bin/activate
|
||||
|
||||
# Install packages
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Run bot (while venv is active)
|
||||
python run_bot_with_reconnect.py
|
||||
|
||||
# Deactivate when done
|
||||
deactivate
|
||||
```
|
||||
|
||||
#### Solution C: System Package Installation (Ubuntu/Debian)
|
||||
```bash
|
||||
# Install system packages instead
|
||||
sudo apt update
|
||||
sudo apt install python3-pip python3-aiosqlite python3-dotenv
|
||||
|
||||
# For IRC library, you may still need pip in venv or --break-system-packages
|
||||
pip install --break-system-packages irc>=20.3.0
|
||||
```
|
||||
|
||||
#### Solution D: Force Installation (Not Recommended)
|
||||
```bash
|
||||
pip install --break-system-packages -r requirements.txt
|
||||
```
|
||||
|
||||
⚠️ **Warning:** This can break system Python packages.
|
||||
|
||||
### Issue 2: venv Module Not Found
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
ModuleNotFoundError: No module named 'venv'
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install python3-venv
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum install python3-venv
|
||||
|
||||
# Or try alternative
|
||||
sudo apt install python3-virtualenv
|
||||
```
|
||||
|
||||
### Issue 3: Permission Denied
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
Permission denied: './install_prerequisites_simple.sh'
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
chmod +x install_prerequisites_simple.sh
|
||||
./install_prerequisites_simple.sh
|
||||
```
|
||||
|
||||
### Issue 4: Python Version Too Old
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
Python 3.6.x is not supported
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
#### Ubuntu/Debian:
|
||||
```bash
|
||||
# Add deadsnakes PPA for newer Python
|
||||
sudo apt update
|
||||
sudo apt install software-properties-common
|
||||
sudo add-apt-repository ppa:deadsnakes/ppa
|
||||
sudo apt update
|
||||
sudo apt install python3.11 python3.11-venv python3.11-pip
|
||||
|
||||
# Use specific version
|
||||
python3.11 -m venv venv
|
||||
```
|
||||
|
||||
#### CentOS/RHEL:
|
||||
```bash
|
||||
# Enable EPEL and install Python 3.9+
|
||||
sudo yum install epel-release
|
||||
sudo yum install python39 python39-pip
|
||||
```
|
||||
|
||||
#### Manual Compilation:
|
||||
```bash
|
||||
# Download and compile Python (last resort)
|
||||
wget https://www.python.org/ftp/python/3.11.0/Python-3.11.0.tgz
|
||||
tar xzf Python-3.11.0.tgz
|
||||
cd Python-3.11.0
|
||||
./configure --enable-optimizations
|
||||
make -j 8
|
||||
sudo make altinstall
|
||||
```
|
||||
|
||||
## Runtime Issues
|
||||
|
||||
### Issue 5: IRC Connection Failed
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
Could not connect to irc.libera.chat:6667
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. Check internet connection: `ping irc.libera.chat`
|
||||
2. Try different IRC server/port
|
||||
3. Check firewall settings
|
||||
4. Use IRC over TLS (port 6697)
|
||||
|
||||
### Issue 6: Database Locked
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
sqlite3.OperationalError: database is locked
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. Stop all bot instances
|
||||
2. Check for stale lock files: `rm -f data/petbot.db-wal data/petbot.db-shm`
|
||||
3. Restart the bot
|
||||
|
||||
### Issue 7: Web Interface Not Accessible
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
Connection refused on port 8080
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. Check if bot is running
|
||||
2. Verify port 8080 is not in use: `netstat -tlnp | grep 8080`
|
||||
3. Try different port in webserver.py
|
||||
4. Check firewall: `sudo ufw allow 8080`
|
||||
|
||||
### Issue 8: Module Import Errors
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
ModuleNotFoundError: No module named 'irc'
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. Make sure virtual environment is activated
|
||||
2. Reinstall packages: `pip install -r requirements.txt`
|
||||
3. Check Python path: `python -c "import sys; print(sys.path)"`
|
||||
|
||||
## Using Virtual Environment
|
||||
|
||||
### Daily Usage Pattern
|
||||
```bash
|
||||
# Activate virtual environment
|
||||
source venv/bin/activate
|
||||
|
||||
# Run bot
|
||||
python run_bot_with_reconnect.py
|
||||
|
||||
# Run tests
|
||||
python test_backup_simple.py
|
||||
|
||||
# Deactivate when done
|
||||
deactivate
|
||||
```
|
||||
|
||||
### Or Use Wrapper Scripts
|
||||
```bash
|
||||
# These automatically handle venv activation
|
||||
./run_petbot.sh # Start bot
|
||||
./run_petbot_debug.sh # Debug mode
|
||||
./test_petbot.sh # Run tests
|
||||
./activate_petbot.sh # Manual activation
|
||||
```
|
||||
|
||||
## Virtual Environment Management
|
||||
|
||||
### Check if Virtual Environment is Active
|
||||
```bash
|
||||
# Should show venv path if active
|
||||
which python
|
||||
|
||||
# Or check environment variable
|
||||
echo $VIRTUAL_ENV
|
||||
```
|
||||
|
||||
### Recreate Virtual Environment
|
||||
```bash
|
||||
# Remove old venv
|
||||
rm -rf venv
|
||||
|
||||
# Create new one
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### List Installed Packages
|
||||
```bash
|
||||
# Activate venv first
|
||||
source venv/bin/activate
|
||||
|
||||
# List packages
|
||||
pip list
|
||||
|
||||
# Show package info
|
||||
pip show irc aiosqlite
|
||||
```
|
||||
|
||||
## System-Specific Issues
|
||||
|
||||
### Ubuntu 22.04+ (externally-managed-environment)
|
||||
- Use virtual environment (recommended)
|
||||
- Or install system packages: `sudo apt install python3-aiosqlite`
|
||||
- IRC library may still need pip installation
|
||||
|
||||
### CentOS/RHEL 8+
|
||||
- Enable EPEL repository
|
||||
- Install python39 or newer
|
||||
- Use virtual environment
|
||||
|
||||
### macOS
|
||||
- Install via Homebrew: `brew install python3`
|
||||
- Virtual environment should work normally
|
||||
|
||||
### Windows
|
||||
- Install Python from python.org
|
||||
- Use Command Prompt or PowerShell
|
||||
- Virtual environment commands:
|
||||
```cmd
|
||||
python -m venv venv
|
||||
venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Development Environment
|
||||
|
||||
### IDE/Editor Setup
|
||||
|
||||
#### VS Code
|
||||
```json
|
||||
{
|
||||
"python.defaultInterpreterPath": "./venv/bin/python",
|
||||
"python.terminal.activateEnvironment": true
|
||||
}
|
||||
```
|
||||
|
||||
#### PyCharm
|
||||
- Set Project Interpreter to `./venv/bin/python`
|
||||
- Enable "Add content roots to PYTHONPATH"
|
||||
|
||||
### Running Tests in IDE
|
||||
Make sure to:
|
||||
1. Set interpreter to venv Python
|
||||
2. Set working directory to project root
|
||||
3. Add project root to PYTHONPATH
|
||||
|
||||
## Quick Diagnosis Commands
|
||||
|
||||
### Check Python Setup
|
||||
```bash
|
||||
python3 --version
|
||||
python3 -c "import sys; print(sys.executable)"
|
||||
python3 -c "import sys; print(sys.path)"
|
||||
```
|
||||
|
||||
### Check Package Installation
|
||||
```bash
|
||||
# In virtual environment
|
||||
python -c "import irc, aiosqlite, dotenv; print('All packages OK')"
|
||||
```
|
||||
|
||||
### Check File Permissions
|
||||
```bash
|
||||
ls -la *.sh *.py
|
||||
ls -la data/ backups/
|
||||
```
|
||||
|
||||
### Check Network Connectivity
|
||||
```bash
|
||||
ping irc.libera.chat
|
||||
telnet irc.libera.chat 6667
|
||||
curl -I http://localhost:8080
|
||||
```
|
||||
|
||||
### Check System Resources
|
||||
```bash
|
||||
free -h # Memory
|
||||
df -h # Disk space
|
||||
ps aux | grep python # Running Python processes
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
1. **Check Logs:** Look at console output for specific error messages
|
||||
2. **Test Components:** Use individual test scripts to isolate issues
|
||||
3. **Verify Environment:** Ensure virtual environment is activated
|
||||
4. **Check Dependencies:** Verify all packages are installed correctly
|
||||
5. **Review Documentation:** Check INSTALLATION.md for detailed setup
|
||||
|
||||
## Emergency Recovery
|
||||
|
||||
### Complete Reset
|
||||
```bash
|
||||
# Remove everything
|
||||
rm -rf venv data/*.db backups/* logs/*
|
||||
|
||||
# Reinstall
|
||||
./install_prerequisites_simple.sh
|
||||
|
||||
# Restart
|
||||
./run_petbot.sh
|
||||
```
|
||||
|
||||
### Backup Database Before Reset
|
||||
```bash
|
||||
# Create manual backup
|
||||
cp data/petbot.db data/petbot_backup_$(date +%Y%m%d_%H%M%S).db
|
||||
```
|
||||
|
||||
### Restore from Backup
|
||||
```bash
|
||||
# List available backups
|
||||
ls -la backups/
|
||||
|
||||
# Restore (replace with actual filename)
|
||||
cp backups/petbot_backup_daily_20240115_030000.db.gz /tmp/
|
||||
gunzip /tmp/petbot_backup_daily_20240115_030000.db
|
||||
cp /tmp/petbot_backup_daily_20240115_030000.db data/petbot.db
|
||||
```
|
||||
|
||||
Remember: When in doubt, use the virtual environment! It solves most installation issues. 🐾
|
||||
Loading…
Add table
Add a link
Reference in a new issue