Skip to content

install.md

Latest commit

 

History

History
148 lines (97 loc) · 4.55 KB

install.md

File metadata and controls

148 lines (97 loc) · 4.55 KB
Raw

安装指南

本指南将帮助您在一台全新的机器上部署 Project Muse 的前后端服务。

📋 前置要求

在开始之前，请确保您的机器已安装以下软件：

  • Docker 和 Docker Compose（必需）
  • Python 3.10+ 和 pip（用于下载 AI 模型）
  • Node.js 18+ 和 pnpm（用于前端开发）
    • 安装 pnpm: npm install -g pnpm
  • NVIDIA GPU（可选，用于加速 AI 推理，CPU 模式也可运行）

🚀 后端部署

步骤 1: 配置环境变量

进入 deploy 目录并创建 .env 文件：

cd deploy
cp .env.example .env

然后编辑 .env 文件，根据实际情况修改配置。至少需要修改以下关键配置：

  • SECRET_KEY: 生产环境请使用强随机字符串
  • MYSQL_ROOT_PASSWORD: MySQL root 密码
  • ADMIN_PASSWORD: 管理员账户密码

提示: 详细的配置说明请参考 README.md 中的"配置环境变量"章节。

步骤 2: 下载 AI 模型（首次安装需要）

AI 模型文件需要单独下载，存储在 deploy/models 目录：

# 安装模型下载所需的依赖
pip install -r requirements.txt

# 下载模型（约 2-3 GB，首次下载可能需要较长时间）
python download_models.py

这将下载以下模型：

  • WD14 Tagger: 用于自动图片打标
  • CLIP ViT-L/14: 用于图片和文本的向量化（语义搜索）

提示: 如果下载速度较慢，脚本会自动使用 hf_transfer 加速下载。

步骤 3: 构建并启动服务

# 构建 Docker 镜像
docker-compose build

# 启动所有服务（包括 MySQL、MinIO、Redis、Qdrant、后端 API、AI Worker）
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志（可选）
docker-compose logs -f

注意:

  • 如果您的机器没有 NVIDIA GPU，需要编辑 docker-compose.yml，注释掉 ai_worker 服务中的 GPU 配置（第 123-129 行的 deploy.resources.reservations.devices 部分）
  • 服务启动后，数据库迁移会自动执行
  • 首次启动时会自动创建管理员账户（如果配置了 ADMIN_USERNAME 和 ADMIN_PASSWORD）

步骤 4: 验证后端服务

访问以下地址验证服务是否正常运行：

🎨 前端部署

前端需要单独启动（开发模式，支持热重载）：

cd frontend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

前端地址: http://localhost:5173

提示:

  • 前端通过 Vite 代理连接到后端 API（/api -> http://localhost:8000）
  • 前端也代理了 MinIO 请求（/minio -> http://localhost:9000），解决 HTTPS 混合内容问题

✅ 验证安装

  1. 访问前端: 打开 http://localhost:5173
  2. 登录系统: 使用配置的管理员账户登录（默认: admin / admin123）
  3. 上传测试: 上传一张图片，等待 AI 自动处理（生成标签、向量嵌入等）

🔧 常见问题

1. AI Worker 启动失败（GPU 相关）

问题: ai_worker 容器启动失败，提示 GPU 相关错误

解决:

2. 模型文件未找到

问题: AI Worker 提示找不到模型文件

解决: 确保已执行 python download_models.py，模型文件位于 deploy/models 目录

3. 前端无法连接后端

问题: 前端页面显示 API 请求失败

解决:

  • 检查后端服务是否正常运行: docker-compose ps
  • 检查 CORS_ORIGINS 配置是否包含前端地址（默认已包含 http://localhost:5173）
  • 查看后端日志: docker-compose logs backend

4. 数据库连接失败

问题: 后端无法连接到 MySQL

解决:

  • 检查 .env 文件中的数据库配置是否正确
  • 确保 MySQL 容器已启动: docker-compose ps db
  • 查看 MySQL 日志: docker-compose logs db

📚 更多信息

  • 详细的配置说明和功能使用，请参考 README.md
  • 系统架构和设计文档，请参考 docs/设计文档.md