matrix/.gitea

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 漏洞（不阻塞流程）

镜像使用

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

# 拉取最新
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 中直接引用：

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 机器上执行：

     # 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 顶部加：

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}}

启用多架构镜像

修改：

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

添加推送后自动部署

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：

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 镜像

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

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

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

建议节奏：

• runner 初始化时：跑一次
• 新增 action 时：跑一次
• 定期清理悬空镜像：

# /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