matrix/.gitea/README.md

# Gitea Actions CI/CD 部署指南

本目录包含 Gitea Actions 工作流配置，用于自动构建并推送 Docker 镜像到
Gitea Container Registry。

## 当前工作流

### `build-image.yml`

- **触发条件**：push 到 `master` / `main` 分支（排除 tag 推送）
- **目标架构**：`linux/amd64`
- **镜像标签**：
  - `latest`（latest 镜像）
  - `<sha>`（commit 短哈希，便于回溯）
- **目标 Registry**：Gitea 内置 Container Registry
  - URL：`http://192.168.6.200:3080/1076code/matrix/packages/container/matrix-music-bot`
- **构建方式**：`docker buildx` + BuildKit 缓存（推到 registry 作为 `:buildcache` 镜像层）
- **安全扫描**：自动跑 Trivy 扫描 CRITICAL/HIGH 漏洞（不阻塞流程）

## 镜像使用

构建完成后，可通过以下方式拉取：

```bash
# 拉取最新
docker pull http://192.168.6.200:3080/1076code/matrix/packages/container/matrix-music-bot:latest

# 拉取特定 commit
docker pull http://192.168.6.200:3080/1076code/matrix/packages/container/matrix-music-bot:abc1234

# 运行（用 docker-compose 简化环境变量管理）
MATRIX_BOT_SECRET_PASSPHRASE="..." docker-compose up -d
```

或在 `docker-compose.yml` 中直接引用：

```yaml
services:
  matrix-music-bot:
    image: 192.168.6.200:3080/1076code/matrix/packages/container/matrix-music-bot:latest
    # 移除 build: 段，改用 image 拉取
    # ... 其他配置不变
```

## Gitea 实例前置要求

1. **Container Registry 已开启**
   - Gitea 管理后台 → packages → 启用 Container Registry
   - 配置域名（与 Gitea 主站一致即可）

2. **注册 Actions Runner**
   - Gitea 管理后台 → Actions → Runners → Create new runner
   - 在 runner 机器上执行：

     ```bash
     # Gitea Actions Runner 安装（参考 https://docs.gitea.com/usage/actions/act-runner）
     # 1. 下载 act_runner 二进制
     curl -O https://dl.gitea.com/act_runner/0.2.11/act_runner-0.2.11-linux-amd64
     chmod +x act_runner-0.2.11-linux-amd64
     mv act_runner-0.2.11-linux-amd64 /usr/local/bin/act_runner

     # 2. 注册 runner（用 Gitea UI 提供的注册 token；标签要记好！）
     act_runner register \
         --instance http://192.168.6.200:3080 \
         --token <RUNNER_REGISTRATION_TOKEN> \
         --labels ubuntu-22.04      # ← 必须与 workflow 中 runs-on 一致

     # 3. 启动 runner（前台或 daemon）
     act_runner daemon
     ```

   - **重要**：`--labels` 指定的标签必须与 workflow 中 `runs-on` 完全一致
   - 本项目 Gitea 实例现有 runner：`hermes-runner`，标签 `ubuntu-22.04`（全局）
   - Runner 必须有 `docker buildx` 可用（Docker 20.10+）

3. **网络可达性**
   - Runner 能访问 `crates.io`（或 rsproxy.cn 镜像）下载 Rust crates
   - Runner 能访问 GitHub 拉取 `actions/checkout` 等 actions
   - Runner 能访问 Gitea Container Registry（通常同主机 / 同网络）

## 工作流调整指南

### 添加 tag 触发的版本镜像

在 `build-image.yml` 顶部加：

```yaml
on:
  push:
    branches: [master, main]
    tags: ['v*']   # ← 新增：tag 推送触发
  tags-ignore: ''   # 取消排除

# 然后在 metadata-action 的 tags 加：
#   type=semver,pattern={{version}}
#   type=semver,pattern={{major}}.{{minor}}
#   type=semver,pattern={{major}}
```

### 启用多架构镜像

修改：

```yaml
env:
  PLATFORM: linux/amd64,linux/arm64

jobs:
  build:
    steps:
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
```

### 添加推送后自动部署

```yaml
deploy:
  needs: build
  runs-on: ubuntu-latest
  if: gitea.ref == 'refs/heads/master'
  steps:
    - name: SSH to production
      uses: appleboy/ssh-action@v1
      with:
        host: ${{ secrets.PROD_HOST }}
        username: ${{ secrets.PROD_USER }}
        key: ${{ secrets.PROD_SSH_KEY }}
        script: |
          cd /opt/matrix-music-bot
          MATRIX_BOT_SECRET_PASSPHRASE=$(cat ~/.matrix-bot-passphrase) \
            docker-compose pull && docker-compose up -d
```

### 添加 PR 检查（不推送）

新增 job：

```yaml
pr-check:
  if: gitea.event_name == 'pull_request'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: docker/setup-buildx-action@v3
    - uses: docker/build-push-action@v5
      with:
        context: .
        push: false  # 不推送，只构建验证
```

## 性能优化

### "Set up job" 步骤慢的优化

**根因**：每个 GitHub Actions step 都是个 Docker 容器，需从 Docker Hub
（ghcr.io / docker.io）拉取镜像。runner 首次运行会卡在拉镜像上，国内网络下尤甚。

**解决方案 A：Runner 本地预拉 action 镜像**

```bash
# 在 runner 主机上跑一次（脚本随仓库发布）
sudo ./scripts/prepull-actions.sh

# 验证缓存命中
docker images | grep -E "(docker/actions|aquasec/trivy-action|moby/buildkit)"
```

脚本会拉取 build-image.yml 用到的所有 Docker 镜像（并行 4 路）。

**建议节奏**：
- runner 初始化时：跑一次
- 新增 action 时：跑一次
- 定期清理悬空镜像：

```bash
# /etc/cron.d/docker-prune
0 3 * * 0  root  docker image prune -f --filter "until=168h"
```

**预期效果**：
- 首次运行：`Set up job` 仍慢（冷启动）
- 后续运行：`Set up job` 仅 5-10 秒（仅做 job 调度，不再拉镜像）

### 构建性能进一步优化

如构建仍是瓶颈（>10 分钟），可叠加：

- **BuildKit registry cache**（已启用）：`docker.io/yourorg/matrix-music-bot:buildcache`
- **Cargo 缓存**：在 Dockerfile 中加 `RUN cargo build --release` 复用 `target/`
- **多架构**（如需要）：`PLATFORM: linux/amd64,linux/arm64`（CI 时间约翻倍）

---

## 故障排查

### Workflow 触发不了

检查：

- `.gitea/workflows/` 目录权限（应为 755）
- workflow 文件名后缀必须是 `.yml` 或 `.yaml`
- 仓库设置 → Actions → Workflows 状态为启用

### `docker/login-action` 失败

- 确认 Gitea 已开启 Container Registry
- 检查 `gitea.actor` / `gitea.token` 是否有 packages 写权限
- Registry URL 必须包含 scheme（如 `http://...`，不能用裸 hostname）

### `docker/build-push-action` 构建失败

- 检查 Dockerfile 路径（默认 `./Dockerfile`）
- 检查 BuildKit 是否启用（Buildx 默认启用）
- 国内环境：考虑加 `RUN cargo config set source.crates-io.replace-with ...`

### 镜像推送后无法 `docker pull`

- Registry 是 HTTP（非 HTTPS）：客户端需加 `--insecure-registry` 或配置 daemon.json
- 或用 Gitea 的 HTTPS 反向代理

## 相关文档

- Gitea Actions 官方文档：https://docs.gitea.com/usage/actions/overview
- docker/build-push-action：https://github.com/docker/build-push-action
- docker/metadata-action：https://github.com/docker/metadata-action