MaxKB v2.7.0 Rocky Linux 9 部署手册

适配系统 ：Rocky Linux 9 x86_64（官方维护至2032年，替代CentOS7，无兼容性坑）
核心要求 ：后端端口 8080、前端独立启动端口 3000（前后端分离部署）
前置约定 ：全程使用 root 用户执行

前置说明（必看）

系统环境：Rocky Linux 9 自带 Python 3.9（系统服务【dnf、firewalld】强制依赖，严禁删除/修改）
项目环境：专用 Python 3.11（与系统Python完全隔离，命令用 python3.11/pip3.11）
Node.js 版本：必须安装 v18.20.8（Node.js 16 不兼容 Vite 所需的 Web Crypto API，会导致前端启动失败）
数据库：PostgreSQL 15 + pgvector 向量扩展、Redis
后端服务启动：python main.py start 为官方一站式启动入口，自动托管后端、Celery异步任务、本地模型服务，禁止单独启动子服务
前后端分离 ：后端服务 8080 + 前端服务 3000 独立启动

一、服务器初始化（标准操作）

1. 关闭SELinux + 安装基础工具

bash 复制代码

# 临时关闭SELinux
setenforce 0
# 永久关闭SELinux
sed -i 's/^SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
# 安装基础依赖工具
dnf install -y wget git tar gcc gcc-c++ make xz

2. 防火墙放行端口（核心必做）

开放项目所需全部端口，确保前后端、数据库、缓存服务正常通信：

bash 复制代码

firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --add-port=3000/tcp --permanent
firewall-cmd --add-port=5432/tcp --permanent
firewall-cmd --add-port=6379/tcp --permanent
firewall-cmd --reload
# 验证端口放行（确认输出包含上述4个端口）
firewall-cmd --list-ports

二、安装运行环境（一键复制执行）

1. 安装 Python 3.11（项目专用）

Rocky 9 官方源直接安装，无需编译，与系统Python 3.9完全隔离：

bash 复制代码

# 安装Python 3.11及依赖
dnf install -y python3.11 python3.11-devel python3.11-pip
# 升级项目专用pip（避免依赖安装报错）
pip3.11 install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple/
# 验证安装（确保输出 Python 3.11.x 和 pip 24.x 以上版本）
python3.11 -V && pip3.11 -V

2. 安装 Node.js 18.20.8（前端专用）

采用清华镜像直装（规避GitHub网络超时问题，适配Vite，解决Crypto API报错）：

bash 复制代码

# 下载清华镜像Node.js 18.20.8（国内网络极速）
wget https://mirrors.tuna.tsinghua.edu.cn/nodejs-release/v18.20.8/node-v18.20.8-linux-x64.tar.xz
# 解压至系统目录
tar -xf node-v18.20.8-linux-x64.tar.xz -C /usr/local/
# 重命名，方便后续管理
mv /usr/local/node-v18.20.8-linux-x64 /usr/local/node18
# 配置全局软链接（确保终端可直接调用node、npm）
ln -sf /usr/local/node18/bin/node /usr/bin/node
ln -sf /usr/local/node18/bin/npm /usr/bin/npm
ln -sf /usr/local/node18/bin/npx /usr/bin/npx
# 配置国内npm镜像（加速前端依赖安装）
npm config set registry https://registry.npmmirror.com/
# 验证安装（确保输出 v18.20.8）
node -v && npm -v

3. 安装 PostgreSQL 15 + pgvector（核心数据库）

数据库用于存储项目数据，pgvector扩展为向量检索功能必备：

bash 复制代码

# 安装PostgreSQL官方源
dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# 安装数据库+向量扩展
dnf install -y postgresql15-server postgresql15-contrib pgvector_15

# 初始化数据库
/usr/pgsql-15/bin/postgresql-15-setup initdb
# 启动数据库并设置开机自启
systemctl enable postgresql-15
systemctl start postgresql-15

# 非交互式配置数据库（密码：MaxKB@123，可按需修改，需与后续配置一致）
su - postgres -c "psql -c \"ALTER USER postgres WITH PASSWORD 'MaxKB@123';\""
su - postgres -c "psql -c \"CREATE DATABASE maxkb;\""
su - postgres -c "psql -d maxkb -c \"CREATE EXTENSION vector;\""

# 修改数据库配置，允许外部连接
sed -i 's/ident/md5/g' /var/lib/pgsql/15/data/pg_hba.conf
echo "host    all             all             0.0.0.0/0               md5" >> /var/lib/pgsql/15/data/pg_hba.conf
# 1. 取消注释并修改监听地址为 *
sed -i "s/#listen_addresses = 'localhost'/listen_addresses = '*'/g" /var/lib/pgsql/15/data/postgresql.conf

# 2. 取消注释并放开默认端口 5432
sed -i "s/#port = 5432/port = 5432/g" /var/lib/pgsql/15/data/postgresql.conf

# 重启数据库，使配置生效
systemctl restart postgresql-15

4. 安装 Redis（缓存服务）

用于缓存项目数据，提升系统响应速度：

bash 复制代码

# 安装Redis
dnf install -y redis
# 修改配置（适配MaxKB，仅允许本地访问，保障安全）
sed -i 's/bind 127.0.0.1 ::1/bind 127.0.0.1/g' /etc/redis/redis.conf
sed -i 's/protected-mode yes/protected-mode no/g' /etc/redis/redis.conf
# 启动Redis并设置开机自启
systemctl enable redis
systemctl start redis
# 验证安装（返回 PONG 即为成功）
redis-cli ping

三、下载 MaxKB v2.7.0 源码

bash 复制代码

# 创建项目根目录
mkdir -p /opt/maxkb && cd /opt/maxkb
# 克隆项目源码
git clone https://github.com/1panel-dev/MaxKB.git
# 进入项目核心目录
cd MaxKB
# 切换到v2.7.0正式版（固定版本，避免兼容性问题）
git checkout v2.7.0

四、项目配置

1. 生成 config.yml 配置文件

bash 复制代码

# 创建配置文件目录
mkdir -p /opt/maxkb/conf
# 生成配置文件（自动生成随机密钥，数据库/Redis配置与前文一致）
cat > /opt/maxkb/conf/config.yml << EOF
SERVER:
  HOST: 0.0.0.0
  PORT: 8080
  DEBUG: false
  SECRET_KEY: $(python3.11 -c "import secrets; print(secrets.token_urlsafe(50))")

DATABASE:
  ENGINE: postgresql
  NAME: maxkb
  USER: postgres
  PASSWORD: MaxKB@123
  HOST: localhost
  PORT: 5432

REDIS:
  HOST: localhost
  PORT: 6379
  PASSWORD: ""
  DB: 0
  PREFIX: maxkb

STORAGE:
  TYPE: local
  PATH: ./data/

EMBEDDING_MODEL:
  PATH: ./model/
  NAME: shibing624_text2vec-base-chinese
EOF

2. 配置项目核心文件（规避部署报错）

bash 复制代码

# 1. 配置数据库连接（确保与config.yml一致，避免连接失败）
cat > /opt/maxkb/MaxKB/apps/maxkb/conf.py << EOF
class Config(dict):
    defaults = {
        # 数据库相关配置
        "DB_HOST": "127.0.0.1",
        "DB_PORT": 5432,
        "DB_USER": "postgres",
        "DB_PASSWORD": "MaxKB@123",
        "DB_NAME": "maxkb",        # 必配项，缺失会导致数据库连接失败
        "DB_ENGINE": "dj_db_conn_pool.backends.postgresql",
        "DB_MAX_OVERFLOW": 80,
        'LOCAL_MODEL_HOST': '127.0.0.1',
        'LOCAL_MODEL_PORT': '11636',
        'LOCAL_MODEL_PROTOCOL': "http",
        'LOCAL_MODEL_HOST_WORKER': 1,
        # 语言
        'LANGUAGE_CODE': 'zh-CN',
        "DEBUG": False,
        # redis host
        'REDIS_HOST': '127.0.0.1',
	# 端口
        'REDIS_PORT': 6379,
        # 密码
        'REDIS_PASSWORD': '',
        # 库
        'REDIS_DB': 0,
        # 最大连接数
        'REDIS_MAX_CONNECTIONS': 100
    }
EOF

# 2. 固定嵌入模型名称（规避数据库迁移时非空约束报错）
sed -i "s/model_name = CONFIG.get('EMBEDDING_MODEL_NAME')/model_name = 'bge-small-zh-v1.5'/g" /opt/maxkb/MaxKB/apps/models_provider/migrations/0001_initial.py

五、后端服务部署（端口 8080）

1. 创建虚拟环境（隔离项目依赖）

bash 复制代码

# 进入项目核心目录
cd /opt/maxkb/MaxKB
# 创建Python虚拟环境（专用环境，不影响系统Python）
python3.11 -m venv venv
# 激活虚拟环境（激活后终端显示 (venv) 前缀，代表进入项目环境）
source venv/bin/activate

2. 安装后端依赖

bash 复制代码

# 安装poetry（依赖管理工具），国内镜像加速
pip install poetry -i https://pypi.tuna.tsinghua.edu.cn/simple/
# 配置阿里云镜像，加速依赖下载
poetry source add --priority=primary mirrors http://mirrors.aliyun.com/pypi/simple
# 安装项目所有后端依赖
poetry install

3. 初始化数据库（必做步骤）

执行数据库表结构迁移，生成项目所需表结构：

bash 复制代码

# 数据库表结构迁移
python main.py upgrade_db

六、前端服务部署（端口 3000）

1. 安装前端依赖

bash 复制代码

# 进入前端目录
cd /opt/maxkb/MaxKB/ui/
# 安装前端所有依赖（国内镜像加速，无报错）
npm install

七、生产环境后台启动服务（关闭终端不停止）

核心说明

python main.py start 自动启动后端服务（8080）、Celery异步任务服务、local_model本地模型服务，无需单独启动任何子服务，避免进程冲突。

bash 复制代码

# 1. 进入项目根目录 + 激活虚拟环境
cd /opt/maxkb/MaxKB
source venv/bin/activate

# 2. 后台启动核心服务（后端+Celery+本地模型），日志输出到server.log
nohup python main.py start > server.log 2>&1 &

# 3. 进入前端目录，后台启动前端服务（3000端口），日志输出到frontend.log
cd ui
nohup npm run dev > frontend.log 2>&1 &

八、服务验证 + 系统访问

1. 检查服务进程（确认所有服务正常运行）

bash 复制代码

ps -ef | grep -E "python main.py|npm run dev"

出现 python main.py start → 核心服务（后端+Celery+本地模型）运行正常
出现 npm run dev → 前端服务运行正常

2. 访问系统（完成验证）

访问地址：http://服务器IP:3000（确保服务器IP可正常访问）
初始用户名：admin
初始密码：MaxKB@123..
首次登录强制修改密码：Admin_1234（可后续自行修改）

九、服务管理命令（日常维护用）

bash 复制代码

# 1. 停止所有服务（一键关停，用于重启或维护）
pkill -f python && pkill -f node

# 2. 查看服务日志（排查问题时使用）
# 查看核心服务日志（后端+Celery+本地模型）
tail -f /opt/maxkb/MaxKB/server.log
# 查看前端服务日志
tail -f /opt/maxkb/MaxKB/ui/frontend.log

十、常见问题及解决方案（遇到问题时查阅）

1. 系统服务异常（dnf、firewalld无法使用）

问题现象：执行 dnf 命令报错，提示"no module named xxx"
原因：误删除/修改了 Rocky Linux 9 自带的 Python 3.9（系统服务强制依赖）

解决方案：

bash 复制代码

# 一键恢复系统Python3.9及相关依赖
dnf reinstall -y python3 python3-libs python3-setuptools python3-pip
# 恢复系统默认软链接
ln -sf /usr/bin/python3.9 /usr/bin/python3
ln -sf /usr/bin/pip3.9 /usr/bin/pip3

2. 前端启动失败，提示"crypto.getRandomValues is not a function"

问题现象：启动前端时报错，Vite无法正常运行
原因：安装了 Node.js 16 版本，不兼容Vite所需的 Web Crypto API
解决方案：卸载Node.js 16，按手册步骤重新安装 Node.js 18.20.8（清华镜像直装）

3. 数据库连接失败，提示"用户 root 认证失败"

问题现象：后端启动报错，无法连接数据库
原因：conf.py 缺失 DB_NAME 配置，程序默认使用root用户连接数据库
解决方案：重新执行"四、项目配置"中的第2步，确保 conf.py 包含 DB_NAME: maxkb

4. 数据库迁移报错，提示"model_name 非空约束失败"

问题现象：执行 python main.py upgrade_db 报错，提示null值违反非空约束
原因：嵌入模型名称未固定，配置文件中无默认值，读取为空
解决方案：重新执行"四、项目配置"中的第2步（sed命令），固定模型名称为 bge-small-zh-v1.5

5. 核心服务启动后自动退出

问题现象：执行后台启动命令后，查看进程发现 python main.py start 不存在
原因：数据库迁移失败、配置文件错误（如数据库密码不匹配）
解决方案：前台启动服务，查看真实报错，针对性修复：
bash 复制代码
```
cd /opt/maxkb/MaxKB
source venv/bin/activate
python main.py start
```

6. 向量检索功能报错，提示"type 'vector' does not exist"

问题现象：使用知识库、对话功能时，报错提示向量类型不存在
原因：① pgvector 扩展未安装；② conf.py 配置错误，未连接到正确的 maxkb 数据库
解决方案：
1. 重新执行"二、安装运行环境"中的第3步，确保 pgvector 扩展已创建
2. 检查 conf.py 和 config.yml 中的数据库配置，确保 DB_NAME: maxkb

7. 单独启动Celery/LocalModel失败

问题现象：执行 nohup python main.py dev celery ... 启动失败，提示端口占用
原因：python main.py start 已自动托管所有子服务，单独启动会导致进程/端口冲突
解决方案：停止所有服务，重新执行手册"七、生产环境后台启动服务"步骤，不单独启动任何子服务

8. 前端依赖安装失败

问题现象：执行 npm install 报错，提示依赖下载超时
原因：npm镜像未配置或镜像地址无效

解决方案：重新配置npm国内镜像，再安装依赖：

bash 复制代码

npm config set registry https://registry.npmmirror.com/
rm -rf node_modules
npm install

总结

核心禁忌：不删除系统Python3.9、不单独启动子服务、不修改向量字段相关代码；
遇到问题时，直接查阅"十、常见问题及解决方案"，对应问题找到修复命令即可；
部署完成后，验证系统访问正常、核心功能（对话、知识库）可用，即部署成功。