Banner

MaxKB 部署教程

2026-09-14

MaxKB 部署教程与快速上手指南

MaxKB 是一款基于大语言模型（LLM）和检索增强生成（RAG）技术的开源知识库问答系统。与 Shopware 依赖 PHP 和宝塔面板不同，MaxKB 的部署主要依赖 Docker 容器化技术。

以下是为您整理的 MaxKB 保姆级部署教程，涵盖环境准备、安装部署、快速上手及常见运维事项。


一、 部署前必须知道的硬性要求

在动手之前，请确保您的服务器满足以下配置要求，否则可能导致安装失败或运行卡顿：

  • 操作系统：Ubuntu 22.04 / CentOS 7.6 64 位系统（也支持主流 Linux 发行版及国产操作系统）。
  • CPU/内存：4核 / 8GB 以上。
  • 磁盘空间：100GB 及以上。
  • Docker 环境：Docker v26.0.0 及以上版本（Docker 容器部署方式必需）。
  • 端口要求：需开放 22 端口（SSH管理）和 8080 端口（默认 Web 服务端口）。


二、 部署方式与安装步骤

MaxKB 官方提供多种部署方式，生产环境强烈推荐使用离线安装包，日常测试可使用 Docker 容器部署。

方式一：离线安装包部署（生产环境推荐）

1. 下载安装包：前往飞致云开源社区 MaxKB 社区版下载页面，下载最新版本的离线安装包（如 maxkb-v1.10.0-lts-offline.tar.gz），并上传至服务器。

2. 解压安装包：

1.  tar -zxvf maxkb-v1.10.0-lts-offline.tar.gz
2.  cd maxkb-v1.10.0-lts-offline

3. 修改配置（可选）：首次安装前，可编辑 install.conf 文件，自定义安装目录（MAXKB_BASE）、Web 端口（MAXKB_PORT）及外部数据库参数等。

4. 执行安装：

1.  bash install.sh

5. 配置生效：安装完成后，如需修改配置，需编辑 /opt/maxkb/.env 文件，并执行 mkctl reload 使配置生效。

方式二：Docker 容器快速部署（适合测试/开发）

在 Linux 环境下执行以下命令即可一键启动：

1.  docker run -d --name=maxkb --restart=always \
2.    -p 8080:8080 \
3.    -v ~/.maxkb:/var/lib/postgresql/data \
4.    -v ~/.python-packages:/opt/maxkb/app/sandbox/python-packages \
5.    registry.fit2cloud.com/maxkb/maxkb

方式三：1Panel 面板部署

如果您使用 1Panel 面板，可直接在“应用商店”中搜索 MaxKB，配置名称、端口并勾选“端口外部访问”后点击安装即可。


三、 登录与快速上手四步曲

安装完成后，在浏览器访问 http://目标服务器IP:8080。

  • 默认账号：admin
  • 默认密码：MaxKB@123..

登录成功后，典型的 MaxKB 操作流程分为以下四步：

1. 添加模型

进入【模型】页面，点击【添加模型】。您可以选择接入通义千问、阿里云百炼等公有云大模型，也可通过 Ollama 接入本地大模型。需配置模型名称、类型（大语言模型/向量模型等）、基础模型及 API Key。

2. 创建知识库

进入【知识库】页面，点击【创建知识库】。选择内置向量模型（如 MaxKB-Embedding），将离线文档（TXT、PDF、DOCX、Markdown、Excel 等）拖拽上传，或输入 Web 站点 URL 自动爬取。

3. 创建应用

进入【智能体/应用】页面，点击【创建应用】。选择“简易配置”或“高级编排”，关联刚刚创建的知识库，配置 AI 模型、提示词、检索模式（向量/全文/混合检索）及开场白。

4. 发布与集成

应用创建完成后即可发布。MaxKB 支持零代码嵌入第三方 Web 系统（全屏/浮窗模式），也可通过 API 接入企业微信、钉钉、飞书等平台。


四、 常见运维与避坑指南

  • 内网穿透与公网访问：如果 MaxKB 部署在公司内网或 NAS 上，可通过配置 ZeroNews 等内网穿透工具，为 Web 控制台提供安全的 HTTPS 公网访问端点，无需将数据库和向量数据暴露到公网。
  • Java 衍生版 MaxKB4j：如果您团队需要纯 Java 技术栈，可使用 MaxKB4j。它基于 Java 21 + Spring Boot 3.5.x，依赖 PostgreSQL（pgvector）和 MongoDB，支持 Docker Compose 一键部署，默认账号为 admin，密码为 tarzan@123456。
  • 安全建议：生产环境中，务必在首次登录后立即修改默认的 admin 密码；如果开放了公网访问，建议配置 IP 黑白名单或 Basic 认证，避免管理后台裸奔。


16
MaxKB
MaxKB = Max Knowledge Brain，是一个强大易用的企业级智能体平台，致力于解决企业 AI 落地面临的技术门槛高、部署成本高、迭代周期长等问题，助力企业在人工智能时代赢得先机。秉承“开箱即用，伴随成长”的设计理念，MaxKB 支持企业快速接入主流大模型，高效构建专属知识库，并提供从基础问答（RAG）、复杂流程自动化（工作流）到智能体（Agent）的渐进式升级路径，全面赋能智能客服、智能办公助手等多种应用场景。
2026-09-14
27
目录