部署前先了解 MaxKB 适合做什么

MaxKB 是面向知识库问答、文档检索和智能客服场景的 AI 知识库平台。

它常用于企业内部资料问答、产品手册查询、运维知识沉淀、售前售后辅助等场景。

其优势在于安装门槛相对低。它能把文档、网页、文本等资料整理为可检索知识，并通过大模型生成回答。

对于希望在 Linux 服务器上长期运行的团队，推荐采用容器方式部署，便于升级、迁移和回滚。

部署前必须明确三件事：

• 用途：服务器是用于测试还是生产？
• 公网：是否需要公网访问？
• 数据：知识库数据是否需要长期保留？

测试环境可以使用较低配置。生产环境则要预留 CPU、内存、磁盘和备份空间，避免后期因资源不足导致服务异常。

服务器环境准备

系统与配置要求

建议使用常见 Linux 发行版，如 Ubuntu 22.04、Debian 12、CentOS Stream 或 Rocky Linux。

基础配置建议为 2 核 CPU、4GB 内存、40GB 磁盘起步。

如果文档量较大、并发访问较多，建议 4 核 8GB 或更高。

服务器时间需要保持准确，可安装时间同步服务，避免证书、日志和任务调度出现偏差。

登录后的基础操作

登录服务器后，先更新系统组件：

• Ubuntu 或 Debian 可执行：apt update && apt upgrade -y
• CentOS/Rocky 系可执行：dnf update -y

随后检查基础工具：curl、wget、vim、tar 是否可用。不存在时按系统包管理器安装。

安全建议：生产环境不建议直接使用最高权限账号长期操作。可创建普通运维账号，并只在需要时提权执行。

安装容器运行环境

检查并安装 Docker

MaxKB 常见部署方式是通过 Docker 运行。先检查是否已安装：docker -v。

如果未安装，可使用官方安装脚本或系统软件源安装。以 Ubuntu 为例：

apt install -y docker.io docker-compose-plugin

安装完成后启动服务：systemctl enable --now docker。

再执行 docker ps，如果能看到容器列表，说明环境基本可用。

端口与网络配置

部分服务器默认未开放相关端口。MaxKB 通常会映射一个 Web 访问端口，例如 8080 或 3000，具体以部署命令为准。

需要在服务器防护策略中放行该端口，但不建议一次性开放过多端口。

若计划通过域名访问，可在后续使用 Nginx 做反向转发，并配置 HTTPS 证书，以提升传输安全性。

创建数据目录与部署文件

统一目录管理

为了方便备份和迁移，建议不要把数据散落在临时目录。

创建统一目录：mkdir -p /opt/maxkb，并进入目录：cd /opt/maxkb。

后续的配置文件、数据卷映射和备份文件都可围绕该目录管理。

若服务器存在多块磁盘，建议把数据目录放在容量充足、性能稳定的磁盘分区。

使用 Docker Compose

如果使用 Docker Compose，通常需要准备一个 docker-compose.yml 文件，定义镜像、端口、数据卷和重启策略。

示例思路为：指定 MaxKB 镜像名称，映射宿主机端口到容器端口，挂载本地数据目录，并设置 restart: always。

注意：实际镜像名称和容器端口应以 MaxKB 官方说明为准。复制命令时不要混用不同版本文档，避免启动后页面空白或接口不匹配。

启动服务并验证访问

启动与状态检查

配置完成后，在部署目录执行：docker compose up -d。其中 -d 表示后台运行，命令返回后容器会在后台保持服务。

随后查看运行状态：docker ps，确认 MaxKB 容器处于 Up 状态。

若容器反复重启，可查看日志：docker logs -f 容器名。重点关注端口占用、环境变量错误、数据目录权限不足等信息。

首次访问与配置

浏览器访问 http://服务器IP:端口，看到初始化或登录页面即说明 Web 服务已启动。

首次进入后台后，应立即修改默认账号密码。

按需配置模型服务、知识库、分段策略和检索参数。

上传文档前建议先用少量样本文档测试解析效果。确认问答质量、引用来源和响应速度符合预期，再批量导入正式资料。

配置后台长期运行

自动重启与系统自启

容器部署时，后台运行主要依赖两层保障：

• 系统自启：Docker 服务随系统启动，可通过 systemctl enable docker 设置
• 容器自启：MaxKB 容器具备自动重启策略，可在 Compose 文件中使用 restart: always 或 restart: unless-stopped

服务器重启后，可执行 docker ps 检查容器是否自动恢复。

使用 Compose 更规范

如果不使用 Compose，而是通过 docker run 启动，也需要增加 --restart always 参数，并正确挂载数据目录。

生产环境不建议仅在命令行临时启动。因为一旦终端关闭、服务器重启或命令参数遗失，后续维护会变得困难。

Compose 文件相当于部署说明书，便于团队交接和复现。

域名访问与反向转发建议

Nginx 配置要点

当 MaxKB 需要给团队多人使用时，建议使用域名加 Nginx 反向转发，而不是让用户直接记 IP 和端口。

Nginx 可监听 80 和 443 端口，再把请求转发到本机 MaxKB 端口。

配置时要保留必要的请求头，如 Host、X-Real-IP、X-Forwarded-For，便于应用识别来源与生成正确链接。

HTTPS 与安全访问

配置 HTTPS 时，应使用正规证书并设置自动续期。证书过期会导致浏览器拦截访问，影响业务使用。

若平台上传的资料包含内部制度、客户资料或技术文档，应限制访问范围，避免把后台管理入口毫无限制地暴露在公共网络中。

升级、备份与回滚思路

升级前必须备份

升级前必须先备份。至少备份三类内容：

• Compose 配置文件
• 数据挂载目录
• 数据库相关数据卷

停止服务：docker compose down

打包目录：tar -czf maxkb-backup-日期.tar.gz /opt/maxkb

如果数据量较大，应使用增量备份或快照方案，并定期做恢复演练，确认备份不是“看起来存在但无法使用”。

升级与回滚步骤

升级时先阅读版本说明，确认是否存在配置变更、数据结构变更或不兼容项。

拉取新镜像：docker compose pull

启动服务：docker compose up -d

如果升级后出现异常，可切回旧镜像版本，并恢复备份目录。

生产环境不建议在业务高峰直接升级，最好先在测试服务器验证。

常见问题排查

页面无法访问

先确认容器是否运行，再确认端口是否监听，可使用 ss -lntp 查看。

若本机能访问、外部不能访问，通常与服务器防护策略、云主机安全规则或 Nginx 配置有关。

若容器启动失败，优先查看日志，不要盲目反复重装，否则可能覆盖已有数据。

文档上传与问答效果

上传文档失败时，检查：

• 磁盘空间
• 文件大小限制
• 目录权限
• 文档格式

问答效果不佳时，不一定是部署问题。可能与文档质量、切分方式、模型能力和检索参数有关。

可以从小样本开始调整分段长度、召回数量和提示词，逐步优化。不要一次性导入大量杂乱资料。

安全边界与运维建议

账号与数据安全

MaxKB 属于知识库与模型应用平台，部署后应重点保护账号、数据和接口。

• 不要使用弱密码
• 不要把管理员账号共享给多人
• 不要把模型密钥写在公开文档或聊天记录中

涉及内部资料的知识库，应设置清晰的访问权限和数据更新流程，避免员工上传无关或未确认来源的文件。

运维监控与规范

运维层面建议开启日志留存、磁盘监控和服务健康检查。

每次调整配置、升级版本、导入大批量文档前，都应记录操作时间、操作人、变更内容和回退方案。

对于企业应用来说，部署成功只是第一步。持续备份、定期更新、权限管理和故障演练，才是让 MaxKB 稳定服务的关键。