428 lines
10 KiB
Markdown
428 lines
10 KiB
Markdown
# GUKO
|
||
|
||
[](https://github.com/shuijiao1/GUKO/pkgs/container/guko)
|
||
[](LICENSE)
|
||
|
||
**中文** | [English](README.en.md)
|
||
|
||
**轻量 VPS / 服务器管理 Telegram Bot：服务器状态面板、SSH 登录管理、常用测试脚本入口**
|
||
|
||
> 私聊打开 Bot 就能查看服务器列表、状态详情、流量与资源占用；支持在 Telegram 内添加服务器、测试 SSH、运行 IP 质量 / NodeQuality / 流媒体 / NextTrace / GB5 等常用检测。
|
||
> 默认白名单模式，适合自托管。
|
||
|
||
---
|
||
|
||
## 🎯 核心特性
|
||
|
||
- **服务器状态面板**：展示在线数量、CPU / 内存 / 硬盘、流量、实时网速、系统信息等。
|
||
- **Telegram 内添加服务器**：支持单台添加、批量导入、编辑、删除和 SSH 连通性测试。
|
||
- **灵活 SSH 鉴权**：支持默认密钥继承、每台独立密钥、已有密钥路径、上传 / 粘贴私钥、密码登录。
|
||
- **常用测试与协议入口**：支持 IP 质量、NodeQuality、流媒体解锁、NextTrace、GB5、SS-Rust、AnyTLS、VLESS、Snell 等任务。
|
||
- **IP / 域名工具**：支持 IPPure 官方图片与 bgp.tools BGP 路由图。
|
||
- **适合 Docker 部署**：提供 Docker Compose、Makefile 和初始化脚本。
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
先准备：
|
||
|
||
1. 到 [@BotFather](https://t.me/BotFather) 创建 Bot，拿到 `BOT_TOKEN`。
|
||
2. 用 [@userinfobot](https://t.me/userinfobot) 或 [@RawDataBot](https://t.me/RawDataBot) 获取你的 Telegram 数字用户 ID。
|
||
|
||
提供 2 种部署方式，**推荐 Docker Compose**。
|
||
|
||
### 方式一：Docker Compose（推荐，无需 git clone）
|
||
|
||
```bash
|
||
mkdir -p guko/keys guko/media guko/results 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
|
||
# 可选：对接 Kulin/Komari 后，地区识别优先使用面板 GeoIP 结果
|
||
KULIN_BASE_URL=
|
||
KULIN_USERNAME=
|
||
KULIN_PASSWORD=
|
||
KULIN_API_CACHE_TTL=300
|
||
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
|
||
```
|
||
|
||
`docker-compose.yml` 已显式设置 `name: guko`，因此在 Docker / DockUP 等管理面板里会显示为 `guko`，不会因为部署目录不同变成随机目录名。
|
||
|
||
最小配置里只需要先改：
|
||
|
||
```env
|
||
BOT_TOKEN=replace-me
|
||
ALLOWED_USERS=123456789
|
||
ADMIN_USERS=123456789
|
||
```
|
||
|
||
启动后在 Bot 里发送 `/addserver` 添加第一台服务器。
|
||
|
||
|
||
### 方式二：源码构建（开发用）
|
||
|
||
```bash
|
||
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 发送：
|
||
|
||
```text
|
||
/start
|
||
```
|
||
|
||
Bot 会显示 GUKO 总览面板，可以点服务器查看详情。
|
||
|
||
### 添加服务器
|
||
|
||
点击 **➕ 添加服务器**，或者发送：
|
||
|
||
```text
|
||
/addserver
|
||
```
|
||
|
||
#### 单台添加
|
||
|
||
选择 **添加单台**，按提示发送：
|
||
|
||
```text
|
||
名称 IP [端口] [用户]
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
hk-01 203.0.113.10 22 root
|
||
jp-01 203.0.113.20:2222 debian
|
||
```
|
||
|
||
然后 Bot 会询问登录方式，支持密钥路径、上传 / 粘贴私钥、密码或先保存后测试。
|
||
|
||
添加后可用按钮或命令测试：
|
||
|
||
```text
|
||
/testssh hk-01
|
||
/testall
|
||
```
|
||
|
||
服务器详情页也支持 **编辑** 和 **删除**；删除需要二次确认，只会删除本地配置，不会操作远端机器。
|
||
|
||
#### 批量导入
|
||
|
||
选择 **批量导入** 后，Bot 会先问：
|
||
|
||
1. 是否全部使用同一个 SSH 端口，还是每台自己写端口。
|
||
2. 是否全部使用同一把密钥、同一个密码、每台自己写认证，还是先只导入不测试。
|
||
|
||
常用批量格式：
|
||
|
||
```text
|
||
hk-01 203.0.113.10 root
|
||
jp-01 203.0.113.20 debian
|
||
sg-01 203.0.113.30 root
|
||
```
|
||
|
||
如果选择“每台自己写端口”：
|
||
|
||
```text
|
||
hk-01 203.0.113.10 22 root
|
||
jp-01 203.0.113.20 2222 debian
|
||
sg-01 203.0.113.30:53580 root
|
||
```
|
||
|
||
如果选择“每台自己写认证”：
|
||
|
||
```text
|
||
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` 示例：
|
||
|
||
```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_SS` | 否 | `true` | 是否启用 SS-Rust 管理入口 |
|
||
| `ENABLE_ANYTLS` | 否 | `true` | 是否启用 AnyTLS 管理入口 |
|
||
| `ENABLE_VLESS` | 否 | `true` | 是否启用 VLESS 管理入口 |
|
||
| `ENABLE_SNELL` | 否 | `true` | 是否启用 Snell 管理入口 |
|
||
| `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` 提交到仓库。
|
||
|
||
---
|
||
|
||
## 🛠 运维
|
||
|
||
所有持久化数据在安装目录下：
|
||
|
||
```text
|
||
GUKO/
|
||
├── docker-compose.example.yml
|
||
├── .env
|
||
├── servers.json # 私有服务器清单
|
||
├── keys/ # SSH 私钥
|
||
├── media/ # 报告图片 / 输出文件
|
||
└── tmp/ # 临时文件
|
||
```
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
cd <安装目录>
|
||
docker compose ps
|
||
docker compose logs -f
|
||
docker compose restart
|
||
docker compose down
|
||
```
|
||
|
||
升级：
|
||
|
||
```bash
|
||
cd <安装目录>
|
||
git pull
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
|
||
也可以使用 Makefile：
|
||
|
||
```bash
|
||
make up
|
||
make logs
|
||
make restart
|
||
make down
|
||
```
|
||
|
||
---
|
||
|
||
## 🧾 直接写配置文件批量添加
|
||
|
||
推荐在 `defaults.ssh` 里写公共默认值，每台服务器只覆盖不同的部分：
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
兼容旧格式，下面这种仍然可用：
|
||
|
||
```json
|
||
{
|
||
"name": "legacy",
|
||
"host": "203.0.113.40",
|
||
"user": "root",
|
||
"port": 53580,
|
||
"key": "/data/keys/server_key"
|
||
}
|
||
```
|
||
|
||
批量添加后可以测试：
|
||
|
||
```bash
|
||
./guko.py list
|
||
./guko.py run hk-01 'hostname'
|
||
```
|
||
|
||
Bot 内还可以导出脱敏配置：
|
||
|
||
```text
|
||
/exportconfig
|
||
```
|
||
|
||
---
|
||
|
||
## 🧩 可选工具
|
||
|
||
GUKO 支持按需启用 IP 质量、NodeQuality、流媒体、NextTrace、GB5、BGP 图、IPPure 图、SS-Rust、AnyTLS、VLESS、Snell 等功能。相关按钮可以通过环境变量关闭。
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 🧩 源码运行（开发用）
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
语法检查：
|
||
|
||
```bash
|
||
make check
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 隐私说明
|
||
|
||
- 仓库不包含任何 Bot Token、真实用户 ID、服务器密码或私钥。
|
||
- `.env`、`servers.json`、`keys/`、`media/`、`tmp/` 已加入 `.gitignore`，不要提交真实配置。
|
||
- 默认白名单模式，未配置允许用户时会拒绝启动。
|
||
- 使用 IPPure、bgp.tools、NodeQuality、流媒体检测等功能时，会访问对应第三方服务。
|
||
- 删除服务器只会删除 Bot 本地配置，不会删除或重装远端机器。
|
||
|
||
## License
|
||
|
||
MIT
|