Files

T

Matrix Music Bot Dev fab14e3196 ci: Gitea Actions 自动构建 + 推送镜像到 Container Registry

按用户选定方案：
  - Registry: Gitea 内置 Container Registry
  - 触发: 仅 push master/main
  - 标签: latest + git short SHA
  - 架构: linux/amd64 单架构

新增文件：
  .gitea/workflows/build-image.yml   CI workflow 定义
  .gitea/README.md                  Gitea Actions 运维手册

workflow 步骤：
  1. actions/checkout@v4           检出源码
  2. dtolnay/rust-toolchain@stable  安装 Rust（仅用于 cache key 计算）
  3. Swatinem/rust-cache@v2        缓存 Cargo registry / target
  4. cargo metadata sanity check    防止 manifest 漂移
  5. docker/setup-buildx-action@v3  Buildx
  6. docker/login-action@v3        登录 Gitea Registry（用 ${{ gitea.token }}）
  7. docker/metadata-action@v5     生成 latest + sha 标签 + OCI labels
  8. docker/build-push-action@v5   构建 + 推送（含 BuildKit registry cache）
  9. aquasecurity/trivy-action      CVE 扫描（不阻塞）

特性：
  - concurrency 控制：避免重复构建（同一 ref 只跑最新）
  - 自动镜像标签：latest + commit short SHA
  - BuildKit cache 推到 :buildcache 镜像（下次构建复用）
  - Gitea 内置 token 自动认证（无需手动 secrets）
  - OCI 标准 labels（title/source/license/vendor）

gitea/README.md 包含：
  - 前置要求（Registry 开启、Runner 注册、网络）
  - 镜像使用示例
  - 常见扩展（tag 触发 / 多架构 / 自动部署）
  - 故障排查（login 失败 / build 失败 / pull 失败）

2026-07-03 00:02:51 +08:00

5.2 KiB

Raw Blame History

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 实例前置要求

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

注册 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-latest:docker

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

Runner 必须有 docker buildx 可用（Docker 20.10+）

网络可达性
- 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  # 不推送，只构建验证

故障排查

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 反向代理

5.2 KiB Raw Blame History Unescape Escape