{"id":46789427,"url":"https://github.com/kereal/rs8kvn_bot","last_synced_at":"2026-05-25T09:10:20.151Z","repository":{"id":343004715,"uuid":"1175449207","full_name":"kereal/rs8kvn_bot","owner":"kereal","description":"telegram bot + 3x-ui panel = vpn subscription link","archived":false,"fork":false,"pushed_at":"2026-05-16T05:00:15.000Z","size":28585,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T06:43:59.763Z","etag":null,"topics":["3x-ui","bot","telegrambot","vless","vless-reality-vision","vpn-service"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kereal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-07T18:17:38.000Z","updated_at":"2026-05-03T09:13:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kereal/rs8kvn_bot","commit_stats":null,"previous_names":["kereal/rs8kvn_bot"],"tags_count":65,"template":false,"template_full_name":null,"purl":"pkg:github/kereal/rs8kvn_bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kereal%2Frs8kvn_bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kereal%2Frs8kvn_bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kereal%2Frs8kvn_bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kereal%2Frs8kvn_bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kereal","download_url":"https://codeload.github.com/kereal/rs8kvn_bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kereal%2Frs8kvn_bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33109461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3x-ui","bot","telegrambot","vless","vless-reality-vision","vpn-service"],"created_at":"2026-03-10T02:29:14.641Z","updated_at":"2026-05-16T16:01:45.174Z","avatar_url":"https://github.com/kereal.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rs8kvn_bot - Telegram Bot for 3x-ui VLESS Subscription Distribution\n\n[![GitHub release](https://img.shields.io/github/v/release/kereal/rs8kvn_bot?logo=github)](https://github.com/kereal/rs8kvn_bot/releases)\n[![Coverage](https://img.shields.io/badge/coverage-85%25%2B-green)](https://github.com/kereal/rs8kvn_bot/actions)\n[![Go](https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go)](https://go.dev/)\n[![Go Report Card](https://goreportcard.com/badge/github.com/kereal/rs8kvn_bot)](https://goreportcard.com/report/github.com/kereal/rs8kvn_bot)\n[![License](https://img.shields.io/github/license/kereal/rs8kvn_bot)](LICENSE)\n\nTelegram bot for distributing VLESS+Reality+Vision proxy subscriptions from 3x-ui panel.\n\n## Features\n\n- 📥 Get subscription on demand with QR code import\n- 🔗 Invite/trial landing page (`/i/{code}`) with one-click Happ setup\n- 👥 Referral system — users generate invite codes with in-memory cache + periodic sync\n- 📊 Configurable traffic limit (default 30GB/month)\n- 🔄 Monthly auto-renewal (last day of month, no expiry)\n- 🔔 Admin notifications on new subscriptions\n- 🛡️ Rate limiting, circuit breaker for 3x-ui, auto-relogin on session expiry\n- 🏥 Health check endpoints (/healthz, /readyz)\n- 🔗 Subscription proxy endpoint (`/sub/{subID}`) with extra servers and headers\n- 🗄️ Daily database backups with rotation, embedded migrations\n- 🐛 Sentry error tracking\n- 🐳 Docker support with health checks\n- 🧪 Unit + E2E tests (~85% coverage, race-safe, fuzzing)\n\n## Quick Start\n\n```bash\ndocker pull ghcr.io/kereal/rs8kvn_bot:latest\n\ndocker run -d \\\n  --name rs8kvn_bot \\\n  --restart unless-stopped \\\n  -v $(pwd)/.env:/app/.env:ro \\\n  -v $(pwd)/data:/app/data \\\n  -p 127.0.0.1:8880:8880 \\\n  ghcr.io/kereal/rs8kvn_bot:latest\n```\n\nSee **[Installation Guide](doc/installation.md)** for:\n- All 4 installation methods (Docker, Docker Compose, Build from Source, Air hot reload)\n- Full configuration table (all env vars)\n- 3x-ui panel setup instructions\n- Database migrations and backups\n\n## Usage\n\n1. Start the bot with `/start`\n2. Use the inline buttons:\n   - **For users with subscription:**\n     - **📋 Подписка** — View subscription info (traffic usage, subscription link)\n       - **📱 QR-код** — Generate QR code for Happ app import\n       - **🏠 В начало** — Return to main menu\n     - **☕ Донат** — View donation info\n     - **❓ Помощь** — View VPN setup instructions\n   - **For users without subscription:**\n     - **📥 Получить подписку** — Create a new subscription\n3. Admin users also see **📊 Стат** — View bot statistics\n\n\u003e All menu buttons are inline (shown under the message). Each submenu has a \"🏠 В начало\" button to return.\n\n## Admin Commands\n\n| Command | Description |\n|---------|-------------|\n| `/lastreg` | Show the last 10 registered users |\n| `/del \u003cid\u003e` | Delete a subscription by database ID |\n| `/broadcast \u003cmessage\u003e` | Send a message to all users who have a subscription |\n| `/send \u003cid or @username\u003e \u003cmessage\u003e` | Send a message to a specific user |\n| `/refstats` | Show referral statistics (count per user from cache) |\n\n**Examples:**\n\n```\n/del 5                                    # Delete subscription with DB ID 5\n/broadcast 🔔 Важное обновление!          # Broadcast to all subscribers\n/send 123456789 Привет!                   # Private message by Telegram ID\n/send @username Привет!                   # Private message by username\n```\n\n## Health Check \u0026 Web Endpoints\n\nThe bot exposes HTTP endpoints on port 8880:\n\n| Endpoint | Description | Status Codes |\n|----------|-------------|--------------|\n| `GET /healthz` | Basic health (process alive, DB and xui status) | 200/503 |\n| `GET /readyz` | Ready state (accepting requests after init) | 200/503 |\n| `GET /i/{code}` | Trial invites landing page | 200/404/429/500 |\n| `GET /sub/{subID}` | Subscription proxy (extra servers + headers, status checked) | 200/404/502/405 |\n| `GET /static/logo.png` | Logo image (mobile-optimized PNG) | 200/404 |\n\n### Invite/Trial Landing Page (`/i/{code}`)\n\nEach user can generate an invite code via the referral flow. The landing page validates the code, applies IP-based rate limiting (429 if exceeded), creates a trial subscription in 3x-ui, and renders a mobile-friendly page with:\n- Happ app download links (Android / iOS)\n- One-click \"Добавить в Happ\" button (`happ://add/` deep-link)\n- Copy-to-clipboard subscription URL\n- Telegram activation link\n\n### Subscription Proxy (`/sub/{subID}`)\n\nServes subscriptions with optional extra servers and custom headers. Validates `subID`, checks cache (240s TTL), fetches from 3x-ui, merges extra servers/headers from config file, returns combined response. Stale cache is used as fallback if 3x-ui is unavailable.\n\n## Traffic and Expiry\n\n- **Traffic**: Configurable via `TRAFFIC_LIMIT_GB` (default: 30GB)\n- **Auto-reset**: Every 30 days from creation date — 3x-ui resets traffic to 0 and extends `ExpiryTime` by 30 days automatically when `ExpiryTime \u003e 0`\n- **Source**: [3x-ui inbound.go - autoRenewClients()](https://github.com/mhsanaei/3x-ui/blob/main/web/service/inbound.go#L888-L912)\n\n## Development\n\n### Test \u0026 Lint\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run with coverage\ngo test -coverprofile=coverage.out ./...\ngo tool cover -func=coverage.out\n\n# Run specific package\ngo test ./internal/database/... -v\n\n# Lint\ngolangci-lint run ./...\ngosec ./...\n```\n\nTest suite: ~85% coverage, 66 E2E tests, race-safe, fuzzing, table-driven tests, integration tests with mock HTTP server.\n\n### Build\n\n```bash\ngo build -ldflags=\"-s -w\" -o rs8kvn_bot ./cmd/bot\n```\n\n### Project Documentation\n\n- **[Installation \u0026 Configuration](doc/installation.md)** — All setup methods, env vars, and 3x-ui instructions\n- **[Handover](doc/handover.md)** — Architecture, stack, current state, nuances\n- **[.serena/instructions.md](.serena/instructions.md)** — AI assistant workflow and memory structure\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkereal%2Frs8kvn_bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkereal%2Frs8kvn_bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkereal%2Frs8kvn_bot/lists"}