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
parent 2518169927
commit fab14e3196
2 changed files with 315 additions and 0 deletions
@@ -0,0 +1,183 @@
+# 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-latest:docker
+
+     # 3. 启动 runner（前台或 daemon）
+     act_runner daemon
+     ```
+
+   - 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  # 不推送，只构建验证
+```
+
+## 故障排查
+
+### 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