企业官网建设流程全解析

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

【免费下载链接】MaxKB🔥 MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。项目地址: https://gitcode.com/GitHub_Trending/ma/MaxKB

MaxKB（Max Knowledge Brain）是一个开源的企业级智能体平台，核心能力是 RAG 知识库问答、可视化工作流编排和大模型接入。无论你是要搭一个能查文档的智能客服，还是想编排带工具调用的 AI 流程，它都提供了解决路径。本文带你走完完整链路：克隆代码 → 容器或源码两种方式启动 → 改好关键配置 → 确认服务可用并登录管理后台。全程预计 10 分钟，只需要一台会基础命令行的 Linux 或 Mac 机器。

环境准备：先确认这 4 样东西

在动手之前，对照下表检查你的机器。MaxKB 后端基于 Python 3.11 / Django 5.2 / LangChain，数据层用 PostgreSQL（含 pgvector 向量扩展）+ Redis，异步任务由 Celery 承担（见 pyproject.toml）。

如果你打算走 Docker 路线，机器上只需要 Docker；源码模式才需要装 Python 和 Node。这一步之后，你手上有一份清楚的环境清单，可以按路线二选一继续。

部署与启动：两条路线任选其一

路线 A：Docker 一键部署（推荐）

克隆仓库拿到镜像拉取与编排信息：

git clone https://gitcode.com/GitHub_Trending/ma/MaxKB

这条命令把 MaxKB 仓库拉到当前目录，后续所有相对路径都基于它。

然后执行官方快速开始命令（来自 README_CN.md）：

docker run -d --name=maxkb --restart=always \ -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_TYPE=ENV时读取MAXKB_前缀环境变量，否则读取/opt/maxkb/conf下的config.yml（实现见 apps/maxkb/conf.py）。

以 Docker 为例，只改数据库密码的最小写法：

docker run -d --name=maxkb -p 8080:8080 -v ~/.maxkb:/opt/maxkb \ -e MAXKB_DB_PASSWORD=YourNewPwd \ -e MAXKB_REDIS_PASSWORD=YourNewPwd \ registry.fit2cloud.com/maxkb/maxkb

-e参数把新密码注入容器的MAXKB_环境变量，容器启动时即按 ENV 方式加载。这一步之后，你手上有一套配置与环境匹配的 MaxKB，可以放心进入验证环节。

启动验证与排错：确认它真的跑通了

按下面三步验证，全部通过才算部署成功：

1. 浏览器访问http://<服务器IP>:8080/admin，出现登录页即 Web 服务正常。
2. 用初始账号登录：用户名admin，密码MaxKB@123..，登录后建议立即在「系统设置」里改密码。
3. 访问http://<服务器IP>:8080/admin/api-doc能看到 Swagger 接口文档，说明管理 API 也已就绪。

三个高频问题

问题 1：8080 端口被占用。执行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 应用嵌进你自己的系统。

FAQ

Q：Docker 部署时知识库数据存在容器里吗？A：不会。-v ~/.maxkb:/opt/maxkb把数据目录挂到了宿主机，容器删了重建，知识库文档依然在。

Q：源码模式必须三个终端都开吗？A：Web 是必须的；只测同步功能可以只开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