{"id":50551674,"url":"https://github.com/shuijiao1/guko","last_synced_at":"2026-06-04T04:00:37.800Z","repository":{"id":357643577,"uuid":"1237901483","full_name":"shuijiao1/GUKO","owner":"shuijiao1","description":"轻量 VPS / 服务器管理 Telegram Bot，支持 SSH 管理、批量导入、质量测试和安全白名单。","archived":false,"fork":false,"pushed_at":"2026-06-01T17:29:19.000Z","size":689,"stargazers_count":23,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T19:25:06.004Z","etag":null,"topics":["docker","nodequality","self-hosted","server-management","ssh","telegram-bot","vps"],"latest_commit_sha":null,"homepage":"https://shuijiao.de/projects/guko/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shuijiao1.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-05-13T16:05:59.000Z","updated_at":"2026-06-01T17:32:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shuijiao1/GUKO","commit_stats":null,"previous_names":["shuijiao1/vpspilot","shuijiao1/guko"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shuijiao1/GUKO","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuijiao1%2FGUKO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuijiao1%2FGUKO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuijiao1%2FGUKO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuijiao1%2FGUKO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shuijiao1","download_url":"https://codeload.github.com/shuijiao1/GUKO/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shuijiao1%2FGUKO/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33888302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["docker","nodequality","self-hosted","server-management","ssh","telegram-bot","vps"],"created_at":"2026-06-04T04:00:37.099Z","updated_at":"2026-06-04T04:00:37.785Z","avatar_url":"https://github.com/shuijiao1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GUKO\n\n[![Docker Image](https://img.shields.io/badge/ghcr.io-guko-blue?logo=docker)](https://github.com/shuijiao1/GUKO/pkgs/container/guko)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n[中文](README.md) | **English**\n\n**A lightweight VPS / server management Telegram Bot: server status dashboard, SSH login management, common diagnostics, and protocol management entries.**\n\n\u003e Open a private chat with the Bot to view server lists, status details, traffic, and resource usage. Add servers, test SSH, and run IP quality, NodeQuality, streaming unlock, NextTrace, GB5, SS-Rust, AnyTLS, VLESS, Snell, and other common checks from Telegram.\n\u003e Whitelist mode is enabled by default, making it suitable for self-hosting.\n\n---\n\n## 🎯 Features\n\n- **Server dashboard**: View online count, CPU / memory / disk usage, traffic, realtime network speed, and system information.\n- **Add servers from Telegram**: Supports single-server add, batch import, edit, delete, and SSH connectivity tests.\n- **Flexible SSH authentication**: Supports inherited default keys, per-server keys, existing key paths, uploaded / pasted private keys, and password login.\n- **Common test shortcuts**: Supports IP quality, NodeQuality, streaming unlock checks, NextTrace, GB5, and more.\n- **IP / domain tools**: Supports IPPure official images and bgp.tools BGP route images.\n- **Safe defaults**: Whitelist mode is required; GUKO focuses on common tests and does not provide a general remote command execution feature.\n- **Docker-friendly deployment**: Includes Docker Compose, Makefile, and initialization script.\n\n---\n\n## 🚀 Quick Start\n\nPrepare first:\n\n1. Create a Bot via [@BotFather](https://t.me/BotFather) and get `BOT_TOKEN`.\n2. Use [@userinfobot](https://t.me/userinfobot) or [@RawDataBot](https://t.me/RawDataBot) to get your numeric Telegram user ID.\n\nTwo deployment methods are available. **Docker Compose is recommended**.\n\n### Method 1: Docker Compose (recommended, no git clone)\n\n```bash\nmkdir -p guko/keys guko/media guko/results guko/tmp\ncd guko\n\ncurl -Lo docker-compose.yml https://github.com/shuijiao1/GUKO/releases/latest/download/docker-compose.example.yml\n\ncat \u003e .env \u003c\u003c'EOF'\nBOT_TOKEN=replace-me\nALLOWED_USERS=123456789\nADMIN_USERS=123456789\nDATA_DIR=/data\nGUKO_INV=/data/servers.json\nMEDIA_DIR=/data/media\nTMP_DIR=/data/tmp\nKEYS_DIR=/data/keys\nGUKO_DEFAULT_USER=root\nGUKO_DEFAULT_PORT=22\nGUKO_DEFAULT_KEY=/data/keys/id_ed25519\nENABLE_BGP=true\nENABLE_IPPURE=true\nENABLE_IPQ=true\nENABLE_NQ=true\nENABLE_GB5=true\nENABLE_STREAM=true\nENABLE_NEXTTRACE=true\nALLOW_INSECURE_STARTUP=false\nEOF\n\ncat \u003e servers.json \u003c\u003c'EOF'\n{\n  \"defaults\": {\n    \"ssh\": {\n      \"user\": \"root\",\n      \"port\": 22,\n      \"key\": \"/data/keys/id_ed25519\"\n    }\n  },\n  \"servers\": []\n}\nEOF\n\nnano .env\ndocker compose pull\ndocker compose up -d\ndocker compose logs -f\n```\n\n`docker-compose.yml` explicitly sets `name: guko`, so Docker / DockUP and other management panels show the project as `guko` instead of deriving a random name from the deployment directory.\n\nOnly these values need to be changed in the minimal config first:\n\n```env\nBOT_TOKEN=replace-me\nALLOWED_USERS=123456789\nADMIN_USERS=123456789\n```\n\nAfter startup, send `/addserver` to the Bot to add your first server.\n\n\n### Method 2: Source build (development)\n\n```bash\ngit clone https://github.com/shuijiao1/GUKO.git\ncd GUKO\ncp .env.example .env\ncp servers.example.json servers.json\nmkdir -p keys media tmp\nnano .env\ndocker build -f telegram-bot/Dockerfile -t guko:local .\ndocker run -d --name guko-bot --restart unless-stopped \\\n  --env-file .env \\\n  -v ./servers.json:/data/servers.json \\\n  -v ./keys:/data/keys \\\n  -v ./media:/data/media \\\n  -v ./tmp:/data/tmp \\\n  guko:local\ndocker logs -f guko-bot\n```\n\n---\n\n## 💬 Usage\n\n### Open dashboard\n\nSend this to the Bot in a private chat:\n\n```text\n/start\n```\n\nThe Bot will show the GUKO dashboard. Tap a server to view details.\n\n### Add servers\n\nTap **➕ Add Server**, or send:\n\n```text\n/addserver\n```\n\n#### Add one server\n\nChoose **Add single server**, then send:\n\n```text\nname IP [port] [user]\n```\n\nExamples:\n\n```text\nhk-01 203.0.113.10 22 root\njp-01 203.0.113.20:2222 debian\n```\n\nThen the Bot will ask for the login method:\n\n- **Use default key / config**: Use `GUKO_DEFAULT_KEY` or `defaults.ssh.key` from `servers.json`.\n- **Use existing key path**: Send a path such as `/data/keys/id_ed25519`.\n- **Upload / paste a new private key**: Send SSH private key text, or upload a private key file. The Bot saves it to `/data/keys/`, sets permission to `600`, and tries an SSH login test.\n- **Use password**: Send SSH password. The Bot saves the config and tries a login test.\n- **Save only, skip test**: Only write the server record. You can add authentication later.\n\nAfter adding, test with buttons or commands:\n\n```text\n/testssh hk-01\n/testall\n```\n\nThe server detail page also supports **Edit** and **Delete**. Delete requires confirmation and only removes local Bot configuration; it does not touch the remote machine.\n\n#### Batch import\n\nChoose **Batch import**. The Bot will ask:\n\n1. Whether all servers use the same SSH port, or each line includes its own port.\n2. Whether all servers use the same key, same password, per-line auth, or import without testing.\n\nCommon batch format:\n\n```text\nhk-01 203.0.113.10 root\njp-01 203.0.113.20 debian\nsg-01 203.0.113.30 root\n```\n\nIf choosing per-line ports:\n\n```text\nhk-01 203.0.113.10 22 root\njp-01 203.0.113.20 2222 debian\nsg-01 203.0.113.30:53580 root\n```\n\nIf choosing per-line auth:\n\n```text\nhk-01 203.0.113.10 22 root key:/data/keys/hk_ed25519\njp-01 203.0.113.20 2222 debian password:your-password\n```\n\n\u003e Passwords / private keys sent through Telegram pass through Telegram cloud. Use a private Bot and restrict `ALLOWED_USERS`.\n\n### Commands\n\n- `/start` — Open GUKO dashboard\n- `/list` — Show server list\n- `/status` — Show overview status\n- `/addserver` — Add / batch import servers\n- `/testssh \u003cname/IP/ID/alias\u003e` — Test SSH for one server\n- `/testall` — Batch test SSH\n- `/exportconfig` — Export sanitized config\n- `/info \u003cname/IP/ID/alias\u003e` — Show single-server details\n- `/health` — Read-only health check\n- `/jobs` — Show background jobs\n- `/ip \u003cIPv4 or domain\u003e` — IPPure / BGP tools\n- `/nexttrace \u003cserver\u003e \u003ctarget\u003e` — Route tracing\n\n---\n\n## ⚙️ Configuration\n\n`.env` example:\n\n```env\nBOT_TOKEN=replace-me\nALLOWED_USERS=123456789\nADMIN_USERS=123456789\nDATA_DIR=/data\nGUKO_INV=/data/servers.json\nMEDIA_DIR=/data/media\nTMP_DIR=/data/tmp\nKEYS_DIR=/data/keys\nGUKO_DEFAULT_USER=root\nGUKO_DEFAULT_PORT=22\nGUKO_DEFAULT_KEY=/data/keys/id_ed25519\nENABLE_BGP=true\nENABLE_IPPURE=true\nENABLE_IPQ=true\nENABLE_NQ=true\nENABLE_GB5=true\nENABLE_STREAM=true\nENABLE_NEXTTRACE=true\nALLOW_INSECURE_STARTUP=false\n```\n\n| Variable | Required | Default | Description |\n|---|---:|---|---|\n| `BOT_TOKEN` | Yes | - | Telegram Bot Token |\n| `ALLOWED_USERS` | Yes | - | Allowed Telegram numeric user IDs, comma-separated |\n| `ADMIN_USERS` | No | `ALLOWED_USERS` | Admin IDs; can add / delete servers and use high-risk features |\n| `DATA_DIR` | No | `/data` | Container data directory |\n| `GUKO_INV` | No | `/data/servers.json` | Server inventory path |\n| `MEDIA_DIR` | No | `/data/media` | Image and report output directory |\n| `TMP_DIR` | No | `/data/tmp` | Temporary directory |\n| `KEYS_DIR` | No | `/data/keys` | SSH private key storage directory |\n| `GUKO_DEFAULT_USER` | No | `root` | Default SSH user |\n| `GUKO_DEFAULT_PORT` | No | `22` | Default SSH port |\n| `GUKO_DEFAULT_KEY` | No | `/data/keys/id_ed25519` | Default SSH private key path |\n| `ENABLE_BGP` | No | `true` | Enable BGP image feature |\n| `ENABLE_IPPURE` | No | `true` | Enable IPPure image feature |\n| `ENABLE_IPQ` | No | `true` | Enable IP quality feature |\n| `ENABLE_NQ` | No | `true` | Enable NodeQuality feature |\n| `ENABLE_GB5` | No | `true` | Enable GB5 feature |\n| `ENABLE_STREAM` | No | `true` | Enable streaming unlock checks |\n| `ENABLE_NEXTTRACE` | No | `true` | Enable NextTrace |\n| `BGP_FETCH` | No | `/data/tools/bgp_fetch.py` | BGP image helper script path |\n| `IPPURE_DOWNLOAD` | No | `/data/tools/download_ippure.js` | IPPure download script path |\n| `ALLOW_INSECURE_STARTUP` | No | `false` | Skip security startup checks for development / migration |\n\n\u003e `BOT_TOKEN` and `ALLOWED_USERS` are required. Do not commit real `.env` files.\n\n---\n\n## 🛠 Operations\n\nPersistent data lives in the installation directory:\n\n```text\nGUKO/\n├── docker-compose.example.yml\n├── .env\n├── servers.json       # private server inventory\n├── keys/              # SSH private keys\n├── media/             # report images / output files\n└── tmp/               # temporary files\n```\n\nCommon commands:\n\n```bash\ncd \u003cinstall-dir\u003e\ndocker compose ps\ndocker compose logs -f\ndocker compose restart\ndocker compose down\n```\n\nUpgrade:\n\n```bash\ncd \u003cinstall-dir\u003e\ngit pull\ndocker compose pull\ndocker compose up -d\n```\n\nOr use Makefile:\n\n```bash\nmake up\nmake logs\nmake restart\nmake down\n```\n\n---\n\n## 🧾 Batch add via config file\n\nIt is recommended to put shared defaults under `defaults.ssh`, and only override differences per server:\n\n```json\n{\n  \"defaults\": {\n    \"ssh\": {\n      \"user\": \"root\",\n      \"port\": 22,\n      \"key\": \"~/.ssh/id_ed25519\"\n    }\n  },\n  \"servers\": [\n    {\n      \"name\": \"hk-01\",\n      \"host\": \"203.0.113.10\"\n    },\n    {\n      \"name\": \"jp-01\",\n      \"host\": \"203.0.113.20\",\n      \"ssh\": {\n        \"user\": \"debian\",\n        \"port\": 2222,\n        \"key\": \"~/.ssh/jp_ed25519\"\n      }\n    },\n    {\n      \"name\": \"sg-password\",\n      \"host\": \"203.0.113.30\",\n      \"ssh\": {\n        \"auth\": \"password\",\n        \"password\": \"change-me\"\n      }\n    }\n  ]\n}\n```\n\nLegacy format is still supported:\n\n```json\n{\n  \"name\": \"legacy\",\n  \"host\": \"203.0.113.40\",\n  \"user\": \"root\",\n  \"port\": 53580,\n  \"key\": \"/data/keys/server_key\"\n}\n```\n\nTest after batch import:\n\n```bash\n./guko.py list\n./guko.py run hk-01 'hostname'\n```\n\nYou can also export sanitized config from the Bot:\n\n```text\n/exportconfig\n```\n\n---\n\n## 🧩 Optional tools\n\nGUKO can enable IP quality, NodeQuality, streaming unlock checks, NextTrace, GB5, BGP images, IPPure images, and other tools as needed. Related buttons can be disabled with environment variables.\n\n---\n\n## 🧩 Source run (development)\n\n```bash\ngit clone https://github.com/shuijiao1/GUKO.git\ncd GUKO\npython3 -m venv .venv\n. .venv/bin/activate\npip install -r telegram-bot/requirements.txt\ncp .env.example .env\ncp servers.example.json servers.json\nnano .env\npython3 telegram-bot/bot.py\n```\n\nSyntax check:\n\n```bash\nmake check\n```\n\n---\n\n## 🔐 Privacy\n\n- The repository does not contain any Bot Token, real user ID, server password, or private key.\n- `.env`, `servers.json`, `keys/`, `media/`, and `tmp/` are ignored by Git. Do not commit real configuration.\n- Whitelist mode is enabled by default. The Bot refuses to start when allowed users are not configured.\n- IPPure, bgp.tools, NodeQuality, streaming checks, and similar features will access corresponding third-party services.\n- Deleting a server only removes local Bot configuration. It does not delete or reinstall the remote machine.\n\n## License\n\nMIT\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuijiao1%2Fguko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshuijiao1%2Fguko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuijiao1%2Fguko/lists"}