这是一个基于 .NET 的 Telegram 群组打卡 bot,支持跨平台运行(Linux/Mac/Windows)。
- 支持群组和私聊两种模式
- 群组模式:将 bot 加入群组后,用户可以使用命令进行签到/签退
- 私聊模式:直接与机器人私聊进行个人打卡管理
- 支持命令:/wakeup, /zao (签到); /sleep, /wan (签退); /status (查看最近签到/签退与时长)
- 新增命令:/start(私聊欢迎消息)、/help(帮助信息)
- 自动命令注册:机器人启动时自动向 Telegram 注册命令,用户输入
/时可看到命令提示 - 使用 SQLite 数据库存储事件
- 支持多环境配置,可自定义消息模板和功能开关
项目使用分层配置文件系统:
包含所有默认配置,包括:
- 日志级别设置
- 数据库连接配置
- 机器人命令和消息模板
- 功能开关
- Development (
appsettings.Development.json): 开发环境配置 - Staging (
appsettings.Staging.json): 测试环境配置 - Production (
appsettings.Production.json): 生产环境配置
提供了配置模板文件(.template),包含敏感信息的占位符:
appsettings.Development.json.templateappsettings.Production.json.template
- 复制相应的模板文件:
cp appsettings.Development.json.template appsettings.Development.json- 编辑配置文件,填入你的 bot token:
{
"Bot": {
"Token": "你的机器人TOKEN"
}
}设置环境变量 TELEGRAM_BOT_TOKEN:
export TELEGRAM_BOT_TOKEN="你的机器人TOKEN"# 开发环境
./start.sh Development
# 生产环境
./start.sh Production
# 默认为开发环境
./start.sh启动脚本会自动:
- 检查配置文件是否存在
- 验证机器人 Token 配置
- 从模板创建配置文件(如果需要)
- 提供友好的错误提示
dotnet run --environment Developmentdotnet run --environment Production- 将机器人添加到目标群组
- 确保机器人有发送消息权限
- 群组成员可以使用打卡命令
- 直接与机器人开始私聊
- 发送
/start查看欢迎信息 - 开始使用打卡功能
- 签到:
/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错误信息:System.ArgumentException: Bot token invalid (Parameter 'token')
解决方案:
-
使用配置文件(推荐):
# 复制模板并编辑 cp appsettings.Development.json.template appsettings.Development.json # 在配置文件中填入真实的 bot token
-
使用环境变量:
export TELEGRAM_BOT_TOKEN="你的真实机器人TOKEN" dotnet run --environment Development
- 确保应用程序对数据库文件目录有写权限
- 检查配置文件中的数据库路径是否正确
- 确保机器人已添加到目标群组
- 验证机器人有发送消息的权限
症状: ❌ Failed to connect to Telegram Bot API 或连接超时
解决方案:
-
检查代理设置:
- 确认代理服务器地址和端口正确
- 验证代理服务器是否正常运行
- 测试代理认证信息(用户名/密码)
-
尝试不同配置:
{ "Bot": { "Proxy": { "Enabled": false // 临时禁用代理测试直连 } } } -
检查网络连接:
# 测试代理连接(示例) curl --proxy http://127.0.0.1:7890 https://api.telegram.org/bot<TOKEN>/getMe
-
查看详细日志:
- 启用 Debug 日志级别
- 查找代理配置和连接相关的日志信息
在开发环境中,应用程序会输出详细的调试信息,包括:
- 连接信息: Bot 连接状态、API 响应
- 代理信息: 代理配置状态、连接日志
- 消息处理: 收到的消息详情、命令处理过程
- 数据库操作: EF Core 查询和插入操作日志
- 配置加载: 配置文件来源、Token 来源(配置文件 vs 环境变量)
- 命令注册: 自动注册的命令列表和作用域
{
"Logging": {
"LogLevel": {
"Default": "Debug",
"WakeupBot.Services.BotHostedService": "Debug"
}
}
}- 数据库文件会在程序启动时自动创建。
- 时间以本地时间显示给用户(内部以 UTC 存储)。
- 配置文件支持热重载,无需重启应用程序。
- 为每次签到/签退配对生成会话记录(Session 表),并支持导出统计。
- 添加管理员命令查看群组统计。
- 支持命令别名或多语言提示。