{"id":47626973,"url":"https://github.com/fxxkrlab/adminchat_panel","last_synced_at":"2026-04-10T12:01:49.090Z","repository":{"id":345911978,"uuid":"1187823506","full_name":"fxxkrlab/ADMINCHAT_PANEL","owner":"fxxkrlab","description":"Telegram Bot Customer Service Platform - Multi-bot pool, bidirectional messaging, FAQ engine (8 modes + AI), real-time web chat, user management. Python/FastAPI + React/TypeScript + PostgreSQL + Redis. Docker deployable.","archived":false,"fork":false,"pushed_at":"2026-04-10T10:10:11.000Z","size":1030,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T10:11:51.507Z","etag":null,"topics":["admin-panel","ai","chatbot","customer-service","docker","faq","fastapi","postgresql","react","telegram-bot","typescript","websocket"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fxxkrlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T08:06:08.000Z","updated_at":"2026-04-10T10:10:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"979035c1-88a8-4524-8493-c2de995b011d","html_url":"https://github.com/fxxkrlab/ADMINCHAT_PANEL","commit_stats":null,"previous_names":["fxxkrlab/adminchat_panel"],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/fxxkrlab/ADMINCHAT_PANEL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxxkrlab%2FADMINCHAT_PANEL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxxkrlab%2FADMINCHAT_PANEL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxxkrlab%2FADMINCHAT_PANEL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxxkrlab%2FADMINCHAT_PANEL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fxxkrlab","download_url":"https://codeload.github.com/fxxkrlab/ADMINCHAT_PANEL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxxkrlab%2FADMINCHAT_PANEL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31641492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admin-panel","ai","chatbot","customer-service","docker","faq","fastapi","postgresql","react","telegram-bot","typescript","websocket"],"created_at":"2026-04-01T22:51:59.642Z","updated_at":"2026-04-10T12:01:49.084Z","avatar_url":"https://github.com/fxxkrlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[English](./README_EN.md) | 中文\n\n---\n\n\u003c!-- Community \u0026 Status --\u003e\n![GitHub Release](https://img.shields.io/github/v/release/fxxkrlab/ADMINCHAT_PANEL?style=flat-square\u0026color=00D9FF\u0026label=Release)\n![GitHub Stars](https://img.shields.io/github/stars/fxxkrlab/ADMINCHAT_PANEL?style=flat-square\u0026color=FFD700\u0026logo=github)\n![GitHub Forks](https://img.shields.io/github/forks/fxxkrlab/ADMINCHAT_PANEL?style=flat-square\u0026color=8B5CF6\u0026logo=github)\n![GitHub Issues](https://img.shields.io/github/issues/fxxkrlab/ADMINCHAT_PANEL?style=flat-square\u0026color=FF8800\u0026logo=github)\n![GitHub Last Commit](https://img.shields.io/github/last-commit/fxxkrlab/ADMINCHAT_PANEL?style=flat-square\u0026color=059669\u0026logo=github)\n![Build Status](https://img.shields.io/github/actions/workflow/status/fxxkrlab/ADMINCHAT_PANEL/build-and-push.yml?style=flat-square\u0026label=Build\u0026logo=githubactions\u0026logoColor=white)\n![PRs Welcome](https://img.shields.io/badge/PRs-welcome-059669?style=flat-square\u0026logo=git\u0026logoColor=white)\n\n\u003c!-- Tech Stack --\u003e\n![Python](https://img.shields.io/badge/Python-3.12-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white)\n![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-009688?style=flat-square\u0026logo=fastapi\u0026logoColor=white)\n![React](https://img.shields.io/badge/React-18-61DAFB?style=flat-square\u0026logo=react\u0026logoColor=black)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white)\n![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4.x-06B6D4?style=flat-square\u0026logo=tailwindcss\u0026logoColor=white)\n![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-4169E1?style=flat-square\u0026logo=postgresql\u0026logoColor=white)\n![Redis](https://img.shields.io/badge/Redis-7-DC382D?style=flat-square\u0026logo=redis\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?style=flat-square\u0026logo=docker\u0026logoColor=white)\n![Telegram](https://img.shields.io/badge/Telegram-Bot_API-26A5E4?style=flat-square\u0026logo=telegram\u0026logoColor=white)\n![aiogram](https://img.shields.io/badge/aiogram-3.x-2CA5E0?style=flat-square\u0026logo=telegram\u0026logoColor=white)\n![License](https://img.shields.io/badge/License-GPL_3.0-blue?style=flat-square)\n\n\u003c!-- Fun / Vibe --\u003e\n![Vibe Coded](https://img.shields.io/badge/Vibe-Coded_%F0%9F%8E%B6-FF69B4?style=flat-square)\n![Built with AI](https://img.shields.io/badge/Built_with-Claude_AI_%F0%9F%A4%96-8B5CF6?style=flat-square)\n![Made with Love](https://img.shields.io/badge/Made_with-%E2%9D%A4%EF%B8%8F-FF4444?style=flat-square)\n![Powered by Coffee](https://img.shields.io/badge/Powered_by-%E2%98%95_Coffee-6F4E37?style=flat-square)\n\n# ADMINCHAT Panel\n\n\u003e \u0026reg; 2026 NovaHelix \u0026 SAKAKIBARA. All rights reserved.\n\n**Telegram 双向消息转发 Bot + Web 客服管理面板** \u0026mdash; 一站式 Telegram 客户服务解决方案，支持多 Bot 池管理、FAQ 自动回复引擎（5 种匹配模式 + 8 种回复模式）、RAG 知识库检索、AI Provider OAuth 多认证、遗漏关键词过滤器和实时 Web 聊天。\n\n---\n\n## 项目简介\n\nADMINCHAT Panel 是一个功能完备的 Telegram 客服管理系统。它将 Telegram Bot 收到的私聊消息和群组 @提及 消息统一转发到 Web 管理面板，让管理员/客服人员可以在浏览器中实时查看并回复用户消息，同时支持 FAQ 自动回复、AI 智能应答、RAG 知识库检索、用户管理等丰富功能。\n\n## 核心功能\n\n### 消息转发与通信\n- **多 Bot 池管理** \u0026mdash; 支持无限添加 Bot，自动限流检测（Redis 令牌桶算法）与故障转移\n- **双向消息转发** \u0026mdash; 私聊 + 群组 @Bot，文本/图片/视频/文件/Markdown 格式完整保留\n- **Web 实时聊天** \u0026mdash; 基于 WebSocket 的实时消息推送，类似客服系统的聊天界面\n- **Bot 分组 + FAQ 分组路由** \u0026mdash; Bot 按组管理，FAQ 规则按 组-分类 两级归类，匹配后自动选择对应组的 Bot 回复\n\n### FAQ 自动回复引擎\n- **5 种匹配模式** \u0026mdash; 精确匹配 / 前缀匹配 / 包含匹配 / 正则匹配 / Catch All 兜底匹配\n- **8 种回复模式** \u0026mdash; 直接回复 / 纯 AI / AI 润色 / AI 兜底 / AI 意图识别 / 模板填充 / RAG 知识库 / AI 综合回答\n- **遗漏关键词过滤器** \u0026mdash; 可配置过滤规则（4 种匹配模式），自动跳过 Bot 命令等无效关键词，保持遗漏知识点统计的准确性\n- **遗漏知识点分析** \u0026mdash; 自动统计未匹配问题，每日凌晨 3 点更新排行榜\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFAQ 匹配与回复模式详细流程（点击展开）\u003c/strong\u003e\u003c/summary\u003e\n\n#### 整体匹配流程\n\n```mermaid\nflowchart TD\n    A[\"用户发送消息\"] --\u003e B[\"加载所有 is_active=true 的 FAQ 规则\\n按 priority DESC 排序\"]\n    B --\u003e C{\"遍历每条规则的 questions\\n按 match_mode 匹配\"}\n    C --\u003e|\"命中\"| D{\"判断 reply_mode\"}\n    C --\u003e|\"全部未命中\"| E[\"记录到 unmatched_messages\"]\n    E --\u003e F[\"推送到 Web 面板\\n等待人工回复\"]\n    D --\u003e M1[\"direct\"]\n    D --\u003e M2[\"ai_only\"]\n    D --\u003e M3[\"ai_polish\"]\n    D --\u003e M4[\"ai_fallback\"]\n    D --\u003e M5[\"ai_classify_and_answer\"]\n    D --\u003e M6[\"rag\"]\n    D --\u003e M7[\"ai_intent\"]\n    D --\u003e M8[\"ai_template\"]\n```\n\n#### 5 种匹配模式说明\n\n| 模式 | 关键词示例 | 用户输入 \"你好，请问价格多少？\" | 适用场景 |\n|------|-----------|-------------------------------|---------|\n| `exact` | `请问价格多少` | 不匹配（必须完全相同） | 精确控制，如特定指令 |\n| `prefix` | `你好` | 匹配（从头开始） | 问候语、固定开头 |\n| `contains` | `价格` | 匹配（包含即可） | 最常用，关键词触发 |\n| `regex` | `价格\\|多少钱\\|费用` | 匹配（正则匹配） | 多关键词/复杂模式 |\n| `catch_all` | `*`（自动填充） | 匹配（匹配所有消息） | 兜底规则，搭配 RAG/AI |\n\n\u003e **优先级**：`priority` 值越大越先匹配。建议 `catch_all` 设为最低优先级（如 1），确保精确规则优先。\n\n#### 8 种回复模式流程\n\n**1. `direct` — 直接回复**\n```\n用户消息 → FAQ 匹配 → 直接返回预设答案（不调 AI）\n```\n最简单的模式，适合固定回答（如营业时间、联系方式）。\n\n**2. `ai_only` — 纯 AI 回复**\n```\n用户消息 → FAQ 匹配 → 发送用户问题给 AI → AI 生成回答 → 回复用户\n```\nFAQ 规则仅作触发器，回答完全由 AI 生成。适合开放性问题。\n\n**3. `ai_polish` — AI 润色**\n```\n用户消息 → FAQ 匹配 → 取出预设答案 → AI 润色改写 → 回复用户\n```\n预设答案 + AI 改写为更自然的语言。保留核心信息的同时让回复更人性化。\n\n**4. `ai_fallback` — AI 兜底**\n```\n用户消息 → FAQ 匹配 → 有预设答案？\n                        ├── 是 → 直接返回预设答案\n                        └── 否 → AI 生成回答\n```\n优先使用 FAQ 预设答案，没有时才调 AI。节省 AI 调用成本。\n\n**5. `ai_classify_and_answer` — AI 综合回答**\n```\n用户消息 → FAQ 匹配 → 预设答案作为知识上下文 → AI 综合理解后生成回答 → 回复用户\n```\nAI 参考 FAQ 知识库内容，综合理解后生成更完整的回答。\n\n**6. `rag` — RAG 知识库检索**\n```\n用户消息 → FAQ 匹配 → Dify Knowledge API 向量搜索\n          → 返回相关文档片段 → AI 基于检索结果生成回答 → 回复用户\n```\n最强大的模式。从外部知识库检索相关信息，AI 基于检索结果回答。适合大量文档/产品信息场景。\n\n**7. `ai_intent` — AI 意图识别**\n```\n用户消息 → FAQ 匹配 → AI 分析用户意图 → 返回分类结果（JSON）\n```\nAI 将用户问题分类到预定义的类别中，返回 `{\"category\": \"xxx\", \"confidence\": 0.95}` 格式。\n\n**8. `ai_template` — 模板填充**\n```\n用户消息 → FAQ 匹配 → 取出模板（含 {变量} 占位符）→ AI 根据用户问题填充变量 → 回复用户\n```\n预定义回答模板，AI 智能填充变量。适合格式化回答场景。\n\n#### 推荐配置组合\n\n| 场景 | 匹配模式 | 回复模式 | 说明 |\n|------|---------|---------|------|\n| 固定 FAQ | `contains` / `regex` | `direct` | 营业时间、联系方式等 |\n| 产品咨询 | `regex` | `ai_polish` | AI 润色预设答案，更自然 |\n| 知识库问答 | `catch_all` (低优先级) | `rag` | 兜底走知识库检索 |\n| 通用客服 | `catch_all` (最低优先级) | `ai_only` | 所有未匹配消息交给 AI |\n| 混合模式 | 高优先级 `contains` + 低优先级 `catch_all` | `direct` + `rag` | 精确匹配优先，未匹配走 RAG |\n\n\u003c/details\u003e\n\n### AI 与知识库\n- **RAG 知识库检索** \u0026mdash; 模块化 RAG 架构，已对接 Dify Knowledge API（支持 GTE-multilingual + pgvector），模块化 `rag_configs` 配置，可扩展其他 RAG 平台\n- **AI Provider OAuth 多认证** \u0026mdash; 支持 API Key / OpenAI OAuth / Claude OAuth / Claude Session Token / Gemini OAuth 五种认证方式，自动 Token 刷新\n- **AI 集成** \u0026mdash; 兼容 OpenAI API 格式，支持多 AI 服务商配置\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eRAG 知识库推荐配置指南（点击展开）\u003c/strong\u003e\u003c/summary\u003e\n\n#### 完整 RAG 客服流程\n\n```\n用户在 Telegram 发消息\n  → ADMINCHAT Bot 收到消息\n  → FAQ Engine 匹配规则（reply_mode=rag）\n  → 调 Dify Knowledge API（把用户问题发过去）\n  → Dify 用 GTE-multilingual-base 把问题转成向量\n  → pgvector 向量搜索，找到最相关的知识库内容\n  → 返回搜索结果给 ADMINCHAT\n  → ADMINCHAT 调 AI API（搜索结果 + 用户问题）\n  → AI 根据知识库内容生成自然语言回答\n  → Bot 回复用户\n```\n\n各组件职责：\n\n| 组件 | 职责 |\n|------|------|\n| **Dify** | 知识库管理 + 向量搜索（只搜不答） |\n| **GTE-multilingual-base** | Embedding 模型（文字→向量，可跑在 CPU 上） |\n| **pgvector**（PostgreSQL 扩展） | 存储和检索向量 |\n| **AI API**（外部，如 GPT/Claude） | 生成最终回答（基于知识库内容润色） |\n| **ADMINCHAT Panel** | 串联所有组件 + Telegram Bot 管理 |\n\n#### 第 1 步：部署 Dify\n\n推荐使用 Dify 官方 Docker Compose 部署。\n\n```bash\n# 克隆 Dify\ngit clone https://github.com/langgenius/dify.git\ncd dify/docker\n\n# 复制环境变量\ncp .env.example .env\n\n# 启动（包含 PostgreSQL + pgvector + Redis + Dify API + Web）\ndocker compose up -d\n```\n\n启动后访问 `http://your-server-ip` 完成 Dify 初始化设置。\n\n\u003e **进阶**：如果你已有 PostgreSQL（带 pgvector 扩展）和 Redis，可以通过 `docker-compose.override.yaml` 禁用 Dify 自带的数据库组件，让 Dify 连接你现有的服务。参考 Dify 官方文档的外部数据库配置说明。\n\n#### 第 2 步：部署 Text Embedding Inference (TEI)\n\nGTE-multilingual-base 是推荐的多语言 Embedding 模型，约 1.1GB，可以在 CPU 上运行。通过 Hugging Face TEI 容器部署。\n\n**方法 A：自动下载模型（简单，但首次启动慢）**\n\n```bash\ndocker run -d \\\n  --name gte-embedding \\\n  --restart unless-stopped \\\n  -p 8090:80 \\\n  -v tei-data:/data \\\n  ghcr.io/huggingface/text-embeddings-inference:cpu-1.6 \\\n  --model-id Alibaba-NLP/gte-multilingual-base \\\n  --port 80\n```\n\n\u003e 首次启动会自动从 Hugging Face 下载模型，可能需要几分钟。\n\n**方法 B：预下载模型到本地（推荐，启动更快）**\n\n```bash\n# 先下载模型到本地目录\nmkdir -p /opt/models\npip install huggingface_hub\nhuggingface-cli download Alibaba-NLP/gte-multilingual-base \\\n  --local-dir /opt/models/gte-multilingual-base\n\n# 启动 TEI 容器，挂载本地模型目录\ndocker run -d \\\n  --name gte-embedding \\\n  --restart unless-stopped \\\n  -p 8090:80 \\\n  -v /opt/models/gte-multilingual-base:/model \\\n  ghcr.io/huggingface/text-embeddings-inference:cpu-1.6 \\\n  --model-id /model \\\n  --port 80\n```\n\n**验证 TEI 是否正常运行：**\n\n```bash\ncurl http://localhost:8090/embed \\\n  -X POST \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"inputs\": \"测试文本\"}'\n```\n\n**将 TEI 加入 Docker 网络（与 Dify 互通）：**\n\n```bash\n# 如果 Dify 使用默认网络 docker_default\ndocker network connect docker_default gte-embedding\n\n# 或者如果你用了自定义网络\ndocker network connect your-shared-network gte-embedding\n```\n\n#### 第 3 步：在 Dify 中安装 TEI 插件并配置\n\n1. 登录 Dify 管理后台 → **插件 (Plugins)**\n2. 搜索 `Text Embedding Inference` → 安装\n3. 进入 **设置** → **模型供应商** → 找到 **Text Embedding Inference**\n4. 配置：\n   - **模型名称**: `gte-multilingual-base`（标识用，可自定义）\n   - **服务器 URL**: `http://gte-embedding:80`（Docker 内部网络名称）\n5. 保存并测试连接\n\n\u003e **注意**：TEI 容器名称就是 Docker 内部 DNS 名称。只要两者在同一个 Docker 网络内，就可以用容器名直接访问。\n\n#### 第 4 步：创建知识库并导入文档\n\n1. 进入 Dify → **知识库** → **创建知识库**\n2. 选择 Embedding 模型为 `gte-multilingual-base`\n3. 上传文档（支持 TXT、PDF、Markdown、CSV 等）\n4. Dify 会自动分段、向量化并存入 pgvector\n5. 创建完成后，记录：\n   - **Dataset ID**：知识库 URL 中的 UUID（如 `datasets/abc123-def456/...` 中的 `abc123-def456`）\n\n#### 第 5 步：获取 Dify API 凭证\n\n1. 进入 Dify → **知识库** → 选择你的知识库\n2. 进入 **API 访问** 或 **设置**\n3. 获取 **Dataset API Key**（格式为 `dataset-xxxxxxxx`）\n4. 记录 Dify API 内部地址：`http://\u003cdify-api容器名\u003e:5001/v1`（Docker 内部）\n\n\u003e Dify API 容器默认监听 5001 端口。容器名可通过 `docker ps | grep dify-api` 查看（通常为 `docker-api-1`）。\n\n#### 第 6 步：在 ADMINCHAT Panel 中配置 RAG\n\n1. 登录 ADMINCHAT 管理面板\n2. 进入 **AI Settings** → **RAG Knowledge Base** 标签页\n3. 点击 **Add RAG Config**，填写：\n   - **Name**: 自定义名称（如 \"产品知识库\"）\n   - **Provider**: `dify`\n   - **Base URL**: Dify API 内部地址（如 `http://docker-api-1:5001/v1`）\n   - **API Key**: Dataset API Key（`dataset-xxxxxxxx`）\n   - **Dataset ID**: 知识库 UUID\n   - **Top K**: `3`（返回前 3 条最相关结果）\n4. 点击 **Test** 验证连接\n5. 保存\n\n\u003e **重要**：ADMINCHAT 后端容器必须与 Dify API 容器在同一个 Docker 网络内，否则无法通过容器名访问。\n\n#### 第 7 步：配置 FAQ 规则使用 RAG\n\n1. 进入 **FAQ Rules** → 创建或编辑规则\n2. 设置 **Reply Mode** 为 `rag`\n3. 选择刚创建的 **RAG Config**\n4. 推荐搭配 `catch_all` 匹配模式作为兜底规则（低 priority），让所有未被其他规则命中的消息走 RAG\n\n#### 推荐部署架构\n\n```\n┌───────────────────────────────────────────────────────┐\n│  Docker Host                                           │\n│                                                         │\n│  ┌── 共享 Docker Network ──────────────────────────┐   │\n│  │                                                   │   │\n│  │  ┌──────────────┐   ┌────────────────────────┐   │   │\n│  │  │ ADMINCHAT    │   │ Dify                    │   │   │\n│  │  │  backend     │──→│  api (:5001)            │   │   │\n│  │  │  frontend    │   │  web                    │   │   │\n│  │  └──────────────┘   │  worker                 │   │   │\n│  │                      │  plugin_daemon          │   │   │\n│  │  ┌──────────────┐   └────────────────────────┘   │   │\n│  │  │ TEI Server   │                                 │   │\n│  │  │ gte-multi    │   ┌────────────────────────┐   │   │\n│  │  │ (:80/8090)   │   │ PostgreSQL + pgvector   │   │   │\n│  │  └──────────────┘   │ Redis                   │   │   │\n│  │                      └────────────────────────┘   │   │\n│  └───────────────────────────────────────────────────┘   │\n│                                                           │\n│                ┌─────────────────────┐                    │\n│                │ AI API (外部)       │                    │\n│                │ GPT / Claude / etc. │                    │\n│                └─────────────────────┘                    │\n└───────────────────────────────────────────────────────┘\n```\n\n\u003e **提示**：所有组件（ADMINCHAT、Dify、TEI、PostgreSQL、Redis）通过同一个 Docker bridge 网络互通，使用容器名作为 DNS 地址通信。这样无需暴露额外端口，更快更安全。\n\n\u003c/details\u003e\n\n### 插件系统 (Plugin System)\n- **ACP 插件架构** \u0026mdash; 沙箱化插件运行时，支持数据库/Bot Handler/API 路由/前端页面/设置面板五种能力声明，插件内部模块自动路径隔离\n- **热更新模块缓存** \u0026mdash; 停用插件时精确清除其在 `sys.modules` 中的全部子模块（含 `backend.routes` 等）以及插件目录下任何运行期惰性导入的模块；重新启用后立刻读取磁盘上的最新代码，无需重启面板容器\n- **跨插件命名空间隔离** \u0026mdash; 启用插件前主动清理与其顶层包同名的缓存条目（例如两个插件都自带 `backend/`），避免后启用的插件被先启用的插件遮蔽；同时启用同名插件会有警告\n- **事务化挂载** \u0026mdash; 插件激活的 mount + setup 阶段是事务性的，`setup()` 抛错会回滚已挂载的 API 路由 / Bot Router / 静态文件 / 事件订阅，避免半挂载状态\n- **ACP Market 集成** \u0026mdash; 通过 [ACP Market](https://acpmarket.novahelix.org) 浏览、安装和管理第三方插件，安装成功/失败有即时通知提示，未连接 Market 时自动显示引导提示\n- **Market JWT 认证** \u0026mdash; 支持邮箱密码登录或 API Key 粘贴连接 Market，Bearer Token 自动管理，Settings 页面显示 Market 账户状态\n- **Ed25519 插件签名验证** \u0026mdash; 自动从 Market 获取公钥，下载插件时验证 Ed25519 签名，防止插件包被篡改\n- **卸载确认与数据清理** \u0026mdash; 卸载插件前弹出确认对话框，可选\"删除所有插件数据（数据库表）\"\n- **插件设置快捷入口** \u0026mdash; 已安装插件列表中带有设置面板的插件显示齿轮图标，点击直接跳转到对应设置标签页\n- **插件数据持久化** \u0026mdash; 插件文件存储在独立的 `/data/plugins` 卷中，容器重启后不会丢失；加载失败时自动显示错误信息和重试按钮\n- **共享依赖架构** \u0026mdash; Panel 通过 `window` 全局变量向插件提供 React / ReactDOM / TanStack Query 等共享依赖，插件以 IIFE 格式构建，避免双 React 实例和模块解析问题\n- **Plugin SDK + CLI** \u0026mdash; [acp-plugin-sdk](https://github.com/fxxkrlab/acp-plugin-sdk) 提供类型提示 + `acp-cli` 命令行工具，支持 init / validate / build / publish 全流程\n- **官方插件仓库** \u0026mdash; [ACP_PLUGINS](https://github.com/fxxkrlab/ACP_PLUGINS) 开源示例插件（如 TMDB 求片系统）\n\n### 用户与安全\n- **用户管理** \u0026mdash; 标签/分组/拉黑/搜索，完整的 TG 用户信息展示\n- **Cloudflare Turnstile** \u0026mdash; 私聊用户人机验证，防止滥用\n- **角色权限系统** \u0026mdash; Super Admin / Admin / Agent 三级权限，细粒度权限控制\n- **操作审计日志** \u0026mdash; 关键操作自动记录，可追溯\n\n### 主题与界面\n- **双主题系统** \u0026mdash; 暗色（默认）+ 亮色主题，所有颜色基于 CSS 变量，一键切换，记忆偏好\n- **毛玻璃效果** \u0026mdash; 侧栏/顶栏/卡片支持 `backdrop-blur` 毛玻璃效果（亮色主题下更明显）\n- **流动渐变背景** \u0026mdash; 亮色主题专属动态渐变光斑背景\n\n### 部署与运维\n- **Docker 一键部署** \u0026mdash; `docker compose up` 即可运行，支持 GHCR 镜像发布\n- **全局 Error Boundary** \u0026mdash; 前端运行时错误优雅降级，不影响整体系统可用性\n\n## 界面预览\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/designs/3.jpg\" width=\"45%\" alt=\"Dashboard\" /\u003e\n  \u003cimg src=\"docs/designs/2.jpg\" width=\"45%\" alt=\"Chat\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/designs/4.jpg\" width=\"45%\" alt=\"Bot Pool\" /\u003e\n  \u003cimg src=\"docs/designs/7.jpg\" width=\"45%\" alt=\"FAQ Editor\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/designs/6.jpg\" width=\"45%\" alt=\"Users\" /\u003e\n  \u003cimg src=\"docs/designs/5.jpg\" width=\"45%\" alt=\"Settings\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/designs/1.jpg\" width=\"45%\" alt=\"Login\" /\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e技术架构（点击展开）\u003c/strong\u003e\u003c/summary\u003e\n\n```mermaid\ngraph TB\n    subgraph 前端 Frontend\n        React[\"React 18 + TypeScript\"]\n        Tailwind[\"Tailwind CSS + shadcn/ui\"]\n        Vite[\"Vite 构建\"]\n    end\n\n    subgraph 后端 Backend\n        FastAPI[\"FastAPI (async)\"]\n        aiogram[\"aiogram 3 (多Bot)\"]\n        SQLAlchemy[\"SQLAlchemy 2.0\"]\n        APScheduler[\"APScheduler 定时任务\"]\n        OAuthModule[\"OAuth 2.0 + PKCE\"]\n    end\n\n    subgraph 存储 Storage\n        PostgreSQL[(\"PostgreSQL 16\")]\n        Redis[(\"Redis 7\")]\n    end\n\n    subgraph 外部服务 External\n        TelegramAPI[\"Telegram Bot API\"]\n        CloudflareAPI[\"Cloudflare Turnstile\"]\n        AIAPI[\"AI API (OpenAI 兼容)\"]\n        DifyAPI[\"Dify Knowledge API\"]\n        OAuthProviders[\"OAuth Providers\\n(OpenAI/Claude/Gemini)\"]\n    end\n\n    React --\u003e|\"REST API + WebSocket\"| FastAPI\n    FastAPI --\u003e aiogram\n    FastAPI --\u003e SQLAlchemy\n    FastAPI --\u003e OAuthModule\n    SQLAlchemy --\u003e PostgreSQL\n    FastAPI --\u003e Redis\n    aiogram --\u003e|\"Bot API\"| TelegramAPI\n    FastAPI --\u003e|\"人机验证\"| CloudflareAPI\n    FastAPI --\u003e|\"AI 回复\"| AIAPI\n    FastAPI --\u003e|\"RAG 检索\"| DifyAPI\n    OAuthModule --\u003e|\"OAuth 2.0 + PKCE\"| OAuthProviders\n```\n\n#### 消息路由流程\n\n```mermaid\nflowchart LR\n    A[\"TG 用户\"] --\u003e|\"私聊 / 群@ Bot\"| B[\"Bot 池\"]\n    B --\u003e|\"存储 + Redis 发布\"| C[\"PostgreSQL + Redis\"]\n    C --\u003e|\"WebSocket 推送\"| D[\"Web 管理面板\"]\n    D --\u003e|\"管理员回复\"| E{\"Bot 调度器\"}\n    E --\u003e|\"优先原路 Bot\"| F[\"Bot1\"]\n    E --\u003e|\"限流时故障转移\"| G[\"Bot2 / Bot3\"]\n    F \u0026 G --\u003e|\"reply 用户消息\"| A\n```\n\n#### FAQ 匹配与回复流程\n\n```mermaid\nflowchart TB\n    MSG[\"用户消息\"] --\u003e FILTER{\"遗漏关键词过滤器\"}\n    FILTER --\u003e|\"命中过滤规则\"| SKIP[\"跳过 (不记录遗漏)\"]\n    FILTER --\u003e|\"未命中过滤\"| MATCH{\"FAQ 匹配引擎\"}\n    MATCH --\u003e|\"exact 精确匹配\"| HIT[\"命中规则\"]\n    MATCH --\u003e|\"prefix 前缀匹配\"| HIT\n    MATCH --\u003e|\"contains 包含匹配\"| HIT\n    MATCH --\u003e|\"regex 正则匹配\"| HIT\n    MATCH --\u003e|\"catch_all 兜底匹配\"| HIT\n    MATCH --\u003e|\"全部未命中\"| MISSED[\"记入遗漏知识点\"]\n    HIT --\u003e REPLY{\"回复模式\"}\n    REPLY --\u003e DIRECT[\"direct 直接回复\"]\n    REPLY --\u003e AI[\"ai_only / ai_polish / ai_fallback\"]\n    REPLY --\u003e INTENT[\"ai_intent 意图识别\"]\n    REPLY --\u003e RAG[\"rag 知识库检索\"]\n    REPLY --\u003e CLASSIFY[\"ai_classify_and_answer 综合回答\"]\n```\n\n#### AI Provider OAuth 认证流程\n\n```mermaid\nflowchart TB\n    U[\"管理员\"] --\u003e|\"选择认证方式\"| S{\"认证方式选择\"}\n    S --\u003e|\"API Key\"| K[\"手动填写 Key\"]\n    S --\u003e|\"OpenAI/Gemini OAuth\"| P[\"弹窗登录 → 自动回调\"]\n    S --\u003e|\"Claude OAuth\"| C[\"打开链接 → 粘贴 Code\"]\n    S --\u003e|\"Claude Session Token\"| T[\"粘贴 Cookie\"]\n    K \u0026 P \u0026 C \u0026 T --\u003e|\"access_token 存入 api_key 字段\"| DB[\"AiConfig 记录\"]\n    DB --\u003e|\"每 5 分钟检查过期\"| R[\"自动刷新 Token\"]\n    R --\u003e|\"更新 api_key\"| DB\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e数据库结构与功能参考表（点击展开）\u003c/strong\u003e\u003c/summary\u003e\n\n### 数据库结构\n\n| 表名 | 说明 | 核心字段 |\n|------|------|---------|\n| `admins` | 管理员/客服 | username, role, permissions (JSONB) |\n| `tg_users` | Telegram 用户 | tg_uid, is_blocked, turnstile_verified_at |\n| `bots` | Bot 池 | token, priority, is_rate_limited |\n| `conversations` | 会话 | status, source_type, assigned_to |\n| `messages` | 消息记录 | direction, content_type, faq_matched |\n| `tg_groups` | Telegram 群组 | tg_chat_id, title |\n| `tags` / `user_tags` | 用户标签 | name, color (多对多) |\n| `user_groups` | 用户分组 | name, description |\n| `faq_questions` | FAQ 问题/关键词 | keyword, match_mode |\n| `faq_answers` | FAQ 答案 | content, content_type |\n| `faq_rules` | FAQ 规则 | response_mode, reply_mode, category_id |\n| `faq_groups` | FAQ 分组 (一级) | name, bot_group_id |\n| `faq_categories` | FAQ 分类 (二级) | name, faq_group_id, bot_group_id |\n| `faq_hit_stats` | FAQ 命中统计 | hit_count, date |\n| `missed_keywords` | 遗漏知识点 | keyword, occurrence_count |\n| `missed_keyword_filters` | 遗漏关键词过滤器 | pattern, match_mode (exact/prefix/contains/regex) |\n| `bot_groups` | Bot 分组 | name, description |\n| `bot_group_members` | Bot 分组成员 | bot_group_id, bot_id (唯一) |\n| `ai_configs` | AI 配置 | base_url, api_key, model, auth_method, oauth_data |\n| `ai_usage_logs` | AI 用量日志 | tokens_used, cost_estimate |\n| `rag_configs` | RAG 知识库配置 | provider, base_url, api_key, dataset_id, top_k, is_active |\n| `installed_plugins` | 已安装插件 | plugin_id, version, status, config |\n| `plugin_secrets` | 插件密钥存储 | plugin_id, key, encrypted_value |\n| `system_settings` | 系统设置 | key-value (JSONB) |\n| `audit_logs` | 审计日志 | action, target_type, details |\n\n\u003e 共 34 张表，完整设计参见 [docs/DATABASE_DESIGN.md](docs/DATABASE_DESIGN.md)\n\n## FAQ 匹配模式\n\n| 匹配模式 | 代码标识 | 说明 |\n|---------|---------|------|\n| 精确匹配 | `exact` | 用户消息与关键词完全一致时命中 |\n| 前缀匹配 | `prefix` | 用户消息以关键词开头时命中 |\n| 包含匹配 | `contains` | 用户消息包含关键词时命中 |\n| 正则匹配 | `regex` | 用户消息满足正则表达式时命中 |\n| 兜底匹配 | `catch_all` | 匹配任何消息，用于 RAG 知识库兜底规则（最低优先级） |\n\n## FAQ 回复模式\n\n| 模式 | 代码标识 | 说明 |\n|------|---------|------|\n| 纯正则匹配 | `direct` | 关键词匹配后直接返回预设答案 |\n| 纯 AI 回复 | `ai_only` | 用户问题直接交给 AI（有次数限制） |\n| AI 润色 | `ai_polish` | 匹配预设答案后让 AI 改写更自然 |\n| AI 兜底 | `ai_fallback` | 先走 FAQ，未命中再交 AI |\n| AI 意图识别 | `ai_intent` | AI 分析意图后路由到对应 FAQ 分类 |\n| 模板填充 | `ai_template` | 预设模板 + AI 动态填充变量 |\n| RAG 知识库 | `rag` | 向量检索 (Dify/pgvector) + AI 综合回答 |\n| AI 综合回答 | `ai_classify_and_answer` | AI 参考 FAQ 知识库综合生成回答 |\n\n## 遗漏关键词过滤器\n\n遗漏关键词过滤器位于「遗漏知识点」页面（`/faq/missed`），用于过滤不需要记录为遗漏知识点的消息（如 Bot 命令 `/start`、`/help` 等）。\n\n| 过滤模式 | 说明 | 示例 |\n|---------|------|------|\n| `exact` | 精确匹配 | 过滤 `/start` 仅匹配完全等于 `/start` 的消息 |\n| `prefix` | 前缀匹配 | 过滤 `/` 匹配所有以 `/` 开头的 Bot 命令 |\n| `contains` | 包含匹配 | 过滤 `bot` 匹配所有包含 `bot` 的消息 |\n| `regex` | 正则匹配 | 过滤 `^/\\w+` 匹配所有斜杠命令格式的消息 |\n\n## AI Provider 认证方式\n\n| 方式 | 流程 | 说明 |\n|------|------|------|\n| API Key | 手动填写 | 传统方式，直接输入 Base URL + API Key |\n| OpenAI OAuth | 弹窗登录 | OAuth 2.0 + PKCE，浏览器弹窗认证后自动回调 |\n| Claude OAuth | 粘贴 Code | OAuth 2.0 + PKCE，Claude 固定回调页面显示 code，手动粘贴 |\n| Claude Session Token | 粘贴 Cookie | 从 claude.ai 复制 sessionKey cookie，后端自动换取 token |\n| Gemini OAuth | 弹窗登录 | Google OAuth 2.0 + PKCE，浏览器弹窗认证后自动回调 |\n\n\u003e Token 自动刷新：后台每 5 分钟检查即将过期的 OAuth token 并自动续期，服务启动时也会补偿刷新。\n\n\u003c/details\u003e\n\n## 快速开始\n\n```bash\n# 克隆仓库\ngit clone https://github.com/fxxkrlab/ADMINCHAT_PANEL.git\ncd ADMINCHAT_PANEL/deploy\n\n# 配置环境变量\ncp .env.example .env\nnano .env  # 修改密码、Bot Token、域名等\n\n# 一键启动 (包含 PostgreSQL + Redis + Nginx)\ndocker compose -f docker-compose.full.yml up -d\n\n# 访问 http://服务器IP\n# 默认账号: admin / 密码见 .env 中的 INIT_ADMIN_PASSWORD\n```\n\n## 安装方式\n\n详细部署文档见 [`deploy/README.md`](deploy/README.md)\n\n| 方式 | 文件 | 适用场景 |\n|------|------|---------|\n| Docker Run | [`deploy/docker-run.sh`](deploy/docker-run.sh) | 已有 PG+Redis，只部署应用 |\n| Compose 独立版 | [`deploy/docker-compose.standalone.yml`](deploy/docker-compose.standalone.yml) | 已有 PG+Redis，Compose 管理 |\n| Compose 一键版 | [`deploy/docker-compose.full.yml`](deploy/docker-compose.full.yml) | 全新服务器，一键全部 |\n\n每种方式都支持 **Named Volume**（Docker 管理）和 **Bind Mount**（映射宿主机目录），在 yml 文件注释中切换。\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e项目结构（点击展开）\u003c/strong\u003e\u003c/summary\u003e\n\n```\nADMINCHAT_PANEL/\n├── backend/                    # Python 后端\n│   ├── app/\n│   │   ├── api/v1/            # REST API 路由 (18 个模块)\n│   │   ├── bot/               # Telegram Bot 核心\n│   │   │   ├── manager.py     # 多 Bot 生命周期管理\n│   │   │   ├── handlers/      # 消息处理器 (私聊/群组/指令)\n│   │   │   ├── dispatcher.py  # 消息发送 + 故障转移\n│   │   │   └── rate_limiter.py# 限流检测 (Redis 令牌桶)\n│   │   ├── faq/               # FAQ 引擎\n│   │   │   ├── engine.py      # 匹配引擎 (5 种匹配模式)\n│   │   │   ├── ai_handler.py  # AI 回复处理 (8 种回复模式)\n│   │   │   ├── rag_handler.py # RAG 兼容 wrapper\n│   │   │   └── rag/           # 模块化 RAG 系统\n│   │   │       ├── base.py    # RAGProvider 抽象基类\n│   │   │       └── dify_provider.py  # Dify Knowledge API\n│   │   ├── oauth/             # OAuth 2.0 多认证\n│   │   │   ├── base.py        # OAuthProvider 抽象基类\n│   │   │   ├── encryption.py  # Fernet Token 加密\n│   │   │   ├── openai.py      # OpenAI OAuth + PKCE\n│   │   │   ├── claude.py      # Claude OAuth + Session Token\n│   │   │   ├── gemini.py      # Gemini/Google OAuth + PKCE\n│   │   │   └── token_refresh.py # 自动 Token 刷新任务\n│   │   ├── models/            # SQLAlchemy ORM (30 张表)\n│   │   ├── schemas/           # Pydantic 请求/响应模型\n│   │   ├── services/          # 业务服务 (Redis/审计/媒体/Turnstile)\n│   │   ├── ws/                # WebSocket 实时通信\n│   │   └── tasks/             # 定时任务 (APScheduler)\n│   ├── alembic/               # 数据库迁移\n│   └── Dockerfile\n├── frontend/                   # React 前端\n│   ├── src/\n│   │   ├── pages/             # 16 个页面\n│   │   ├── components/        # 可复用组件 (chat/layout/ui/ai)\n│   │   │   ├── ai/           # OAuth 认证组件\n│   │   │   │   ├── AuthMethodSelector.tsx  # 认证方式选择器\n│   │   │   │   └── OAuthFlowModal.tsx      # OAuth 流程弹窗\n│   │   │   └── ErrorBoundary.tsx  # 全局错误边界\n│   │   ├── stores/            # Zustand 状态管理\n│   │   ├── services/          # API 调用层 (11 个模块)\n│   │   ├── hooks/             # 自定义 hooks (WebSocket/debounce)\n│   │   └── types/             # TypeScript 类型定义\n│   └── Dockerfile\n├── deploy/                     # 部署配置\n├── docs/                       # 设计文档\n├── docker-compose.yml          # 本地开发 (仅 PG+Redis)\n├── .env.example\n└── LICENSE                     # GPL-3.0\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e开发指南（点击展开）\u003c/strong\u003e\u003c/summary\u003e\n\n### 后端开发\n\n```bash\ncd backend\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n\n# 需要 PostgreSQL 和 Redis 运行中\n# 可以用 docker compose up postgres redis -d 启动\n\n# 运行数据库迁移\nalembic upgrade head\n\n# 启动开发服务器\nuvicorn app.main:app --reload --port 8000\n```\n\n### 前端开发\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n# 访问 http://localhost:5173\n```\n\n### 代码规范\n\n- 后端全部使用异步（`async def` / `await`），SQLAlchemy 2.0 风格 + async session\n- 前端使用函数式组件 + Hooks，Zustand 管理全局状态，TanStack Query 管理服务端状态\n- 数据库查询注意使用 `joinedload` / `selectinload` 避免 N+1 问题\n- Pydantic Schema 使用 `default_factory` 处理可变默认值（如 `list`、`dict`）\n\n\u003c/details\u003e\n\n## 版本说明\n\n- **公开版本**: `VERSION` 文件 (semver 格式)\n- **内部版本**: `BUILD_VERSION` 文件 (格式 YYYYMMDD.NNNN)\n- 页脚显示: `Powered By ADMINCHAT PANEL v{VERSION} ({BUILD_VERSION})`\n\n## 许可证\n\n本项目采用 [GNU General Public License v3.0](LICENSE) 开源。\n\n**版权所有 \u0026copy; 2026 NovaHelix \u0026 SAKAKIBARA**\n\n你可以自由使用、修改和分发本软件，但必须：\n- 保持开源（不可闭源商用，版权所有者除外）\n- 保留原始版权声明\n- 使用相同的 GPL-3.0 许可证\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csmall\u003e\u0026reg; 2026 NovaHelix \u0026 SAKAKIBARA\u003c/small\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxxkrlab%2Fadminchat_panel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffxxkrlab%2Fadminchat_panel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxxkrlab%2Fadminchat_panel/lists"}