一、版本

二、系统初始化

1. 更新系统

apt update apt upgrade -y

安装基础工具

apt install -y \ git \ curl \ wget \ vim \ build-essential \ zlib1g-dev \ libncurses5-dev \ libgdbm-dev \ libnss3-dev \ libssl-dev \ libreadline-dev \ libffi-dev \ libsqlite3-dev \ libbz2-dev \ software-properties-common

三、安装 Python 3.11

Ubuntu 22.04 默认 Python 3.10。我是通过deadsnakes PPA 安装

1、添加 PPA 并更新源

add-apt-repository ppa:deadsnakes/ppa apt update

2、安装Python3.11

apt install python3.11

建议同时安装开发头和虚拟环境支持：

apt install python3.11-dev python3.11-venv

3、验证是否为3.11.x

python3.11 --version

四、pip安装uv

Ubuntu 22.04 默认没有 pip：

先安装：

apt update apt install python3-pip -y

检查：

pip3 --version

安装 uv：

pip3 install uv

检查：

uv --version

五、安装 PostgreSQL

1、添加 PostgreSQL 官方仓库

安装依赖：

apt update apt install -y curl ca-certificates gnupg

添加 PostgreSQL GPG Key：

install -d /usr/share/postgresql-common/pgdg curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \ --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc

添加 Ubuntu 22.04 jammy 仓库：

sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] \ https://apt.postgresql.org/pub/repos/apt jammy-pgdg main" \ > /etc/apt/sources.list.d/pgdg.list'

更新：

apt update

2. 安装PostgreSQL 17

apt install -y postgresql-17 postgresql-client-17

安装完成检查：（正常 psql (PostgreSQL) 17.x）

psql --version

查看：

systemctl status postgresql

设置开机启动：

systemctl enable postgresql

3、安装pgvector 扩展包

apt install postgresql-17-pgvector

重启服务

systemctl restart postgresql

4、查看 PostgreSQL 17 集群

pg_lsclusters

正常应该类似：

Ver Cluster Port Status Owner 17 main 5432 online postgres

5、 创建数据库

进入：

sudo -u postgres psql

执行：

CREATE USER maxkb WITH PASSWORD '你的密码'; CREATE DATABASE maxkb OWNER maxkb; ALTER USER maxkb CREATEDB;

切换到maxkb数据库

\c maxkb

给 maxkb 用户授权 public schema

GRANT ALL ON SCHEMA public TO maxkb;

修改 schema 所属用户

ALTER SCHEMA public OWNER TO maxkb;

给 maxkb 数据库全部权限

GRANT ALL PRIVILEGES ON DATABASE maxkb TO maxkb;

创建 pgvector 扩展

CREATE EXTENSION "vector";

测试：

psql \ -h 127.0.0.1 \ -p 5432 \ -U maxkb \ -d maxkb

六、安装 Redis

apt install redis-server -y

启动：

# 启动 Redis 服务 systemctl start redis-server # 设置开机自启 systemctl enable redis-server # 查看服务状态 systemctl status redis-server

测试：

redis-cli ping

返回：pong

七、安装 Node.js

MaxKB 前端需要。下载并运行NodeSouce安装脚本（针对node.js 20）

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

安装：

apt install -y nodejs

查看：

node -v npm -v

八、运行代码

1、拉取MaxKB源码

github链接：https://github.com/1Panel-dev/MaxKB
我是下载了zip包，然后再解压

安装unzip

apt update apt install unzip

解压

unzip your_file.zip

2、运行后端

① 配置文件（MaxKB v2没有配置文件，我是参考v1的）

mkdir /opt/maxkb/conf cd /opt/maxkb/conf vim config.yml

把下面的内容拷到config.yml，并改成对应的

#数据库配置
B_HOST: 127.0.0.1
DB_PORT: 5432
DB_NAME: maxkb
DB_USER: maxkb
DB_PASSWORD: 你的密码
DB_ENGINE: dj_db_conn_pool.backends.postgresql
DB_MAX_OVERFLOW: 80

#redis配置
REDIS_HOST: 127.0.0.1
REDIS_PORT: 6379
REDIS_PASSWORD: "" #前面安装redis的时候我没有设置密码
REDIS_DB: 0
REDIS_MAX_CONNECTIONS: 100

LOCAL_MODEL_HOST: 127.0.0.1
LOCAL_MODEL_PORT: 11434
LOCAL_MODEL_PROTOCOL: http
LOCAL_MODEL_HOST_WORKER: 1
EMBEDDING_MODEL_NAME: maxkb-embedding
EMBEDDING_MODEL_PATH: /opt/maxkb-app/model/embedding

LANGUAGE_CODE: zh-CN
DEBUG: true
TIME_ZONE: Asia/Shanghai

ADMIN_PATH: /admin
CHAT_PATH: /chat

SESSION_TIMEOUT: 28800

EMBEDDING_MODEL_NAME: maxkb-embedding
EMBEDDING_MODEL_PATH: /opt/maxkb-app/model/embedding
这是我从docker里面拷出来的

通过网盘分享的文件：max-app.zip
链接: https://pan.baidu.com/s/17DHO25pqw0xbR3E25ohCmg?pwd=0000 提取码: 0000

② 创建虚拟环境

进入 MaxKB 根目录：

例如：

cd /root/MaxKB-2

删除旧环境（如果之前 pip 创建过）：

rm -rf .venv

使用 uv 创建：

uv venv --python 3.11

③ 安装依赖（依赖文件：/MaxKB-2/pyproject.toml ）

uv sync

安装完成查看：

uv pip list

④ 激活环境

source .venv/bin/activate

看到：

(MaxKB-2)

运行python

python main.py dev

查看8080端口是否开启

ss -tuln | grep :8080

3、运行前端

进入：

cd /root/MaxKB-2/ui

①安装：

npm install

②启动：(对应配置文件：/env.env )

npm run dev

③ 启动对话(对应配置文件：/env.chat)

npm run chat

④ 浏览器访问

http://localhost:3001/
用户名：admin
密码：MaxKB@123..