From 985a00b92328230c94c68bfca5a86e88fd3eb969 Mon Sep 17 00:00:00 2001
From: meoacgx <a1478882500@gmail.com>
Date: Fri, 19 Dec 2025 21:50:57 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E7=B2=BE=E7=AE=80README=E5=B9=B6?=
 =?UTF-8?q?=E8=A1=A5=E5=85=85Docker=E4=B8=80=E9=94=AE=E5=AE=89=E8=A3=85?=
 =?UTF-8?q?=E4=B8=8E=E6=96=87=E6=A1=A3=E7=9B=AE=E5=BD=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md             |  5 +++++
 docs/README.md        | 10 ++++++++++
 docs/advanced.md      | 40 ++++++++++++++++++++++++++++++++++++++++
 docs/import.md        | 31 +++++++++++++++++++++++++++++++
 docs/reverse-proxy.md | 37 +++++++++++++++++++++++++++++++++++++
 docs/sync.md          | 27 +++++++++++++++++++++++++++
 6 files changed, 150 insertions(+)
 create mode 100644 docs/README.md
 create mode 100644 docs/advanced.md
 create mode 100644 docs/import.md
 create mode 100644 docs/reverse-proxy.md
 create mode 100644 docs/sync.md

diff --git a/README.md b/README.md
index 479d8b4..0f0ac74 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,11 @@
 
 > 基于 WTelegramClient 的 Telegram 多账户管理面板，支持批量账号管理、频道统计与操作。
 
+## 社区
+
+- TG 频道：https://t.me/zhanzhangck
+- 站长交流群：https://t.me/vpsbbq
+
 ## 项目概述
 
 ### 核心功能
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..7f03b00
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,10 @@
+# 文档索引
+
+如果你只是想快速跑起来：优先看根目录 `README.md` 的 Docker 一键安装。
+
+## 目录
+
+- `docs/import.md`：压缩包批量导入账号结构（推荐）
+- `docs/sync.md`：同步功能说明（同步什么/为什么要同步/自动同步）
+- `docs/reverse-proxy.md`：反向代理示例（Nginx/Caddy，含 WebSocket）
+- `docs/advanced.md`：架构/配置项/环境变量/数据持久化位置等
diff --git a/docs/advanced.md b/docs/advanced.md
new file mode 100644
index 0000000..3b8bcfc
--- /dev/null
+++ b/docs/advanced.md
@@ -0,0 +1,40 @@
+# 进阶说明
+
+## 技术栈
+
+- .NET 8 / ASP.NET Core / Blazor Server
+- MudBlazor
+- EF Core（默认 SQLite）
+- WTelegramClient（MTProto）
+
+## Docker 数据目录（强相关）
+
+`docker-compose.yml` 会把宿主机 `./docker-data` 挂载到容器 `/data`，核心文件包括：
+
+- `/data/telegram-panel.db`：SQLite 数据库
+- `/data/sessions/`：账号 session 文件
+- `/data/appsettings.local.json`：UI 保存后的本地覆盖配置
+- `/data/admin_auth.json`：后台登录账号/密码（首次会用初始默认值生成）
+
+## 后台任务（刷新页面不影响）
+
+部分批量任务会在后台静默执行（避免“刷新页面就中断”）：
+
+- 批量邀请
+- 批量设置管理员
+
+## 账号状态检测（深度探测）
+
+为更可靠识别冻结/受限等状态，支持深度探测（例如通过创建/删除测试频道来探测权限）。
+
+检测结果会持久化到数据库，避免刷新页面又变回“未检测”。
+
+## 配置项速查
+
+Docker 下常用环境变量（见 `docker-compose.yml`）：
+
+- `ConnectionStrings__DefaultConnection`：SQLite 路径（默认 `/data/telegram-panel.db`）
+- `Telegram__SessionsPath`：session 目录（默认 `/data/sessions`）
+- `AdminAuth__CredentialsPath`：后台密码文件（默认 `/data/admin_auth.json`）
+- `Sync__AutoSyncEnabled`：账号创建的频道/群组自动同步（默认关闭）
+- `Telegram__BotAutoSyncEnabled`：Bot 频道轮询自动同步（默认关闭）
diff --git a/docs/import.md b/docs/import.md
new file mode 100644
index 0000000..1a976aa
--- /dev/null
+++ b/docs/import.md
@@ -0,0 +1,31 @@
+# 压缩包导入（推荐）
+
+支持批量导入账号压缩包：**每个账号一个独立子文件夹**，文件夹内包含一个 `.json` + 一个 `.session`。
+
+## 批量导入压缩包结构（示例）
+
+例如你要导入 2 个账号：
+
+```
+accounts.zip
+  ├─ 8613111111111
+  │   ├─ 8613111111111.json
+  │   └─ 8613111111111.session
+  └─ 8615119714541
+      ├─ 8615119714541.json
+      └─ 8615119714541.session
+```
+
+### 命名规则
+
+- 子文件夹名建议使用手机号（或你能区分账号的唯一标识）。
+- `.json` 与 `.session` 文件名建议与子文件夹同名（上面的例子就是同名）。
+- 每个子文件夹内只要能找到 **1 个 `.json` + 1 个 `.session`** 即可。
+
+## Docker 部署下导入的文件会存哪？
+
+如果你使用 Docker，所有 session 会写入：
+
+- `./docker-data/sessions/`
+
+不要手工乱改里面的文件名，避免程序找不到 session。
diff --git a/docs/reverse-proxy.md b/docs/reverse-proxy.md
new file mode 100644
index 0000000..6da651a
--- /dev/null
+++ b/docs/reverse-proxy.md
@@ -0,0 +1,37 @@
+# 反向代理（Nginx/Caddy）
+
+Telegram Panel 是 **Blazor Server**，需要 WebSocket（`/_blazor`）。
+
+如果你反代后出现页面卡住/断开/一直重连，九成是 WebSocket 没配对。
+
+## Nginx（HTTP）示例
+
+注意：请确保你的上游是 `http://127.0.0.1:5000`（对应 `docker-compose.yml` 暴露端口）。
+
+```nginx
+server {
+  listen 80;
+  server_name example.com;
+
+  location / {
+    proxy_pass http://127.0.0.1:5000;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "Upgrade";
+    proxy_set_header Host $host;
+
+    proxy_read_timeout 3600;
+    proxy_send_timeout 3600;
+  }
+}
+```
+
+## Caddy 示例
+
+```caddy
+example.com {
+  reverse_proxy 127.0.0.1:5000
+}
+```
+
+如果你使用了 CDN/面板（例如 Cloudflare），也要确认它对 WebSocket 的支持与超时设置。
diff --git a/docs/sync.md b/docs/sync.md
new file mode 100644
index 0000000..9bacec9
--- /dev/null
+++ b/docs/sync.md
@@ -0,0 +1,27 @@
+# “同步”功能说明
+
+## 同步到底同步什么？
+
+同步 = 从 Telegram 拉取并更新本地数据库中的“账号创建的数据”，主要用于**列表展示/筛选/分组/批量操作**：
+
+- 账号创建的频道（Channel）
+- 账号创建的群组（Group）
+
+它不是：
+
+- 手机号登录/收验证码
+- 检测账号是否冻结/封禁
+- 同步消息/聊天记录
+
+## 为什么需要同步？
+
+面板的频道/群组列表、分类、批量任务都依赖本地数据库。同步负责把 Telegram 侧的最新信息拉下来并落库。
+
+## 自动同步是什么？
+
+“自动同步”就是定时在后台执行同样的同步逻辑。
+
+- 默认关闭：避免频繁调用 Telegram API。
+- 开启后会写入本地覆盖配置（Docker 下在 `./docker-data/appsettings.local.json`）。
+
+如果你不需要自动同步：保持关闭，平时用手动同步即可。