企业官网建设流程全解析

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

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

MaxKB（Max Knowledge Brain）是一个企业级智能体平台，核心能力是基于 RAG 的知识库问答、工作流编排和 MCP 工具调用，适合想把大模型问答落地到客服、办公助手的开发者和运维。本文按真实操作顺序，从一条 Docker 命令部署、配置逐项讲解到启动失败排查，带你把它跑起来。

📋 部署前先确认这三件事

不用额外装数据库——Docker 镜像内已自带 PostgreSQL（含 pgvector 向量扩展）和 Redis，只需确认三件事：

• 端口：MaxKB 的 Web 服务监听 8080，宿主机上没被占用就行，被占了把映射改到 8081 试试；
• 数据目录：镜像约定数据落在/opt/maxkb，挂载到本地目录（Linux 下~/.maxkb，Windows 下C:/maxkb）保证升级不丢数据；
• 账号：首次登录的默认账号是admin，密码MaxKB@123..，登录后建议先改掉。

如果以后要从源码方式跑，依赖才需要自己备：Python 3.11、PostgreSQL（5432）和 Redis（6379），main.py 启动时会先执行collectstatic和数据库迁移再拉起服务。

🚀 用一条命令把服务拉起来

前置条件确认后，最快速路径就是直接跑官方镜像：

docker run -d --name=maxkb --restart=always \ -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_TYPE=ENV，改用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 消息队列。默认密码是Password123@redis，接外部 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: Password123@postgres DB_MAX_OVERFLOW: 80 REDIS_HOST: 127.0.0.1 REDIS_PORT: 6379 REDIS_PASSWORD: Password123@redis 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