一、 前言

TaiXu-Admin 是一款集成 RAG（检索增强生成）、Agent（智能体）以及多模型管理能力的后台系统。本文将详细记录如何在 Ubuntu 环境下，通过 Docker Compose 快速构建后端基础设施，并调通前后端交互，解决字体缺失、API 地址硬编码等常见坑点。

当前TaiXu-Admin 还是非常不成熟的，在安装和使用过程中踩了很多坑，花了比较多的时间，代码质量也存在较多问题（很多不规范的写法导致适配性差），在做技术选型时需要慎重考虑。

---

二、 基础环境信息

在开始安装前，请确保您的系统满足以下配置（本文测试环境）：

• 操作系统: Ubuntu 24.04 LTS (Kernel 6.8.0)

• CPU: Intel(R) Xeon(R) Gold 5220R (16 Cores)

• 内存: 16GB RAM / 4GB Swap

• 磁盘空间: 建议 50GB 以上

---

三、 核心组件安装

1. 安装 Node.js 与 pnpm

前端构建需要稳定的 Node 环境。

# 安装必要工具
apt update && apt install -y curl git

# 配置 NodeSource 并安装 Node.js 20.x
mkdir ~/nodesource && cd ~/nodesource
curl -fsSL https://deb.nodesource.com/setup_20.x -o nodesource_setup.sh
bash nodesource_setup.sh
apt install -y nodejs

# 全局安装 pnpm
npm install -g pnpm

2. 克隆项目与 Python 环境准备

mkdir ~/code && cd ~/code
git clone https://gitee.com/xuesjie/TaiXu-Admin.git
cd TaiXu-Admin

# 激活您的 Python 虚拟环境（假设路径为 /root/.venv）
source /root/.venv/bin/activate

# 批量安装后端依赖（建议直接复制）
uv pip install flask flask-SQLAlchemy flask-cors flask_socketio apscheduler python-dotenv \
psycopg2-binary PyPDF2 python-docx python-pptx openpyxl PyYAML qdrant_client neo4j \
tavily-python bs4 akshare beautifulsoup4 umap-learn scikit-learn arxiv networkx \
python-louvain trafilatura langdetect spacy spacy-pkuseg tencentcloud-sdk-python \
jieba rank_bm25 langchain langgraph langchain-openai langchain-ollama langchain-qdrant \
langchain-neo4j langchain-community langchain-experimental langchain-mcp-adapters --upgrade

当前TaiXu-Admin 后端taixu-system-service给出的requirements.txt依赖文件中存在依赖冲突的情况，解决这个依赖冲突花了我很多时间，巨坑巨坑！！！各位新人请务必使用我给出的依赖来尝试安装。

---

四、 环境适配：解决Window-->Linux适配(关键步骤)

在正式运行前，必须进行以下四项核心修正，否则系统将无法在 Linux 下正常启动或被外部访问。

1. 开启全网段访问 (必须)

默认配置仅允许本地回环访问，外部机器无法调用 API。

• 修改文件: taixu-system-service/src/resources/application.yml

• 操作: 将 app.host 从 127.0.0.1 修改为 0.0.0.0。

2. 跨平台路径兼容性改造（必须）

Linux 不识别 D:/ 这种盘符。我们需要通过 os.path 增强代码的鲁棒性。

请修改 /root/code/TaiXu-Admin/taixu-system-service/src/common/config.py 文件：

class Config:

    ……

    def parse_config_path(self, file_name):
        abspath = os.path.dirname(os.path.abspath(__file__))
        #return abspath.replace("common", "resources") + "\\" + file_name
        #注释掉上面的return,修改为下面一行
        return os.path.join(abspath.replace("common", "resources"), file_name)
    ……

3. 处理代码中“写死”的 Windows 路径（可选）

部分功能（如 Agent 绘图、文档下载）在 models 或 routes 中硬编码了 Windows 下载目录。

• 搜索关键字: D:/, C:\Users

• 修改点: taixu-system-web/src/pages/agent/models/searchState.js 等文件。

• 正规做法: 将 const image_path = "D:/Downloads/..." 改为指向 Linux 下项目的相对路径或 /tmp/ 目录。

4. 验证码字体资源补全（必须）

Linux 缺失 Windows 的 arial.ttf，会导致验证码接口报 OSError: cannot open resource。

• 快速修复:

  # 建立软链接，将 Linux 自带字体映射为代码寻找的名称
  ln -s /usr/share/fonts/truetype/dejavu/DejaVuSans.ttf /usr/share/fonts/truetype/arial.ttf
  

---

五、 基础设施搭建 (Docker Compose)

为了方便管理，我们将 PostgreSQL、Qdrant (向量数据库) 和 Neo4j (图数据库) 统一通过容器化部署。

1. 编写配置文件

在 taixu-system-service 目录下创建 database 目录并编写 docker-compose.yml：

services:
  postgres:
    image: postgres:15
    container_name: taixu-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: root
      POSTGRES_DB: taixu_system
    ports:
      - "5432:5432"
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

  qdrant:
    image: qdrant/qdrant
    container_name: taixu-qdrant
    ports:
      - "6333:6333"
    volumes:
      - ./data/qdrant:/qdrant/storage

  neo4j:
    image: neo4j:latest
    container_name: taixu-neo4j
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      NEO4J_AUTH: neo4j/neo4j@123
    volumes:
      - ./data/neo4j/data:/data

2. 启动服务与数据初始化

cd ~/code/TaiXu-Admin/taixu-system-service/database
docker compose up -d

# 导入初始化 SQL 脚本
cd ../src/resources/database/
for f in init_db.sql init_user.sql init_setting.sql init_model.sql init_document.sql init_history.sql; do
    echo "正在导入 $f ..."
    cat $f | docker exec -i taixu-postgres psql -U postgres -d taixu_system
done

---

六、 关键配置修改

1. 前端 API 地址对齐

由于前端默认指向 localhost，在分布式或虚拟机环境需修改为实际物理 IP。

• 修改文件: taixu-system-web/src/config/configApi.js

// 修改 TAIXU_SYSTEM_API 为您的虚拟机 IP
const TAIXU_SYSTEM_API = "http://10.197.210.242:5000";
const OLLAMA_MODEL_HOST = "http://10.197.210.242:11434";

2. 解决验证码字体报错（此处再重复提一次）

Linux 默认缺失 arial.ttf，会导致登录页验证码报 500 错误。

# 方案：建立软链接使用系统自带字体
ln -s /usr/share/fonts/truetype/dejavu/DejaVuSans.ttf /usr/share/fonts/truetype/arial.ttf

---

七、 服务启动与访问

1. 启动后端

cd ~/code/TaiXu-Admin/taixu-system-service/
source /root/.venv/bin/activate
python3 app.py

2. 启动前端

cd ~/code/TaiXu-Admin/taixu-system-web/
pnpm start --host

3. Web 访问

• URL: http://10.197.210.242:8000

• 默认账号: admin

• 默认密码: admin (或根据 init_user.sql 配置)

---

八、 总结与注意事项

1. 数据库连接: 若报 database does not exist，请检查 docker-compose 中的环境变量与 application.yml 是否一致。

2. 硬编码问题: 某些页面（如 SearchPage）可能存在 Windows 路径硬编码，建议检查 src/pages/ 下的 models 文件。

3. LLM 配置: 登录后需在“系统设置”中配置 API Key，否则聊天功能会抛出 Exception: not setting llm。