Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Wakeup Bot (dotnet, SQLite)

这是一个基于 .NET 的 Telegram 群组打卡 bot,支持跨平台运行(Linux/Mac/Windows)。

功能

  • 支持群组和私聊两种模式
  • 群组模式:将 bot 加入群组后,用户可以使用命令进行签到/签退
  • 私聊模式:直接与机器人私聊进行个人打卡管理
  • 支持命令:/wakeup, /zao (签到); /sleep, /wan (签退); /status (查看最近签到/签退与时长)
  • 新增命令:/start(私聊欢迎消息)、/help(帮助信息)
  • 自动命令注册:机器人启动时自动向 Telegram 注册命令,用户输入 / 时可看到命令提示
  • 使用 SQLite 数据库存储事件
  • 支持多环境配置,可自定义消息模板和功能开关

配置文件

项目使用分层配置文件系统:

基础配置 (appsettings.json)

包含所有默认配置,包括:

  • 日志级别设置
  • 数据库连接配置
  • 机器人命令和消息模板
  • 功能开关

环境特定配置

  • Development (appsettings.Development.json): 开发环境配置
  • Staging (appsettings.Staging.json): 测试环境配置
  • Production (appsettings.Production.json): 生产环境配置

配置模板

提供了配置模板文件(.template),包含敏感信息的占位符:

  • appsettings.Development.json.template
  • appsettings.Production.json.template

快速开始

1. 配置设置

方法一:使用配置文件(推荐)

  1. 复制相应的模板文件:
cp appsettings.Development.json.template appsettings.Development.json
  1. 编辑配置文件,填入你的 bot token:
{
  "Bot": {
    "Token": "你的机器人TOKEN"
  }
}

方法二:使用环境变量

设置环境变量 TELEGRAM_BOT_TOKEN:

export TELEGRAM_BOT_TOKEN="你的机器人TOKEN"

2. 运行应用

方法一:使用启动脚本(推荐)

# 开发环境
./start.sh Development

# 生产环境
./start.sh Production

# 默认为开发环境
./start.sh

启动脚本会自动:

  • 检查配置文件是否存在
  • 验证机器人 Token 配置
  • 从模板创建配置文件(如果需要)
  • 提供友好的错误提示

方法二:直接运行

开发环境
dotnet run --environment Development
生产环境
dotnet run --environment Production

3. 使用机器人

群组使用

  1. 将机器人添加到目标群组
  2. 确保机器人有发送消息权限
  3. 群组成员可以使用打卡命令

私聊使用

  1. 直接与机器人开始私聊
  2. 发送 /start 查看欢迎信息
  3. 开始使用打卡功能

可用命令

  • 签到: /wakeup 或 /zao
  • 签退: /sleep 或 /wan
  • 状态查询: /status
  • 帮助信息: /help
  • 开始使用: /start (仅私聊)

注意: 在群聊中使用时,Telegram 会自动在命令后添加机器人用户名,如 /wakeup@hellozaobot。机器人已经自动处理这种格式,您可以直接使用任一格式。

配置说明

数据库配置

{
  "Database": {
    "ConnectionString": "Data Source=wakeup.db",
    "Provider": "Sqlite"
  }
}

机器人配置

{
  "Bot": {
    "Token": "你的机器人TOKEN",
    "AllowedChatTypes": ["Group", "Supergroup", "Private"],
    "Proxy": {
      "Enabled": false,
      "Type": "HTTP",
      "Host": "127.0.0.1",
      "Port": 8080
    },
    "Commands": {
      "CheckIn": ["/wakeup", "/zao"],
      "CheckOut": ["/sleep", "/wan"],
      "Status": ["/status"]
    },
    "Messages": {
      "CheckInSuccess": "✅ 签到成功:{UserName} 在 {Time} 签到。"
    }
  }
}

代理配置

如果您的网络环境需要使用代理访问 Telegram API,可以配置代理设置。

基本代理配置

{
  "Bot": {
    "Proxy": {
      "Enabled": true,
      "Type": "HTTP",
      "Host": "127.0.0.1",
      "Port": 8080
    }
  }
}

带认证的代理配置

{
  "Bot": {
    "Proxy": {
      "Enabled": true,
      "Type": "HTTP",
      "Host": "proxy.example.com",
      "Port": 3128,
      "Username": "your_username",
      "Password": "your_password"
    }
  }
}

支持的代理类型

  • HTTP/HTTPS: 完全支持,推荐使用
  • SOCKS4/SOCKS5: 基础支持(自动回退到 HTTP 模式)

配置参数说明

参数 类型 必需 说明
Enabled boolean 是 是否启用代理
Type string 是 代理类型:HTTP, HTTPS, SOCKS4, SOCKS5
Host string 是 代理服务器地址
Port int 是 代理服务器端口
Username string 否 代理认证用户名
Password string 否 代理认证密码

配置示例

本地代理(如科学上网工具):

{
  "Bot": {
    "Proxy": {
      "Enabled": true,
      "Type": "HTTP",
      "Host": "127.0.0.1",
      "Port": 7890,
      "Username": "username",
      "Password": "passwd"
    }
  }
}

代理测试

启动应用时,您会看到如下日志:

  • 🌐 Using direct connection (no proxy) - 直连模式
  • 🌐 Configuring proxy: HTTP://127.0.0.1:7890 - 代理模式
  • ✅ Proxy configured successfully - 代理配置成功
  • ✅ Bot connected successfully! - 机器人连接成功

💡 提示: 详细的代理配置说明请参考 PROXY_CONFIGURATION.md

功能开关

{
  "Features": {
    "EnableStatus": true,
    "EnableDurationTracking": true,
    "RequireGroupChat": false
  }
}
  • EnableStatus: 是否启用状态查询功能
  • EnableDurationTracking: 是否启用时长跟踪功能
  • RequireGroupChat: 是否仅限群组使用(false = 同时支持私聊)
  • EnableCommandRegistration: 是否启用自动命令注册功能

命令注册配置

机器人支持自动向 Telegram 注册命令,用户输入 / 时可看到可用命令。详见 COMMAND_REGISTRATION.md。

{
  "Bot": {
    "Commands": {
      "RegisteredCommands": [
        {
          "Command": "wakeup",
          "Description": "签到 - 记录开始工作时间",
          "Scope": ["default"]
        }
      ]
    }
  }
}

环境变量

  • ASPNETCORE_ENVIRONMENT: 设置运行环境(Development/Staging/Production)
  • TELEGRAM_BOT_TOKEN: Telegram 机器人 token(配置文件优先)

代理环境变量(可选)

# 代理配置(作为配置文件的补充或替代)
export BOT_PROXY_ENABLED=true
export BOT_PROXY_TYPE=HTTP
export BOT_PROXY_HOST=127.0.0.1
export BOT_PROXY_PORT=7890
export BOT_PROXY_USERNAME=username
export BOT_PROXY_PASSWORD=password

故障排除

常见问题

1. "Bot token invalid" 错误

错误信息:System.ArgumentException: Bot token invalid (Parameter 'token')

解决方案:

  1. 使用配置文件(推荐):

    # 复制模板并编辑
    cp appsettings.Development.json.template appsettings.Development.json
    # 在配置文件中填入真实的 bot token
  2. 使用环境变量:

    export TELEGRAM_BOT_TOKEN="你的真实机器人TOKEN"
    dotnet run --environment Development

2. 数据库连接问题

  • 确保应用程序对数据库文件目录有写权限
  • 检查配置文件中的数据库路径是否正确

3. 权限问题

  • 确保机器人已添加到目标群组
  • 验证机器人有发送消息的权限

4. 代理连接问题

症状: ❌ Failed to connect to Telegram Bot API 或连接超时

解决方案:

  1. 检查代理设置:

    • 确认代理服务器地址和端口正确
    • 验证代理服务器是否正常运行
    • 测试代理认证信息(用户名/密码)
  2. 尝试不同配置:

    {
      "Bot": {
        "Proxy": {
          "Enabled": false // 临时禁用代理测试直连
        }
      }
    }
  3. 检查网络连接:

    # 测试代理连接(示例)
    curl --proxy http://127.0.0.1:7890 https://api.telegram.org/bot<TOKEN>/getMe
  4. 查看详细日志:

    • 启用 Debug 日志级别
    • 查找代理配置和连接相关的日志信息

调试模式

在开发环境中,应用程序会输出详细的调试信息,包括:

  • 连接信息: Bot 连接状态、API 响应
  • 代理信息: 代理配置状态、连接日志
  • 消息处理: 收到的消息详情、命令处理过程
  • 数据库操作: EF Core 查询和插入操作日志
  • 配置加载: 配置文件来源、Token 来源(配置文件 vs 环境变量)
  • 命令注册: 自动注册的命令列表和作用域

启用详细日志

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "WakeupBot.Services.BotHostedService": "Debug"
    }
  }
}

说明

  • 数据库文件会在程序启动时自动创建。
  • 时间以本地时间显示给用户(内部以 UTC 存储)。
  • 配置文件支持热重载,无需重启应用程序。

后续改进建议

  • 为每次签到/签退配对生成会话记录(Session 表),并支持导出统计。
  • 添加管理员命令查看群组统计。
  • 支持命令别名或多语言提示。

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages