diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..f218920
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,62 @@
+name: Docs (MkDocs)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+          cache-dependency-path: "requirements-docs.txt"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-docs.txt
+
+      - name: Build site
+        run: |
+          mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index 7bb1ebc..4e67de7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -40,6 +40,11 @@ session数据/
 .DS_Store
 Thumbs.db
 
+# Python / docs site
+.venv/
+__pycache__/
+site/
+
 # SQLite
 *.db
 
diff --git a/README.md b/README.md
index 18c8258..674f713 100644
--- a/README.md
+++ b/README.md
@@ -10,9 +10,9 @@
 </p>
 
 <p align="center">
-  📦 <b><a href="docs/installation.md">安装部署</a></b> |
+  📦 <b><a href="docs/getting-started/installation.md">安装部署</a></b> |
   🏪 <b><a href="https://faka.boxmoe.eu.org/">API 账号购买</a></b> |
-  🧯 <b><a href="docs/anti-freeze.md">防冻结指南</a></b> |
+  🧯 <b><a href="docs/guides/anti-freeze.md">防冻结指南</a></b> |
   🖼️ <b><a href="screenshot/">截图</a></b> |
   💬 <b><a href="https://t.me/zhanzhangck">TG 频道</a></b> |
   👥 <b><a href="https://t.me/vpsbbq">站长交流群</a></b>
@@ -25,7 +25,7 @@
 - 📱 一键踢出其他设备：保留面板当前会话，清理其它在线设备
 - 🧹 废号检测与一键清理：封禁/受限/冻结/未登录/Session 失效等状态批量处理
 - 🔐 2FA 管理：单个/批量修改二级密码；绑定/换绑找回邮箱（支持对接 Cloud Mail 自动收码确认）
-- 🧩 模块化扩展：任务 / API / UI 可安装扩展（见 `docs/modules.md`）
+- 🧩 模块化扩展：任务 / API / UI 可安装扩展（见 `docs/developer/modules.md`）
 
 ## 快速开始
 
@@ -54,7 +54,7 @@ docker compose up -d --build
 
 登录后到「修改密码」页面改掉即可。
 
-> 更完整的安装、更新、导入与生产部署建议：见 `docs/installation.md`。
+> 更完整的安装、更新、导入与生产部署建议：见 `docs/getting-started/installation.md`。
 
 ## 截图
 
diff --git a/docs/README.md b/docs/README.md
index 4bf99f0..464c398 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,13 +1,10 @@
-# 文档索引
+# 文档
 
-建议阅读顺序：先看安装部署，再按需查看其它主题。
+使用者文档入口：[`docs/index.md`](index.md)
 
-- [docs/installation.md](installation.md)：安装部署（Docker/本地运行）、更新方法、账号导入简要、生产部署建议入口
-- [docs/anti-freeze.md](anti-freeze.md)：防冻结指南（新号必看）
-- [docs/import.md](import.md)：压缩包导入结构（更详细的示例与命名规则）
-- [docs/reverse-proxy.md](reverse-proxy.md)：反向代理示例（Nginx/Caddy，含 WebSocket）
-- [docs/advanced.md](advanced.md)：配置项/环境变量/数据目录/后台任务说明（含 Webhook 配置）
-- [docs/sync.md](sync.md)：同步说明（同步什么/为什么要同步/自动同步）
-- [docs/api.md](api.md)：接口速查（面向二次开发）
-- [docs/database.md](database.md)：数据库与主要表结构（面向排障/扩展）
-- [docs/modules.md](modules.md)：模块系统（可安装/可卸载/依赖/回滚/扩展点）
+本地预览（任选其一）：
+
+- `uv venv && uv pip install -r requirements-docs.txt && uv run mkdocs serve`
+- `python -m venv .venv` 后：
+  - Windows：`.venv\\Scripts\\pip install -r requirements-docs.txt`，再 `.venv\\Scripts\\mkdocs serve`
+  - macOS/Linux：`.venv/bin/pip install -r requirements-docs.txt`，再 `.venv/bin/mkdocs serve`
diff --git a/docs/deployment/bot-webhook.md b/docs/deployment/bot-webhook.md
new file mode 100644
index 0000000..99ce071
--- /dev/null
+++ b/docs/deployment/bot-webhook.md
@@ -0,0 +1,58 @@
+# Bot Webhook（生产环境推荐）
+
+> 如果你不使用「Bot 频道管理」功能，可以跳过本页。
+
+默认情况下，Bot 使用**长轮询（Long Polling）**模式接收更新。生产环境建议使用 Webhook 模式，优势如下：
+
+- 更低的资源消耗（无需持续轮询）
+- 更快的响应速度（Telegram 主动推送）
+- 更适合高流量/多 Bot 场景
+
+前置条件：
+
+- 需要公网可访问地址（强烈建议 HTTPS）
+- 需要反向代理正确配置 WebSocket/转发头（见 [反向代理](reverse-proxy.md)）
+
+## Webhook 配置项
+
+在 `docker-compose.yml` 或 `appsettings.local.json` 中配置：
+
+| 配置项 | 环境变量 | 说明 |
+|--------|----------|------|
+| `Telegram:WebhookEnabled` | `Telegram__WebhookEnabled` | 设为 `true` 启用 Webhook 模式；默认 `false` 使用轮询 |
+| `Telegram:WebhookBaseUrl` | `Telegram__WebhookBaseUrl` | 你的公网 HTTPS 地址（Telegram 要求必须 HTTPS） |
+| `Telegram:WebhookSecretToken` | `Telegram__WebhookSecretToken` | 验证密钥，Telegram 会在请求头中携带此值供校验 |
+| `Telegram:BotAutoSyncEnabled` | `Telegram__BotAutoSyncEnabled` | 设为 `true` 启用自动同步；Bot 加入新频道后自动添加到列表 |
+
+## docker-compose.yml 配置示例
+
+```yaml
+environment:
+  Telegram__WebhookEnabled: "true"
+  Telegram__WebhookBaseUrl: "https://your-domain.com"
+  Telegram__WebhookSecretToken: "your-random-secret-token"
+  Telegram__BotAutoSyncEnabled: "true"
+```
+
+## 注意事项
+
+- Webhook 模式必须使用 HTTPS，Telegram 不支持 HTTP
+- 启用 Webhook 后，系统会在启动时为所有活跃 Bot 注册 Webhook
+- 如果你使用反向代理，确保 `/api/bot/webhook/*` 路径可以被外部访问
+- 同一个 Bot Token 同时只能使用一种模式（Webhook 或 Long Polling），切换模式会自动覆盖
+- 切换模式后需要重启服务生效
+
+## 反向代理配置（Webhook 路径）
+
+Nginx 示例：
+
+```nginx
+location /api/bot/webhook/ {
+  proxy_pass http://127.0.0.1:5000;
+  proxy_http_version 1.1;
+  proxy_set_header Host $host;
+  proxy_set_header X-Real-IP $remote_addr;
+  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+  proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
diff --git a/docs/reverse-proxy.md b/docs/deployment/reverse-proxy.md
similarity index 92%
rename from docs/reverse-proxy.md
rename to docs/deployment/reverse-proxy.md
index b5289e4..223c362 100644
--- a/docs/reverse-proxy.md
+++ b/docs/deployment/reverse-proxy.md
@@ -45,3 +45,5 @@ example.com {
 
 - 反代目标：`http://127.0.0.1:5000`
 - 需要透传：`Host` + `X-Forwarded-Host` + `X-Forwarded-Proto`（否则可能跳到 `localhost`）
+
+如果你要启用 Bot Webhook，还需要确保 Webhook 路径可外网访问：见 [Bot Webhook](bot-webhook.md)。
diff --git a/docs/developer/documentation.md b/docs/developer/documentation.md
new file mode 100644
index 0000000..149a2ba
--- /dev/null
+++ b/docs/developer/documentation.md
@@ -0,0 +1,44 @@
+# 文档维护
+
+本项目使用 **MkDocs Material** 生成文档站，文档源文件统一放在 `docs/`。
+
+## 本地预览
+
+使用 `uv`（推荐）：
+
+```bash
+uv venv
+uv pip install -r requirements-docs.txt
+uv run mkdocs serve
+```
+
+生成静态站点：
+
+```bash
+uv run mkdocs build
+```
+
+## 目录约定（面向使用者优先）
+
+- `docs/getting-started/`：从 0 到可用（安装、升级、FAQ）
+- `docs/guides/`：日常使用与操作指南
+- `docs/deployment/`：反向代理、Webhook、生产运维相关
+- `docs/reference/`：配置/数据库/API 等参考型内容
+- `docs/developer/`：模块开发与维护者说明
+
+## 新增/移动页面的规则
+
+- 新页面：直接在对应目录新增 `*.md`
+- 侧边栏与顺序：在 `mkdocs.yml` 的 `nav:` 中维护
+- 链接：尽量使用相对路径链接（例如 `../guides/sync.md`），避免写死仓库 URL
+
+## GitHub Pages 发布
+
+已内置工作流：`.github/workflows/docs.yml`。
+
+启用方式（只需要做一次）：
+
+1) 仓库 Settings → Pages
+2) Source 选择 **GitHub Actions**
+
+之后每次合并到 `main`（且改动命中 `docs/**`/`mkdocs.yml` 等）会自动构建并发布。
diff --git a/docs/modules.md b/docs/developer/modules.md
similarity index 100%
rename from docs/modules.md
rename to docs/developer/modules.md
diff --git a/docs/getting-started/faq.md b/docs/getting-started/faq.md
new file mode 100644
index 0000000..c0b9f13
--- /dev/null
+++ b/docs/getting-started/faq.md
@@ -0,0 +1,6 @@
+# 常见问题
+
+## 发送验证码提示“session 被占用/进程占用”
+
+- 确保不要多开多个面板实例共享同一个 `sessions` 目录（会互相锁文件）
+- 如果刚修改了全局 `ApiId/ApiHash`，建议重启面板再登录
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
new file mode 100644
index 0000000..c48800a
--- /dev/null
+++ b/docs/getting-started/installation.md
@@ -0,0 +1,66 @@
+# 安装部署
+
+本文档用于把 Telegram Panel 跑起来（推荐 Docker）。
+
+## Docker 部署（推荐）
+
+### 环境要求
+
+- Docker（Windows 推荐 Docker Desktop + WSL2；Linux 直接安装 Docker Engine）
+
+### 启动
+
+```bash
+git clone https://github.com/moeacgx/Telegram-Panel
+cd Telegram-Panel
+docker compose up -d --build
+```
+
+启动后访问：`http://localhost:5000`
+
+### 默认后台账号（首次登录）
+
+- 用户名：`admin`
+- 密码：`admin123`
+
+登录后到「修改密码」页面改掉即可。
+
+### 必做配置：Telegram API 凭据
+
+到 https://my.telegram.org/apps 用任意一个 Telegram 账号申请一次 `api_id` / `api_hash`，然后在面板「系统设置」里保存即可。
+
+> 说明：不需要每个账号都申请，全站共用这一对即可工作。  
+> 注意：`api_hash` 是 **32 位十六进制字符串（0-9a-f）**，请不要填 Token/用户名/URL 等其它值。
+
+### 数据持久化（别乱删）
+
+容器内所有持久化数据统一挂载到宿主机 `./docker-data`：
+
+- 数据库：`./docker-data/telegram-panel.db`
+- Sessions：`./docker-data/sessions/`
+- 系统设置本地覆盖：`./docker-data/appsettings.local.json`
+- 后台登录凭据文件：`./docker-data/admin_auth.json`
+
+更多说明见：[配置与数据目录](../reference/configuration.md)。
+
+## 生产部署入口
+
+- 反向代理（含 WebSocket）：见 [反向代理](../deployment/reverse-proxy.md)
+- Bot Webhook（可选，生产推荐）：见 [Bot Webhook](../deployment/bot-webhook.md)
+
+## 更新与常见问题
+
+- 更新升级：见 [更新升级](update.md)
+- 常见问题：见 [常见问题](faq.md)
+
+## 下一步
+
+- 账号导入：见 [账号导入（压缩包）](../guides/account-import.md)
+- 新号必看：见 [防冻结指南](../guides/anti-freeze.md)
+- 列表/批量能力依赖同步：见 [同步说明](../guides/sync.md)
+
+## 本地开发运行（可选）
+
+```bash
+dotnet run --project src/TelegramPanel.Web
+```
diff --git a/docs/getting-started/update.md b/docs/getting-started/update.md
new file mode 100644
index 0000000..1c7bb4c
--- /dev/null
+++ b/docs/getting-started/update.md
@@ -0,0 +1,54 @@
+# 更新升级（Docker 部署）
+
+> 更新前建议先备份：`./docker-data/telegram-panel.db` 与 `./docker-data/`（尤其是重要账号的 sessions）。
+
+在项目目录下执行：
+
+```bash
+git pull --rebase
+docker compose up -d --build
+```
+
+说明：
+
+- `docker compose up -d --build` 会重新构建并滚动更新容器（数据仍在 `./docker-data`，不会丢）
+- 若你修改过 `.env` 或 `./docker-data/appsettings.local.json`，更新后也建议重启一次确保新配置生效
+
+## 更新出错：git pull 提示本地修改会被覆盖
+
+典型报错：
+
+```
+error: Your local changes to the following files would be overwritten by merge:
+        docker-compose.yml
+Please commit your changes or stash them before you merge.
+Aborting
+```
+
+原因：你本地改过 `docker-compose.yml`，导致更新时 Git 不允许直接覆盖。
+
+推荐做法：尽量不要直接改 `docker-compose.yml`：
+
+- Webhook 等部署差异：用 `.env`（参考 `.env.example`）
+- 功能开关/参数：用面板「系统设置」保存到 `./docker-data/appsettings.local.json`（见 [配置与数据目录](../reference/configuration.md)）
+
+处理方式（二选一）：
+
+1) 放弃本地修改（最快、推荐）
+
+```bash
+git restore docker-compose.yml
+git pull --rebase
+docker compose up -d --build
+```
+
+2) 保留本地修改（自己承担后续合并成本）
+
+```bash
+git stash push -m "local docker-compose" -- docker-compose.yml
+git pull --rebase
+git stash pop
+docker compose up -d --build
+```
+
+如果 `git stash pop` 出现冲突，按提示手动合并 `docker-compose.yml` 后再继续。
diff --git a/docs/import.md b/docs/guides/account-import.md
similarity index 100%
rename from docs/import.md
rename to docs/guides/account-import.md
diff --git a/docs/anti-freeze.md b/docs/guides/anti-freeze.md
similarity index 100%
rename from docs/anti-freeze.md
rename to docs/guides/anti-freeze.md
diff --git a/docs/sync.md b/docs/guides/sync.md
similarity index 95%
rename from docs/sync.md
rename to docs/guides/sync.md
index 56b52cd..5dedda9 100644
--- a/docs/sync.md
+++ b/docs/guides/sync.md
@@ -47,7 +47,7 @@ Bot 频道管理功能支持两种更新接收模式：
   - `Telegram__WebhookSecretToken: "your-secret"`
   - `Telegram__BotAutoSyncEnabled: "true"`
 
-详细配置说明见 [advanced.md](./advanced.md#bot-webhook-模式生产环境推荐)。
+详细配置说明见 [Bot Webhook](../deployment/bot-webhook.md)。
 
 ## 同步失败时的状态更新
 
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..347d1d1
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,30 @@
+# Telegram Panel 文档
+
+本页是面向使用者的文档入口。建议先按「快速开始」完成部署，再按需阅读各指南。
+
+## 快速开始
+
+- [安装部署](getting-started/installation.md)
+- [更新升级](getting-started/update.md)
+- [常见问题](getting-started/faq.md)
+
+## 使用指南
+
+- [防冻结指南（新号必看）](guides/anti-freeze.md)
+- [账号导入（压缩包）](guides/account-import.md)
+- [同步说明](guides/sync.md)
+
+## 部署与运维
+
+- [反向代理（Nginx/Caddy/宝塔）](deployment/reverse-proxy.md)
+- [Bot Webhook（生产推荐）](deployment/bot-webhook.md)
+
+## 参考
+
+- [配置与数据目录](reference/configuration.md)
+- [数据库结构（简版）](reference/database.md)
+
+## 开发者
+
+- [模块开发](developer/modules.md)
+- [接口速查（面向二次开发）](reference/api.md)
diff --git a/docs/installation.md b/docs/installation.md
deleted file mode 100644
index f03e81b..0000000
--- a/docs/installation.md
+++ /dev/null
@@ -1,139 +0,0 @@
-# 安装部署
-
-本文档用于把 Telegram Panel 跑起来（推荐 Docker）。README 只保留简洁入口信息。
-
-## Docker 部署（推荐）
-
-### 环境要求
-
-- Docker（Windows 推荐 Docker Desktop + WSL2；Linux 直接安装 Docker Engine）
-
-### 启动
-
-```bash
-git clone https://github.com/moeacgx/Telegram-Panel
-cd Telegram-Panel
-docker compose up -d --build
-```
-
-启动后访问：`http://localhost:5000`
-
-### 默认后台账号（首次登录）
-
-- 用户名：`admin`
-- 密码：`admin123`
-
-登录后到「修改密码」页面改掉即可。
-
-### 必做配置：Telegram API 凭据
-
-到 https://my.telegram.org/apps 用任意一个 Telegram 账号申请一次 `api_id` / `api_hash`，然后在面板「系统设置」里保存即可。
-
-> 说明：不需要每个账号都申请，全站共用这一对即可工作。  
-> 注意：`api_hash` 是 **32 位十六进制字符串（0-9a-f）**，请不要填 Token/用户名/URL 等其它值。
-
-### 数据持久化（别乱删）
-
-容器内所有持久化数据统一挂载到宿主机 `./docker-data`：
-
-- 数据库：`./docker-data/telegram-panel.db`
-- Sessions：`./docker-data/sessions/`
-- 系统设置本地覆盖：`./docker-data/appsettings.local.json`
-- 后台登录凭据文件：`./docker-data/admin_auth.json`
-
-## 更新方法（Docker 部署）
-
-> 更新前建议先备份：`./docker-data/telegram-panel.db` 与 `./docker-data/`（尤其是重要账号的 sessions）。
-
-在项目目录下执行：
-
-```bash
-git pull --rebase
-docker compose up -d --build
-```
-
-说明：
-
-- `docker compose up -d --build` 会重新构建并滚动更新容器（数据仍在 `./docker-data`，不会丢）
-- 若你修改过 `.env` 或 `./docker-data/appsettings.local.json`，更新后也建议重启一次确保新配置生效
-
-### 更新出错：git pull 提示本地修改会被覆盖
-
-典型报错：
-
-```
-error: Your local changes to the following files would be overwritten by merge:
-        docker-compose.yml
-Please commit your changes or stash them before you merge.
-Aborting
-```
-
-原因：你本地改过 `docker-compose.yml`（很常见：顺手把某个开关写死在 compose 里），导致更新时 Git 不允许直接覆盖。
-
-推荐做法：尽量不要直接改 `docker-compose.yml`：
-
-- Webhook 等部署差异：用 `.env`（参考 `.env.example`）
-- 功能开关/参数：用面板「系统设置」保存到 `./docker-data/appsettings.local.json`
-
-处理方式（两选一）：
-
-1) 放弃本地修改（最快、推荐）
-
-```bash
-git restore docker-compose.yml
-git pull --rebase
-docker compose up -d --build
-```
-
-2) 保留本地修改（自己承担后续合并成本）
-
-```bash
-git stash push -m "local docker-compose" -- docker-compose.yml
-git pull --rebase
-git stash pop
-docker compose up -d --build
-```
-
-如果 `git stash pop` 出现冲突，按提示手动合并 `docker-compose.yml` 后再继续。
-
-### 反向代理（生产环境建议）
-
-如果你用宝塔面板（Nginx）部署，通常**直接用默认反向代理**到面板端口即可：
-
-- 目标 URL：`http://127.0.0.1:5000`（或你 compose 暴露的端口）
-- 记得在宝塔反代设置里开启/勾选 **WebSocket**（Blazor Server 需要）
-- HTTPS 建议在宝塔侧配置证书
-
-更完整的 Nginx/Caddy 配置参考：`docs/reverse-proxy.md`。
-
-### Bot Webhook（可选）
-
-如果你使用 Bot 相关功能并希望用 Webhook（而非长轮询），请先确保：
-
-- 已配置反向代理并能外网访问（HTTPS 强烈建议）
-- 面板访问域名稳定，且能被 Telegram 访问
-
-Webhook 的具体配置项、`.env`/`appsettings.local.json` 覆盖方式请参考 `docs/advanced.md`。
-
-## 其它文档入口
-
-- 反向代理：`docs/reverse-proxy.md`
-- 配置项/环境变量/后台任务：`docs/advanced.md`
-- 同步说明：`docs/sync.md`
-- API 速查：`docs/api.md`
-- 数据库结构：`docs/database.md`
-- 模块系统：`docs/modules.md`
-- 防冻结指南：`docs/anti-freeze.md`
-
-## 本地开发运行（可选）
-
-```bash
-dotnet run --project src/TelegramPanel.Web
-```
-
-## 常见问题
-
-### 发送验证码提示“session 被占用/进程占用”
-
-- 确保不要多开多个面板实例共享同一个 `sessions` 目录（会互相锁文件）
-- 如果刚修改了全局 `ApiId/ApiHash`，建议重启面板再登录
diff --git a/docs/api.md b/docs/reference/api.md
similarity index 100%
rename from docs/api.md
rename to docs/reference/api.md
diff --git a/docs/advanced.md b/docs/reference/configuration.md
similarity index 57%
rename from docs/advanced.md
rename to docs/reference/configuration.md
index c2b3e2a..02534b0 100644
--- a/docs/advanced.md
+++ b/docs/reference/configuration.md
@@ -1,4 +1,4 @@
-# 进阶说明
+# 配置与数据目录
 
 ## 技术栈
 
@@ -68,58 +68,4 @@ Docker 下常用环境变量（见 `docker-compose.yml`）：
 
 ## Bot Webhook 模式（生产环境推荐）
 
-> **💡 提示**：如果你不使用「Bot 频道管理」功能，可以跳过此节。
-
-默认情况下，Bot 使用**长轮询（Long Polling）**模式接收更新。**生产环境建议使用 Webhook 模式**，优势如下：
-
-- ✅ 更低的资源消耗（无需持续轮询）
-- ✅ 更快的响应速度（Telegram 主动推送）
-- ✅ 更适合高流量/多 Bot 场景
-
-### Webhook 配置项
-
-在 `docker-compose.yml` 或 `appsettings.local.json` 中配置：
-
-| 配置项 | 环境变量 | 说明 |
-|--------|----------|------|
-| `Telegram:WebhookEnabled` | `Telegram__WebhookEnabled` | 设为 `true` 启用 Webhook 模式；默认 `false` 使用轮询 |
-| `Telegram:WebhookBaseUrl` | `Telegram__WebhookBaseUrl` | 你的公网 HTTPS 地址（Telegram 要求必须 HTTPS） |
-| `Telegram:WebhookSecretToken` | `Telegram__WebhookSecretToken` | 验证密钥，Telegram 会在请求头中携带此值供校验 |
-| `Telegram:BotAutoSyncEnabled` | `Telegram__BotAutoSyncEnabled` | 设为 `true` 启用自动同步；Bot 加入新频道后自动添加到列表 |
-
-### docker-compose.yml 配置示例
-
-```yaml
-environment:
-  # 启用 Webhook 模式（生产环境推荐）
-  Telegram__WebhookEnabled: "true"
-  # Webhook 公网基础 URL（必须是 HTTPS）
-  Telegram__WebhookBaseUrl: "https://your-domain.com"
-  # Webhook 验证密钥（建议使用随机字符串）
-  Telegram__WebhookSecretToken: "your-random-secret-token"
-  # 启用自动同步（Bot 加入新频道后自动添加到列表）
-  Telegram__BotAutoSyncEnabled: "true"
-```
-
-### 注意事项
-
-- Webhook 模式**必须使用 HTTPS**，Telegram 不支持 HTTP
-- 启用 Webhook 后，系统会**自动在启动时**为所有活跃 Bot 注册 Webhook
-- 如果你使用反向代理，确保 `/api/bot/webhook/*` 路径可以被外部访问
-- 同一个 Bot Token 同时只能使用一种模式（Webhook 或 Long Polling），切换模式会自动覆盖
-- 切换模式后需要重启服务生效
-
-### 反向代理配置
-
-Nginx 示例（确保 Webhook 路径可访问）：
-
-```nginx
-location /api/bot/webhook/ {
-  proxy_pass http://127.0.0.1:5000;
-  proxy_http_version 1.1;
-  proxy_set_header Host $host;
-  proxy_set_header X-Real-IP $remote_addr;
-  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-  proxy_set_header X-Forwarded-Proto $scheme;
-}
-```
+Bot Webhook 的完整配置与注意事项已单独整理：见 [Bot Webhook](../deployment/bot-webhook.md)。
diff --git a/docs/database.md b/docs/reference/database.md
similarity index 100%
rename from docs/database.md
rename to docs/reference/database.md
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..c202df9
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,47 @@
+site_name: Telegram Panel 文档
+site_description: Telegram Panel 使用文档（面向使用者）
+repo_url: https://github.com/moeacgx/Telegram-Panel
+repo_name: moeacgx/Telegram-Panel
+
+docs_dir: docs
+
+exclude_docs: |
+  README.md
+
+theme:
+  name: material
+  language: zh
+  features:
+    - content.code.copy
+    - navigation.sections
+    - navigation.top
+
+plugins:
+  - search
+
+markdown_extensions:
+  - admonition
+  - tables
+  - toc:
+      permalink: true
+
+nav:
+  - 首页: index.md
+  - 快速开始:
+      - 安装部署: getting-started/installation.md
+      - 更新升级: getting-started/update.md
+      - 常见问题: getting-started/faq.md
+  - 使用指南:
+      - 防冻结指南: guides/anti-freeze.md
+      - 账号导入: guides/account-import.md
+      - 同步说明: guides/sync.md
+  - 部署与运维:
+      - 反向代理: deployment/reverse-proxy.md
+      - Bot Webhook: deployment/bot-webhook.md
+  - 参考:
+      - 配置与数据目录: reference/configuration.md
+      - 数据库: reference/database.md
+      - API: reference/api.md
+  - 开发:
+      - 模块开发: developer/modules.md
+      - 文档维护: developer/documentation.md
diff --git a/requirements-docs.txt b/requirements-docs.txt
new file mode 100644
index 0000000..372ffe2
--- /dev/null
+++ b/requirements-docs.txt
@@ -0,0 +1,2 @@
+mkdocs>=1.6
+mkdocs-material>=9.5