## gitea 中使用 woodpecker

### 放哪里

Woodpecker 会按顺序找你的配置：

.woodpecker/*.{yaml,yml}（文件夹里每个 yml 是一个独立 workflow）

.woodpecker.yaml（仓库根的单文件）

.woodpecker.yml（仓库根的单文件）
你也可以在项目设置里改成自定义路径（如果填成目录，必须以 / 结尾，如 .woodpecker/）。

### 启用仓库

在 Woodpecker Web 打开你的仓库，点 Enable 后它会自动在 Gitea 里装好 webhook。之后你只要往仓库推代码、开 PR、打 tag，就会触发 CI。最简单的是在根目录放 .woodpecker.yml。

### 通用模板（单文件 .woodpecker.yml）

```bash
# 触发条件：main/dev 分支的 push 和 PR；打 tag 时发布
when:
  - event: push
    branch:
      - main
      - dev
  - event: pull_request
  - event: tag

# （推荐）完整 clone（需要时）
clone:
  git:
    image: woodpeckerci/plugin-git
    settings:
      depth: 0

steps:
  - name: lint-and-test
    image: node:20
    environment:
      NODE_ENV: test
    commands:
      - node -v
      - npm ci
      - npm run lint
      - npm test

  # 用 buildx 构建并推镜像（示例，需在 UI 里创建对应 secrets）
  - name: docker-build
    image: quay.io/thegeeklab/wp-docker-buildx
    privileged: true
    when:
      event:
        - push
        - tag
      branch:
        - main
    settings:
      repo: registry.example.com/myorg/myapp
      tags: latest
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password
```

要点：

secrets 现在统一通过 environment/settings -> from_secret 注入，不再用旧的 secrets: 块（3.x 迁移规则）。
“你的第一个流水线”示例 & from_secret 的写法，官方文档也有。
上面用的 wp-docker-buildx 是常见的多架构镜像构建插件（需要 privileged: true）。

多文件结构（文件夹 .woodpecker/）

如果你想把 CI 拆开管理，就在仓库根新建目录：

```bash
.woodpecker/
  ci.yaml       # 普通 CI
  release.yaml  # 发布
  gpu.yaml      # 需要 GPU 的任务（示例见下）
```

Woodpecker 会把每个 yml 当成一个独立 workflow 来跑。

适合 90% 项目：push/PR 都跑、用 secrets、再给个 Docker 构建示例。

### 增加agent

外部/跨机器 agent 一律用 ci-agent.jmsu.top:443。

ci.jmsu.top：Web UI + REST API 的域名（人用浏览器访问、OAuth 回调等）。不是 gRPC 入口。

ci-agent.jmsu.top：gRPC（TCP） 的域名，你的 Traefik TCP 路由会把它转到 server 的 9000 端口——agent 该连这里。

在你现在的架构里：

内网/同 Compose 里的 agent → WOODPECKER_SERVER=woodpecker-server:9000（容器内直连）。

跨机器/公网（或 tailnet）agent → WOODPECKER_SERVER=ci-agent.jmsu.top:443（走 Traefik TCP）。

只要机器能连通 ci-agent.jmsu.top:443，并且你给了正确的 WOODPECKER_AGENT_SECRET，它就能注册成为 agent。

（可选）如果 agent 在你的 tailnet 内，也可以直连 100.64.0.27:8419，那就把 WOODPECKER_GRPC_SECURE=false（因为这是你映射出来的明文 gRPC 端口）。

#### GPU agent + GPU 流水线

GPU Agent 的 docker-compose.yml（放在有 NVIDIA 显卡的那台机器上）

```yaml
services:
  woodpecker-agent-gpu:
    image: woodpeckerci/woodpecker-agent:latest
    container_name: woodpecker-agent-gpu
    restart: unless-stopped
    environment:
      WOODPECKER_SERVER=ci-agent.jmsu.top:443
      WOODPECKER_GRPC_SECURE=true
      WOODPECKER_GRPC_VERIFY=true
      WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
      # 给 agent 打标签，供 workflow 定向调度
      WOODPECKER_AGENT_LABELS=gpu=true,location=gpu-node-01,backend=docker
      # 并发数（按需）
      WOODPECKER_MAX_WORKFLOWS=2
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
```

前置：这台 GPU 主机要装 NVIDIA Container Toolkit 并启用 Docker runtime：
sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker。官方指引推荐这样配置。

GPU 专用工作流（.woodpecker/gpu.yaml）

```bash
# 只有带 gpu=true 标签的 agent 会接单
labels:
  gpu: "true"

when:
  - event: push
    branch:
      - main
      - dev
  - event: manual

steps:
  - name: cuda-smoke
    image: nvidia/cuda:12.4.1-base-ubuntu22.04
    commands:
      - nvidia-smi
```

要点：workflow 顶层的 labels 会作为调度选择器，只会派给拥有相同标签的 agent（你刚才在 GPU agent 用 WOODPECKER_AGENT_LABELS=gpu=true,... 打过标签）。

## 3) 外部 Agent 使用示例

在其他机器（非同一 docker 网络）的 agent：

```bash
export WOODPECKER_SERVER=ci-agent.jmsu.top:443   # Traefik TCP 对外端口
export WOODPECKER_AGENT_SECRET=3ad4d1a5fc1876bf126bafbcbd0c5b75afa944f299cdbb9e690e27db74766252
docker run --rm -e WOODPECKER_SERVER -e WOODPECKER_AGENT_SECRET \
  -v /var/run/docker.sock:/var/run/docker.sock woodpeckerci/woodpecker-agent:latest
```

## 测试解析日志

```bash
curl -s http://100.64.0.1:8500/v1/agent/services \
  | jq '.["woodpecker-web-100.64.0.27-8420"]'
```

## woodpecker 的其他镜像

1. woodpeckerci/plugin-gitea-release

用途：在 Gitea 上发布 Release。

典型场景：

当你在流水线里构建好二进制或打包好的产物后，可以用这个插件直接把产物上传到 Gitea 的 release 页面。

类似 GitHub Actions 里的 gh release create。

关键参数（pipeline yaml 里用的时候要传 env）：

api_key: Gitea 的个人访问令牌

files: 需要上传的文件路径

base_url: Gitea 实例的 URL

title / note: Release 标题、描述

2. woodpeckerci/woodpecker-cli

用途：Woodpecker 的命令行客户端。

典型场景：

在 CI/CD 环境或本地 shell 中调用 Woodpecker API，触发/查询流水线。

类似 gh（GitHub CLI）、glab（GitLab CLI）。

功能示例：

woodpecker-cli info → 查看服务器信息

woodpecker-cli build start <repo> → 触发构建

woodpecker-cli build logs <build_id> → 查看日志

3. woodpeckerci/plugin-s3

用途：将构建产物上传到 S3 存储（或兼容 S3 的对象存储，例如 MinIO、Ceph RGW、阿里云 OSS、腾讯云 COS）。

典型场景：

构建产物（模型文件、Docker 镜像 tar 包、静态网站文件）上传到对象存储，方便下载或后续部署。

关键参数：

bucket：目标存储桶

access_key / secret_key：认证凭据

endpoint：对象存储的 API 地址

source：要上传的文件路径

4. woodpeckerci/plugin-git

用途：在流水线里进行 Git 操作（checkout、clone、push）。

典型场景：

默认情况下，Woodpecker agent 会自动 clone 对应的仓库，但如果你需要 额外操作 Git，比如 push 生成的文件回仓库、同步到另一个 repo，就会用到这个插件。

常见用法：

自动更新子模块

构建完成后，把生成的文档推送到 gh-pages / docs 分支

将版本号 tag 回写到仓库

| 镜像                     | 主要功能                        | 常见用途                         |
| ---------------------- | --------------------------- | ---------------------------- |
| `plugin-gitea-release` | 在 Gitea 上创建 Release 并上传产物   | 发布二进制包 / 模型文件到 Gitea Release |
| `woodpecker-cli`       | CLI 工具，管理 Woodpecker 服务器和构建 | 本地或 CI 脚本里触发/监控流水线           |
| `plugin-s3`            | 上传产物到 S3 / 对象存储             | 存放模型、静态文件、备份                 |
| `plugin-git`           | 执行 Git 操作（clone/push）       | 自动推送 tag、同步分支、更新文档           |


结合你的场景（LLM 微调 + 自动部署）：

plugin-s3：可以把训练好的模型权重、日志直接上传到 MinIO/OSS，方便分发。

plugin-gitea-release：你可以在 Gitea release 里发一个“训练完成的模型包”。

plugin-git：可以在训练完成后自动 push 版本号/配置文件回到仓库。

woodpecker-cli：你本地调试流水线、或在另一台机器上触发/监控 build。