开发速查

主题

MaxKB 部署与容器操作 ​

官方文档：https://maxkb.cn/docs/v2/installation/online_installtion/#12 本文聚焦官方标准做法（一键/离线安装、容器管理、启停、自定义 UI），不展开 Docker 基础科普。

一、版本与运行环境 ​

⚠️ MaxKB 2.x 版本信息：官方镜像仓库已迁移，registry.fit2cloud.com/maxkb/maxkb 为历史版本。 最新版请参考官方文档：https://maxkb.cn/docs/ 常见镜像仓库：docker pull 1175368340/maxkb/maxkb:latest（Docker Hub 镜像加速）

部署前确认 Docker / Docker Compose 已安装，并记录版本（排错时常用）：

bash
docker --version
docker compose version        # Docker v2（主流，2023 起默认）；旧版 v1 才是 docker-compose --version

下文启停命令统一写作 docker compose；若你的环境是老版，请改成 docker-compose（带连字符）。

二、安装方案 ​

1. 官网一键安装（推荐） ​

  • 文档地址：https://maxkb.cn/docs/
  • 特点：
    • 一键安装启动，自动包含数据卷挂载。
    • 可修改实例名称与对外映射端口。
    • 最新版具备流程编排能力，支持多对话模式，支持图片 / 视频等多模态模型。
    • 优先选「离线安装」可永久锁定版本（如 2.7+）不升级；首次在线安装后也可离线升级。
  • 数据卷映射：~/.maxkb:/opt/maxkb，删除容器再启动数据不丢失。
bash
# 示例：使用 Docker Hub 镜像加速的 MaxKB
docker run -d \
  --name=maxkb \
  --restart=always \
  -p 8080:8080 \
  -v ~/.maxkb:/opt/maxkb \
  1175368340/maxkb/maxkb:latest
参数作用
-d后台运行
--name=maxkb容器命名，便于后续管理
--restart=always宿主机重启后自动拉起
-p 8080:8080宿主机端口:容器端口
-v ~/.maxkb:/opt/maxkb持久化数据卷，防数据丢失

2. 离线安装（推荐用于生产锁版本） ​

  • 适合内网 / 需要锁定版本（如 2.7+）的场景。
  • 首次在线安装后，可离线升级到指定版本。
  • 离线包自带安装脚本，按官方离线文档执行即可。

3. 镜像加速 / 备用源 ​

  • Docker Hub 镜像：docker pull 1175368340/maxkb/maxkb:latest（国内常用）
  • 原始镜像：docker pull jumpserver/maxkb:latest（官方）
  • 腾讯云镜像为历史版本，不再推荐。

三、容器日常管理 ​

操作命令说明
查看所有镜像docker images列出本地镜像，确认 maxkb 镜像存在
停止容器docker stop maxkb优雅停止（发 SIGTERM）
启动容器docker start maxkb重启已停止容器
查看状态docker ps -a含运行中 / 已停止 / 已退出，看 STATUS 列
查看日志docker logs maxkb排错首选；加 -f 实时跟踪，--tail 100 看末尾
进入容器docker exec -it maxkb bash交互式 shell；Alpine 基础镜像用 sh
查看数据目录ls -l ~/.maxkb/确认挂载数据卷内容
删除容器docker rm maxkb删容器后可用 docker run 重启，数据不丢
删除镜像docker rmi <镜像名>删镜像即不可恢复，非必要不执行
bash
# 停止所有运行中的容器
docker stop $(docker ps -aq)
# 清理所有已停止的容器（释放空间）
docker container prune

docker stop/start 是单容器启停；docker compose down/up 才是带依赖（pgsql / redis）的完整启停，见下一节。

四、启动 / 停止 / 重启服务 ​

MaxKB 由多个 Compose 文件组合启动（主服务 + pgsql + redis）。必须用同一组 -f 文件保证依赖一致。

下文统一采用 docker compose（v2，无连字符）；老版 v1 请自行替换为 docker-compose。

bash
cd /opt/maxkb

# 查看运行状态
docker compose ps

# 停止（含 pgsql / redis）
docker compose -f docker-compose.yml \
              -f docker-compose-pgsql.yml \
              -f docker-compose-redis.yml \
              down

# 启动（强制重建容器，配置变更后必加 --force-recreate）
docker compose -f docker-compose.yml \
              -f docker-compose-pgsql.yml \
              -f docker-compose-redis.yml \
              up -d --force-recreate

# 查看日志
docker compose logs -f --tail 200 web
  • 修改了 docker-compose.yml（如挂载、端口）后，必须带 --force-recreate 才能生效。
  • down 默认不删数据卷；down -v 会删数据卷，生产勿用。

五、自定义 UI 部署 ​

适合对 MaxKB 前端做二次开发（改 logo、文案、主题等）后挂载到容器。

1. 提取 UI 目录（从容器拷到宿主机） ​

bash
docker cp maxkb:/opt/maxkb-app/ui /root/maxkb-ui

有源码的可直接打包，无需此步。

2. 编辑部署目录的 compose 文件（注意：是部署目录 /opt/maxkb/docker-compose.yml，不是安装包内的文件） ​

bash
cd /opt/maxkb
vi /opt/maxkb/docker-compose.yml

添加 UI 挂载（以及标准的持久化挂载）：

yaml
volumes:
  - ${MAXKB_BASE}/maxkb/python-packages:/opt/maxkb/python-packages
  - ${MAXKB_BASE}/maxkb/logs:/opt/maxkb/logs
  - ${MAXKB_BASE}/maxkb/local:/opt/maxkb/local
  - /root/maxkb-ui:/opt/maxkb-app/ui    # ← 外挂 UI 目录
env_file:
  - ${MAXKB_BASE}/maxkb/conf/maxkb.env

3. 修改对外端口（8080 易被浏览器禁用，建议改 9000） ​

yaml
# 修改前
ports:
  - ${MAXKB_EXPOSE_WEB_LISTEN_HOST:-0.0.0.0}:${MAXKB_PORT:-8080}:8080
healthcheck:
  test: ["CMD", "curl", "-f", "localhost:8080"]

# 修改后
ports:
  - ${MAXKB_EXPOSE_WEB_LISTEN_HOST:-0.0.0.0}:9000:8080
healthcheck:
  test: ["CMD", "curl", "-f", "localhost:9000"]

映射的是宿主机 9000 → 容器 8080，容器内端口不变。

4. 修改 UI 源码 ​

  • 开发环境要求：Node.js 20.0.0；本地只启动前端时，把 vite.config.ts 的代理地址 127.0.0.1 改为线上后端 193.112.163.19。
  • 常见修改点：
    1. 登录页：背景图、图标、语言切换
    2. 首页：右上角项目地址、用户手册、论坛求助
    3. 用户下拉菜单：语言切换、关于
    4. 静态资源：public/favicon.ico 和 public/theme/default.jpg 等
  • 构建命令：npm run build（管理端）、npm run build-chat（用户端）。

5. 重启生效 ​

按第四节命令重启。UI 外挂后约 5 分钟才生效，且访问速度会变慢（属已知性能影响）。

六、常见问题 ​

  • 资源加载失败 / 页面白屏：通常是前端打包编译报错导致资源未生成。检查构建日志，确认 npm run build / npm run build-chat 无报错后再挂载重启。
  • 配置不生效：忘记 --force-recreate，或改了安装包内的 docker-compose.yml 而非部署目录的。
  • 数据丢失：误用 docker-compose down -v 或删除 ~/.maxkb 数据卷。
  • 端口被占用：改用其他宿主机端口（如 9000），参考第五节。

附录：前端开发脚本速查（package.json scripts） ​

二次开发参考：本地修改 MaxKB UI 后使用的 npm 脚本，部署 MaxKB 时无需关注。

jsonc
{
  "scripts": {
    "dev": "vite",                                          // 启动开发服务器（Vite），热更新
    "chat": "vite --mode chat",                             // chat 模式开发服务器
    "build": "run-p type-check \"build-only {@}\" --",       // 生产构建（先类型检查）
    "build-chat": "run-p type-check \"build-only-chat {@}\" --", // chat 模式生产构建
    "preview": "vite preview",                              // 预览生产构建
    "build-only": "vite build",                             // 仅打包（跳过类型检查）
    "build-only-chat": "vite build --mode chat",            // chat 模式仅打包
    "type-check": "vue-tsc --build",                        // TypeScript 类型检查
    "lint": "eslint . --fix",                               // ESLint 检查并自动修复
    "format": "prettier --write src/"                      // Prettier 格式化
  }
}

© 2026 开发速查