# 安装指南

本综合指南涵盖了 Speakr 的生产环境部署，包括详细的配置选项、性能调优和部署最佳实践。虽然快速入门指南能让你快速运行，但本指南提供了稳健生产部署所需的一切。

## 了解 Speakr 的架构

在开始安装之前，了解 Speakr 的工作原理会很有帮助。该应用集成了外部 API，主要用于两个目的：将音频转换为文本的转录服务，以及为摘要、标题和交互式聊天等功能提供支持的文本生成服务。Speakr 设计灵活，既支持 OpenAI 等云端服务，也支持运行在你自有基础设施上的自托管方案。

Speakr 使用特定的 API 端点格式进行这些集成。对于转录，它支持标准的 OpenAI Whisper API 格式，使用 `/audio/transcriptions` 端点，该格式被 OpenAI、OpenRouter 和许多自托管方案所实现。另外，对于说话人分离等高级功能，Speakr 可以连接提供 `/asr` 端点的 ASR Web 服务。**注意：使用 ASR 端点选项需要与 Speakr 一起运行额外的 Docker 容器**（`onerahmet/openai-whisper-asr-webservice`）——完整的设置说明请参考下方的[运行 ASR 服务用于说话人分离](#running-asr-service-for-speaker-diarization)部分。对于文本生成，Speakr 使用 OpenAI Chat Completions API 格式的 `/chat/completions` 端点，该格式被不同的 AI 提供商广泛支持。

## 前置要求

对于生产环境部署，请确保你的系统满足以下要求。你需要 Docker Engine 20.10 或更高版本以及 Docker Compose 2.0 或更高版本。系统应至少有 4GB 内存，推荐 8GB 以获得最佳性能，尤其是处理较长录音时。预留至少 20GB 可用磁盘空间来存放录音和转录文件，实际需求将取决于你的使用模式。除非你在本地运行所有服务，否则服务器应有稳定的互联网连接以进行转录和 AI 服务的 API 调用。

## 选择部署方式

你有两种主要的部署方式。第一种（推荐）是使用 Docker Hub 上的预构建 Docker 镜像，无需源代码即可快速运行。第二种是从源码构建，适用于需要修改代码或偏好自行构建镜像的场景。两种方法都使用 Docker Compose 进行编排和管理。

## 使用预构建镜像的标准安装

### 步骤 1：创建安装目录

为你的 Speakr 安装选择合适的位置。该目录将包含你的配置文件和数据卷。对于生产环境部署，建议使用专用目录如 `/opt/speakr` 或 `/srv/speakr`，这样可以与用户主目录清晰分离，并遵循 Linux 文件系统层次标准。

```bash
mkdir -p /opt/speakr
cd /opt/speakr
```

如果只是测试或个人使用，也可以在主文件夹中创建目录。位置不是关键，但将所有内容组织在一个地方更便于管理。

### 步骤 2：创建 Docker Compose 配置

创建 `docker-compose.yml` 文件，内容如下：

```yaml
services:
  app:
    image: learnedmachine/speakr:latest
    container_name: speakr
    restart: unless-stopped
    ports:
      - "8899:8899"
    env_file:
      - .env
    volumes:
      - ./uploads:/data/uploads
      - ./instance:/data/instance
```

或下载示例配置：

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

重启策略 `unless-stopped` 确保 Speakr 在系统重启后自动启动，除非你显式停止了它。数据卷挂载本地目录用于持久化存储上传文件和数据库文件。

### 步骤 3：环境配置

环境配置用于告诉 Speakr 使用哪些 AI 服务以及如何连接它们。根据你的转录服务选择下载相应的环境模板。该模板包含所有配置变量，并附有 helpful 注释解释每个设置。

#### 使用 OpenAI Whisper API

如果你使用 OpenAI 的 Whisper API 或任何兼容服务，下载 Whisper 环境模板：

```bash
wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.whisper.example -O .env
```

然后编辑 `.env` 文件添加你的 API 密钥并自定义设置。配置按逻辑部分组织。首先，配置用于摘要、标题和聊天功能的文本生成模型。这里推荐使用 OpenRouter，因为它能以有竞争力的价格访问多个 AI 模型，但你也可以使用任何 OpenAI 兼容服务：

```bash
TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL_API_KEY=sk-or-v1-your-key-here
TEXT_MODEL_NAME=openai/gpt-4o-mini
```

如果你更喜欢直接使用 OpenAI 进行文本生成，只需将 base URL 改为 `https://api.openai.com/v1` 并使用你的 OpenAI API 密钥。你也可以通过 Ollama 或 LM Studio 使用本地模型，指向 `http://localhost:11434/v1` 或类似地址。

接下来，配置转录服务。这是将音频文件转换为文本的服务：

```bash
TRANSCRIPTION_BASE_URL=https://api.openai.com/v1
TRANSCRIPTION_API_KEY=sk-your-openai-key-here
WHISPER_MODEL=whisper-1
```

#### 使用自定义 ASR 端点配合说话人分离

如果你想要说话人分离功能来识别录音中的不同说话者，你需要使用 ASR Web 服务端点。**这需要与 Speakr 一起运行额外的 Docker 容器**（`onerahmet/openai-whisper-asr-webservice`），但为会议转录和多说话者录音提供了强大的功能。

> **重要提示：** 在进行此配置之前，你需要先设置 ASR 服务容器。请参考[运行 ASR 服务用于说话人分离](#running-asr-service-for-speaker-diarization)获取完整的说明，了解如何一起或分别部署两个容器。

下载 ASR 配置模板：

```bash
wget https://raw.githubusercontent.com/murtaza-nasir/speakr/master/config/env.asr.example -O .env
```

ASR 配置启用自定义端点并告诉 Speakr 在哪里找到它：

```bash
USE_ASR_ENDPOINT=true
ASR_BASE_URL=http://your-asr-service:9000
```

ASR_BASE_URL 取决于你的部署架构。如果你在与 Speakr 相同的 Docker Compose 堆栈中运行 ASR 服务，请使用 docker-compose.yml 中的服务名，如 `http://whisper-asr:9000`。这使用 Docker 的内部网络进行通信。如果 ASR 服务运行在其他地方，请使用其完整 URL 和适当的 IP 地址或域名。

使用 ASR 端点时会自动启用说话人分离。系统将识别录音中的不同说话者并标记为 Speaker 1、Speaker 2 等。你可以选择取消注释并调整环境文件中的 ASR_MIN_SPEAKERS 和 ASR_MAX_SPEAKERS 来覆盖默认的说话者检测设置。

### 步骤 4：配置系统设置

Speakr 的一个便利功能是自动创建管理员账户。无需经过注册流程，你只需在环境文件中定义管理员凭据，Speakr 会在首次启动时自动创建账户。这确保你可以立即登录，无需额外的设置步骤：

```bash
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@your-domain.com
ADMIN_PASSWORD=your-secure-password-here
```

为管理员账户选择强密码，因为它拥有完整的系统访问权限，包括管理用户和查看所有录音的能力。管理员账户是特殊的，无法通过常规注册流程创建，只能通过环境变量创建。

接下来，配置应用程序的行为方式。这些设置控制用户访问和系统操作：

```bash
ALLOW_REGISTRATION=false
TIMEZONE="America/New_York"
LOG_LEVEL="INFO"
```

设置 `ALLOW_REGISTRATION=false` 意味着只有管理员可以创建新用户账户，这对于需要控制访问权限的私有安装是推荐的。如果你为团队或家庭运行 Speakr，这可以防止无关人员创建账户。时区设置影响整个界面中日期和时间的显示方式，因此请将其设置为你的本地时区以方便使用。日志级别控制 Speakr 写入日志的信息量。在初始设置和测试期间使用 `INFO` 以了解发生了什么，然后在生产环境中切换到 `ERROR` 以减少日志量并提高性能。

### 步骤 5：配置高级功能

#### 大文件处理

Speakr 最有用的功能之一是自动处理大音频文件。许多转录 API 有文件大小限制，OpenAI 的 25MB 限制就是一个常见的约束。Speakr 通过智能分段自动处理这个问题，而不是强制你手动分割文件：

```bash
ENABLE_CHUNKING=true
CHUNK_LIMIT=20MB
CHUNK_OVERLAP_SECONDS=3
```

启用分段后，Speakr 会自动检测文件是否超过配置的限制并将其分割为较小的部分。每个部分单独处理，转录结果无缝合并回一起。重叠设置确保在分段边界处不会丢失单词，这对于连续语音尤为重要。分段限制可以指定为文件大小如 `20MB` 或持续时间如 `20m`（20 分钟），具体取决于你的 API 限制。

此功能仅适用于标准 Whisper API 方法。如果你使用 ASR 端点，则不需要分段，因为这些服务通常原生支持大文件。

#### Inquire 模式用于语义搜索

Inquire 模式将 Speakr 从简单的转录工具转变为你所有录音的知识库。启用后，你可以使用自然语言问题在所有转录中进行搜索：

```bash
ENABLE_INQUIRE_MODE=true
```

启用 Inquire 模式后，Speakr 会为你的转录创建嵌入向量，从而支持语义搜索。这意味着你可以问"我们什么时候讨论了营销预算？"这样的问题，即使没有使用确切的词语也能找到相关录音。该功能在转录期间需要额外的处理，但随着你的录音库增长，它将提供强大的搜索能力。

#### 自动化文件处理

自动化文件处理功能（有时称为"黑洞"目录）会监控指定文件夹中的新音频文件并自动处理它们，无需手动干预。这非常适合与录音设备、自动化工作流或批处理场景集成：

```bash
ENABLE_AUTO_PROCESSING=true
AUTO_PROCESS_MODE=admin_only
AUTO_PROCESS_WATCH_DIR=/data/auto-process
AUTO_PROCESS_CHECK_INTERVAL=30
```

启用后，Speakr 每 30 秒检查一次监控目录是否有新音频文件。发现的任何文件都会自动移动到上传目录并使用你配置的转录设置进行处理。`admin_only` 模式将所有处理后的文件分配给管理员用户，但你也可以为多用户场景配置每个用户的独立目录。

要使用此功能，你需要在 Docker Compose 配置中挂载额外的数据卷，我们将在接下来的步骤中介绍。

### 步骤 6：设置数据目录

Speakr 需要本地目录来持久化存储你的数据。这些目录作为 Docker 数据卷挂载，确保你的录音和数据库在容器更新和重启后仍然存在：

```bash
mkdir -p uploads instance
chmod 755 uploads instance
```

`uploads` 目录存储所有音频文件及其转录内容，按用户组织。`instance` 目录包含跟踪所有录音、用户和设置的 SQLite 数据库。将权限设置为 755 确保 Docker 容器可以读写这些目录，同时保持合理的安全性。

如果你使用自动化文件处理功能，也需要创建该目录：

```bash
mkdir -p auto-process
chmod 755 auto-process
```

### 步骤 7：启动 Speakr

所有配置完成后，你就可以启动 Speakr 了。`-d` 标志以分离模式运行容器，意味着它将在后台持续运行：

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

首次运行此命令时，Docker 将从 Docker Hub 下载 Speakr 镜像。该镜像约 3GB，包含运行 Speakr 所需的所有依赖项，包括用于音频处理的 FFmpeg 和各种 Python 库。下载时间取决于你的互联网连接速度。

监控启动过程以确保一切正常运行：

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

观察日志是否有任何错误消息。你应该会看到关于数据库初始化、管理员用户创建的消息，最后会显示 Flask 应用程序在 8899 端口运行的消息。按 Ctrl+C 停止查看日志（这不会停止容器，只是停止日志查看）。

### 步骤 8：验证安装

打开浏览器并访问 `http://your-server:8899`，将 `your-server` 替换为你的实际服务器地址，如果是本地运行则使用 `localhost`。你应该会看到 Speakr 登录页面，带有其独特的渐变设计。

使用你在环境文件中配置的管理员凭据登录。如果登录失败，请检查 Docker 日志以确保管理员账户创建成功。有时环境文件中的拼写错误会导致问题。

登录成功后，通过创建测试录音或上传示例音频文件来测试安装。录音界面应显示麦克风、系统音频或两者的选项。首先尝试上传一个小型音频文件以验证你的 API 密钥是否正常工作。对于短文件，转录过程应在几秒钟内完成，你应该会看到转录文本出现以及 AI 生成的摘要。

如果转录失败，请检查 Docker 日志中的 API 认证错误或连接问题。常见问题包括 API 密钥不正确、API 额度不足或网络连接问题。

## 高级部署场景

### 运行 ASR 服务用于说话人分离

如果你需要说话人分离功能来识别录音中的不同说话者，你需要与 Speakr 一起运行 ASR 服务。这涉及部署额外的 Docker 容器（`onerahmet/openai-whisper-asr-webservice`）来提供 ASR 端点。推荐的方法是在同一个 Docker Compose 堆栈中运行两个容器，以简化网络和管理。

首先，你需要一个 Hugging Face 令牌来访问说话人分离模型。在 Hugging Face 创建账户，生成访问令牌，并且重要的是，访问 pyannote/segmentation-3.0 和 pyannote/speaker-diarization-3.1 模型页面以接受它们的条款。这些是需要明确授权的受限模型。

以下是包含两个服务的完整 Docker Compose 配置：

```yaml
services:
  whisper-asr:
    image: onerahmet/openai-whisper-asr-webservice:latest-gpu
    container_name: whisper-asr-webservice
    ports:
      - "9000:9000"
    environment:
      - ASR_MODEL=distil-large-v3
      - ASR_COMPUTE_TYPE=int8
      - ASR_ENGINE=whisperx
      - HF_TOKEN=your_huggingface_token_here
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]
              device_ids: ["0"]
    restart: unless-stopped
    networks:
      - speakr-network

  speakr:
    image: learnedmachine/speakr:latest
    container_name: speakr
    restart: unless-stopped
    ports:
      - "8899:8899"
    env_file:
      - .env
    volumes:
      - ./uploads:/data/uploads
      - ./instance:/data/instance
    depends_on:
      - whisper-asr
    networks:
      - speakr-network

networks:
  speakr-network:
    driver: bridge
```

> **Mac 用户注意：** 由于 Docker 的架构，GPU 直通在 macOS 上不起作用。请使用 `onerahmet/openai-whisper-asr-webservice:latest`（CPU 版本）而不是 `:latest-gpu`，并删除 `deploy` 部分。ASR 服务将使用 CPU 处理，速度较慢但功能完整。请参考[常见问题](../faq.md#can-i-use-the-asr-webservice-for-speaker-diarization-on-mac)获取 Mac 特定的配置示例。

当在同一个 Docker Compose 文件中运行两个服务时，容器使用服务名进行通信。在 `.env` 文件中，设置 `ASR_BASE_URL=http://whisper-asr:9000`，使用服务名而不是 localhost 或 IP 地址。这是一个常见的混淆点，但这就是 Docker 网络的工作方式。

#### 在独立的 Docker Compose 文件中运行服务

如果你偏好独立管理服务或将 ASR 服务添加到现有 Speakr 安装中，你可以在单独的 Docker Compose 文件中运行它们。这种方法提供了更大的灵活性，无论服务是在同一台机器还是不同的机器上都可以工作。

##### 选项 1：同一台机器共享网络

如果两个服务运行在同一台机器上，你可以使用 Docker 的内部网络进行通信：

首先，创建共享的 Docker 网络：

```bash
docker network create speakr-network
```

为 ASR 服务创建 `docker-compose.asr.yml`：

```yaml
services:
  whisper-asr:
    image: onerahmet/openai-whisper-asr-webservice:latest-gpu
    container_name: whisper-asr-webservice
    ports:
      - "9000:9000"
    environment:
      - ASR_MODEL=distil-large-v3
      - ASR_COMPUTE_TYPE=int8
      - ASR_ENGINE=whisperx
      - HF_TOKEN=your_huggingface_token_here
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]
              device_ids: ["0"]
    restart: unless-stopped
    networks:
      - speakr-network

networks:
  speakr-network:
    external: true
```

更新你的 Speakr `docker-compose.yml` 以使用共享网络：

```yaml
services:
  app:
    image: learnedmachine/speakr:latest
    container_name: speakr
    restart: unless-stopped
    ports:
      - "8899:8899"
    env_file:
      - .env
    volumes:
      - ./uploads:/data/uploads
      - ./instance:/data/instance
    networks:
      - speakr-network

networks:
  speakr-network:
    external: true
```

在你的 `.env` 文件中，使用容器名：
```bash
ASR_BASE_URL=http://whisper-asr-webservice:9000
```

##### 选项 2：不同机器

当在不同机器上运行时，你不需要共享网络。每个服务独立运行，并使用 IP 地址或主机名通过网络进行通信。

在 ASR 服务器上，创建 `docker-compose.asr.yml`：

```yaml
services:
  whisper-asr:
    image: onerahmet/openai-whisper-asr-webservice:latest-gpu
    container_name: whisper-asr-webservice
    ports:
      - "9000:9000"  # 暴露到网络
    environment:
      - ASR_MODEL=distil-large-v3
      - ASR_COMPUTE_TYPE=int8
      - ASR_ENGINE=whisperx
      - HF_TOKEN=your_huggingface_token_here
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]
              device_ids: ["0"]
    restart: unless-stopped
```

在 Speakr 服务器上，使用标准的 `docker-compose.yml`：

```yaml
services:
  app:
    image: learnedmachine/speakr:latest
    container_name: speakr
    restart: unless-stopped
    ports:
      - "8899:8899"
    env_file:
      - .env
    volumes:
      - ./uploads:/data/uploads
      - ./instance:/data/instance
```

在你的 Speakr `.env` 文件中，使用 ASR 服务器的 IP 地址或主机名：
```bash
# 使用 IP 地址
ASR_BASE_URL=http://192.168.1.100:9000

# 或使用主机名
ASR_BASE_URL=http://asr-server.local:9000
```

在各自的机器上启动两个服务：

```bash
# 在 ASR 服务器上
docker compose -f docker-compose.asr.yml up -d

# 在 Speakr 服务器上
docker compose up -d
```

确保机器之间可以访问端口 9000（如有需要请检查防火墙规则）。

## 生产环境注意事项

### 使用反向代理配置 SSL

对于生产环境部署，将 Speakr 运行在反向代理后面对于安全性和启用所有功能至关重要。浏览器录音功能，特别是系统音频捕获，由于浏览器安全限制需要 HTTPS 才能工作。反向代理处理 SSL 终止，意味着它管理 HTTPS 证书，同时在内部通过 HTTP 与 Speakr 通信。

以下是 nginx 的完整配置示例：

```nginx
server {
    listen 443 ssl http2;
    server_name speakr.yourdomain.com;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;

    # 安全头部
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    location / {
        proxy_pass http://localhost:8899;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 实时功能的 WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 实时 ASR WebSocket 代理。如果存在更广泛的 /tool/speakr/ 路由，请将其放在前面。
        # location /tool/speakr/ws/ {
        #     proxy_pass http://speakr:8899/ws/;
        #     proxy_http_version 1.1;
        #     proxy_set_header Upgrade $http_upgrade;
        #     proxy_set_header Connection "upgrade";
        #     proxy_read_timeout 3600s;
        # }
        
        # 大文件上传的超时设置
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

# 将 HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name speakr.yourdomain.com;
    return 301 https://$server_name$request_uri;
}
```

WebSocket 配置对 Speakr 的实时功能很重要。超时设置确保大文件上传不会被中断。你可以使用 Certbot 从 Let's Encrypt 获取免费的 SSL 证书，让每个人都能使用 HTTPS。

### 备份策略

定期备份对于生产环境部署至关重要。你的 Speakr 数据包含三个需要备份的关键组件：`instance` 目录中的 SQLite 数据库、`uploads` 目录中的音频文件和转录内容，以及 `.env` 文件中的配置。

创建一个备份脚本来捕获所有三个组件：

```bash
#!/bin/bash
BACKUP_DIR="/backup/speakr"
DATE=$(date +%Y%m%d_%H%M%S)

# 如果备份目录不存在则创建
mkdir -p "$BACKUP_DIR"

# 创建备份
tar czf "$BACKUP_DIR/speakr_backup_$DATE.tar.gz" \
    /opt/speakr/instance \
    /opt/speakr/uploads \
    /opt/speakr/.env

# 可选：仅保留最近 30 天的备份
find "$BACKUP_DIR" -name "speakr_backup_*.tar.gz" -mtime +30 -delete

echo "备份完成：speakr_backup_$DATE.tar.gz"
```

使脚本可执行并使用 cron 安排自动每日备份：

```bash
chmod +x /opt/speakr/backup.sh
crontab -e
# 添加此行以在每天凌晨 2 点进行备份：
0 2 * * * /opt/speakr/backup.sh
```

对于关键部署，考虑将备份复制到远程存储或云服务以获得额外的冗余。压缩后的备份大小通常远小于原始数据，因为音频文件压缩效果很好。

### 监控和维护

主动监控有助于在问题影响用户之前预防问题。音频文件会随着时间的推移占用大量存储空间，尤其是如果你经常录制较长的会议。设置磁盘空间监控，当使用率超过 80% 时发出警报。一种简单的监控方法是使用 cron 和 df：

```bash
#!/bin/bash
USAGE=$(df /opt/speakr | tail -1 | awk '{print $5}' | sed 's/%//')
if [ $USAGE -gt 80 ]; then
    echo "警告：Speakr 磁盘使用率已达 ${USAGE}%" | mail -s "Speakr 磁盘警报" admin@example.com
fi
```

定期监控 Docker 容器的健康和日志。你可以使用 Docker 内置的健康检查功能或外部监控工具。检查是否存在重复的 API 失败、认证错误或处理超时等模式。同时跟踪你的 API 使用情况和成本，因为大量使用会产生可观的费用。

### 安全加固

生产环境部署需要比默认配置更多的安全措施。首先确保所有账户使用强密码，尤其是管理员账户。切勿在生产环境中使用默认或简单密码。

使用防火墙规则限制网络访问。如果 Speakr 仅在内部使用，请将访问限制为你组织的 IP 范围：

```bash
# 使用 ufw 的示例
ufw allow from 192.168.1.0/24 to any port 8899
ufw deny 8899
```

在反向代理级别实施速率限制以防止滥用和 API 耗尽。在 nginx 中，你可以添加：

```nginx
limit_req_zone $binary_remote_addr zone=speakr:10m rate=10r/s;
limit_req zone=speakr burst=20;
```

保持 Docker 镜像更新以获得最新的安全补丁。定期检查更新并规划维护窗口进行更新。更新前务必先备份，如果可能的话先在暂存环境中测试更新。

## 更新 Speakr

保持 Speakr 更新可确保你拥有最新的功能和安全补丁。更新过程很简单，但应谨慎操作以避免数据丢失。

首先，更新前务必创建备份：

```bash
# 创建备份
tar czf speakr_backup_before_update.tar.gz uploads/ instance/ .env

# 拉取最新镜像
docker compose pull

# 停止当前容器
docker compose down

# 使用新镜像启动
docker compose up -d

# 检查日志以确保成功启动
docker compose logs -f app
```

更新过程会保留你所有的数据，因为数据存储在容器外的挂载数据卷中。但是，查看发布说明很重要，因为某些更新可能需要配置更改或有需要注意的破坏性变更。

如果更新导致问题，你可以通过在 docker-compose.yml 中指定先前版本来回滚：

```yaml
image: learnedmachine/speakr:v1.2.3  # 替换为你之前的版本
```

## 常见问题排查

### 容器无法启动

当容器无法启动时，日志通常会准确告诉你问题所在。首先检查日志：

```bash
docker compose logs app
```

常见的启动问题包括缺失或格式不正确的 `.env` 文件。确保你的 `.env` 文件存在且具有正确的语法。每一行应该是 `KEY=value` 格式，等号周围不要有空格。注释以 `#` 开头。

端口冲突是另一个常见问题。检查端口 8899 是否已被占用：

```bash
netstat -tulpn | grep 8899
# 或在 macOS 上：
lsof -i :8899
```

如果端口被占用，请停止冲突的服务或更改 docker-compose.yml 中 Speakr 的端口。

### 转录失败

转录失败通常源于 API 配置问题。检查 Docker 日志中的具体错误消息：

```bash
docker compose logs app | grep -i error
```

常见的转录问题包括不正确的 API 密钥，这在日志中会显示为认证错误。仔细检查 `.env` 文件中的密钥并确保它们是正确的服务。API 额度不足会显示为配额或支付错误。检查你的 API 提供商账户余额。网络连接问题会显示为连接超时或 DNS 解析失败。

对于 ASR 端点，验证服务是否正在运行并可访问：

```bash
# 测试 ASR 端点连接
curl http://your-asr-service:9000/docs
```

如果使用 Docker 网络和服务名，请记住容器必须在同一网络上才能通信。

### 性能问题

性能缓慢可能有多种原因。首先检查系统资源：

```bash
# 检查内存使用情况
free -h

# 检查磁盘 I/O
iotop

# 检查 Docker 资源使用情况
docker stats speakr
```

如果内存紧张，考虑添加 swap 空间或升级你的服务器。对于磁盘 I/O 问题，确保 uploads 和 instance 目录使用 SSD 存储。传统硬盘会显著降低操作速度，尤其是多用户并发使用时。

对于大文件处理，确保正确配置了分段。没有分段的话，大文件可能会超时或完全失败。分段大小应略低于你的 API 限制，以考虑编码开销。

如果你在许多并发用户情况下看到转录缓慢，你可能触及了 API 速率限制。查看你的 API 提供商文档中的速率限制，如果需要请考虑升级你的计划。

### 浏览器录音问题

如果浏览器录音不起作用，尤其是系统音频，最常见的原因是你使用的是 HTTP 而不是 HTTPS。由于隐私问题，浏览器需要安全连接才能进行音频捕获。要么使用反向代理设置 SSL，要么（仅用于本地开发）修改浏览器的安全设置，将你的本地 URL 视为安全。

在 Chrome 中，导航到 `chrome://flags`，搜索"insecure origins"，并将你的 URL 添加到列表中。请记住这会降低安全性，仅应用于开发环境。

## 从源码构建

如果你需要修改 Speakr 的代码或偏好自行构建镜像，你可以从源码构建。这需要克隆仓库并使用 Docker 的构建功能。

首先，克隆仓库并进入目录：

```bash
git clone https://github.com/murtaza-nasir/speakr.git
cd speakr
```

修改 docker-compose.yml 以本地构建而不是使用预构建镜像：

```yaml
services:
  app:
    build: .  # 从当前目录构建
    image: speakr:custom  # 自定义构建的标签
    container_name: speakr
    restart: unless-stopped
    ports:
      - "8899:8899"
    env_file:
      - .env
    volumes:
      - ./uploads:/data/uploads
      - ./instance:/data/instance
```

构建并启动自定义版本：

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

`--build` 标志强制 Docker 即使已有镜像也重新构建。当你进行了代码更改并想测试时很有用。

## 性能优化

对于高负载部署或处理大量大文件时，优化变得很重要。如果使用 ASR，首先从模型选择开始。distil-large-v3 模型在速度和准确性之间提供了极佳的平衡。对于纯英语内容，使用 `.en` 变体，它们在英语上更快更准确。

为你的工作负载优化 Docker 资源分配：

```yaml
services:
  app:
    image: learnedmachine/speakr:latest
    deploy:
      resources:
        limits:
          memory: 8G
          cpus: '4'
        reservations:
          memory: 4G
          cpus: '2'
```

这确保 Speakr 有足够的资源，同时防止它在共享服务器上消耗所有资源。

对于存储性能，为 Docker 数据卷使用 SSD 驱动器。数据库从快速随机 I/O 中获益良多，大音频文件处理在 SSD 上也会快得多。如果使用网络存储，请确保低延迟连接。

---

下一步：[用户指南](../user-guide/index.md) 了解如何使用 Speakr 的所有功能