前言

企业智能知识库 Python 后端是一套基于 FastAPI 框架的企业级智能知识管理平台。

本文介绍如何在本地环境中运行该项目。

1. 环境准备

  • Python:3.12+(推荐 3.13)
  • MySQL:8.0
  • Redis:7.2+
  • Elasticsearch:8.x
  • MongoDB:7.0
  • Neo4j:5.x
  • MinIO:S3 兼容对象存储
  • RabbitMQ:3.x
  • UV:Python 包管理器
  • Git:代码版本管理

1.1 安装 Python

macOS:

brew install python@3.13

或者访问 https://www.python.org/downloads/ 下载 .pkg 安装包。

Windows:

访问 https://www.python.org/downloads/ 下载 3.12 或 3.13 版本安装包,安装时务必勾选 "Add Python to PATH"。

验证:

python --version

1.2 安装 UV

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

访问 https://docs.astral.sh/uv/getting-started/installation/ 下载 Windows 安装包。

安装后重启终端,验证:

uv --version

1.3 安装 Git

macOS:

brew install git
# 或:已安装 Xcode Command Line Tools 则自带 git

Windows:

访问 https://git-scm.com/download/win 下载安装。

验证:

git --version

2. 获取代码

cd ~
mkdir -p projects && cd projects
git clone https://gitcode.com/dv-susan/knowledge-base-python.git
cd project/knowledge-base-python

3. 安装并启动基础服务

3.1 MySQL 8.0

macOS:

brew install mysql@8.0
brew services start mysql@8.0

设置 root 密码:

mysql -uroot -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'root123456'; FLUSH PRIVILEGES;"

Windows:

  1. 访问 https://dev.mysql.com/downloads/mysql/ 下载 MySQL Installer(选 8.0 版本)
  2. 运行安装程序,选择 "Developer Default" 安装类型
  3. 安装过程中设置 root 密码为 root123456
  4. 安装完成后 MySQL 会作为 Windows 服务自动启动

验证:

mysql -uroot -proot123456 -e "SELECT VERSION();"

3.2 Neo4j

macOS:

brew install neo4j
neo4j-admin dbms set-initial-password neo4j123
brew services start neo4j

Windows:

  1. 访问 https://neo4j.com/download/ 下载 Community Edition ZIP 包
  2. 解压到本地目录(如 C:\neo4j)
  3. 在命令行中进入 C:\neo4j 目录,执行:

     bin\neo4j-admin.bat dbms set-initial-password neo4j123
     bin\neo4j.bat console

    或执行 bin\neo4j.bat windows-service install 安装为 Windows 服务后启动

验证:

cypher-shell -u neo4j -p neo4j123 "RETURN 1;"

4. 数据库初始化

4.1 创建 MySQL 数据库

macOS / Linux:

mysql -uroot -proot123456 <<'SQL'
CREATE DATABASE IF NOT EXISTS kb_user       DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS kb_document   DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS kb_search     DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS kb_file       DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS kb_ai         DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS kb_statistics DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS kb_foundation DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
SHOW DATABASES;
SQL

Windows:

打开 MySQL 命令行客户端(开始菜单搜索 "MySQL Command Line Client"),逐条执行上述 SQL。或者使用 Navicat / DBeaver 等可视化工具,连接 127.0.0.1:3306,用户名 root,密码 root123456,执行上述 SQL。

数据库初始化脚本通过文章《企业智能知识库系统本地运行(指南)》获取。

看到 7 个 kb_ 开头的数据库即表示创建成功。

4.2 执行数据库迁移(建表)

uv run alembic upgrade head

看到 Running upgrade ... -> ... 表示建表成功。


5. 项目配置

5.1 创建环境变量文件

# macOS/Linux
cp .env.example .env

# Windows
copy .env.example .env

5.2 编辑 .env 文件

用编辑器打开 .env,修改以下关键配置。

必填配置:

# ── MySQL ──
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=root123456

# ── Redis ──
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=2
REDIS_PASSWORD=

# ── Elasticsearch ──
ES_HOST=127.0.0.1
ES_PORT=9200
ES_USER=
ES_PASSWORD=

# ── MongoDB ──
MONGO_HOST=127.0.0.1
MONGO_PORT=27017
MONGO_USER=
MONGO_PASSWORD=
MONGO_DB=knowledge_base

# ── Neo4j ──
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=neo4j123

# ── MinIO / S3 ──
S3_ENDPOINT=http://127.0.0.1:9000
S3_ACCESS_KEY=rustfs
S3_SECRET_KEY=rustfs123
S3_BUCKET=knowledge-dev
S3_REGION=us-east-1
S3_USE_SSL=false

# ── RabbitMQ ──
RABBITMQ_HOST=127.0.0.1
RABBITMQ_PORT=5672
RABBITMQ_USER=admin
RABBITMQ_PASSWORD=susan123

# ── Celery ──
CELERY_BROKER_URL=redis://127.0.0.1:6379/3
CELERY_RESULT_BACKEND=redis://127.0.0.1:6379/3

AI 大模型配置(如果使用 AI 功能必须配置):

# ── 通义千问 ──
QWEN_API_KEY=your-qwen-api-key
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen3-max

# ── DeepSeek ──
DEEPSEEK_API_KEY=your-deepseek-api-key
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
DEEPSEEK_MODEL=deepseek-chat

JWT 密钥配置(生产环境务必修改):

JWT_SECRET_KEY=your-secret-key-change-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=120
REFRESH_TOKEN_EXPIRE_DAYS=7

5.3 安装 Python 依赖

uv sync
uv pip install pymupdf

5.4 idea中配置密钥

咱们的企业智能知识库python项目中包含了:邮件、大模型等功能,需要配置自己的专属密码和key。

在idea中找到KB Startup(Shell),点击Edit Configurations,打开配置窗口。

图片.png

在窗口中找到Environment variables

图片.png

在里面配置如下参数:

PYTHONUNBUFFERED=1;QWEN\_API\_KEY=你们的千问key;DEEPSEEK\_API\_KEY=你的deepseek key;SMTP\_USER=发件人邮箱;SMTP\_PASSWORD=发件人密码;SMTP\_FROM=发件人邮箱


6. 启动后端(命令行)

uv run uvicorn main:app --host 0.0.0.0 --port 8080 --reload

看到以下输出表示启动成功:

INFO:     Uvicorn running on http://0.0.0.0:8080
INFO:     Starting knowledge-base v0.1.0
INFO:     Environment: development

7. 访问系统

Swagger 页面上可以直接测试所有 API 接口。

8. 常见问题排查

MySQL 连接失败

Can't connect to MySQL server on '127.0.0.1'
  • macOS:brew services list | grep mysql 确认运行状态
  • Windows:通过 services.msc 确认 MySQL 服务状态
  • 确认 .env 中 MYSQL_PASSWORD=root123456
  • 测试:mysql -uroot -proot123456

Redis 连接失败

  • macOS:brew services list | grep redis
  • Windows:通过 services.msc 确认 Redis / Memurai 服务状态
  • WSL 用户:wsl sudo service redis-server status

Elasticsearch 启动失败

macOS:

tail -f /opt/homebrew/var/log/elasticsearch/elasticsearch.log

Windows:

查看 C:\elasticsearch\logs\ 目录下的日志文件。

Linux 还需要设置 sudo sysctl -w vm.max_map_count=262144。

端口被占用

macOS:

lsof -i :3306    # MySQL
lsof -i :6379    # Redis
lsof -i :9200    # Elasticsearch
lsof -i :27017   # MongoDB
lsof -i :7687    # Neo4j
lsof -i :5672    # RabbitMQ
lsof -i :9000    # MinIO
lsof -i :8080    # Python 后端
kill -9 <PID>

Windows:

netstat -ano | findstr :3306
# 最后一列是 PID,然后用:
taskkill /PID <PID> /F

uv sync 失败(cryptography 编译失败)

macOS:

brew install openssl
export LDFLAGS="-L$(brew --prefix openssl)/lib"
export CFLAGS="-I$(brew --prefix openssl)/include"
uv sync

Windows:

安装 Visual C++ Build Tools(https://visualstudio.microsoft.com/visual-cpp-build-tools/),或使用预编译 Python 版本。

Alembic 迁移失败

  1. 确认 9 个数据库已创建:mysql -uroot -proot123456 -e "SHOW DATABASES;"
  2. 确认 .env 中 MySQL 密码正确
  3. 重试:uv run alembic upgrade head

IDEA 中环境变量不生效

如果 IDEA 中运行项目提示数据库连接失败,但命令行 uv run uvicorn ... 正常:

  1. 确认 Run Configuration 中已正确加载 .env 文件
  2. 检查 Working directory 是否设置为项目根目录
  3. 尝试重启 IDEA
  4. 临时方案:在 Environment variables 中逐条手动添加所有环境变量

上传 PDF 后内容显示为 [文件: xxx]

缺少 pymupdf 库:

uv pip install pymupdf

重启后端即可。

知识图谱无法使用(Neo4j 未连接)

cypher-shell -u neo4j -p neo4j123 "RETURN 1;"
  • macOS:brew services list | grep neo4j
  • Windows:通过 services.msc 确认 Neo4j 服务状态

后端启动报错,某个服务连不上

这种情况通常是某项基础服务未启动或未正确配置。逐一排查:

  1. uv run uvicorn main:app --host 0.0.0.0 --port 8080(不加 --reload 能看到完整报错信息)
  2. 根据报错信息检查对应的服务是否已启动(参考上面的排查项)
  3. 确认 .env 配置与该服务的实际端口、用户名、密码一致
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏