shuijiao1/GUKO: **中文** | [English](https://github.com/shuijiao1/GUKO/b

轻量 VPS / 服务器管理 Telegram Bot：服务器状态面板、SSH 登录管理、常用测试脚本入口

私聊打开 Bot 就能查看服务器列表、状态详情、流量与资源占用；支持在 Telegram 内添加服务器、测试 SSH、运行 IP 质量 / NodeQuality / 流媒体 / NextTrace / GB5 等常用检测。默认白名单模式，适合自托管。

🎯 核心特性

服务器状态面板：展示在线数量、CPU / 内存 / 硬盘、流量、实时网速、系统信息等。
Telegram 内添加服务器：支持单台添加、批量导入、编辑、删除和 SSH 连通性测试。
灵活 SSH 鉴权：支持默认密钥继承、每台独立密钥、已有密钥路径、上传 / 粘贴私钥、密码登录。
常用测试入口：支持 IP 质量、NodeQuality、流媒体解锁、NextTrace、GB5 等任务。
IP / 域名工具：支持 IPPure 官方图片与 bgp.tools BGP 路由图。
适合 Docker 部署：提供 Docker Compose、Makefile 和初始化脚本。

🚀 快速开始

先准备：

到 @BotFather 创建 Bot，拿到 BOT_TOKEN。
用 @userinfobot 或 @RawDataBot 获取你的 Telegram 数字用户 ID。

提供 2 种部署方式，推荐 Docker Compose。

方式一：Docker Compose（推荐，无需 git clone）

mkdir -p guko/keys guko/media guko/tmp
cd guko

curl -Lo docker-compose.yml https://github.com/shuijiao1/GUKO/releases/latest/download/docker-compose.example.yml

cat > .env <<'EOF'
BOT_TOKEN=replace-me
ALLOWED_USERS=123456789
ADMIN_USERS=123456789
DATA_DIR=/data
GUKO_INV=/data/servers.json
MEDIA_DIR=/data/media
TMP_DIR=/data/tmp
KEYS_DIR=/data/keys
GUKO_DEFAULT_USER=root
GUKO_DEFAULT_PORT=22
GUKO_DEFAULT_KEY=/data/keys/id_ed25519
ENABLE_BGP=true
ENABLE_IPPURE=true
ENABLE_IPQ=true
ENABLE_NQ=true
ENABLE_GB5=true
ENABLE_STREAM=true
ENABLE_NEXTTRACE=true
ALLOW_INSECURE_STARTUP=false
EOF

cat > servers.json <<'EOF'
{
  "defaults": {
    "ssh": {
      "user": "root",
      "port": 22,
      "key": "/data/keys/id_ed25519"
    }
  },
  "servers": []
}
EOF

nano .env
docker compose pull
docker compose up -d
docker compose logs -f

最小配置里只需要先改：

BOT_TOKEN=replace-me
ALLOWED_USERS=123456789
ADMIN_USERS=123456789

启动后在 Bot 里发送 /addserver 添加第一台服务器。

方式二：源码构建（开发用）

git clone https://github.com/shuijiao1/GUKO.git
cd GUKO
cp .env.example .env
cp servers.example.json servers.json
mkdir -p keys media tmp
nano .env
docker build -f telegram-bot/Dockerfile -t guko:local .
docker run -d --name guko-bot --restart unless-stopped \
  --env-file .env \
  -v ./servers.json:/data/servers.json \
  -v ./keys:/data/keys \
  -v ./media:/data/media \
  -v ./tmp:/data/tmp \
  guko:local
docker logs -f guko-bot

💬 使用方式

打开面板

私聊 Bot 发送：

/start

Bot 会显示 GUKO 总览面板，可以点服务器查看详情。

添加服务器

点击 ➕ 添加服务器，或者发送：

/addserver

单台添加

选择 添加单台，按提示发送：

名称 IP [端口] [用户]

示例：

hk-01 203.0.113.10 22 root
jp-01 203.0.113.20:2222 debian

然后 Bot 会询问登录方式：

沿用默认密钥/配置：使用 GUKO_DEFAULT_KEY 或 servers.json 里的 defaults.ssh.key。
使用已有密钥路径：发送 /data/keys/id_ed25519 这类路径。
上传/粘贴新私钥：发送 SSH 私钥文本，或直接上传私钥文件；Bot 会保存到 /data/keys/，权限设为 600，并尝试 SSH 登录测试。
使用密码：发送 SSH 密码；Bot 会保存配置并尝试登录测试。
先只保存，不测试登录：只写入服务器清单，后续再补认证。

添加后可用按钮或命令测试：

/testssh hk-01
/testall

服务器详情页也支持编辑和删除；删除需要二次确认，只会删除本地配置，不会操作远端机器。

批量导入

选择 批量导入 后，Bot 会先问：

是否全部使用同一个 SSH 端口，还是每台自己写端口。
是否全部使用同一把密钥、同一个密码、每台自己写认证，还是先只导入不测试。

常用批量格式：

hk-01 203.0.113.10 root
jp-01 203.0.113.20 debian
sg-01 203.0.113.30 root

如果选择“每台自己写端口”：

hk-01 203.0.113.10 22 root
jp-01 203.0.113.20 2222 debian
sg-01 203.0.113.30:53580 root

如果选择“每台自己写认证”：

hk-01 203.0.113.10 22 root key:/data/keys/hk_ed25519
jp-01 203.0.113.20 2222 debian password:your-password

Telegram 里发送密码 / 私钥会经过 Telegram 云端。建议使用私有 Bot，并限制 ALLOWED_USERS。

命令

/start — 打开 GUKO 面板
/list — 查看服务器列表
/status — 查看总览状态
/addserver — 添加 / 批量导入服务器
/testssh <名字/IP/ID/别名> — 测试单台服务器 SSH
/testall — 批量测试 SSH
/exportconfig — 导出脱敏配置
/info <名字/IP/ID/别名> — 查看单台详情
/health — 只读巡检
/jobs — 查看后台任务
/ip <IPv4 或域名> — IPPure / BGP 工具
/nexttrace <服务器> <目标> — 路由追踪

⚙️ 配置说明

.env 示例：

BOT_TOKEN=replace-me
ALLOWED_USERS=123456789
ADMIN_USERS=123456789
DATA_DIR=/data
GUKO_INV=/data/servers.json
MEDIA_DIR=/data/media
TMP_DIR=/data/tmp
KEYS_DIR=/data/keys
GUKO_DEFAULT_USER=root
GUKO_DEFAULT_PORT=22
GUKO_DEFAULT_KEY=/data/keys/id_ed25519
ENABLE_BGP=true
ENABLE_IPPURE=true
ENABLE_IPQ=true
ENABLE_NQ=true
ENABLE_GB5=true
ENABLE_STREAM=true
ENABLE_NEXTTRACE=true
ALLOW_INSECURE_STARTUP=false

变量	是否必填	默认值	说明
`BOT_TOKEN`	是	-	Telegram Bot Token
`ALLOWED_USERS`	是	-	允许使用 Bot 的 Telegram 数字 ID，多个用英文逗号分隔
`ADMIN_USERS`	否	`ALLOWED_USERS`	管理员 ID，能添加 / 删除服务器、执行高危功能
`DATA_DIR`	否	`/data`	容器内数据目录
`GUKO_INV`	否	`/data/servers.json`	服务器清单路径
`MEDIA_DIR`	否	`/data/media`	图片和报告输出目录
`TMP_DIR`	否	`/data/tmp`	临时文件目录
`KEYS_DIR`	否	`/data/keys`	SSH 私钥保存目录
`GUKO_DEFAULT_USER`	否	`root`	��认 SSH 用户
`GUKO_DEFAULT_PORT`	否	`22`	默认 SSH 端口
`GUKO_DEFAULT_KEY`	否	`/data/keys/id_ed25519`	默认 SSH 私钥路径
`ENABLE_BGP`	否	`true`	是否启用 BGP 图功能
`ENABLE_IPPURE`	否	`true`	是否启用 IPPure 图功能
`ENABLE_IPQ`	否	`true`	是否启用 IP 质量功能
`ENABLE_NQ`	否	`true`	是否启用 NodeQuality 功能
`ENABLE_GB5`	否	`true`	是否启用 GB5 功能
`ENABLE_STREAM`	否	`true`	是否启用流媒体检测
`ENABLE_NEXTTRACE`	否	`true`	是否启用 NextTrace
`BGP_FETCH`	否	`/data/tools/bgp_fetch.py`	BGP 图片工具脚本路径
`IPPURE_DOWNLOAD`	否	`/data/tools/download_ippure.js`	IPPure 下载脚本路径
`ALLOW_INSECURE_STARTUP`	否	`false`	开发 / 迁移时跳过安全启动检查

BOT_TOKEN 和 ALLOWED_USERS 必须填写；不要把真实 .env 提交到仓库。

🛠 运维

所有持久化数据在安装目录下：

GUKO/
├── docker-compose.example.yml
├── .env
├── servers.json       # 私有服务器清单
├── keys/              # SSH 私钥
├── media/             # 报告图片 / 输出文件
└── tmp/               # 临时文件

常用命令：

cd <安装目录>
docker compose ps
docker compose logs -f
docker compose restart
docker compose down

升级：

cd <安装目录>
git pull
docker compose pull
docker compose up -d

也可以使用 Makefile：

make up
make logs
make restart
make down

🧾 直接写配置文件批量添加

推荐在 defaults.ssh 里写公共默认值，每台服务器只覆盖不同的部分：

{
  "defaults": {
    "ssh": {
      "user": "root",
      "port": 22,
      "key": "~/.ssh/id_ed25519"
    }
  },
  "servers": [
    {
      "name": "hk-01",
      "host": "203.0.113.10"
    },
    {
      "name": "jp-01",
      "host": "203.0.113.20",
      "ssh": {
        "user": "debian",
        "port": 2222,
        "key": "~/.ssh/jp_ed25519"
      }
    },
    {
      "name": "sg-password",
      "host": "203.0.113.30",
      "ssh": {
        "auth": "password",
        "password": "change-me"
      }
    }
  ]
}

兼容旧格式，下面这种仍然可用：

{
  "name": "legacy",
  "host": "203.0.113.40",
  "user": "root",
  "port": 53580,
  "key": "/data/keys/server_key"
}

批量添加后可以测试：

./guko.py list
./guko.py run hk-01 'hostname'

Bot 内还可以导出脱敏配置：

/exportconfig

🧩 可选工具自动准备

IP 质量 / NodeQuality / 流媒体 / NextTrace / GB5 都是在目标服务器通过 SSH 执行对应��开脚本；首次运行会按脚本自身逻辑安装或下载依赖。
BGP 图和 IPPure 图是在 Bot 容器本地生成；默认 Dockerfile 已包含 Node.js、Playwright、Chromium 和渲染依赖。
如果 BGP_FETCH 或 IPPURE_DOWNLOAD 指向的脚本不存在，Bot 会尝试自动下载工具脚本；失败时会给出明确错误。
可以通过环境变量关闭某些按钮：ENABLE_BGP=false、ENABLE_IPPURE=false、ENABLE_IPQ=false、ENABLE_NQ=false、ENABLE_GB5=false、ENABLE_STREAM=false、ENABLE_NEXTTRACE=false。

⚙️ 版本与发布

当前版本：v0.1.4
更新记录见 CHANGELOG.md
Docker 镜像会发布 latest、v0.1.4 和 commit sha 标签
GitHub Release 会根据 CHANGELOG.md 自动生成说明
维护者发布新版本可使用：

./release.sh <version> "更新说明"

🧩 源码运行（开发用）

git clone https://github.com/shuijiao1/GUKO.git
cd GUKO
python3 -m venv .venv
. .venv/bin/activate
pip install -r telegram-bot/requirements.txt
cp .env.example .env
cp servers.example.json servers.json
nano .env
python3 telegram-bot/bot.py

语法检查：

make check

🔐 隐私说明

仓库不包含任何 Bot Token、真实用户 ID、服务器密码或私钥。
.env、servers.json、keys/、media/��tmp/ 已加入 .gitignore，不要提交真实配置。
默认白名单模式，未配置允许用户时会拒绝启动。
使用 IPPure、bgp.tools、NodeQuality、流媒体检测等功能时，会访问对应第三方服务。
删除服务器只会删除 Bot 本地配置，不会删除或重装远端机器。

shuijiao1/GUKO: 中文 | [English](https://github.com/shuijiao1/GUKO/blob/main/README.en.md)

🎯 核心特性

🚀 快速开始

方式一：Docker Compose（推荐，无需 git clone）

方式二：源码构建（开发用）

💬 使用方式

打开面板

添加服务器

单台添加

批量导入

命令

⚙️ 配置说明

🛠 运维

🧾 直接写配置文件批量添加

🧩 可选工具自动准备

⚙️ 版本与发布

🧩 源码运行（开发用）

🔐 隐私说明

Comments

🎯 核心特性

🚀 快速开始

方式一：Docker Compose（推荐，无需 git clone）

方式二：源码构建（开发用）

💬 使用方式

打开面板

添加服务器

单台添加

批量导入

命令

⚙️ 配置说明

🛠 运维

🧾 直接写配置文件批量添加

🧩 可选工具自动准备

⚙️ 版本与发布

🧩 源码运行（开发用）

🔐 隐私说明

Comments

Related Posts

GongyiChuren/tg-watchbot: <h1>tg-watchbot</h1>

blcktuzinLab/ton-sniper-bot: local, non-custodial **classic sniper**: poll until **STON.fi** or

vzzoxo/xiaoyizi: > 一个为个人和小团队打造的多协议代理管理面板。

marketpulseLab/solana-rug-checker-bot: **Catch the red flags while you live your life.** This l

blcktuzinLab/ton-sniper-bot: local, non-custodial classic sniper: poll until STON.fi or

marketpulseLab/solana-rug-checker-bot: Catch the red flags while you live your life. This l