用户指南 · 01

快速开始

1.1 三种启动方式

方式	适合人群	优点
桌面 App（Tauri）	不熟悉命令行的终端用户	双击即用，自带运行时，自动管理
命令行	开发者	热重载、自由调试
Docker	团队/服务器部署	一键部署、生产稳定

1.2 桌面 App（推荐新用户）

从 GitHub Release 下载对应平台的安装包：
- Windows：JellyfishBot-x.y.z-x64.exe（NSIS 安装器）
- macOS（Apple Silicon）：JellyfishBot-x.y.z-aarch64.dmg
- macOS（Intel）：JellyfishBot-x.y.z-x64.dmg
安装并打开 JellyfishBot。
首次启动会自动完成：
- 检测内置 Python 3.12 + Node.js 20 运行时
- 解压 backend / frontend 资源到安装目录
在 控制台 页填入至少一个 LLM API Key（OpenAI 或 Anthropic），点击 测试连接 验证。
点击中央圆形 START 按钮启动后台服务。
服务就绪后会自动跳到浏览器：默认 http://localhost:3000。

桌面端 4 个 Tab

Tab	功能
控制台	环境检测、API Keys 配置、START / STOP 按钮
注册码管理	生成、复制、删除注册码（首次部署需要）
账户管理	查看用户列表、重置密码、删除用户、统计
关于 / 工具	版本号、查看最新 Release、打开项目目录 / 用户数据 / 日志目录

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

1.3 命令行启动（开发者）

前置条件

Python 3.11+
Node.js 20+
至少一个 LLM API Key（Anthropic 或 OpenAI）
一个有效的注册码（首次部署运行 python generate_keys.py 生成）

推荐：跨平台启动器

bash

# 一键启动（自动端口检测 + 旧实例清理 + 双进程管理）
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。

手动启动（调试用）

bash

# 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 部署（团队/服务器）

bash

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

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

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

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

架构

text

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

数据持久化

yaml

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

健康检查

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

下一篇登录与注册→