一个功能完整的 Telegram 骰子竞技群聊 Bot，支持多种对局模式、积分红包、排行榜、节日彩蛋等，基于 aiogram 3 + Redis + Docker 构建。
| 模式 | 发起方式 | 说明 |
|---|---|---|
| 普通双人局 | 大100 3 |
等待任意 1 人接单，立刻开局 |
| 指定单挑局 | 回复对手消息发 大100 3 |
只有被回复者能接，1 分钟超时退款；对方已在对局中则无法发起 |
| 多人拼车局 | 大100 3 多 |
2-5 人皆可，有人进就触发 15 秒倒计时 |
| 定员死等局 | 大100 3 多 4 |
死等凑齐指定人数才发车 |
- 支持 1-5 颗骰子，填 0 积分即为友谊赛
- 发车/等人面板实时显示玩法大小、押注金额、骰子数
- 平局自动触发加赛直至分出胜负
- 落跑机制：投掷超时自动判负
- 乐善好施：连赢 3 局（有积分加）→ 按最近 3 局平均下注的 20% 四舍五入取整 自动扣分，重置后继续循环计算
- 同舟共济：连败 3 局（有积分扣）→ 按最近 3 局平均下注的 20% 四舍五入取整 自动补贴，重置后继续循环计算
- 平局（±0）重置连胜/连败计数；胜败以实际盈亏符号判定，与名次无关
- 连胜/连败奖惩公告为常驻消息，不自动删除
- 比大出 0 点 / 比小出 9 点：太惨了！系统补偿该局下注的 20% 四舍五入取整 仅当该玩家本局未盈利时生效（本局已赢则不再叠加补偿）
- 比大出 9 点 / 比小出 0 点：太幸运了！回馈社会该局下注的 20% 四舍五入取整 仅当该玩家本局未亏损时生效（本局已输则不再叠加扣分）
- 极端点数奖惩公告为常驻消息，不自动删除
回复某人的消息发送 /dice_attack 向其发起攻击挑战：
- 发起方立即扣 1000 积分，双方可在 1 分钟内反复追加（每次 +1000）
- 加大力度（仅发起方）/ 回手反击（仅迎战方）
- 投入越多赢面越大（加权随机），但不保证必赢
- 每人最高可投入 20000 积分
- 1 分钟后自动结算：赢家取回本金 + 缴获对方 90% 投入（10% 销毁防止刷积分）
- 对方未回应：全额退回发起方，@提醒发起方
- 同一时间每人只能发起 1 个 Attack；同一目标同时只能被 1 个 Attack 挑战
- 每日签到：随机 100-1000 积分，连续 5 天额外 +20000
- 赠送积分：
/dice_gift 金额回复指定玩家转账 - 拼手气红包：
/dice_redpack 总额 个数，随机金额，按钮秒抢 - 口令红包：
/dice_redpack_pw 总额 个数 口令，发出口令才能领 - 骰子口令红包：口令设为
🎲，参与骰子局时自动触发
/dice_rank/dice_rank_week/dice_rank_month：今日 / 本周 / 本月榜- 支持切换「胜负榜（总赢/总亏 + 胜率 TOP 5 + 胜率 LAST 5）」和「净胜负榜（净赢家 TOP5 + 净亏损 TOP5）」
- 每日 00:01 自动播报昨日战况，上榜玩家各奖励 +500 积分
- 每小时自动备份积分数据到 SQLite（
backup.db） - 每天 12:00 检测节假日（元旦、春节、端午、七夕、中秋……20+ 节日），触发全员积分彩蛋并置顶公告至 17:00
- 每周一 10:00 自动向所有活跃群发送帮助指南并置顶
- 管理员强杀异常对局：
/dice_forced_stop额外包含残留对局锁回收，避免玩家被误判“在对局中” - 超管手动备份/恢复：
/dice_backup_db、/dice_restore_db - 超管调账（覆写）：回复某人消息发
/dice_let 金额 - 超管调账（增加）：回复某人消息发
/dice_give 金额 - 超管调账（扣除）：回复某人消息发
/dice_take 金额 - 停机维护：超管发
/dice_maintain→ 自动退款所有对局、终止所有 Attack 并退款双方、退回所有红包、销毁群内所有面板消息、置顶维护公告、锁定期间禁止触发任何指令（仅停机补偿除外） - 停机补偿：超管发
/dice_compensate <更新内容>→ 全员 +500 积分、解除维护锁定、置顶补偿公告 30 分钟
通过环境变量 ALLOWED_CHAT_ID + ALLOWED_THREAD_ID 将 bot 锁定在指定群组的指定话题频道内，其他位置唤起直接报错。命令菜单也仅向该群推送，其他群/私聊不显示。
/dice_event：展示过去 24 小时内的系统事件（节日彩蛋、停机补偿），每页 5 条，支持翻页；多页时面板无操作 1 分钟后自动删除；最多保留 200 条历史
aiogram 3 (Telegram Bot 框架)
└─ Redis (主存储，积分/对局/排行榜/红包/attack)
└─ SQLite backup.db (灾备，每小时同步)
└─ Docker Compose (一键部署)
config.py # 环境变量、常量、并发锁
core.py # bot/dp/redis 实例
utils.py # 工具函数
balance.py # 积分读写、排行榜周期 key
tasks.py # 定时任务（备份/战报/节日彩蛋/每周 help）
redpack.py # 红包系统
game_settle.py # 结算/投掷逻辑（含连胜/连败奖惩）
game.py # 游戏流程管理
handlers.py # 所有 /dice_指令 和 callback 注册（含 /dice_attack 系统）
bot.py # 入口、黑洞路由、main()
- Docker + Docker Compose（推荐 Docker Desktop 或服务器安装）
- 一个 Telegram Bot Token（向 @BotFather 申请）
- 把 Bot 加入群组并赋予管理员权限（需要置顶/删除消息权限）
git clone https://github.com/Likhixang/dice_bot.git
cd dice_bot复制模板文件并填入真实值：
cp .env.example .env编辑 .env：
BOT_TOKEN=你的BotToken
BOT_ID=你的Bot数字ID
SUPER_ADMIN_ID=你的Telegram数字UID
ADMIN_IDS=UID1,UID2,UID3
RUN_MODE=webhook
WEBHOOK_BASE_URL=https://dc.khixang.dpdns.org
WEBHOOK_PATH=/telegram/webhook
WEBHOOK_PORT=9999
WEBHOOK_SECRET_TOKEN=
# 可选：限制 bot 只在指定群组的指定话题频道内响应（留空则不限制）
ALLOWED_CHAT_ID=你的群组数字ID
ALLOWED_THREAD_ID=话题的MessageThreadId如何获取 Telegram 数字 ID？ 向 @userinfobot 发送任意消息即可看到你的 UID。
运行模式说明：
RUN_MODE=webhook时需要配置WEBHOOK_BASE_URL，若未配置会自动回退到polling。
docker compose up -d首次启动会自动拉取镜像并安装依赖，约需 1-2 分钟。
查看运行日志：
docker logs dice_bot -fdocker compose down # 停止
docker restart dice_bot # 重启 bot（修改 .py 文件后生效）
docker compose up -d # 重新拉起（修改 .env 后需用此命令）项目使用 volume 挂载整目录（
.:/app），修改任何.py文件后只需docker restart dice_bot即可，无需 rebuild。
发送 /dice_help 查看完整指令列表。
- 进入群组后发送
/dice_checkin签到获取初始积分 - 发送
大100 3（押大，100 积分，3 颗骰子）发起对局 - 有人点击「接单」按钮后双方依次投掷
- 按“底分 + 同点加成 + 顺子翻倍后取个位”得到最终点数（见下方计算规则）
- 胜者获得全部押注，败者扣除押注
- 每位玩家先投
N颗骰子（支持 1-5 颗）。 - 底分 = 所有骰子点数之和。
- 同点加成：每多一颗重复点数 +1。例：
[2,2,5]加 +1，[4,4,4]加 +2，[6,6,1,1]加 +2。 - 顺子翻倍：当点数互不重复且连续（至少 3 颗）时，整组结果 ×2。例：
[1,2,3]、[2,3,4,5]。 - 最终点数 = （底分 + 同点加成，顺子再翻倍）后取个位（
%10），结果范围为 0-9。 - 比大：最终点数越大越强；比小：最终点数越小越强。
- 同分会自动加赛：并列玩家每轮各补投 1 颗，直到分出胜负；最多加到 20 颗后强制清算。
- 超时未投记为逃跑判负。
| 人数 | 结算分配 |
|---|---|
| 2 人 | 赢家 +总注，败者 -总注 |
| 3 人 | 第1 +总注，第2 ±0，第3 -总注 |
| 4 人 | 第1 +总注，第2 +总注/2，第3 -总注/2，第4 -总注 |
| 5 人 | 第1 +总注，第2 +总注/2，第3 ±0，第4 -总注/2，第5 -总注 |
Q: Bot 没有响应？
检查 Bot 是否有管理员权限，以及 .env 中的 BOT_TOKEN 是否正确。另外确认消息是否发在了配置的话题频道内（若设置了 ALLOWED_THREAD_ID）。
Q: Redis 数据丢了？
超管发送 /dice_restore_db 可从 backup.db 恢复最近一次备份数据。
Q: 修改了代码不生效？
运行 docker restart dice_bot。如果修改了 .env，需要 docker compose up -d。
Q: 农历节日彩蛋没有触发？
需要确保 requirements.txt 中包含 lunardate，并执行过 docker compose up --build -d 重新构建镜像。
aiogram==3.4.1
redis==5.0.1
lunardate==2.0.1
MIT