# Speakr CI/CD 设置

本文档解释了 Speakr 项目的持续集成和持续部署（CI/CD）流水线是如何设置的。

## 自动 Docker 镜像构建与发布

Speakr 项目使用 GitHub Actions 在代码推送到仓库时自动构建 Docker 镜像并发布到 Docker Hub。

### 工作原理

1. 当代码推送到 `master` 分支或创建新标签（格式为 `v*.*.*`）时，GitHub Actions 工作流将被触发。
2. 工作流使用项目的 Dockerfile 构建 Docker 镜像。
3. 如果触发原因是推送到 `master` 分支，镜像将被标记为：
   - `latest`
   - 提交的短 SHA 值
   - 分支名称（`master`）
4. 如果触发原因是新标签（例如 `v1.2.3`），镜像将被标记为：
   - 完整版本号（`1.2.3`）
   - 主.次版本号（`1.2`）
   - 标签名称（`v1.2.3`）
5. 然后镜像会被推送到你账户下的 Docker Hub。

### 设置步骤

要设置自动 Docker 镜像发布，请按照以下步骤操作：

1. **创建 Docker Hub 账户**（如果你还没有的话）：
   - 访问 [Docker Hub](https://hub.docker.com/) 并注册账户。
   - 创建一个名为 `speakr` 的仓库。

2. **创建 Docker Hub 访问令牌**：
   - 登录 Docker Hub。
   - 点击右上角的用户名，选择"Account Settings"进入账户设置。
   - 导航到"Security"选项卡。
   - 点击"New Access Token"。
   - 给令牌取个名字（例如"GitHub Actions"）并设置适当的权限（至少需要"Read & Write"）。
   - 复制生成的令牌（你将无法再次看到它）。

3. **将 Docker Hub 凭据添加到 GitHub Secrets**：
   - 进入你的 GitHub 仓库。
   - 点击"Settings" > "Secrets and variables" > "Actions"。
   - 点击"New repository secret"。
   - 添加以下密钥：
     - 名称：`DOCKERHUB_USERNAME`，值：你的 Docker Hub 用户名
     - 名称：`DOCKERHUB_TOKEN`，值：你在上一步生成的访问令牌

4. **验证工作流**：
   - 工作流文件位于 `.github/workflows/docker-publish.yml`。
   - 它已经配置好可以构建并推送 Docker 镜像到 Docker Hub。
   - 如果需要，你可以进一步自定义它。

5. **触发工作流**：
   - 推送更改到 `master` 分支或创建新标签来触发工作流。
   - 进入 GitHub 仓库的"Actions"选项卡来监控工作流进度。

### 使用已发布的 Docker 镜像

镜像发布到 Docker Hub 后，你可以在 docker-compose.yml 文件中使用它们：

```yaml
version: '3.8'

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

### 版本控制策略

要创建新版本的应用程序：

1. 进行更改并提交到仓库。
2. 按照语义化版本控制创建新标签：
   ```bash
   git tag v1.0.0  # 替换为适当的版本号
   git push origin v1.0.0
   ```
3. GitHub Actions 工作流将自动构建并发布带有相应版本标签的新 Docker 镜像。

这样用户可以选择使用最新版本（`learnedmachine/speakr:latest`）或特定版本（`learnedmachine/speakr:1.0.0`）。