MaxKB 安装与上手指南：10 分钟从零跑通企业级智能体平台

MaxKB 安装与上手指南10 分钟从零跑通企业级智能体平台【免费下载链接】MaxKB MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。项目地址: https://gitcode.com/GitHub_Trending/ma/MaxKBMaxKBMax Knowledge Brain是一个开源的企业级智能体平台核心能力是 RAG 知识库问答、可视化工作流编排和大模型接入。无论你是要搭一个能查文档的智能客服还是想编排带工具调用的 AI 流程它都提供了解决路径。本文带你走完完整链路克隆代码 → 容器或源码两种方式启动 → 改好关键配置 → 确认服务可用并登录管理后台。全程预计 10 分钟只需要一台会基础命令行的 Linux 或 Mac 机器。环境准备先确认这 4 样东西在动手之前对照下表检查你的机器。MaxKB 后端基于 Python 3.11 / Django 5.2 / LangChain数据层用 PostgreSQL含 pgvector 向量扩展 Redis异步任务由 Celery 承担见 pyproject.toml。依赖版本要求说明Docker20.10官方推荐的部署方式自带 PostgreSQL/Redis 编排Python3.11锁定~3.11.0仅源码开发模式需要依赖用 uv 管理Node.js18仅前端本地开发需要端口8080 / 5432 / 6379主服务、数据库、缓存冲突时先改映射如果你打算走 Docker 路线机器上只需要 Docker源码模式才需要装 Python 和 Node。这一步之后你手上有一份清楚的环境清单可以按路线二选一继续。部署与启动两条路线任选其一路线 ADocker 一键部署推荐克隆仓库拿到镜像拉取与编排信息git clone https://gitcode.com/GitHub_Trending/ma/MaxKB这条命令把 MaxKB 仓库拉到当前目录后续所有相对路径都基于它。然后执行官方快速开始命令来自 README_CN.mddocker run -d --namemaxkb --restartalways \ -p 8080:8080 -v ~/.maxkb:/opt/maxkb \ registry.fit2cloud.com/maxkb/maxkb这条命令做了三件事后台启动容器、把容器 8080 端口映射到本机 8080、把~/.maxkb挂载为数据目录知识库文档、日志都落在这里升级容器不丢数据。路线 B源码开发模式适合要改代码的读者。进入仓库后后端统一由 main.py 驱动而不是直接manage.py它负责收集静态文件、执行数据库迁移、再拉起服务python main.py dev # Web 服务监听 0.0.0.0:8080 python main.py dev celery # Celery 异步任务 worker python main.py dev local_model # 本地 Embedding 模型服务127.0.0.1:11636三条命令分别对应三个进程建议开三个终端并行跑参考 CLAUDE.md。前端在ui/目录下npm install npm run dev即可Vite 会把/admin/api、/chat/api代理到后端的 8080 端口。这一步之后你手上有一个正在运行的 MaxKB 实例浏览器里能打开 8080 端口了。5 分钟改完核心配置Docker 方式下默认配置已能跑但部署到真实环境前这几个环境变量是必改项。运行时配置由CONFIG单例统一加载MAXKB_CONFIG_TYPEENV时读取MAXKB_前缀环境变量否则读取/opt/maxkb/conf下的config.yml实现见 apps/maxkb/conf.py。配置项作用建议值MAXKB_DB_NAME/MAXKB_DB_HOST/MAXKB_DB_PORTPostgreSQL 连接信息业务数据与向量都存这里指向你的 PG 实例容器内默认127.0.0.1:5432/maxkbMAXKB_DB_USER/MAXKB_DB_PASSWORD数据库账号密码生产环境务必用独立账号MAXKB_REDIS_HOST/MAXKB_REDIS_PORT/MAXKB_REDIS_PASSWORD缓存与 Celery 消息队列默认127.0.0.1:6379密码非空MAXKB_SECRET_KEYDjango 会话签名密钥不设置时启动脚本会自动随机生成建议显式固定MAXKB_LANGUAGE_CODE后台界面语言zh-CN/en-US/zh-HantMAXKB_DEBUG调试开关生产保持False以 Docker 为例只改数据库密码的最小写法docker run -d --namemaxkb -p 8080:8080 -v ~/.maxkb:/opt/maxkb \ -e MAXKB_DB_PASSWORDYourNewPwd \ -e MAXKB_REDIS_PASSWORDYourNewPwd \ registry.fit2cloud.com/maxkb/maxkb-e参数把新密码注入容器的MAXKB_环境变量容器启动时即按 ENV 方式加载。这一步之后你手上有一套配置与环境匹配的 MaxKB可以放心进入验证环节。启动验证与排错确认它真的跑通了按下面三步验证全部通过才算部署成功浏览器访问http://服务器IP:8080/admin出现登录页即 Web 服务正常。用初始账号登录用户名admin密码MaxKB123..登录后建议立即在「系统设置」里改密码。访问http://服务器IP:8080/admin/api-doc能看到 Swagger 接口文档说明管理 API 也已就绪。三个高频问题问题 18080 端口被占用。执行ss -lntp | grep 8080找到占用进程或直接把映射改成-p 9090:8080之后用 9090 访问即可。问题 2启动日志反复出现 Database is not ready yet。这是 main.py 里迁移逻辑的等待重试说明 PostgreSQL 还在崩溃恢复或首次初始化等 10 次以内会自动继续如果最终报Perform migrate failed检查MAXKB_DB_*是否指向了正确的实例。问题 3能登录但知识库向量化失败。确认 PostgreSQL 已安装 pgvector 扩展且MAXKB_EMBEDDING_MODEL_*指向的模型路径存在Docker 镜像默认内置shibing624_text2vec-base-chinese见 installer/Dockerfile。这一步之后你手上是一个验证通过的 MaxKB 实例可以开始建知识库了。接下来可以做什么进入「知识库」页面上传第一份 PDF/Word 文档观察自动拆分与向量化过程在「模型管理」里接入 OpenAI、DeepSeek、Ollama 等任一提供商的 LLM厂商实现都在 apps/models_provider/impl/创建一个「应用」把知识库挂上去试试基础问答再升级成工作流编排复杂流程需要对外暴露能力时探索 API 密钥与 MCP 端点把 MaxKB 应用嵌进你自己的系统。FAQQDocker 部署时知识库数据存在容器里吗A不会。-v ~/.maxkb:/opt/maxkb把数据目录挂到了宿主机容器删了重建知识库文档依然在。Q源码模式必须三个终端都开吗AWeb 是必须的只测同步功能可以只开dev但文档解析、Embedding 等异步任务依赖dev celery建议三个都跑。Q内网服务器拉不到镜像怎么办A官方提供离线安装包在有网机器下载后拷贝到内网导入再执行安装流程即可。【免费下载链接】MaxKB MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。项目地址: https://gitcode.com/GitHub_Trending/ma/MaxKB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考