快速开始

v1.3.1 可以选择两条模型接入路径：已有 Codex / Cursor 账号，或 DeepAgents + 模型 API Key。已有账号模式既可用于管理员日常聊天，也可用于内部 Service 的网页、API 与微信渠道；仅使用该连接的对话不需要另配 LLM API Key，仍使用该账号可用的模型与额度。

启动器内置 Python 和 Node.js；Codex / Cursor CLI 需要另行安装、登录和授权。账号模式目前要求 macOS / Linux 后端；Windows 安装包继续支持 DeepAgents / API 工作流。先看本书「对话」中的 4.12 Codex / Cursor，完成日常使用后再按「设置中心」的 6.6.7 发布 Service。

1.1 三种启动方式

1.2 桌面 App（推荐新用户）

1. 从 GitHub Release 下载对应平台的安装包：
   • Windows：OpenJellyfish_x.y.z_x64-setup.exe（NSIS 安装器）
   • macOS（Apple Silicon）：OpenJellyfish_x.y.z_aarch64.dmg
   • macOS（Intel）：OpenJellyfish_x.y.z_x64.dmg
2. 安装并打开 OpenJellyfish。
3. 首次启动会自动完成：
   • 检测内置 Python 3.12 + Node.js 20 运行时
   • 解压 backend / frontend 资源到安装目录
4. 使用 DeepAgents 时，在 控制台 页配置 LLM API Key 并测试连接。使用 Codex / Cursor 套餐时，先完成 4.12 的 CLI 安装与 Runtime 启用，再启动服务并登录 /superadmin 授权；不必另填 LLM API Key。
5. 点击中央圆形 START 按钮启动后台服务。
6. 服务就绪后会自动跳到浏览器：默认 http://localhost:3000。

桌面端 4 个 Tab

关闭桌面 App = 停止后台服务 + 清理子进程。

1.3 命令行启动（开发者）

前置条件

• Python 3.11+
• Node.js 20+
• DeepAgents 路径：一个可用的 LLM API Key；套餐路径：已安装对应 CLI，并按 4.12 启用 Runtime、登录及授权
• 一个有效的注册码（首次部署运行 python generate_keys.py 生成）

推荐：跨平台启动器

# 一键启动（自动端口检测 + 旧实例清理 + 双进程管理）
python launcher.py              # 生产模式
python launcher.py --dev        # 开发模式（uvicorn --reload + vite dev）
python launcher.py --port 9000  # 自定义后端端口
python launcher.py --backend-only  # 仅后端

# 快捷脚本
./start_local.sh    # Mac/Linux
start_local.bat     # Windows（双击）

启动后浏览器访问 http://localhost:3000。

手动启动（调试用）

# 1. 后端
python -m venv venv
venv\Scripts\activate          # Windows
source venv/bin/activate       # Linux/macOS
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env，填入 API Key
python generate_keys.py        # 生成注册码（首次）
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 2. 前端（新终端）
cd frontend
npm install
npm run dev                    # → http://localhost:3000

1.4 Docker 部署（团队/服务器）

# 1. 准备配置
cp .env.example .env
# 编辑 .env，填入 API Key 等

# 2. 生成注册码
python generate_keys.py
# 或在 Tauri 桌面 App 的「注册码管理」页生成

# 3. 准备数据目录权限（首次部署必做）
#    应用容器以 jellyfish (uid=1000) 运行，挂载的 ./data 必须可写
mkdir -p ./data/users
sudo chown -R 1000:1000 ./data

# 4. 构建并启动
docker compose up -d --build

# 5. 查看日志
docker compose logs -f
docker compose logs -f openjellyfish   # 仅应用日志
docker compose logs -f nginx          # 仅 Nginx 日志

⚠️ 第 3 步不能省：如果 ./data 不存在，docker daemon 会以 root 自动创建，容器内 uid=1000 写不进去，FastAPI 启动会报 sqlite3.OperationalError: unable to open database file 然后无限重启。详见 FAQ。

架构

Cloudflare (SSL) → Nginx (:80) → Express (:3000) → FastAPI (:8000)

数据持久化

volumes:
  - ./data/users:/app/users    # 用户数据：对话、文件、checkpoints、API Key

健康检查

容器内置健康检查（检查 FastAPI /docs），Nginx 在后端就绪后才接受流量。