65 lines
2.0 KiB
Markdown
65 lines
2.0 KiB
Markdown
# “同步”功能说明
|
||
|
||
## 同步到底同步什么？
|
||
|
||
同步 = 从 Telegram 拉取并更新本地数据库中的“账号创建的数据”，主要用于**列表展示/筛选/分组/批量操作**：
|
||
|
||
- 账号创建的频道（Channel）
|
||
- 账号创建的群组（Group）
|
||
|
||
它不是：
|
||
|
||
- 手机号登录/收验证码
|
||
- 检测账号是否冻结/封禁
|
||
- 同步消息/聊天记录
|
||
|
||
## 为什么需要同步？
|
||
|
||
面板的频道/群组列表、分类、批量任务都依赖本地数据库。同步负责把 Telegram 侧的最新信息拉下来并落库。
|
||
|
||
## 自动同步是什么？
|
||
|
||
"自动同步"就是定时在后台执行同样的同步逻辑。
|
||
|
||
- 默认关闭：避免频繁调用 Telegram API。
|
||
- 开启后会写入本地覆盖配置（Docker 下在 `./docker-data/appsettings.local.json`）。
|
||
|
||
如果你不需要自动同步：保持关闭，平时用手动同步即可。
|
||
|
||
## Bot 频道同步
|
||
|
||
Bot 频道管理功能支持两种更新接收模式：
|
||
|
||
### 长轮询模式（默认）
|
||
|
||
- 后台服务定时调用 `getUpdates` 拉取更新
|
||
- 适合开发测试环境
|
||
- 配置：`Telegram__BotAutoSyncEnabled: "true"`
|
||
|
||
### Webhook 模式（生产推荐）
|
||
|
||
- Telegram 主动推送更新到你的服务器
|
||
- 更低资源消耗、更快响应速度
|
||
- 需要公网 HTTPS 地址
|
||
- 配置：
|
||
- `Telegram__WebhookEnabled: "true"`
|
||
- `Telegram__WebhookBaseUrl: "https://your-domain.com"`
|
||
- `Telegram__WebhookSecretToken: "your-secret"`
|
||
- `Telegram__BotAutoSyncEnabled: "true"`
|
||
|
||
详细配置说明见 [Bot Webhook](../deployment/bot-webhook.md)。
|
||
|
||
## 同步失败时的状态更新
|
||
|
||
当账号同步失败（如 Session 失效、账号被封禁等），系统会自动更新账号的 Telegram 状态：
|
||
|
||
- `TelegramStatusOk = false`
|
||
- `TelegramStatusSummary`：可读的错误摘要
|
||
- `TelegramStatusDetails`：详细错误信息
|
||
|
||
常见错误类型：
|
||
- `AUTH_KEY_UNREGISTERED`：Session 失效
|
||
- `AUTH_KEY_DUPLICATED`：Session 冲突（多设备使用同一 Session）
|
||
- `SESSION_REVOKED`：Session 已被撤销
|
||
- `PHONE_NUMBER_BANNED` / `USER_DEACTIVATED_BAN`：账号被封禁
|