前言
企业智能知识库 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 --version1.2 安装 UV
macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows:
访问 https://docs.astral.sh/uv/getting-started/installation/ 下载 Windows 安装包。
安装后重启终端,验证:
uv --version1.3 安装 Git
macOS:
brew install git
# 或:已安装 Xcode Command Line Tools 则自带 gitWindows:
访问 https://git-scm.com/download/win 下载安装。
验证:
git --version2. 获取代码
cd ~
mkdir -p projects && cd projects
git clone https://gitcode.com/dv-susan/knowledge-base-python.git
cd project/knowledge-base-python3. 安装并启动基础服务
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:
- 访问 https://dev.mysql.com/downloads/mysql/ 下载 MySQL Installer(选 8.0 版本)
- 运行安装程序,选择 "Developer Default" 安装类型
- 安装过程中设置 root 密码为
root123456 - 安装完成后 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 neo4jWindows:
- 访问 https://neo4j.com/download/ 下载 Community Edition ZIP 包
- 解压到本地目录(如
C:\neo4j) 在命令行中进入
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;
SQLWindows:
打开 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 .env5.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/3AI 大模型配置(如果使用 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-chatJWT 密钥配置(生产环境务必修改):
JWT_SECRET_KEY=your-secret-key-change-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=120
REFRESH_TOKEN_EXPIRE_DAYS=75.3 安装 Python 依赖
uv sync
uv pip install pymupdf5.4 idea中配置密钥
咱们的企业智能知识库python项目中包含了:邮件、大模型等功能,需要配置自己的专属密码和key。
在idea中找到KB Startup(Shell),点击Edit Configurations,打开配置窗口。

在窗口中找到Environment variables

在里面配置如下参数:
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: development7. 访问系统
- Swagger UI:http://127.0.0.1:8080/doc.html
- OpenAPI JSON:http://127.0.0.1:8080/openapi.json
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.logWindows:
查看 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> /Fuv sync 失败(cryptography 编译失败)
macOS:
brew install openssl
export LDFLAGS="-L$(brew --prefix openssl)/lib"
export CFLAGS="-I$(brew --prefix openssl)/include"
uv syncWindows:
安装 Visual C++ Build Tools(https://visualstudio.microsoft.com/visual-cpp-build-tools/),或使用预编译 Python 版本。
Alembic 迁移失败
- 确认 9 个数据库已创建:
mysql -uroot -proot123456 -e "SHOW DATABASES;" - 确认
.env中 MySQL 密码正确 - 重试:
uv run alembic upgrade head
IDEA 中环境变量不生效
如果 IDEA 中运行项目提示数据库连接失败,但命令行 uv run uvicorn ... 正常:
- 确认
Run Configuration中已正确加载.env文件 - 检查
Working directory是否设置为项目根目录 - 尝试重启 IDEA
- 临时方案:在
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 服务状态
后端启动报错,某个服务连不上
这种情况通常是某项基础服务未启动或未正确配置。逐一排查:
uv run uvicorn main:app --host 0.0.0.0 --port 8080(不加--reload能看到完整报错信息)- 根据报错信息检查对应的服务是否已启动(参考上面的排查项)
- 确认
.env配置与该服务的实际端口、用户名、密码一致