diff --git a/deploy/runner/install-runner.sh b/deploy/runner/install-runner.sh new file mode 100755 index 0000000..0aa51c1 --- /dev/null +++ b/deploy/runner/install-runner.sh @@ -0,0 +1,128 @@ +#!/usr/bin/env bash +# 在 CI 主机上安装并注册 Gitea Actions runner(Ubuntu/arm64 或 amd64)。 +# +# 用法(在 runner 主机上、仓库之外执行): +# GITEA_URL=https://git.example.com RUNNER_TOKEN=xxx ./deploy/runner/install-runner.sh +# DRY_RUN=1 ... ./deploy/runner/install-runner.sh # 只打印将执行的命令 +# +# 需要的环境变量: +# GITEA_URL Gitea 站点地址 +# RUNNER_TOKEN 仓库 Settings → Actions → Runners 里生成的注册 token +# 可选: +# RUNNER_NAME runner 名称,默认取 hostname +# RUNNER_LABELS 默认 ubuntu-latest,oracle-arm +# RUNNER_VERSION 默认 5.2.0 +# RUNNER_ROOT 默认 $HOME/gitea-runner +# CACHE_PORT 默认 8193 +# RUNNER_CACHE_HOST 默认 172.17.0.1(Docker 默认 bridge 网关) +set -euo pipefail + +GITEA_URL=${GITEA_URL:?需要设置 GITEA_URL} +RUNNER_TOKEN=${RUNNER_TOKEN:?需要设置 RUNNER_TOKEN} +RUNNER_NAME=${RUNNER_NAME:-$(hostname -s)} +RUNNER_LABELS=${RUNNER_LABELS:-ubuntu-latest,oracle-arm} +RUNNER_VERSION=${RUNNER_VERSION:-5.2.0} +RUNNER_ROOT=${RUNNER_ROOT:-$HOME/gitea-runner} +CACHE_PORT=${CACHE_PORT:-8193} +RUNNER_CACHE_HOST=${RUNNER_CACHE_HOST:-172.17.0.1} +CACHE_DIR=${CACHE_DIR:-$RUNNER_ROOT/cache-data} +DRY_RUN=${DRY_RUN:-0} + +command -v docker >/dev/null 2>&1 || { echo "缺少 docker,请先安装并启动 Docker" >&2; exit 1; } +command -v systemctl >/dev/null 2>&1 || { echo "缺少 systemd,当前脚本只支持 systemd 主机" >&2; exit 1; } + +case "$(uname -m)" in + aarch64 | arm64) ARCH=arm64 ;; + x86_64 | amd64) ARCH=amd64 ;; + *) echo "不支持的架构: $(uname -m)" >&2; exit 1 ;; +esac + +run() { + if [ "$DRY_RUN" = "1" ]; then + echo "+ ${*//$RUNNER_TOKEN/***}" + else + "$@" + fi +} + +archive="gitea-runner-${RUNNER_VERSION}-linux-${ARCH}.xz" +base="https://dl.gitea.com/gitea-runner/${RUNNER_VERSION}" + +run mkdir -p "$RUNNER_ROOT" "$CACHE_DIR" +if [ ! -x "$RUNNER_ROOT/gitea-runner-${RUNNER_VERSION}-linux-${ARCH}" ]; then + run curl -fsSL -o "$RUNNER_ROOT/$archive" "$base/$archive" + run curl -fsSL -o "$RUNNER_ROOT/$archive.sha256" "$base/$archive.sha256" + run env -C "$RUNNER_ROOT" sha256sum -c "$archive.sha256" + run xz -d -f "$RUNNER_ROOT/$archive" +fi +run ln -sf "gitea-runner-${RUNNER_VERSION}-linux-${ARCH}" "$RUNNER_ROOT/gitea-runner" + +if [ ! -f "$RUNNER_ROOT/.runner" ]; then + run env -C "$RUNNER_ROOT" ./gitea-runner register \ + --no-interactive \ + --instance "$GITEA_URL" \ + --token "$RUNNER_TOKEN" \ + --name "$RUNNER_NAME" \ + --labels "$RUNNER_LABELS" + run chmod 600 "$RUNNER_ROOT/.runner" +fi + +run tee "$RUNNER_ROOT/config.yaml" >/dev/null </dev/null </dev/null 2>&1; then + run sudo loginctl enable-linger "$USER" +fi +run systemctl --user daemon-reload +run systemctl --user enable --now gitea-runner.service + +# 任务容器经 Docker bridge 访问 runner 内置 cache server,ufw 默认 INPUT DROP 会拦截。 +# Gitea Actions 会给每个 job 建独立 bridge(实测 192.168.x),因此三个私网段都要放行。 +if command -v ufw >/dev/null 2>&1; then + for cidr in 172.16.0.0/12 192.168.0.0/16 10.0.0.0/8; do + run sudo ufw allow from "$cidr" to any port "$CACHE_PORT" proto tcp comment "gitea actions cache" + done +fi + +echo +echo "runner 已安装:$RUNNER_ROOT" +echo "检查状态:systemctl --user status gitea-runner.service" +echo "检查 linger:loginctl show-user \"$USER\" -p Linger" +echo "检查日志:journalctl --user -u gitea-runner -n 100 --no-pager" diff --git a/docs/runner-setup.md b/docs/runner-setup.md new file mode 100644 index 0000000..ebf5f45 --- /dev/null +++ b/docs/runner-setup.md @@ -0,0 +1,60 @@ +# CI Runner 安装与运维 + +CI 跑在自托管 Gitea Actions runner 上(当前主机 `oracle_arm`,与生产 API 共用 2 核)。本文件记录可复现的安装步骤,避免换机器时重新摸索。 + +## 一次性准备 + +1. 在 Gitea 仓库 Settings → Actions → Runners 里创建注册 token(只对单个仓库或整个实例生效)。 +2. 目标主机需要:Docker、`curl`、`xz`、`ufw`、systemd、可用 sudo、Node 不需要(任务容器自带)。 + +## 安装 + +把仓库里的脚本拷到目标主机后执行: + +```bash +GITEA_URL=https://git.example.com \ +RUNNER_TOKEN=<注册 token> \ +RUNNER_NAME=oracle-arm \ +RUNNER_LABELS=ubuntu-latest,oracle-arm \ +./install-runner.sh +``` + +加 `DRY_RUN=1` 可先看它准备执行哪些命令(token 会被替换成 `***`)。 + +脚本做的事: + +1. 按架构下载 `gitea-runner--linux-`,校验 `.sha256` 后解压到 `~/gitea-runner`。 +2. 用 `--no-interactive` 注册,写出 `.runner`(已存在则跳过,可重复执行)。 +3. 生成 `config.yaml`:单并发、`docker://node:24-bookworm` 标签、内置 cache server 监听 `172.17.0.1:8193`、任务容器限制 `--cpus=1.5 --memory=4g`。 +4. 装 systemd user unit `gitea-runner.service`,执行 `loginctl enable-linger` 后 `enable --now`。 +5. 放行任务容器到 cache 端口的 ufw 规则。 + +## 为什么 ufw 要放行三个网段 + +任务容器访问宿主机的 cache server 走 Docker bridge,`ufw` 默认 `INPUT DROP` 会直接丢包。Gitea Actions 每个 job 会新建独立 bridge(实测 `192.168.x`),默认 `docker0` 又是 `172.17.x`,所以需要 `172.16.0.0/12`、`192.168.0.0/16`、`10.0.0.0/8` 三条规则。只放行其中一条的后果是缓存恢复/保存各空等数分钟并最终超时。 + +## 日常检查 + +```bash +systemctl --user status gitea-runner.service +journalctl --user -u gitea-runner -n 100 --no-pager +du -sh ~/gitea-runner/cache-data +``` + +仓库侧 `pnpm deploy:status` 也会打印 `ci-runner=` 一行。 + +## 排障 + +| 现象 | 先查什么 | +| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| push 后 CI 一直 queued 不启动 | runner 服务是否 active;Gitea 仓库 Runners 页面是否显示 online | +| 日志出现 `Failed to GetCacheEntryDownloadURL ... ETIMEDOUT` | ufw 是否放行三个私网段;`docker exec node -e 'fetch("http://172.17.0.1:8193/")'` 应返回 404 | +| 一轮 CI 突然变慢 | 缓存是否命中;宿主机负载与磁盘余量 | +| 生产 API 变慢 | CI 与生产共用主机,检查是否在跑 build/api job;必要时暂停 runner | +| 重启后 runner 没起来 | `loginctl show-user "$USER" -p Linger` 应为 `Linger=yes`;否则执行 `sudo loginctl enable-linger "$USER"` | + +## 约束 + +- `capacity: 1`:不要提高并发,2 核主机上并发只会让生产和 CI 一起变慢。 +- 日志级别保持 `debug`:`info` 级别不记录各 step 的结果行,排障时等于没有日志。 +- 浏览器回归不进 CI(见 `docs/ci.md`),因为 Playwright 会长期占用 CPU。