1Panel-dev/MaxKB · 上手攻略

• 仓库：1Panel-dev/MaxKB
• 链接：https://github.com/1Panel-dev/MaxKB
• 分类：agent, rag, database, llm-infra
• 作者：Tom
• 更新：2026-07-05

这是什么

MaxKB = Max Knowledge Brain，是一款开箱即用的企业级智能体平台，核心定位是让企业无需深厚 AI 技术背景，也能快速搭建私有化知识库问答、智能客服、复杂流程自动化 Agent。

它整合了 RAG（检索增强生成）管道、工作流引擎、MCP（Model Context Protocol）工具调用三大能力，同时支持国内外数十种大模型（DeepSeek、Qwen、Llama、通义千问、腾讯混元、OpenAI、Claude 等），前端 Vue.js + 后端 Django + LangChain + PostgreSQL/pgvector，技术栈清晰，私有化部署只需一条 Docker 命令。

GPL-3.0 开源，来自 1Panel 团队（FIT2CLOUD），周增 Stars +833，成熟度 production，适合企业落地。

解决什么问题

1. 企业 AI 落地门槛高：不需要写代码，拖拽工作流、传文档、配模型，就能搭出一个可用的 AI 知识库问答系统。
2. RAG 效果差：MaxKB 提供完整 RAG 管道——文档上传/爬取、自动分块、向量化、混合检索，减少大模型幻觉。
3. 复杂业务流程无法自动化：传统 FAQ 机器人处理不了多轮对话、条件分支、工具调用，MaxKB 工作流引擎支持编排复杂 AI 流程。
4. 模型绑定：支持私有模型（DeepSeek、Qwen、Llama）和公有模型，不被单一供应商绑定。
5. 嵌入已有系统：通过 iframe 嵌入或 API 调用，把 AI 能力快速集成进现有 CRM、帮助中心等业务系统，零代码。

快速安装

前提

• Linux / macOS / Windows，Docker 已安装

Docker 一键启动（推荐）

# 国际用户
docker run -d --name=maxkb --restart=always \
  -p 8080:8080 \
  -v ~/.maxkb:/opt/maxkb \
  1panel/maxkb

# 国内用户（镜像不同）
docker run -d --name=maxkb --restart=always \
  -p 8080:8080 \
  -v ~/.maxkb:/opt/maxkb \
  registry.fit2cloud.com/maxkb/maxkb

⚠️ 注意：国内用户如果遇到 Docker 镜像拉取失败，参考 离线安装文档。

访问

• 地址：http://your_server_ip:8080
• 用户名：admin
• 密码：MaxKB@123..

⚠️ 首次登录请立即修改默认密码。

其他安装方式

• 1Panel 应用商店：在 1Panel 面板中搜索 MaxKB，一键部署。
• 离线安装包：内网环境用户从 社区下载页 获取离线包。

硬件建议

核心用法

1. 创建知识库（RAG Pipeline）

Step 1：上传文档

支持： - 直接上传（PDF、Word、TXT、Markdown、Excel 等） - 自动爬取在线文档（URL 输入）

Step 2：配置向量化模型

在「模型设置」中选择 Embedding 模型（如 m3e、text2vec 等），文档会被切成块并向量化存入 pgvector。

Step 3：创建应用（应用 = 一个 AI 问答机器人）

• 关联知识库
• 选择 LLM（支持 DeepSeek、Qwen、OpenAI、Claude 等）
• 配置检索策略（关键词 + 向量混合检索）
• 保存后即可对话

API 嵌入（零代码集成到业务系统）：

MaxKB 为每个应用生成 API Token，通过 REST API 把问答能力嵌入任何页面：

# 调用示例（需要先获取 API Token）
curl -X POST https://your-maxkb-server/api/v1/chat/completion \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-app-id",
    "query": "你们的退换货政策是什么？"
  }'

2. 工作流编排（Agentic Workflow）

MaxKB 内置可视化工作流编辑器，支持：

• 节点类型：LLM 调用、代码执行、HTTP 请求、向量检索、条件分支、循环、变量
• MCP 工具调用：接入 MCP Server，扩展工作流能调用的外部工具（数据库查询、CRM 读取等）
• 多轮对话状态管理：工作流内保持上下文记忆

典型工作流示例：用户提问 → 检索知识库 → 判断是否命中 → 命中则返回答案 + 推荐问题；未命中 → 转人工客服。

3. MCP 集成

MaxKB 支持作为 MCP Server 使用，让外部 AI 助手（如 Claude Desktop）调用 MaxKB 管理的知识库能力。

⚠️ MCP 配置细节请参考 MaxKB 官方文档。

4. 多模型支持（配置示例）

在「系统设置 → 模型」中添加模型，MaxKB 支持：

配置时填入 API Key 和 API Base URL（部分模型需要）。

5. 权限与用户管理

支持多用户、角色权限控制，适合企业内部门禁场景（客服部只能访问特定知识库）。

典型适用场景

1. 企业内知识库：把公司 Confluence、Notion、内部文档上传后，员工作为内部 AI 助手使用，减少重复提问。
2. 智能客服：替代传统 FAQ 机器人，支持多轮对话、意图识别、上下文记忆，接入网站后 7×24 响应。
3. 业务流程自动化：用工作流编排复杂操作，如：订单查询 → 查库存 → 判断是否预售 → 返回不同话术。
4. 教育/学术知识库：上传课程资料、论文，搭建专业领域的 AI 助教。
5. 垂直行业知识库：法律、医疗、金融等强知识依赖行业，私有化部署保障数据安全。
6. 现有系统智能化：通过 iframe 嵌入或 API，把 MaxKB 的问答能力加到现有 CRM、ERP 或帮助中心，无需重构。

坑与注意

1. 默认密码必须修改：MaxKB@123.. 为安装默认值，首次登录后务必在用户设置中修改密码。

2. Docker 卷权限问题： - Linux 上如果遇到 ~/.maxkb 目录权限报错，确保目录存在且当前用户有读写权限： bash mkdir -p ~/.maxkb chmod 755 ~/.maxkb

3. 国内 Docker 镜像拉取失败： - 使用国内镜像 registry.fit2cloud.com/maxkb/maxkb 而非 Docker Hub 地址。 - 内网/离线环境使用离线安装包。

4. Embedding 模型决定 RAG 效果： - MaxKB 默认不带 Embedding 模型，需要在「模型设置」中自行配置。中文场景推荐使用 m3e 或 text2vec-large-chinese 等中文 embedding 模型，否则检索质量会差。

5. 向量数据库资源： - pgvector 随 PostgreSQL 一起运行，文档量超过 1 万篇时注意 PostgreSQL 内存配置（建议 ≥8 GB 内存）。

6. 工作流调试： - 工作流节点较多时，先在测试环境验证逻辑，再发布到生产。 - MCP 工具调用需要 MCP Server 正确配置，不确定时先看官方文档的 MCP 示例。

7. API Token 安全： - API Token 生成后像密码一样保管，不要硬编码在前端代码中。 - 生产环境建议配合 API 限流。

8. GPL-3.0 许可证： - MaxKB 是 GPL-3.0，商用时需注意开源传染性——如果修改了 MaxKB 源码且对外提供服务，需开源修改版本。若仅作为内部工具使用无此限制。

9. 版本升级： - 升级前备份 ~/.maxkb 目录（包含 PostgreSQL 数据和配置）。 - 查看 GitHub Releases 获取版本升级说明。

与同类对比

MaxKB 的核心差异：开箱即用的企业级体验 + 中文友好 + 完整 RAG 管道。Dify 更偏向通用应用编排，FastGPT 中文场景更强但生态稍小，LangFlow 偏向 LLM 流程实验。MaxKB 在"企业快速交付可用 AI 知识库"这个具体场景上，门槛最低、文档最完整。

一句话推荐结论

如果你的企业需要快速交付一个可用的私有化 AI 知识库或智能客服，MaxKB 是目前门槛最低的生产级选择——一条 Docker 命令起服务，拖拽配置就能用，不需要 AI 团队。