企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• RAG
• 工具调用
• 后端
• 前端
• 知识库

MaxKB（Max Knowledge Brain）是飞致云（FIT2CLOUD）出品的开源企业级智能体平台，面向企业 AI 落地中「技术门槛高、部署成本高、迭代周期长」三大痛点，提供从基础问答（RAG）、复杂流程自动化（工作流）到智能体（Agent）的渐进式升级路径。本文将以仓库 README_CN.md 为核心骨架，结合仓库内部署脚本、配置源码与依赖清单，完整讲解 MaxKB 的四大核心能力、Docker 快速部署步骤、默认账号与配置项，以及其前后端技术栈与启动链路，帮助读者在 10 分钟内完成平台搭建并理解其运行原理。

一、MaxKB 是什么：定位与核心价值

MaxKB = Max Knowledge Brain，是一个强大易用的企业级智能体平台，致力于解决企业 AI 落地面临的技术门槛高、部署成本高、迭代周期长等问题。其设计理念是「开箱即用，伴随成长」：企业可以快速接入主流大模型，高效构建专属知识库，并逐步从 RAG 问答演进到工作流自动化乃至 Agent 智能体，全面赋能智能客服、智能办公助手等多种应用场景。

从仓库结构看，MaxKB 的核心能力被拆分为多个 Django App，与上述定位一一对应：

• 知识库与检索：knowledgeApp 承载文档上传、文本拆分、向量化与检索（向量检索 SQL、混合检索 SQL）；
• 应用编排：applicationApp 中的flow模块是工作流引擎核心，包含 146 个步骤节点实现（step_node），并提供 default_workflow.json 等默认工作流模板；
• 模型接入：models_providerApp 内置 20 余种模型供应商实现（impl 目录），涵盖国内公共大模型、国外公共大模型与本地私有模型；
• 对外嵌入：chatApp 提供免登录的对话链路与 embed.js 嵌入脚本，支持零编码嵌入第三方业务系统。

二、四大核心能力详解

README_CN 将其核心价值归纳为四点，这里结合源码逐一展开：

2.1 RAG 检索增强生成

高效搭建本地 AI 知识库，支持直接上传文档 / 自动爬取在线文档，支持文本自动拆分、向量化，有效减少大模型幻觉，提升问答效果。

仓库中knowledgeApp 提供了完整实现链路：文档通过 document.py 完成入库，文本拆分与 QA 解析由common/handle下的处理器完成（base_split_handle.py、base_parse_qa_handle.py），向量化由 knowledge/vector 模块执行（支持 pg_vector），检索 SQL 则区分了关键词、向量与混合三种模式（keywords_search.sql、embedding_search.sql、blend_search.sql）。同时内置了行业模板，见 knowledge/template 下的 CSV 与 Excel 导入模板，方便批量导入知识数据。

2.2 灵活编排

内置强大的工作流引擎、函数库和 MCP 工具调用能力，支持编排 AI 工作过程，满足复杂业务场景下的需求。

工作流引擎位于 apps/application/flow，i_step_node.py定义了步骤节点抽象基类，146 个节点实现覆盖条件分支、循环、知识库检索、工具调用等能力。MCP 能力由common/mcp模块提供（client.py、config.py），并基于 LangChain 生态集成。pyproject.toml中锁定了langchain、langgraph、deepagents、mcp等依赖版本，为 Agent 编排提供了坚实的底层框架（pyproject.toml）。

2.3 无缝嵌入

支持零编码快速嵌入到第三方业务系统，让已有系统快速拥有智能问答能力，提高用户满意度。

chatApp 提供聊天嵌入能力：chat_embed_api.py与配套的 embed.js 允许开发者通过几行脚本把智能问答对话框嵌入任意 Web 页面，无需改动业务系统后端；application_chat_link.py则支持生成独立的分享链接。

2.4 模型中立

支持对接各种大模型，包括本地私有大模型（DeepSeek R1 / Qwen 3 等）、国内公共大模型（通义千问 / 腾讯混元 / 字节豆包 / 百度千帆 / 智谱 AI / Kimi / MiniMax 等）和国外公共大模型（OpenAI / Claude / Gemini 等）。

这一能力由 models_provider/impl 目录下的 20 余个供应商实现支撑，每个供应商目录包含模型凭据定义、接口封装等文件；仓库同时提供本地模型部署脚本 install_model.py 与 install_model_bert_base_cased.py，支持将开源向量模型 / 本地大模型一并打包进容器。

三、快速开始：Docker 一键部署

README_CN 给出了 Linux 与 Windows 两种 Docker 启动方式，这是本平台最快捷的上手路径，原样可复制执行。

Linux 机器：

docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb registry.fit2cloud.com/maxkb/maxkb

Windows 机器：

docker run -d --name=maxkb --restart=always -p 8080:8080 -v C:/maxkb:/opt/maxkb registry.fit2cloud.com/maxkb/maxkb

默认登录账号：

• 用户名：admin
• 密码：MaxKB@123..

启动后浏览器访问http://<服务器IP>:8080即可进入控制台。需要特别说明的是：-v ~/.maxkb:/opt/maxkb（Windows 下为C:/maxkb）这一数据卷目录非常关键——MaxKB 的数据库数据、日志、本地模型与用户配置均持久化于此，升级或重建容器时数据不会丢失。

3.1 容器内部启动链路（源码级解读）

镜像内部的启动编排可以从 installer 目录下的脚本还原：

• 容器入口为start-all.sh（见 start-all.sh）：依次拉起 PostgreSQL（start-postgres.sh）、Redis（start-redis.sh）与 MaxKB 主进程，并使用wait-for-it对 5432 / 6379 / 8080 三个端口做就绪探测；
• 主进程脚本 start-maxkb.sh：创建日志与本地目录、执行/opt/maxkb/local/init-shells下的初始化脚本（可挂载自定义初始化 shell），最后运行python /opt/maxkb-app/main.py start；
• 启动入口 main.py：start动作会依次执行静态资源收集（collectstatic）、数据库迁移（migrate），随后按--daemon/--worker等参数拉起 web / task 服务。其中perform_db_migrate()内置了最多 10 次、间隔 5 秒的数据库就绪重试逻辑，用于规避 PostgreSQL 崩溃恢复期间端口已开放但拒绝查询的竞态问题。

3.2 镜像依赖与版本基础

• 基础镜像由 Dockerfile-base 定义：基于postgres:17.11，内置postgresql-17-pgvector（向量检索）与postgresql-17-age（图数据库扩展）、Redis、ffmpeg，并预置了中文字符嵌入向量模型（maxkb-vector-model:v2.0.3）；
• 应用镜像由 Dockerfile 构建：前端在 Node 24 环境下编译ui目录产出dist，后端基于 Python 3.11 + uv 安装依赖，最后合成单镜像并暴露8080端口。

四、更多部署方式与运行配置

除 Docker 直接拉取镜像外，README_CN 还提供了三类补充部署路径：

4.1 1Panel 应用商店部署

可通过 1Panel 应用商店快速部署 MaxKB，适合已使用 1Panel 运维面板的用户，在面板内即可完成应用安装、启停与升级。

4.2 离线安装包（内网环境）

如果企业处于内网 / 离线环境，推荐使用官方离线安装包进行安装部署，安装包内含镜像与依赖资源，无需外网即可完成整套平台的初始化。

4.3 环境变量与配置文件

MaxKB 支持通过环境变量（MAXKB_前缀）或 YAML 配置文件两种方式注入运行参数。从 const.py 可知：设置环境变量MAXKB_CONFIG后，配置从项目根目录的config_example.yml/config.yaml/config.yml读取；否则默认从挂载数据卷/opt/maxkb/conf读取。若设置MAXKB_CONFIG_TYPE=ENV，则直接由环境变量驱动。

核心环境变量及其默认值可从 Dockerfile 与 conf.py 中还原：

其中数据库连接池与 Redis 缓存的组装逻辑定义在 conf.py 的get_db_setting()/get_cache_setting()中：数据库引擎采用dj_db_conn_pool连接池（POOL_SIZE=20、RECYCLE=1800、PRE_PING=True），Redis 使用django_redis，且支持通过MAXKB_REDIS_SENTINEL_SENTINELS配置切换到 Redis Sentinel 高可用模式（对应 web.py 中的DJANGO_REDIS_CONNECTION_FACTORY设置）。

五、技术栈与仓库源码结构

README_CN 明确了 MaxKB 的技术栈，与仓库实测完全一致：

• 前端：Vue.js（源码位于 ui/src，包含 227 个.vue视图组件与 119 个工作流组件，构建产物为ui/dist）；
• 后端：Python / Django（Django 5.2 + Django REST Framework，见 pyproject.toml，业务代码位于 apps）；
• LangChain：langchain/langgraph/deepagents等框架用于 RAG 编排与 Agent 构建；
• 向量数据库：PostgreSQL / pgvector（基础镜像内置 pgvector 扩展，knowledge/vector提供向量读写封装）。

后端业务模块（Django App）与平台能力映射关系如下：

六、配套资源与使用参考

• 案例展示：仓库内 USE-CASES.md 收录了典型应用场景，可作为选型与落地方案参考；
• 使用手册与论坛：部署与日常使用中遇到问题，可查阅官方使用手册，或通过官方论坛求助交流；
• 产品版本对比：MaxKB 不同产品版本（社区版 / 企业版等）的能力差异可参考官方「MaxKB 产品版本对比」页，按需选择；
• 团队介绍材料：官方提供了可下载的 MaxKB 介绍 PPT，便于在企业内部同步技术选型结论。

七、小结：从一条命令到企业级 Agent 平台

从 README_CN.md 出发可以看到，MaxKB 的价值在于用一条 Docker 命令把「模型接入 + 知识库 + 工作流 + 智能体 + 外部嵌入」完整串起来：docker run即可获得开箱即用的企业级智能体平台，默认账号admin / MaxKB@123..登录后即可创建知识库、编排工作流并嵌入现有业务系统。而仓库源码则揭示了其背后扎实的实现基础——Django 模块化业务、pgvector 向量检索、LangChain/LangGraph Agent 编排、MCP 工具调用与 20 余家模型供应商适配层。对企业团队而言，这既是一套可立即投入生产的 AI 应用底座，也是一份值得深入研读的开源实现范本。

• 人工智能
• 大模型
• AI Agent
• RAG
• 工具调用
• 后端
• 前端
• 知识库