根据您提供的GitHub仓库信息，Jellyfish 是一个专为AI生成短剧设计的端到端生产工作台。它管理从剧本输入、分镜故事板、角色/场景一致性、到视频生成与导出的完整流程。

以下是一份详细的部署教程，推荐使用 Docker Compose 方式，能快速启动全部依赖服务。

📋 部署前准备

  1. 核心依赖:

    • Docker 和 Docker Compose (推荐方式)。
    • 或 Python 3.11+ (使用 uv 工具) 和 Node.js (使用 pnpm) 以进行本地开发。

  2. 项目获取:

    1
    2
    git clone https://github.com/Forget-C/Jellyfish.git
    cd Jellyfish

🐳 第一步：使用 Docker Compose 部署 (推荐)

这是最快捷的方式，会启动前端、后端、MySQL数据库、Redis缓存和RustFS文件服务。

  1. 进入部署目录

    1
    cd deploy/compose

  2. 配置环境变量
    复制示例环境变量文件，并根据需要编辑：

    1
    cp .env.example .env

    你可以使用文本编辑器打开 .env 文件，查看或修改端口等配置（如 MYSQL_PORT, REDIS_PORT 等）。通常情况下，默认配置即可直接使用。

  3. 启动所有服务
    在 deploy/compose 目录下，执行以下命令：

    1
    docker compose --env-file .env -f docker-compose.yml up --build
    • --build 参数会强制重新构建镜像。
    • 如果需要后台运行，可以添加 -d 参数：docker compose up --build -d。

  4. 查看服务状态
    可以使用以下命令查看所有容器的运行状态和日志：

    1
    2
    docker compose ps
    docker compose logs -f

🌐 第二步：访问服务

服务启动成功后，你可以通过以下端口访问各个组件：

  • 前端界面 (主要入口): http://localhost:7788
  • 后端 API 文档 (Swagger): http://localhost:8000/docs
  • MySQL 数据库: localhost 端口 ${MYSQL_PORT:-3306}
  • Redis 缓存: localhost 端口 ${REDIS_PORT:-6379}
  • RustFS 文件服务: http://localhost:${RUSTFS_PORT:-9000}

💻 第三步：本地开发模式 (可选)

如果你希望进行二次开发或调试，可以分别启动前后端服务。

后端 (Backend)

  1. 进入后端目录并配置环境

    1
    2
    3
    cd backend
    cp .env.example .env
    # 编辑 .env 文件，确保数据库等连接信息正确

  2. 安装依赖并启动
    项目使用 uv 作为Python包管理器。

    1
    2
    uv sync
    uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

    后端服务将在 http://localhost:8000 运行。

前端 (Frontend)

  1. 进入前端目录并安装依赖

    1
    2
    cd front
    pnpm install

  2. 启动开发服务器

    1
    pnpm dev

    前端开发服务器通常在 http://localhost:5173 (或类似端口) 运行，并支持热重载。

🔧 第四步：初始配置与使用

首次启动后，你可以通过以下流程体验核心功能：

  1. 创建项目: 在Web界面中创建一个新的项目。
  2. 添加章节: 在项目下创建章节，并输入你的剧本脚本。
  3. AI剧本理解: 使用系统功能，让AI将章节脚本自动拆解为镜头（Shots），并提取角色、场景、道具等信息。
  4. 镜头准备: 进入镜头准备流程，审核和确认AI提取的候选资产（角色、场景、对话等），将镜头状态标记为“已准备 (Ready)”。
  5. 生成工作区: 对于已准备的镜头，进入生成工作区，管理参考图、关键帧，并启动AI图像或视频生成任务。
  6. 任务中心: 在全局任务中心查看所有生成任务的状态、进度和结果。

📚 重要配置与提示

  • OpenAPI客户端生成: 如果你修改了后端API，前端需要重新生成请求客户端和类型。确保后端运行在 http://127.0.0.1:8000，然后在前端目录执行：

    1
    2
    cd front
    pnpm run openapi:update

  • AI模型配置: 系统需要你配置AI模型提供商（如用于文本理解、图像生成、视频生成的模型）。请通过后端 .env 文件或管理界面设置相应的API密钥和端点。

  • 数据持久化: Docker Compose 配置会将数据库数据存储在Docker卷中，确保容器重启后数据不丢失。

❗ 常见问题

  • 端口冲突: 如果本地端口（如7788、8000、3306等）已被占用，可以在 deploy/compose/.env 文件中修改对应的端口映射。
  • 后端连接失败: 请确保后端服务已完全启动，并且前端配置的后端API地址（通常为 http://localhost:8000）正确。检查浏览器控制台和网络请求。
  • 任务生成失败: 请检查后端日志，确认AI模型的API密钥和网络连接配置正确，且模型服务可用。

至此，您已经完成了Jellyfish的部署。这是一个功能非常丰富的AI短剧生产平台，建议从创建第一个项目和章节开始，逐步探索其剧本拆解、镜头管理和生成工作流。如果遇到具体问题，可以查阅项目更详细的文档或在GitHub仓库提交Issue。