Skip to content

GUIDE.md

Latest commit

 

History

History
115 lines (100 loc) · 7.86 KB

GUIDE.md

File metadata and controls

115 lines (100 loc) · 7.86 KB

EchoWaveBot 使用与部署指南

本指南面向运营/管理员，涵盖环境准备、功能说明、数据位置、部署与排障。假设你已拥有一个 Telegram Bot Token，并能把 Bot 拉进你的群组。

1. 环境与配置

  • Python 3.13（本地调试）或 Docker（推荐生产）。
  • 依赖：见 requirements.txt，主要包括 python-telegram-bot[job-queue]、aiosqlite、httpx、python-dotenv。
  • 必填环境变量（.env）：
    • BOT_TOKEN：BotFather 生成的 token。
    • ADMIN_GROUP_ID：超级管理员 ID，可填个人 user_id（推荐）或一个“管理员群” chat_id。只有它能使用 /report、/revoke、/set_topic。
  • 数据文件（默认值与位置）：
    • SQLite DB：echowave.db（当前代码指向项目根；若按生产部署方案，则在容器内 /app/echowave.db，挂载宿主 /root/echowave.db）。
    • 旧版 JSON 数据：bot_data.json（首次启动会尝试迁移到 DB，迁移后会重命名为 .bak）。
    • 段位默认值：{"0":"🌱茁壮韭菜", "100":"💎钻石双手", "500":"🐋潜水巨鲸", "2000":"📈K线主宰", "5000":"🚀交易战神"}（初始化时写入 groups.rank_config）。

2. 本地运行（非 Docker）

  1. python -m venv .venv && source .venv/bin/activate
  2. pip install -r requirements.txt
  3. 创建 .env，填入 BOT_TOKEN 和 ADMIN_GROUP_ID。
  4. 运行 python main.py。启动后日志显示 “EchoWave Pro Max (SQLite Edition) 已启动…”。

3. 功能总览

  • 公共指令：/shop（积分商城）、/invite（邀请好友）、/my（我的积分）、/top（积分榜）、/fear（恐慌贪婪指数）、/help。
  • 管理员/高级指令：
    • 终极管理员（ADMIN_ID）：/report、/revoke <chat_id>、/set_topic <news|analysis|marketing|signal>、/request_broadcast。
    • 群管理员：/request_broadcast。
    • 私聊管理员工具：/setup（配置群）、/add_product、/products、/use <code>。
  • 互动与积分规则（默认）：
    • 签到口令：恒智牛逼（可在 /setup 修改）。
    • 晒单关键词：盈/吃肉 → kw_profit，损/止损 → kw_loss（默认可在 /setup 设置，积分默认 50/30；示例数据为 20/20）。
    • 每日晒单上限：5 次（-2 表示不限）。
    • 邀请奖励：15 分（通过验证后触发）。

4. 核心流程

4.1 入群验证与邀请

  • 新人进群（非 Bot）会被禁言并收到验证按钮。超时未验证将被封禁后解禁。
  • 通过验证后：
    • 标记为已验证；
    • 若是通过邀请链接（https://t.me/<bot>?start=ref_<referrerId>_<groupId>），邀请人得积分奖励；
    • 发送欢迎语（支持 {name} 占位符）。
  • 邀请链接生成：私聊 /invite → 选择一个你已经有积分记录的群（users 表里有记录即可）→ Bot 返回带 group_id 的 deep link。管理员需确保 Bot 在目标群且有生成邀请链接权限，否则无法附带入群按钮。

4.2 配置面板 /setup（仅私聊、群管理员）

  • 进入后选择要配置的群。面板项目：
    • 开关：欢迎语、验证码、各类型订阅（早报/分析/战绩/信号）、暂停广播。
    • 路由：topic ID 绑定（早报/分析/战绩/信号）。
    • 欢迎语、签到口令、晒单关键词、各积分数值、段位表 JSON、晒单上限。
  • 注意：/setup 是会话式指令。若被卡在会话里影响其他回调，请使用关闭/返回或 /cancel 结束。

4.3 广播与话题绑定

  • 在群内 /request_broadcast 向 ADMIN_ID 申请；终极管理员批准后该群标记为广播群。
  • 终极管理员发消息（常在 ADMIN_ID 对应的聊天/话题）→ Bot弹出类型选择 → 分发到订阅了对应类型的群，支持按话题发送。
  • 回执会尝试用原话题回复，找不到则发到 General。
  • 如果群不存在/被踢，会自动关闭该群的广播标记。

4.4 商城

  • /add_product（私聊，管理员）：选择群→传图（可跳过）→“价格 商品名”→上架。
  • /products（私聊，管理员）：列出商品，点击“下架”。
  • /shop（群内）：列出商品列表，带“购买”按钮。
  • 购买流程：扣积分→生成核销码 ORD-XXXXXX → 私聊买家发送核销信息（若无法私聊则回到群提示）。管理员 /use <code> 核销，校验管理员身份（需在订单所属群有 admin 权限）。

4.5 积分&榜单

  • /my：当前积分（points），历史总分（total_points），段位基于 total_points。
  • /top：按当前积分排序显示前 10。
  • 积分获取：签到、晒单（盈/亏），邀请奖励。

5. 部署（Docker）

5.1 镜像构建

  • 已提供 Dockerfile：基于 python:3.13-slim，设置时区为上海，安装依赖后 CMD ["python", "main.py"]。
  • 推荐新增 .dockerignore（如排除 .env、.venv、本地 DB/WAL/SHM、__pycache__ 等）。

5.2 数据持久化

  • 默认 DB 路径：/app/echowave.db。必须通过 volume 将宿主机文件或目录挂载进容器，避免重建容器丢数据。
  • 现有 GitHub Action 部署脚本（.github/workflows/deploy.yml 示例）挂载方式：
    • -v /root/bot_data.json:/app/bot_data.json
    • -v /root/echowave.db:/app/echowave.db
  • 如果你改成目录挂载（推荐）：把代码里的 DB_FILE 指向 data/echowave.db，运行容器时 -v /root/bot_data:/app/data，WAL/SHM 也会被持久化。

5.3 GitHub Action 示例要点

  • main 分支推送触发，构建并推送镜像到 Docker Hub。
  • SSH 到 VPS，拉取最新镜像，停止旧容器，挂载数据文件后重新运行： 
    docker run -d \
  --name echowave \
  --restart always \
  -v /root/bot_data.json:/app/bot_data.json \
  -v /root/echowave.db:/app/echowave.db \
  --env-file /root/.env \
  jerry113/echowave:latest
  • 确保 /root/.env 存在且含 BOT_TOKEN/ADMIN_GROUP_ID。

6. 常见问题与排障

  • /invite 生成后没有入群按钮：Bot 在目标群没有创建邀请链接权限或不在群。解决：赋予生成链接权限或增加一个“自填邀请链接”字段作为兜底。
  • /invite 选择群后跳到 /setup：旧设计下 setup 会话会截获回调，需要给 setup 的 CallbackQueryHandler 加 pattern 或手动结束会话（本仓库已修复）。
  • /report 无响应：ADMIN_ID 未正确解析（.env 错误/空），或你不是 ADMIN_ID/所在聊天不是 ADMIN_ID。
  • /report 订阅只显示“早,信”：旧版漏掉“析”“战”，已在 handlers/admin.py 修复。
  • 新人验证后仍无法发图/视频：需使用 ChatPermissions 的关键字参数覆盖全部媒体字段（本仓库已修复）。
  • 数据丢失：检查容器启动命令是否正确挂载 DB 文件/目录。
  • 无法推送/拉取镜像：确认网络代理及 Docker Hub 凭证；CI 使用的代理可能导致 127.0.0.1:7890 连接失败。

7. 表结构概览（简述）

  • groups：群配置（订阅开关、topic、欢迎语、积分规则、段位表）。
  • users：群内用户积分、签到/晒单计数、邀请人、验证状态。
  • message_map：管理员消息 ID 与各群回执消息 ID 的映射（用于追踪回复）。
  • pending_req：广播申请队列。
  • admin_topic_mappings：管理员话题 -> 类型绑定。
  • products / orders：商城商品与订单（核销码）。

8. 快速检查清单

  1. .env 填了 BOT_TOKEN、ADMIN_GROUP_ID。
  2. Bot 已加入目标群且是管理员（必要权限：禁言/解禁、发送消息、创建邀请链接（可选）、管理话题（如需话题路由）、读取管理员列表（核销鉴权））。
  3. 部署时挂载了 DB 文件/目录；首次运行后确认 DB 文件大小有增长。
  4. 终极管理员（ADMIN_ID）能在私聊执行 /report；群内管理员能 /setup。
  5. /invite 生成的链接能打开，若无按钮检查 Bot 邀请权限或提供手动链接。