Lightweight VPS bilateral traffic monitoring Telegram Bot
Designed for VPS providers like BandwagonHost that bill by inbound + outbound combined traffic
🇬🇧 English | 🇨🇳 中文
| Feature | Description |
|---|---|
| 📊 Daily Report | Auto-push daily digest at your chosen time — yesterday's usage, cycle total, days remaining |
| Real-time alerts at 10%, 20% … 100% usage (checked every 5 minutes) | |
| 🔄 Manual Sync | Sync actual usage from your VPS panel, overriding local statistics |
| 📐 Calibration Factor | Set a multiplier to correct systematic drift between vnStat and your panel |
| 📅 Custom Billing Cycle | Supports any reset day (e.g. the 15th), not limited to calendar months |
| 🕐 Dual Timezone | Separate timezones for push notifications (your local time) and billing cycle (provider's reset time) — system clock untouched |
| 🧹 Auto Cleanup | Only retains current and previous cycle data — database stays lean |
| 🔐 Auth Protection | Responds only to your authorized Chat ID |
| Item | Support |
|---|---|
| OS | CentOS 7/8, Ubuntu 18.04/20.04/22.04, Debian 10/11/12 |
| Arch | x86_64 (AMD64), ARM64 (AArch64) |
| vnStat | Auto-adapts to both 1.x (older systems) and 2.x (newer systems) |
You'll need two things before deploying:
- Telegram Bot Token — Message @BotFather on Telegram, send
/newbot, and follow the prompts. You'll receive a token like123456789:ABCdefGHIjklMNOpqrsTUVwxyz - Your Chat ID — Message @userinfobot on Telegram, it will reply with your numeric ID
SSH into your VPS as root and run:
git clone https://github.com/deusaw/traffic-bot.git
cd traffic-bot
bash install.shThe script will prompt you for Bot Token and Chat ID, then handle everything else:
Install curl/gcc/git → Install Go compiler → Install & configure vnStat → Compile → Register systemd service → Start
To skip interactive prompts, set environment variables beforehand:
export BOT_TOKEN="your_token"
export CHAT_ID="your_chat_id"
bash install.shOnce deployed, send /start to your Bot on Telegram and follow the 5-step setup wizard.
When a new version is available, run one command on your VPS:
bash /opt/traffic-bot/update.shPulls latest code → Recompiles → Restarts service. Fully automatic.
| Command | Description |
|---|---|
/start |
First-time setup wizard (bandwidth → reset day → push time → push timezone → billing timezone) |
/help |
Show all available commands |
/status |
View current billing cycle status with progress bar and days remaining |
/daily |
View daily upload/download breakdown for the current cycle |
/config |
View current settings (bandwidth, reset day, push time, timezones, calibration factor) |
/report |
Trigger an immediate daily report (don't wait for scheduled time) |
/settings |
Re-enter setup wizard to change bandwidth, reset day, push time, or timezones |
| Command | Description |
|---|---|
/sync |
Manually sync panel usage. Enter the actual usage shown on your VPS panel (e.g. 6.81 GB). Bot overwrites local stats and may suggest a calibration factor based on the difference. Reply "yes" to apply |
/sync 6.81 GB |
Same as above, inline shorthand |
/calibrate |
Interactive calibration factor setup, showing current factor and raw vnStat data |
/calibrate 1.25 |
Directly set calibration factor to 1.25 |
/cancel |
Cancel an ongoing /sync or /calibrate interaction |
When do I need
/syncand/calibrate?vnStat and your VPS panel may report different numbers — this is common. For example, your panel shows 100 GB used, but vnStat only reports 80 GB.
- Use
/sync 100 GBto tell the Bot the real value. It will immediately show 100 GB and suggest a factor of 1.25 (= 100 ÷ 80)- Reply "yes" to apply the factor. From then on, vnStat data is automatically multiplied by 1.25 — no more manual syncing needed
The bot uses two separate timezones (neither changes your system clock):
| Timezone | Purpose | Example |
|---|---|---|
| Push Timezone | When you receive daily reports and alerts (your local time) | Asia/Shanghai |
| Billing Timezone | When the billing cycle resets (your VPS provider's time) | America/New_York |
For example, if you're in China using a BandwagonHost DC9 server (US East Coast):
- Push Timezone:
Asia/Shanghai— so10:00means Beijing time 10 AM - Billing Timezone:
America/New_York— traffic resets at midnight Eastern Time
Common timezone values: UTC, Asia/Shanghai, Asia/Tokyo, America/New_York, America/Los_Angeles, Europe/London
Passed via the systemd service file. The install script configures these automatically. To modify manually:
# Edit the service file
nano /etc/systemd/system/traffic-bot.service
# Reload and restart after changes
systemctl daemon-reload
systemctl restart traffic-bot| Variable | Description | Default |
|---|---|---|
BOT_TOKEN |
Telegram Bot Token | Required |
CHAT_ID |
Authorized Telegram Chat ID (only this ID can operate the Bot) | Required |
INTERFACE |
Network interface to monitor | eth0 (auto-detected by install script) |
DB_PATH |
SQLite database file path | /opt/traffic-bot/traffic-bot.db |
# Check service status
systemctl status traffic-bot
# View live logs (Ctrl+C to exit)
journalctl -u traffic-bot -f
# Restart service
systemctl restart traffic-bot
# Stop service
systemctl stop traffic-bot
# Disable auto-start on boot
systemctl disable traffic-bottraffic-bot/
├── main.go # Entry point
├── config.go # Environment variable loading
├── db.go # SQLite database operations
├── vnstat.go # vnStat data collection (auto-adapts 1.x / 2.x)
├── bot.go # Telegram Bot command handling
├── scheduler.go # Scheduled tasks (daily report, alert checks, data cleanup)
├── utils.go # Utilities (formatting, cycle calculation, progress bar)
├── install.sh # One-click deploy script
├── update.sh # One-click update script
├── traffic-bot.service # Systemd service template
├── go.mod # Go module dependencies
└── README.md
MIT