3x-ui/docs/AI_MIGRATION.md

AI Feature Migration Guide

For Existing 3X-UI Users

This guide helps you safely upgrade your existing 3X-UI installation to include the new AI-powered Telegram bot feature.

📋 Pre-Migration Checklist

1. Check Current Version

/usr/local/x-ui/x-ui -v

2. Backup Your Database

# Create backup
cp /etc/x-ui/x-ui.db /etc/x-ui/x-ui.db.backup.$(date +%Y%m%d_%H%M%S)

# Verify backup
ls -lh /etc/x-ui/x-ui.db*

3. Stop Telegram Bot (Critical!)

# This prevents 409 bot conflicts
systemctl stop x-ui

🔄 Migration Steps

Option 1: Automatic Update (Recommended)

# 1. Stop service
systemctl stop x-ui

# 2. Run update script (when merged to main branch)
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/update.sh)

# 3. Start service
systemctl start x-ui

# 4. Check logs
tail -f /var/log/x-ui/3xipl.log

Option 2: Manual Update (From Source)

# 1. Stop service
systemctl stop x-ui

# 2. Backup current installation
cp -r /usr/local/x-ui /usr/local/x-ui.backup

# 3. Pull latest code
cd /usr/local/x-ui/source  # Or your source directory
git fetch origin
git checkout main
git pull origin main

# 4. Build
go mod download
go build -o /usr/local/x-ui/x-ui ./main.go

# 5. Start service
systemctl start x-ui

# 6. Verify
/usr/local/x-ui/x-ui -v

Option 3: From Feature Branch (Testing)

# For testing the feature before it's merged
cd /usr/local/x-ui/source
git fetch origin
git checkout feat/ai-integration  # Or the branch name
git pull origin feat/ai-integration

go mod download
go build -o /usr/local/x-ui/x-ui ./main.go

systemctl restart x-ui

⚙️ Post-Migration Configuration

Enable AI Feature

Method 1: Database (Fastest)

sqlite3 /etc/x-ui/x-ui.db <<'EOF'
-- Enable AI
INSERT OR REPLACE INTO setting (key, value) VALUES ('aiEnabled', 'true');

-- Add your API key (get from https://makersuite.google.com/app/apikey)
INSERT OR REPLACE INTO setting (key, value) VALUES ('aiApiKey', 'YOUR_GEMINI_API_KEY_HERE');

-- Optional: Set max tokens (default: 1024)
INSERT OR REPLACE INTO setting (key, value) VALUES ('aiMaxTokens', '1024');

-- Optional: Set temperature (default: 0.7, range: 0.0-1.0)
INSERT OR REPLACE INTO setting (key, value) VALUES ('aiTemperature', '0.7');
EOF

# Restart to apply
systemctl restart x-ui

Method 2: Web Panel (Recommended for non-technical users)

1. Login to panel: http://your-server:2053
2. Navigate to: Settings → Telegram Bot
3. Scroll to: AI Integration section
4. Toggle: Enable AI Features → ON
5. Paste: Your Gemini API key
6. Click: Save Settings
7. Click: Restart Panel (or restart Telegram bot)

Method 3: API Call

# Get your session token first by logging in
SESSION_TOKEN="your_session_token_here"

# Update AI settings
curl -X POST http://localhost:2053/panel/api/setting/ai/update \
  -H "Content-Type: application/json" \
  -H "Cookie: session=$SESSION_TOKEN" \
  -d '{
    "enabled": true,
    "apiKey": "YOUR_GEMINI_API_KEY",
    "maxTokens": 1024,
    "temperature": 0.7
  }'

✅ Verification

Test AI Integration

1. Check Logs

tail -f /var/log/x-ui/3xipl.log | grep -i "ai"

# Expected output:
# [INFO] Telegram Bot: AI service initialized - Enabled: true
# [INFO] AI Service: Gemini client initialized successfully

2. Test in Telegram Open your bot and send:

show server status

Expected response: Server metrics (CPU, memory, traffic, etc.)

3. Verify Settings

sqlite3 /etc/x-ui/x-ui.db "SELECT key, value FROM setting WHERE key LIKE 'ai%';"

# Expected output:
# aiEnabled|true
# aiApiKey|AIza...
# aiMaxTokens|1024
# aiTemperature|0.7

🔍 Troubleshooting

Issue: "AI service not enabled"

Diagnosis:

# Check if enabled
sqlite3 /etc/x-ui/x-ui.db "SELECT value FROM setting WHERE key = 'aiEnabled';"

# Check if API key exists
sqlite3 /etc/x-ui/x-ui.db "SELECT length(value) FROM setting WHERE key = 'aiApiKey';"

Solution:

# Enable and add API key
sqlite3 /etc/x-ui/x-ui.db <<EOF
UPDATE setting SET value = 'true' WHERE key = 'aiEnabled';
UPDATE setting SET value = 'YOUR_API_KEY' WHERE key = 'aiApiKey';
EOF

systemctl restart x-ui

Issue: "Telegram bot 409 conflict"

Cause: Previous bot instance still running

Solution:

# Force stop all instances
pkill -f "x-ui"
sleep 2
systemctl start x-ui

Issue: "Module not found: generative-ai-go"

Cause: Dependencies not installed

Solution:

cd /usr/local/x-ui/source
go mod download
go build -o /usr/local/x-ui/x-ui ./main.go
systemctl restart x-ui

Issue: Bot doesn't respond to natural language

Diagnosis:

# Check if AI is actually initialized
tail -f /var/log/x-ui/3xipl.log | grep "AI Service"

# Test with explicit command first
# In Telegram: /status (should work)
# Then: show status (AI should work)

Solution:

1. Verify you're an admin user in bot settings
2. Check API key validity at Google AI Studio
3. Restart bot: systemctl restart x-ui

🔙 Rollback Procedure

If you encounter issues and want to revert:

Complete Rollback

# 1. Stop service
systemctl stop x-ui

# 2. Restore backup
cp /usr/local/x-ui.backup/x-ui /usr/local/x-ui/x-ui

# 3. Restore database (if needed)
cp /etc/x-ui/x-ui.db.backup.* /etc/x-ui/x-ui.db

# 4. Start service
systemctl start x-ui

Disable AI Only (Keep Feature Code)

# Just disable AI, keep everything else
sqlite3 /etc/x-ui/x-ui.db "UPDATE setting SET value = 'false' WHERE key = 'aiEnabled';"
systemctl restart x-ui

📊 Database Schema Changes

The migration adds these new settings:

Key	Type	Default	Description
aiEnabled	boolean	false	Enable/disable AI
aiApiKey	string	""	Gemini API key
aiMaxTokens	int	1024	Max response tokens
aiTemperature	float	0.7	Response creativity

No structural changes to existing tables - backward compatible!

🔐 Security Notes

API Key Storage

• Stored in SQLite database: /etc/x-ui/x-ui.db
• File permissions: 600 (owner read/write only)
• Never logged in plain text
• Not exposed in API responses

Access Control

• Only users in tgBotChatId setting can use AI
• Non-admin messages are ignored
• Rate limited: 20 requests/minute per user

Data Privacy

• Messages sent to Google Gemini API for processing
• No conversation history stored (except 5-min cache)
• Cache cleared on bot restart
• Consider GDPR/data residency requirements

📞 Support

Get Help

• GitHub Issues: 3x-ui/issues
• Telegram Group: 3X-UI Community
• Documentation: AI_INTEGRATION.md

Report Bugs

When reporting issues, include:

# System info
uname -a
/usr/local/x-ui/x-ui -v

# Logs
tail -n 100 /var/log/x-ui/3xipl.log

# Configuration
sqlite3 /etc/x-ui/x-ui.db "SELECT key, CASE WHEN key='aiApiKey' THEN '***REDACTED***' ELSE value END FROM setting WHERE key LIKE 'ai%';"

🎉 Success Indicators

You've successfully migrated when:

• ✅ systemctl status x-ui shows "active (running)"
• ✅ Logs show "AI service initialized - Enabled: true"
• ✅ Traditional commands work: /status, /usage
• ✅ Natural language works: "show server status"
• ✅ Bot responds intelligently with server info

📚 Next Steps

After successful migration:

1. Read AI_QUICKSTART.md for usage examples
2. Explore AI_INTEGRATION.md for advanced features
3. Join community to share feedback
4. Consider contributing improvements!

---

Migration Guide Version: 1.0 Last Updated: February 2, 2026 Status: Production-Ready ✅