GraveEaterMadison/Raspberry_pi_telegram_bot

# 树莓派 Telegram 机器人   [](https://opensource.org/licenses/MIT) 一个多功能的 Telegram 机器人，运行在树莓派上，允许你通过 Telegram 远程控制你的树莓派并与之交互。监控系统健康状况、控制 GPIO 引脚、管理文件、运行 shell 命令、拍摄摄像头快照等等 —— 一切尽在 Telegram 中完成。 ## 目录 ## 功能 - **系统监控** — CPU、内存、磁盘、温度、运行时间和综合健康评分 - **交互式仪表盘** — 带有实时统计的内联键盘控制面板 - **远程 Shell** — 使用黑名单/白名单安全过滤器执行 shell 命令 - **文件管理** — 列出、读取、下载和上传文件 - **GPIO 控制** — 数字开关、PWM 占空比、伺服电机角度、I2C 总线扫描 - **摄像头** — 拍摄快照并运行带自动捕获的运动检测 - **网络工具** — IP 信息、WiFi 扫描、ping、端口扫描、网速测试 - **进程管理器** — 列出顶级进程并根据 PID 终止 - **指标与警报** — 后台指标收集，生成图表和阈值警报 - **AI 助手** — 通过 Anthropic Claude 或 OpenAI GPT 提问 - **任务调度器** — 调度命令每天在设定时间运行；管理 cron 作业 - **软件包管理器** — 搜索、安装和删除 APT 软件包 - **备份** — 创建树莓派目录的 `.tar.gz` 备份并发送至 Telegram - **天气** — 通过 OpenWeatherMap 获取当前天气 - **传感器中心** — 读取 DHT11/DHT22、BMP280 和 PIR 传感器 - **便签** — 基于 SQLite 的用户独立便签 - **授权与速率限制** — 仅白名单中的用户 ID 可使用该机器人 - **审计日志** — 每条命令都记录到 SQLite，包含时间戳和用户信息 ## 要求 - 运行 Raspberry Pi OS（基于 Debian）的树莓派 - Python 3.11+ - 一个 Telegram 账户和来自 [@BotFather](https://t.me/BotFather) 的机器人令牌 ## 安装 ### 1. 克隆仓库 ``` git clone https://github.com/GraveEaterMadison/Raspberry_pi_telegram_bot.git cd Raspberry_pi_telegram_bot ``` ### 2. 创建虚拟环境 ``` python3 -m venv venv source venv/bin/activate ``` ### 3. 安装依赖 ``` pip install -r requirements.txt ``` 对于可选的硬件支持，请先取消注释 `requirements.txt` 中的相关行，然后重新运行上述命令。或手动安装： ``` # GPIO pip install RPi.GPIO # 摄像头（Pi 4 及更新型号） pip install picamera2 # DHT11 / DHT22 传感器 pip install adafruit-circuitpython-dht adafruit-blinka # BMP280 压力/温度传感器 pip install bmp280 smbus2 # I2C 工具（通过 apt，非 pip） sudo apt install i2c-tools python3-smbus # 网络速度测试 pip install speedtest-cli ``` ### 4. 在 Telegram 上创建你的机器人 - 向 [@BotFather](https://t.me/BotFather) 发送消息并运行 `/newbot` - 按照提示操作并复制它提供给你的 API 令牌 ### 5. 设置你的环境文件 ``` cp .env.example .env nano .env ``` 至少设置这两个值： ``` TELEGRAM_BOT_TOKEN=your_token_here AUTHORIZED_USERS=123456789 ``` 要找到你的 Telegram 用户 ID，向 [@userinfobot](https://t.me/userinfobot) 发送消息。 ### 6. 运行机器人 ``` python main.py ``` ## 配置 所有配置均通过 `.env` 文件完成。将 `.env.example` 复制为 `.env` 并填入你的值。 | 变量 | 是否必需 | 默认值 | 描述 | |---|---|---|---| | `TELEGRAM_BOT_TOKEN` | ✅ | — | 来自 @BotFather 的令牌 | | `AUTHORIZED_USERS` | ✅ | — | 逗号分隔的 Telegram 用户 ID，例如 `123456789,987654321` | | `AI_PROVIDER` | 否 | `anthropic` | `anthropic` 或 `openai` | | `ANTHROPIC_API_KEY` | 否 | — | 用于 `/ai` 命令（在 console.anthropic.com 获取） | | `OPENAI_API_KEY` | 否 | — | 用于通过 OpenAI 的 `/ai` 命令 | | `OPENWEATHER_API_KEY` | 否 | — | 用于 `/weather`（在 openweathermap.org 获取免费密钥） | | `CAMERA_BACKEND` | 否 | `picamera2` | `picamera2`、`opencv` 或 `dummy` | | `GPIO_MODE` | 否 | `BCM` | `BCM` 或 `BOARD` | | `DHT_SENSOR_TYPE` | 否 | `DHT22` | `DHT11` 或 `DHT22` | | `DHT_PIN` | 否 | `4` | DHT 传感器的 GPIO 引脚号 | | `BMP280_ADDRESS` | 否 | `0x76` | BMP280 传感器的 I2C 地址 | | `PIR_PIN` | 否 | `17` | PIR 运动传感器的 GPIO 引脚号 | | `BACKUP_PATHS` | 否 | `/home/pi,/etc` | 逗号分隔的要备份的路径 | | `MAX_EXEC_OUTPUT` | 否 | `4000` | shell 命令输出的最大字符数 | | `RATE_LIMIT_PER_MINUTE` | 否 | `20` | 每个用户每分钟的最大命令数 | | `METRICS_HISTORY_SIZE` | 否 | `60` | 内存中保留的指标数据点数 | | `METRICS_INTERVAL` | 否 | `10` | 指标收集之间的秒数 | | `LOG_LEVEL` | 否 | `INFO` | `DEBUG`、`INFO`、`WARNING` 或 `ERROR` | | `DB_PATH` | 否 | `data/bot.db` | SQLite 数据库路径 | | `EXEC_WHITELIST` | 否 | _(空)_ | 逗号分隔的允许的命令。空 = 允许所有 | | `EXEC_BLACKLIST` | 否 | `rm -rf /,mkfs,dd if=/dev/zero` | 始终被阻止的命令模式 | ## 作为服务运行 要使用 systemd 在启动时自动运行机器人： ### 1. 复制服务文件 ``` sudo cp pibot.service /etc/systemd/system/pibot.service ``` ### 2. 需要时编辑路径 ``` sudo nano /etc/systemd/system/pibot.service ``` 确保 `WorkingDirectory`、`ExecStart` 和 `EnvironmentFile` 都指向你实际的安装位置。 ### 3. 启用并启动 ``` sudo systemctl daemon-reload sudo systemctl enable pibot sudo systemctl start pibot ``` ### 4. 检查状态和日志 ``` sudo systemctl status pibot journalctl -u pibot -f ``` ## 命令 ### 系统 | 命令 | 描述 | |---|---| | `/start` | 欢迎消息 | | `/help` | 列出所有命令 | | `/dashboard` | 交互式控制面板 | | `/info` | 完整系统概览 | | `/cpu` | 每个核心的 CPU 使用率和平均负载 | | `/ram` | 内存和交换分区使用情况 | | `/disk` | 每个分区的磁盘使用情况 | | `/uptime` | 系统运行时间 | | `/temperature` | CPU 温度及状态 | | `/healthscore` | 整体树莓派健康评分（0–100） | ### 网络 | 命令 | 描述 | |---|---| | `/ip` | 所有接口的 IP 地址 | | `/netinfo` | 网络接口统计 | | `/ping ` | ping 一台主机 | | `/wifi` | 扫描附近的 WiFi 网络 | | `/speedtest` | 网速测试 | | `/portscan [range]` | 扫描主机上的开放端口 | ### 电源与服务 | 命令 | 描述 | |---|---| | `/reboot` | 重启树莓派（要求确认） | | `/shutdown` | 关闭树莓派（要求确认） | | `/service ` | `start`、`stop`、`restart`、`status`、`enable`、`disable` 一个服务 | | `/services` | 列出所有运行中的 systemd 服务 | ### 远程执行 | 命令 | 描述 | |---|---| | `/exec ` | 运行 shell 命令 | | `/ps` | 按 CPU 使用率排序的前 20 个进程 | | `/kill ` | 向进程发送 SIGTERM 信号 | ### 文件 | 命令 | 描述 | |---|---| | `/ls [path]` | 列出目录（默认：`/home/pi`） | | `/cat ` | 读取文件内容 | | `/download ` | 将文件发送到 Telegram | | _(发送一个文件)_ | 将文件上传到树莓派的 `/tmp/telegram_uploads/` | ### GPIO 与硬件 | 命令 | 描述 | |---|---| | `/gpio ` | 将 GPIO 引脚设置为高电平或低电平 | | `/pwm <0-100>` | 设置引脚的 PWM 占空比 | | `/servo <0-180>` | 将伺服移动到指定角度 | | `/i2c` | 扫描 I2C 总线上连接的设备 | | `/sensors` | 读取 DHT、BMP280 和 CPU 温度传感器 | ### 摄像头 | 命令 | 描述 | |---|---| | `/snapshot` | 拍照并发送 | | `/motion ` | 切换带自动快照的运动检测 | ### 监控 | 命令 | 描述 | |---|---| | `/graph ` | 绘制指标历史图表 | | `/alert set ` | 设置资源警报，例如 `/alert set cpu > 85` | | `/alert list` | 列出你的活动警报 | | `/alert clear` | 清除你所有的警报 | | `/metrics` | 最近 10 次指标读数的表格 | ### AI（人工智能） | 命令 | 描述 | |---|---| | `/ai ` | 向 AI 助手提问任何问题 | ### 调度器 | 命令 | 描述 | |---|---| | `/schedule ` | 调度一个命令每天在指定时间运行 | | `/cron list` | 列出已调度的任务 | | `/cron del ` | 删除一个已调度的任务 | ### 便签 | 命令 | 描述 | |---|---| | `/note add ` | 保存一条便签 | | `/note list` | 列出你的便签 | | `/note del ` | 删除一条便签 | ### 软件包 | 命令 | 描述 | |---|---| | `/pkg search ` | 搜索 APT 软件包 | | `/pkg install ` | 安装一个软件包 | | `/pkg remove ` | 删除一个软件包 | | `/pkg update` | 运行 `apt update` | ### 杂项 | 命令 | 描述 | |---|---| | `/backup [paths...]` | 创建一个 `.tar.gz` 备份并发送 | | `/weather [city]` | 当前天气（如果省略城市，则根据 IP 自动检测） | ## 文件结构 ``` Raspberry_pi_telegram_bot/ │ ├── main.py # Entry point — registers all handlers ├── config.py # Loads all settings from .env ├── requirements.txt # Python dependencies ├── pibot.service # systemd service file ├── .env.example # Environment variable template ├── .env # Your local config (never commit this) │ ├── handlers/ │ ├── core.py # /start, /help, /dashboard │ ├── system.py # /info, /cpu, /ram, /disk, /uptime, /temperature, /healthscore │ ├── network.py # /ip, /netinfo, /ping, /wifi, /speedtest, /portscan │ ├── power.py # /reboot, /shutdown, /service, /services │ ├── exec_handler.py # /exec │ ├── files.py # /ls, /cat, /download, upload handler │ ├── gpio_handler.py # /gpio, /pwm, /servo, /i2c │ ├── camera.py # /snapshot, /motion │ ├── monitoring.py # /graph, /alert, /metrics │ ├── ai_handler.py # /ai │ ├── scheduler.py # /schedule, /cron, background scheduler loop │ ├── notes.py # /note │ ├── packages.py # /pkg │ ├── backup.py # /backup │ ├── weather.py # /weather │ ├── sensors.py # /sensors │ ├── process.py # /ps, /kill │ └── callbacks.py # Inline keyboard callback router │ ├── utils/ │ ├── auth.py # Authorization middleware and rate limiter │ ├── logger.py # SQLite audit logger │ ├── metrics.py # Background metrics collector │ └── pi_info.py # Legacy system utility functions │ └── data/ # Created at runtime ├── bot.db # SQLite database (audit log, notes, scheduler) └── bot.log # Log file ``` ## 安全性 - **授权** — `.env` 中的 `AUTHORIZED_USERS` 是 Telegram 用户 ID 的白名单。任何不在名单上的人都会收到“访问被拒绝”的消息。 - **速率限制** — 每个授权用户每分钟限制 `RATE_LIMIT_PER_MINUTE` 条命令（默认 20）。 - **执行安全** — `/exec` 根据 `EXEC_BLACKLIST` 检查每个命令。你还可以设置 `EXEC_WHITELIST` 仅允许特定命令。 - **文件访问** — `/ls`、`/cat`、`/download` 仅允许访问 `/home`、`/var/log`、`/etc`、`/tmp` 和 `/opt` 下的内容。 - **密钥** — 请保密你的 `.env` 文件。它默认被 gitignore，绝不应提交。 - **重启 / 关机** — 这两个命令在执行前都需要一个内联确认按钮。 ## 贡献 欢迎贡献！请 fork 本仓库，并提交包含你改进或错误修复的 pull request。 ## 许可证 本项目根据 MIT 许可证授权 —— 详见 [LICENSE](LICENSE) 文件。 由 [GraveEaterMadison](https://github.com/GraveEaterMadison) 使用 ❤️ 开发

标签：AI助手, DIY项目, GPIO控制, I2C通信, MIT许可, Python, SQLite, Telegram Bot, 仪表盘, 任务调度, 传感器集成, 包管理, 多引擎聚合, 安全认证, 家庭自动化, 开源, 摄像头控制, 数字取证, 数据备份, 文件管理, 无后门, 智能设备, 物联网, 监控系统, 硬件控制, 科技爱好者, 网络工具, 自动化脚本, 软件开发, 远程控制, 远程访问, 逆向工具