5 分钟跑通 MaxKB：开源知识库问答智能体平台部署与使用完整指南

5 分钟跑通 MaxKB开源知识库问答智能体平台部署与使用完整指南【免费下载链接】MaxKB MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。项目地址: https://gitcode.com/GitHub_Trending/ma/MaxKBMaxKBMax Knowledge Brain是一个企业级智能体平台核心能力是基于 RAG 的知识库问答、工作流编排和 MCP 工具调用适合想把大模型问答落地到客服、办公助手的开发者和运维。本文按真实操作顺序从一条 Docker 命令部署、配置逐项讲解到启动失败排查带你把它跑起来。 部署前先确认这三件事不用额外装数据库——Docker 镜像内已自带 PostgreSQL含 pgvector 向量扩展和 Redis只需确认三件事端口MaxKB 的 Web 服务监听 8080宿主机上没被占用就行被占了把映射改到 8081 试试数据目录镜像约定数据落在/opt/maxkb挂载到本地目录Linux 下~/.maxkbWindows 下C:/maxkb保证升级不丢数据账号首次登录的默认账号是admin密码MaxKB123..登录后建议先改掉。如果以后要从源码方式跑依赖才需要自己备Python 3.11、PostgreSQL5432和 Redis6379main.py 启动时会先执行collectstatic和数据库迁移再拉起服务。 用一条命令把服务拉起来前置条件确认后最快速路径就是直接跑官方镜像docker run -d --namemaxkb --restartalways \ -p 8080:8080 -v ~/.maxkb:/opt/maxkb \ registry.fit2cloud.com/maxkb/maxkb跑成功后你应看到什么docker logs maxkb里出现MaxKB started字样然后浏览器打开http://127.0.0.1:8080看到登录页。用默认账号密码登录后在模型设置里接入一个大模型或直接用内置向量模型上传几份文档建个知识库就能问出第一条 RAG 答案。容器内的编排逻辑在 启动脚本先创建日志和 local 目录、生成MAXKB_SECRET_KEY再执行python /opt/maxkb-app/main.py start把 gunicorn 和 Celery 一起拉起来。⚙️ 配置文件每项该不该改配置不走传统settings.py硬编码而是由 配置加载模块 统一管理优先读/opt/maxkb/conf下的config_example.yml、config.yaml、config.yml存在哪个读哪个也可以设MAXKB_CONFIG_TYPEENV改用MAXKB_前缀的环境变量。下面按改哪个 → 为什么改 → 不改会怎样过一遍关键键DB_HOST / DB_PORT / DB_USER / DB_PASSWORD→ 数据库连接四件套。用镜像自带 PostgreSQL 就保持默认127.0.0.1:5432不动脚本会自动拉起它指向外部 PG 实例时把四行换成你的值。不改会怎样指向了外部库却不改密码启动阶段migrate连不上直接退出。DB_NAME→ 数据库名。自建实例时先CREATE DATABASE再填进来和现有库重名会直接复用注意别指向生产库。REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_DB→ 缓存和 Celery 消息队列。默认密码是Password123redis接外部 Redis 且开了密码时这行必须换否则任务队列全线不可用。DB_MAX_OVERFLOW→ 数据库连接池溢出上限默认 80。高并发问答场景可调大普通部署不动。LANGUAGE_CODE→ 界面语言默认zh-CN可选en、zh-Hant。不改就是简体中文一般不用动。DEBUG / LOG_LEVEL→ 调试开关。线上保持DEBUG: False排查问题时把LOG_LEVEL调成DEBUG日志落在挂载目录的logs/下。ADMIN_PATH / CHAT_PATH→ 管理端和对话端路径默认/admin和/chat一般不改。最后给一份可直接复制的最小配置存为config.yaml或转成MAXKB_前缀环境变量DB_NAME: maxkb DB_HOST: 127.0.0.1 DB_PORT: 5432 DB_USER: root DB_PASSWORD: Password123postgres DB_MAX_OVERFLOW: 80 REDIS_HOST: 127.0.0.1 REDIS_PORT: 6379 REDIS_PASSWORD: Password123redis REDIS_DB: 0 REDIS_MAX_CONNECTIONS: 100 LANGUAGE_CODE: zh-CN DEBUG: False 目录结构速读后端是 Django 多应用架构按业务域拆 app前端是 Vue 3 双 SPA管理端 对话嵌入端。一级目录长这样MaxKB/ ├── main.py # 服务入口迁移、静态收集、启动 web/task ├── apps/ # 后端全部 Django 应用 │ ├── application/ # 应用智能体管理与工作流引擎 │ ├── chat/ # 对话、分享链接、MCP 服务端 │ ├── knowledge/ # 知识库文档、段落、向量检索 │ ├── models_provider/ # 各家大模型适配层 │ ├── maxkb/ # Django settings、配置加载 │ └── ... # common、users、tools、trigger 等 ├── ui/ # Vue 3 前端源码 └── installer/ # Dockerfile 与容器内启动脚本日常部署基本只在installer/改启动行为和配置层面动手业务逻辑都在apps/对应域里。 常见坑与启动失败排查8080 端口被占docker run改-p 8081:8080访问地址同步换成 8081 即可。日志停在 migrate 阶段、报 Connection refused多为外部 PostgreSQL 还没就绪或密码不对核对DB_*四项后docker restart maxkb镜像对数据库启动有最多 10 次重试真正连不上会直接退出。登录页打不开但容器在跑先docker logs maxkb看是否有MaxKB started没等到就绪前页面会 404再等 30 秒刷新。【免费下载链接】MaxKB MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。项目地址: https://gitcode.com/GitHub_Trending/ma/MaxKB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考