前置条件
- 1已注册腾讯云账号
- 2已购买一台轻量应用服务器（建议 4C8G 起步）
- 3服务器已安装 Docker
读完想动手？新用户首单 8 折上云
服务器 + 大模型 API + 对象存储，新用户首购享 20% 补贴
MaxKB 腾讯云私有化部署完整指南
本教程将详细介绍如何在 腾讯云轻量应用服务器上部署国产开源知识库问答系统 MaxKB，提供 Docker 一键部署与 1Panel 应用商店两条完整路径，并走完「建模型 → 传文档 → 建应用 → 发布 → 对话」的完整链路。它的特点是把数据库、向量库和缓存全部打包进一个镜像，一条命令就能跑起来，适合想在十分钟内拿到成果的场景。
前置准备
在开始之前，请确保你已经完成以下准备工作：
- 已注册腾讯云账号
- 已购买一台轻量应用服务器（建议 4C8G 起步）
- 服务器已安装 Docker
警告
⚠️ 版本说明：本教程基于 MaxKB v1 系列。MaxKB 官方在 v1 版本中对数据持久化目录做过调整，升级时务必保持 -v 挂载目录与首次部署时完全一致，否则启动后数据会是空的。这一点在后面「升级」一节会再强调。
为什么选 MaxKB
一句话定位
信息
MaxKB = 国产开源知识库问答系统 + 一个镜像打包全依赖 + 十分钟跑通 RAG + 支持零编码嵌入第三方业务系统。
它不是功能最深的知识库平台（深度调优要上 FastGPT），但它是部署链路最短、出成果最快的那个 —— 对「我只是想让同事能问文档」这类诉求，多花的复杂度往往换不来等值收益。
三个国产平台的取舍
| 平台 | 部署复杂度 | RAG 精调深度 | 工作流编排 | 出成果速度 | 适合谁 |
|---|---|---|---|---|---|
| MaxKB | ⭐ 极低（单镜像） | 中 | 支持基础编排 | ⭐ 十分钟 | 个人、小团队、快速验证 |
| FastGPT | 中（多容器） | ⭐ 深 | ⭐ 强 | 约半天 | 要持续调优召回质量的团队 |
| Dify | 中 | 深 | ⭐ 最强（生态丰富） | 约半天到一天 | 要搭复杂 Agent 与大量外部工具 |
关键事实：
- 官方镜像内置 PostgreSQL + pgvector + Redis，不用自己编排数据库，这是它上手快的核心原因
- 支持直接对接本地 Ollama 模型，也支持国产云端模型（阿里云百炼、DeepSeek、智谱等）
- 支持把问答应用一键嵌入现有网站（iframe 或 JS），零编码给老系统加 AI 能力
- 由飞致云（1Panel 团队）维护，中文文档、中文社区、中文报错，排障不用猜
什么时候该选 MaxKB
✅ 适合：个人或小团队要快速拥有一套内部文档问答 / 客服知识库 / 想给现有网站加一个问答入口 / 不想维护多套容器编排 / 主要用现成模型而非自己训
❌ 不适合：需要对召回做极度精细的参数调优 / 要搭复杂的多智能体工作流 / 需要对接大量外部工具与插件生态
云服务器选型
MaxKB 自身的瓶颈在文档解析与向量检索，不在 GPU —— 因为模型计算交给了你配置的模型供应商。
| 配置 | 能否跑起来 | 文档体量建议 | 适用场景 |
|---|---|---|---|
| 2C4G | ⚠️ 勉强，容易在解析大文档时 OOM | 几十篇 | 纯功能验证，不建议生产 |
| 4C8G | ✅ 官方推荐起步 | 数百篇文档 | 推荐起步，小团队知识库 |
| 8C16G | ⭐ 宽裕 | 数千篇文档 | 正式对外或部门级使用 |
| 16C32G | 非常富裕 | 海量文档 + 高并发 | 企业级、多应用并行 |
磁盘：官方建议 100GB 以上。文档原文、切片、向量索引都存在挂载目录里，几百 MB 的 PDF 文档向量化后通常会占数倍空间。
提示
💡 务实建议：先用 4C8G 把整条链路跑通，确认有效果再升配。腾讯云轻量服务器支持平滑升配，不用重装系统。
前往 腾讯云轻量应用服务器 选购页对照上表选择。
路径 A：Docker 一键部署（推荐）
A1. 安装 Docker（走腾讯云内网源）
腾讯云服务器务必用内网镜像源，比 Docker 官方源快一个数量级：
1apt-get update
2apt-get install -y ca-certificates curl gnupg lsb-release
3
4curl -fsSL https://mirrors.cloud.tencent.com/docker-ce/linux/ubuntu/gpg -o docker-keyring.gpg
5gpg --dearmor -o /etc/apt/keyrings/docker.gpg docker-keyring.gpg
6
7echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.cloud.tencent.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
8
9apt-get update
10apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
11
12mkdir -p /etc/docker
13tee /etc/docker/daemon.json <<-'EOF'
14{
15 "registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
16}
17EOF
18
19systemctl daemon-reload
20systemctl restart docker
21systemctl enable docker警告
⚠️ MaxKB 镜像托管在 registry.fit2cloud.com，这个源在国内访问通常没问题；如果拉得很慢，上面的 Docker Hub 加速器同样生效。
A2. 一条命令启动 MaxKB
1docker run -d --name=maxkb --restart=always \
2 -p 8080:8080 \
3 -v ~/.maxkb:/var/lib/postgresql/data \
4 -v ~/.python-packages:/opt/maxkb/app/sandbox/python-packages \
5 registry.fit2cloud.com/maxkb/maxkb:v1
6
7# 观察启动日志（首次会拉镜像、初始化数据库，约 1 到 3 分钟）
8docker logs -f maxkb这条命令在做什么：
| 部分 | 作用 |
|---|---|
--restart=always | 开机自动拉起，服务器重启后不用手动救火 |
-p 8080:8080 | 宿主机 8080 映射到容器 8080，Web 服务端口 |
-v ~/.maxkb:... | 数据库持久化目录，升级时这个路径不能变 |
-v ~/.python-packages:... | 代码沙箱的 Python 依赖目录，避免每次重建都重装依赖 |
警告
⚠️ 如果你的服务器上 8080 已被占用，改成 -p 9000:8080，然后用 http://<你的IP>:9000 访问。
等待容器状态变成 healthy：
1# 看到 (healthy) 才算就绪
2docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"A3. 用 compose 管理（可选，推荐生产用）
一条 docker run 够快，但参数散落在命令行里不利于后续维护。生产环境建议写成 compose：
1mkdir -p /opt/maxkb && cd /opt/maxkb
2
3cat > docker-compose.yml <<-'EOF'
4version: '3.8'
5
6services:
7 maxkb:
8 image: registry.fit2cloud.com/maxkb/maxkb:v1
9 container_name: maxkb
10 restart: always
11 ports:
12 - "8080:8080"
13 volumes:
14 - ./data:/var/lib/postgresql/data
15 - ./python-packages:/opt/maxkb/app/sandbox/python-packages
16 healthcheck:
17 test: ["CMD", "curl", "-f", "http://localhost:8080"]
18 interval: 30s
19 timeout: 10s
20 retries: 5
21EOF
22
23docker compose up -d
24docker compose ps提示
💡 从 docker run 迁移到 compose 时，先把原 ~/.maxkb 目录整体拷到 ./data 再启动，历史数据就保留下来了。
A4. 首次登录与安全设置
浏览器访问 http://<你的公网IP>:8080，使用官方默认账号登录：
| 项目 | 值 |
|---|---|
| 用户名 | admin |
| 默认密码 | MaxKB@123.. |
⚠️ 登录后第一件事必须是改密码。这个默认口令是公开的，等于写在源码里，任何知道 MaxKB 的人都能试出来，留着上线就是裸奔。修改路径：「个人设置 → 修改密码」。
路径 B：1Panel 应用商店部署（更省事）
如果你已经用 1Panel 管理服务器（见 1Panel 腾讯云部署教程），可以直接从应用商店安装，连命令行都不用敲。
B1. 操作步骤
- 登录 1Panel 面板，进入「应用商店」
- 搜索
MaxKB，点击「安装」 - 填好安装参数（端口默认 8080，按需调整；建议勾选「端口外部访问」仅在确有需要时开启）
- 等待安装完成，在「已安装」列表里点击 MaxKB 的访问地址
B2. 两种方式的差异
| 维度 | Docker 命令行 | 1Panel 应用商店 |
|---|---|---|
| 上手难度 | 需要熟悉 docker | ⭐ 点几下鼠标 |
| 参数控制 | ⭐ 完全可控 | 由面板预设，部分需进容器改 |
| 备份升级 | 手动 | ⭐ 面板一键备份/升级 |
| 多台机器统一管理 | 无 | ⭐ 面板可管多台主机 |
| 适合场景 | 想要完全掌控细节 | 想省事、不常调底层参数 |
提示
💡 建议：开发环境用 1Panel 快速装，验证通过后在正式机器上用 compose 固定参数部署，兼顾效率与可控性。
第一步：配置模型（不做这步后面全是空的）
MaxKB 只是编排层，没有可用模型就无法问答。进入「模型管理 → 添加模型」，按你手头的资源选一种。
方案 1：接云端国产模型（最省事）
以阿里云百炼为例：
| 配置项 | 值 |
|---|---|
| 模型类型 | 选「通义千问」或 OpenAI 兼容类 |
| 模型名称 | 如 qwen-plus / qwen-max |
| API Key | 百炼控制台创建 |
| 基础 URL | https://dashscope.aliyuncs.com/compatible-mode/v1 |
DeepSeek、智谱等同理，选中对应厂商填 Key 即可。向量模型也在这里添加，选 embedding 类模型（如 text-embedding-v3），后面的知识库会用它做向量化。
方案 2：接本地 Ollama 模型（数据完全私有）
如果你已按 Qwen3 腾讯云部署教程 在服务器上跑起了 Qwen3：
| 配置项 | 值 |
|---|---|
| 模型类型 | 选 Ollama |
| 模型名称 | qwen3:8b |
| 基础 URL | http://<你的服务器内网IP>:11434 |
警告
⚠️ Docker 网络坑：MaxKB 跑在容器里，填 127.0.0.1 指向的是 MaxKB 容器自己，必须填宿主机的内网 IP 或 host.docker.internal。如果 MaxKB 与 Ollama 在同一台机器，用内网 IP 最稳妥。
添加完成后务必点「测试」按钮，看到返回成功再往下走 —— 模型调不通时，后面所有报错都会被归咎到知识库身上，很容易排查错方向。
第二步：创建知识库并上传文档
进入「知识库 → 创建知识库」，填写名称与描述，选择刚才添加好的向量模型。
警告
⚠️ 选完向量模型就别再换。更换 embedding 模型会导致向量维度不匹配，已有的索引全部失效，必须删库重建。这是 RAG 类系统通用的坑，MaxKB、FastGPT 都一样。
上传文档（支持 PDF、DOCX、TXT、Markdown、CSV，也支持在线网页 URL）：
上传后系统会自动执行「文本拆分 → 向量化入库」，文档状态从 解析中 变成 已完成 才可用。
文档处理参数怎么调
| 参数 | 作用 | 推荐值 |
|---|---|---|
| 分段方式 | 按字符或按层级拆分 | 常规文档用「智能分段」即可 |
| 分段长度 | 每段最大字符数 | 500 到 1500 字 |
| 重叠长度 | 相邻段的重叠字符 | 设为分段长度的 10% 左右 |
| 相似度阈值 | 低于该分值的片段不要 | 先用默认 0.6，看召回效果再微调 |
| 最大返回片段数 | 一次召回几段给模型 | 3 到 5 段 |
提示
💡 调参心法：回答含糊、东拉西扯 → 阈值调高；经常答「没找到相关内容」→ 阈值调低或分段缩短。不要一开始就大面积改参数，先用一个你确定文档里有的关键词做测试，有结果了再微调。
第三步：创建应用并绑定知识库（最容易卡的一步）
MaxKB 的心智模型是：知识库提供资料，应用负责问答，两者必须显式绑定。
- 进入「应用 → 创建应用」，选「知识库问答」类型
- 在应用配置里绑定刚才创建的知识库
- 选择用于生成回答的对话模型
- 写好提示词（可用默认模板，后续再优化）
- 点击「发布」
⚠️ 三个高频卡点：
| 现象 | 原因 | 解决 |
|---|---|---|
| 输入框是灰的，无法对话 | 应用未发布 | 回到应用详情页点「发布」 |
| 回答跟我的文档毫无关系 | 没绑定知识库 | 在应用配置里勾选目标知识库 |
| 一直说「未找到相关内容」 | 文档还在「解析中」 | 到知识库页确认文档状态是「已完成」 |
发布后，在应用页面的「演示」里直接提问验证。正确答案下方会列出引用的知识片段，点进去核对原文 —— 这是判断检索链路是否健康的最快方法。
第四步：嵌入到现有网站（零编码加 AI 能力）
MaxKB 支持把应用嵌入第三方页面，这是它比很多同类工具更实用的地方。
在应用详情页选择「嵌入」，会给出两种接入方式：
1<!-- 方式 1：iframe 全屏嵌入 -->
2<iframe
3 src="http://<你的服务器IP>:8080/ui/chat/<应用ID>"
4 width="100%"
5 height="600"
6 frameborder="0">
7</iframe>1<!-- 方式 2：悬浮聊天按钮（官方会给出一段 JS） -->
2<script>
3 // 粘贴官方提供的嵌入脚本即可
4</script>警告
⚠️ 如果主站是 HTTPS，嵌入的 iframe 地址必须同样是 HTTPS，否则浏览器会拦截混合内容。先按下一节配置 HTTPS 再嵌入。
也可以用 API 方式接入自己的系统（在应用详情页获取 API Key）：
1curl -X POST http://<你的IP>:8080/api/application/chat_openai/<应用ID> \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer <你的APIKey>" \
4 -d '{"message": "报销流程是怎样的？"}'Nginx 反向代理 + HTTPS
8080 不要直接暴露公网：
1apt-get install -y nginx certbot python3-certbot-nginx
2
3cat > /etc/nginx/sites-available/maxkb <<-'EOF'
4server {
5 listen 80;
6 server_name kb.yourcompany.com;
7
8 location / {
9 proxy_pass http://127.0.0.1:8080;
10 proxy_set_header Host $host;
11 proxy_set_header X-Real-IP $remote_addr;
12 proxy_http_version 1.1;
13 proxy_set_header Upgrade $http_upgrade;
14 proxy_set_header Connection "upgrade";
15 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
16 proxy_set_header X-Forwarded-Proto $scheme;
17 # 流式对话必须关缓冲
18 proxy_buffering off;
19 proxy_read_timeout 300s;
20 # 上传大文档需要
21 client_max_body_size 100m;
22 }
23}
24EOF
25
26ln -s /etc/nginx/sites-available/maxkb /etc/nginx/sites-enabled/
27nginx -t && systemctl reload nginx
28
29certbot --nginx -d kb.yourcompany.com备份与升级
备份
所有数据都在挂载目录里，备份就是把目录打包：
1#!/bin/bash
2DATE=$(date +%F)
3BACKUP_DIR=/root/maxkb-backup
4mkdir -p $BACKUP_DIR
5
6docker exec maxkb pg_dump -U maxkb maxkb > $BACKUP_DIR/pg_$DATE.sql
7tar czf $BACKUP_DIR/data_$DATE.tar.gz ~/.maxkb
8tar czf $BACKUP_DIR/py_$DATE.tar.gz ~/.python-packages
9
10# 只保留最近 7 天
11find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete
12find $BACKUP_DIR -name "*.sql" -mtime +7 -delete
13
14echo "备份完成: $BACKUP_DIR"提示
💡 建议用 SCP 或对象存储把备份同步到另一处，放在同一台机器上等于没备份。腾讯云 COS 走内网免流量费。
升级
⚠️ 升级前先看一眼当前挂载目录，这是最容易导致数据清空的一步：
1# 1. 记录当前挂载路径
2docker inspect maxkb | grep -A 5 Mounts
3
4# 2. 拉新镜像
5docker pull registry.fit2cloud.com/maxkb/maxkb:v1
6
7# 3. 删旧容器（数据目录不受影响）
8docker rm -f maxkb
9
10# 4. 用【与第 1 步完全一致】的挂载路径重新启动
11docker run -d --name=maxkb --restart=always \
12 -p 8080:8080 \
13 -v ~/.maxkb:/var/lib/postgresql/data \
14 -v ~/.python-packages:/opt/maxkb/app/sandbox/python-packages \
15 registry.fit2cloud.com/maxkb/maxkb:v1故障排查表
| # | 症状 | 可能原因 | 解决方案 |
|---|---|---|---|
| 1 | docker: command not found | Docker 未装成功 | 重跑腾讯云内网源安装步骤 |
| 2 | permission denied 连 docker socket | 用户不在 docker 组 | usermod -aG docker $USER 后重新登录 SSH |
| 3 | 拉取 maxkb 镜像极慢 | 源站网络问题 | 确认 Docker Hub 加速器已配并 systemctl restart docker |
| 4 | 容器一直显示 starting 不 healthy | 首次初始化未完成 | 耐心等 2 到 3 分钟；用 docker logs -f maxkb 看进度 |
| 5 | 8080 端口连不上 | 两层防火墙 | 腾讯云控制台安全组 + 系统 ufw 都要放行 |
| 6 | 忘了 admin 密码 | 默认密码改了记不住 | 进容器执行重置命令（官方文档有对应脚本） |
| 7 | 添加模型测试失败 | API Key 错或余额不足 | 到厂商控制台确认 Key 有效且有额度 |
| 8 | 接本地 Ollama 报连接拒绝 | 填了 127.0.0.1 | 改成宿主机内网 IP；确认 Ollama 在监听 0.0.0.0 |
| 9 | 模型测试通过但问答报错 | 对话模型与向量模型配反 | 知识库要选 embedding 模型，应用要选 chat 模型 |
| 10 | 文档一直卡在「解析中」 | 加密 PDF 或文件损坏 | 先本地转换一次再传；小文件重试看是否偶发 |
| 11 | 上传大文件失败 | Nginx 限制 | client_max_body_size 调到 100m 以上 |
| 12 | 向量化特别慢 | 低配机器处理大文档 | 用 4C8G 以上；分批上传；避开高峰期处理 |
| 13 | 报 dimension mismatch | 换了 embedding 模型 | 必须删掉知识库重建，别指望原地修复 |
| 14 | 回答总是「未找到相关内容」 | 相似度阈值过高 | 阈值调低到 0.4 左右试试 |
| 15 | 回答跑题，引用片段不相关 | 阈值过低拉进垃圾片段 | 阈值调高到 0.7 以上；开启 rerank 若版本支持 |
| 16 | 应用页面无法输入 | 未发布 | 回应用详情页点「发布」 |
| 17 | 绑定了知识库但回答无关 | 文档没解析完成 | 确认文档状态是「已完成」而不是「解析中」 |
| 18 | 对话没有打字机效果 | Nginx 开了缓冲 | 加 proxy_buffering off |
| 19 | 嵌入 iframe 被浏览器拦截 | HTTPS 页面嵌 HTTP | 先给 MaxKB 配好 HTTPS 再嵌入 |
| 20 | 升级后数据空了 | 挂载目录变了 | 用 docker inspect 找回原路径，用原路径重新启动容器 |
总结
通过本文，你在腾讯云上完成了 MaxKB 国产知识库的私有化部署，得到了一套文档不出内网、答案可溯源、还能一键嵌进现有网站的问答系统。
| 环节 | 关键点 |
|---|---|
| 部署 | 单镜像内置全部依赖，一条 docker run 即可；生产建议写 compose |
| 模型 | 先配模型并点测试；接本地 Ollama 要用宿主机内网 IP 而非 127.0.0.1 |
| 知识库 | embedding 模型选定后不要更换，否则索引全部失效需重建 |
| 应用 | 必须绑定知识库并发布才能对话 —— 新手最高频的卡点 |
| 安全 | 默认密码必须改；8080 不裸奔；备份要同步到另一处 |
四条落地建议：
- 先配模型再建库 —— 模型调不通时所有报错都会甩锅给知识库，确认模型能跑能省一半排查时间。
- embedding 一开始就定好 —— 中途换模型的代价是删库重建，这是整个流程里返工成本最高的决策。
- 用「演示」页而不是嵌入页调参 —— 演示页能直接看到引用片段，比在业务页面里盲调参数效率高得多。
- 备份脚本第一天就配上 —— 知识库的价值全在积累的数据里，重装容易重建难。
现在上传一份你们团队的真实流程文档，问一个只有内部同事才知道答案的问题 —— 当答案带着引用片段返回时，你会明白为什么「十分钟能跑通」这件事对小团队这么重要。
常见问题
QMaxKB 和 FastGPT、Dify 相比该怎么选？
三者都是优秀的国产平台，差异在复杂度与上手速度。MaxKB 最轻：数据库、向量库、缓存全部打包在一个镜像里，一条命令起服务，十分钟跑通问答，适合个人或小团队快速要一个能用的知识库。FastGPT 在 RAG 参数精调与工作流编排上更深，适合要持续调优召回质量的场景。Dify 生态最丰富，适合要搭复杂 Agent 与对接大量外部工具。如果你的首要诉求是「这周就要一个能回答内部文档问题的东西」，MaxKB 上手最快；确定要长期做深度优化，再考虑迁移到 FastGPT 或 Dify。
Q一定要接 GPU 服务器吗？
不需要。MaxKB 本身只负责文档切分、向量检索和应用编排，真正的模型计算交给你配置的模型供应商。如果你接的是云端 API（阿里云百炼、DeepSeek 等），4C8G 轻量服务器就完全够用。只有当你要在同一台机器上跑本地大模型时才需要更高配置或 GPU，那时可参考本站 Qwen3 本地部署那篇把模型跑在另一台机器上，MaxKB 通过网络调用。
Q为什么建完应用还是不能对话？
这是 MaxKB 新手最高频的卡点，通常三个原因：一是应用没有点击「发布」，未发布的应用无法发起对话；二是应用没有绑定知识库，或者绑定的知识库里文档还停在「解析中」没变成「已完成」；三是没有配置可用的模型，或模型额度已用完。排查顺序建议先看文档状态，再看应用是否已发布且绑定了知识库，最后到模型管理里点「测试」确认模型能调通。