MaxKB 快速部署上手教程：10 分钟跑通第一个企业级智能体问答
MaxKB 快速部署上手教程：10 分钟跑通第一个企业级智能体问答
项目地址: https://gitcode.com/GitHub_Trending/ma/MaxKB MaxKB（Max Knowledge Brain）是开源的企业级智能体平台，内置 RAG 流水线、工作流编排和 MCP 工具调用，常见于智能客服、企业知识库这类场景。这篇教程带你从零部署 MaxKB：一条 Docker 命令拉起服务，登录后接入模型、导入知识库，约 10 分钟完成第一次基于自己文档的问答。开始前只需确认环境满足下表要求：
| 项目 | 最低要求 |
|---|---|
| Docker | 20.10+，服务正常运行 |
| CPU / 内存 | 2 核 / 4GB |
| 磁盘 | 10GB+（镜像 + 向量库） |
| 操作系统 | Linux / macOS / Windows（Docker Desktop） |
跑起来：Docker 一条命令启动 MaxKB
默认用官方镜像部署，只有二次开发才需要走源码构建。下面这条命令拉取镜像并启动容器，把 8080 端口映射出来，数据目录持久化到本机 ~/.maxkb——容器内部已自带 PostgreSQL（含 pgvector）、Redis 和本地向量模型，不用单独安装任何依赖：
docker run -d --name=maxkb --restart=always \
-p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb
启动后核对一下：
docker ps
你应该看到一行 maxkb 容器，状态为 Up，端口列显示 0.0.0.0:8080->8080/tcp。首次启动要拉镜像并初始化数据库，耐心等待几分钟。需要源码构建时，克隆仓库 https://gitcode.com/GitHub_Trending/ma/MaxKB 后在根目录执行 docker build -t maxkb:local . 即可，构建过程见 installer/Dockerfile。
默认账号与首次登录
浏览器打开 http://你的服务器IP:8080，用默认账号登录：
- 用户名：
admin - 密码：
MaxKB@123..
你应该看到：登录后进入管理控制台，左侧是知识库、应用、模型管理等菜单。首次登录后立刻去系统设置修改默认密码，生产环境这一步不能省。
核心场景演练
模型接入：LLM + Embedding
进入模型管理，接入两个模型：
- LLM：任选一个 OpenAI 兼容接口（DeepSeek、通义千问、OpenAI 等），填入 API 地址和密钥；
- Embedding：MaxKB 内置本地向量模型，零配置直接可用，也可以换成远端 embedding 服务。
预期效果：两个模型在列表里都显示"测试通过"，否则先检查密钥和网络连通性。
知识库构建与文档向量化
在知识库页面新建一个知识库，上传几份 PDF / TXT / Markdown 文档，或填一个网页 URL 自动抓取。上传完成后系统会自动分片、向量化，文档状态变为解析完成。
快速验证：在知识库详情里用"命中测试"输入文档里出现过的关键词，你应该看到对应段落被命中，并显示来源文档。
创建应用，跑通第一次问答
新建应用，选刚才接好的 LLM，关联知识库，提示词写上"仅根据检索到的知识回答，检索不到就明确说不知道"，然后发布。打开问答页问一个文档里的问题，预期是流式返回带引用来源的答案，而不是一篇泛泛的编造。
问答跑通后，可以切到工作流模式：在画布上拖 LLM、知识检索、条件分支、MCP 工具等节点，编排"先判断意图、再路由到不同知识库"这类更复杂的流程。
排障与运维速查
| 现象或事项 | 排查命令 / 操作 | 处理建议 |
|---|---|---|
| 8080 访问不通 | docker ps 看端口映射 | 防火墙未放行或端口冲突，调整 -p 后重建容器 |
| 容器起不来 | docker logs -f maxkb | 确认内存 ≥4GB、磁盘充足，按日志定位报错 |
| 问答响应慢 | 检查外部模型 API 连通性 | 换私有化模型减少网络延迟 |
| 知识库解析失败 | 知识库详情页看文档状态 | 大文件拆分上传，保证内存充足 |
| 查看日志 | 容器内 /opt/maxkb/logs | docker logs maxkb 实时跟踪 |
| 数据备份 | 备份挂载卷 ~/.maxkb | 定期执行 tar -czf maxkb_$(date +%F).tar.gz ~/.maxkb |
| 版本升级 | docker pull 1panel/maxkb 后重建容器 | 数据在挂载卷里，升级不会丢 |
下一步
- 工作流编排与 MCP：看 apps/application/flow/step_node/ 了解各节点的输入输出参数，应用还可以暴露为 MCP 工具供其他智能体调用
- API 集成：用
/chat/api/*下的聊天接口接入第三方系统，在线接口文档见/admin/api-doc - 跟进更新：项目迭代频繁，升级前先查看 README_CN.md 中的版本与安装说明，确认新版对现有知识库配置的影响
北京人形旗下天工造物具身智能开源社区，聚焦具身天工与慧思开物两大平台
更多推荐
0
0- 0
已为社区贡献21条内容
所有评论(0)