# 快速入门指南

只需几分钟即可使用预构建的 Docker 镜像运行 Speakr！本指南将带你了解部署 Speakr 的最快方法，支持使用 OpenAI Whisper API 或[自定义 ASR 端点](features.md#speaker-diarization)。

> **注意：** 如果你想使用 ASR 端点选项来实现说话人分离功能，你需要运行一个额外的 Docker 容器（`onerahmet/openai-whisper-asr-webservice`）。请参阅[运行 ASR 服务以支持说话人分离](getting-started/installation.md#running-asr-service-for-speaker-diarization)获取详细的设置说明。

## 前置条件

开始之前，请确保你的系统上已安装 Docker 和 Docker Compose。你还需要一个 API 密钥（OpenAI 或 OpenRouter，或兼容服务），至少 2GB 可用内存，以及约 10GB 可用磁盘空间用于存储录音和转录内容。

## 步骤 1：创建项目目录

首先，为 Speakr 安装创建一个目录并进入：

```bash
mkdir speakr
cd speakr
```

## 步骤 2：下载配置文件

下载 Docker Compose 配置，并根据你选择的转录服务选择合适的环境模板：

```bash
# Download docker compose example
wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/docker-compose.example.yml -O docker-compose.yml
```

现在下载环境配置模板。根据你要使用的转录服务，你有两种选择。

使用标准 OpenAI Whisper API（推荐大多数用户使用）：
```bash
wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.whisper.example -O .env
```

或使用带说话人分离功能的自定义 ASR 端点（需要额外的 ASR 容器——见下方说明）：
```bash
wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.asr.example -O .env
```

> **重要：** ASR 端点选项需要与 Speakr 一起运行一个额外的 Docker 容器（`onerahmet/openai-whisper-asr-webservice`）。有关完整的设置说明，包括两个容器的 docker-compose 配置，请参阅[运行 ASR 服务以支持说话人分离](getting-started/installation.md#running-asr-service-for-speaker-diarization)。

## 步骤 3：配置你的转录服务

在你喜欢的文本编辑器中打开 `.env` 文件，并根据你选择的服务进行配置。

### 选项 A：OpenAI Whisper 配置

如果你使用 OpenAI Whisper，你需要同时设置转录服务和文本生成模型。文本生成模型用于创建摘要、生成标题和驱动聊天功能。

编辑你的 `.env` 文件并更新以下关键变量：

```bash
# For text generation (summaries, chat, titles)
TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL_API_KEY=your_openrouter_api_key_here
TEXT_MODEL_NAME=openai/gpt-4o-mini

# For transcription
TRANSCRIPTION_BASE_URL=https://api.openai.com/v1
TRANSCRIPTION_API_KEY=your_openai_api_key_here
WHISPER_MODEL=whisper-1
```

文本模型可以使用 OpenRouter 来访问各种 AI 模型，或者你可以将其直接指向 OpenAI，使用与转录服务相同的基础 URL 和 API 密钥。OpenRouter 提供对多种模型的访问，包括 GPT-4、Claude 等，对于文本生成任务来说可能更具成本效益。

### 选项 B：自定义 ASR 端点配置

> **前置条件：** 此选项需要运行一个额外的 ASR 服务容器（`onerahmet/openai-whisper-asr-webservice`）。你可以：
>
> - 在同一个 Docker Compose 栈中运行两个容器（推荐）——请参阅[完整设置指南](getting-started/installation.md#running-asr-service-for-speaker-diarization)
> - 在同一台或不同的机器上单独运行 ASR 服务
> - 如果你已经部署了现有的 ASR 服务，可以直接使用

如果你使用的是自定义 ASR 服务（如 WhisperX 或自托管的 Whisper 服务器），请配置以下变量：

```bash
# For text generation (summaries, chat, titles)
TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL_API_KEY=your_openrouter_api_key_here
TEXT_MODEL_NAME=openai/gpt-4o-mini

# Enable ASR endpoint
USE_ASR_ENDPOINT=true

# ASR service URL (use container name if in same docker compose)
ASR_BASE_URL=http://whisper-asr:9000
```

当使用 ASR 端点时，[说话人分离](features.md#speaker-diarization)功能会自动启用，使 Speakr 能够识别录音中的不同说话人。转录完成后，你需要[识别说话人](user-guide/transcripts.md#speaker-identification)来构建你的说话人库。ASR_BASE_URL 应指向你的 ASR 服务。如果你在同一个 Docker Compose 栈中运行 ASR 服务，请使用容器名称和内部端口（如 `http://whisper-asr:9000`）。对于外部服务，请使用带有适当 IP 地址或域名的完整 URL。

## 步骤 4：配置管理员账户

Speakr 会在首次启动时自动创建一个管理员用户。在启动之前，请在 `.env` 文件中配置这些凭据：

```bash
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=changeme
```

确保将这些值更改为更安全的值，尤其是密码。当你首次启动 Speakr 时，该管理员账户将自动创建，你将使用这些凭据进行登录。通过此方法创建的第一个用户将成为系统管理员，拥有对所有功能的完全访问权限，包括用户管理和系统设置。

## 步骤 5：启动 Speakr

配置完成后，使用 Docker Compose 启动 Speakr：

```bash
docker compose up -d
```

首次启动需要几分钟时间，因为 Docker 需要下载预构建镜像（约 3GB）并初始化数据库。你可以通过查看日志来监控启动过程：

```bash
docker compose logs -f app
```

查找表示 Flask 应用程序正在运行并已准备好接受连接的消息。按 Ctrl+C 退出日志视图（这不会停止容器）。

## 步骤 6：访问 Speakr

容器运行后，打开你的 Web 浏览器并访问：

```
http://localhost:8899
```

使用你在步骤 4 中配置的管理员凭据登录。现在你应该能看到 Speakr 仪表盘，已准备好进行你的第一次录音。

## 你的第一次录音

登录后，你可以立即开始使用 Speakr。点击顶部导航栏中的"New Recording"按钮，上传现有音频文件或开始[现场录音](user-guide/recording.md)。有关详细说明，请参阅[录音指南](user-guide/recording.md)。对于上传文件，Speakr 支持[常见音频格式](faq.md#what-audio-formats-does-speakr-support)，如 MP3、M4A、WAV 等，默认文件大小限制为 500MB。你可以在[系统设置](admin-guide/system-settings.md)中调整此限制。对于现场录音，你可以从麦克风、系统音频或同时进行录制。

## 可选功能

### 启用 Inquire 模式

[Inquire 模式](user-guide/inquire-mode.md)允许你使用自然语言问题在所有录音中进行搜索。在功能指南中了解更多关于[语义搜索功能](features.md#semantic-search-inquire-mode)的信息。要启用它，请在 `.env` 文件中设置：

```bash
ENABLE_INQUIRE_MODE=true
```

然后使用 `docker compose restart` 重启容器以使更改生效。

### 启用用户注册

默认情况下，只有管理员可以创建新用户。在管理员指南中了解更多关于[用户管理](admin-guide/user-management.md)的信息。要允许自行注册，请设置：

```bash
ALLOW_REGISTRATION=true
```

### 配置你的时区

设置本地时区以显示准确的时间戳：

```bash
TIMEZONE="America/New_York"
```

使用 TZ 数据库中的任何有效时区，如"Europe/London"、"Asia/Tokyo"或"UTC"。

## 停止和启动 Speakr

要停止 Speakr 同时保留所有数据：

```bash
docker compose down
```

要再次启动：

```bash
docker compose up -d
```

你的录音、转录内容和设置将保存在主机系统上的 `./uploads` 和 `./instance` 目录中。

## 故障排除

如果 Speakr 无法正常启动，请使用 `docker compose logs app` 检查日志中的错误信息。有关更详细的帮助，请参阅[故障排除指南](troubleshooting.md)，特别是[安装问题](troubleshooting.md#installation-and-setup-issues)部分。常见问题包括 API 密钥不正确（日志中会显示身份验证错误）或端口冲突（如果其他服务正在使用 8899 端口）。你可以通过编辑 `docker-compose.yml` 文件并修改 ports 部分来更改端口。

如果转录失败，请验证你的 API 密钥是否正确，并且你选择的服务有足够的额度。日志将显示详细的错误信息，有助于识别问题。

---

下一步：[安装指南](getting-started/installation.md)（用于生产部署和高级配置）