ToolBox/.gitea/README.md

Gitea Actions CI 模板（Go + Vue）

复制整个 .gitea/ 目录到新仓库即可启用 CI：可选 go test + Docker 构建/推送（Go 编译与 Vue 构建在 Dockerfile 内完成）。

项目约定

路径	说明
go.mod	仓库根目录
Dockerfile	仓库根目录，多阶段构建（含前端 web/）
web/	可选；由 Dockerfile 内 npm run build 处理，CI 不再单独构建

Dockerfile 要求

工作流的 Build image 步骤在仓库根目录（或 Variable DOCKERFILE 指定路径）执行 docker buildx build，不会在 CI 里单独装 Node / 跑 npm。因此 Dockerfile 必须能独立完成构建与（运行时）启动。

基本要求

项	要求
位置	默认仓库根目录 Dockerfile；其他路径用 Variable DOCKERFILE
构建上下文	仓库根目录 .（整个仓库会被 COPY 进镜像）
Go 版本	go.mod 里 go 行与 golang 基础镜像大版本一致
多架构	go build 须使用 GOARCH="$TARGETARCH"（buildx 注入）；推荐 CGO_ENABLED=0
Go 模块代理	必须在镜像内显式设置 GOPROXY / GOSUMDB（见下）；容器内不会自动读取 go.env
基础镜像加速	支持构建参数 IMAGE_PREFIX（CI 默认 docker.1panel.live/library/）
前端（可选）	存在 web/ 时在 Dockerfile 内完成 npm ci + npm run build

CI 自动传入的构建参数

参数	默认	说明
IMAGE_PREFIX	docker.1panel.live/library/	基础镜像前缀；hub 表示 Docker Hub
GOPROXY	https://goproxy.cn,direct	与 workflow / Variable 一致
GOSUMDB	sum.golang.google.cn	checksum 数据库

buildx 还会注入 TARGETARCH、BUILDPLATFORM 等，无需在 workflow 里写。

推荐：Go + Vue 多阶段模板

# syntax=docker/dockerfile:1
ARG IMAGE_PREFIX=

# 1) 前端（无 web/ 时可删整个 stage，并去掉 go-builder 里 COPY dist）
FROM --platform=$BUILDPLATFORM ${IMAGE_PREFIX}node:20-alpine AS web-builder
WORKDIR /src/web
COPY web/package.json web/package-lock.json web/.npmrc ./
RUN npm ci
COPY web/ ./
RUN npm run build

# 2) Go 编译
FROM --platform=$BUILDPLATFORM ${IMAGE_PREFIX}golang:1.25-alpine AS go-builder
ARG TARGETARCH
ARG GOPROXY=https://goproxy.cn,direct
ARG GOSUMDB=sum.golang.google.cn
ENV GOPROXY=${GOPROXY} GOSUMDB=${GOSUMDB}

WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download

COPY cmd/ ./cmd/
COPY internal/ ./internal/
# 若静态资源嵌入 Go：COPY --from=web-builder /src/web/dist/ ./path/to/static/

RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=linux GOARCH="$TARGETARCH" \
    go build -ldflags="-w -s" -o /app ./cmd/yourapp

# 3) 运行镜像
FROM ${IMAGE_PREFIX}alpine:3.20
RUN apk add --no-cache ca-certificates tzdata
COPY --from=go-builder /app /usr/local/bin/yourapp
ENTRYPOINT ["/usr/local/bin/yourapp"]

按项目调整：./cmd/yourapp、静态资源路径、运行用户、EXPOSE / VOLUME 等。

仅 Go（无前端）

删除 web-builder stage；go-builder 中不要 COPY 前端产物；其余 GOPROXY / TARGETARCH / IMAGE_PREFIX 要求相同。

前端 npm 源（国内）

在 web/.npmrc 配置 registry，并在 Dockerfile 里与 package.json 一并 COPY：

registry=https://registry.npmmirror.com

本地验证（与 CI 一致）

docker buildx build --platform linux/amd64 \
  --build-arg IMAGE_PREFIX=docker.1panel.live/library/ \
  --build-arg GOPROXY=https://goproxy.cn,direct \
  -f Dockerfile -t myapp:test .

常见 Dockerfile 构建错误

报错	原因	处理
proxy.golang.org timeout	镜像内未设 ENV GOPROXY	go-builder 阶段加 ARG/ENV GOPROXY
node / Vite 版本不符	基础镜像 Node 过旧	使用 node:20-alpine 及以上
某架构 build 失败	未使用 TARGETARCH	GOARCH="$TARGETARCH"
拉基础镜像 timeout	Hub 不可达	--build-arg IMAGE_PREFIX=docker.1panel.live/library/ 或 1Panel 配镜像加速

一次性配置

1. Runner：部署 act_runner，标签含 ubuntu-latest，并挂载 docker.sock（见 act-runner/README.md）。
2. Secret：仓库 Settings → Actions → Secrets，添加 REGISTRY_TOKEN（PAT，write:package 权限）。
3. Variable（推荐）：若 runner 与 Gitea 同机、或 gitea.server_url 为内网地址，必须设置 REGISTRY=你的公网域名（如 git.example.com，不要填 172.17.0.1:13827）。
4. Gitea Registry：服务端 [packages] ENABLED = true，ROOT_URL 正确；穿透场景建议 PUBLIC_URL_DETECTION = never（Gitea 1.26+）。

REGISTRY 未设置时，会从 GITEA_ROOT_URL 或 gitea.server_url 推断；均为内网地址时 workflow 会提前失败并提示。

可选 Variables

仓库 Settings → Actions → Variables（留空则用默认值）：

变量	默认	说明
REGISTRY	见下方推断顺序	公网 Registry 主机名，如 git.example.com（勿用内网 IP:13827）
GITEA_ROOT_URL	（空）	当 gitea.server_url 为内网时，可设 https://git.example.com/
IMAGE_NAME	仓库名小写	镜像名，非 owner/repo 全路径
DOCKERFILE	Dockerfile	Dockerfile 路径
DOCKER_PLATFORMS	linux/amd64,linux/arm64	push 时 buildx 平台
GO_TEST_SCOPE	./...	go test 包路径
RUN_GO_TEST	（空，即运行）	设 false 跳过 go test，仅 Docker 构建
DOCKER_IMAGE_PREFIX	1panel	基础镜像前缀；可选 hub / daocloud
GOPROXY	https://goproxy.cn,direct	Go 模块代理
GOSUMDB	sum.golang.google.cn	Go checksum 数据库

触发与镜像 tag

• pull_request：go test（可关）+ 单架构 docker build 验证（不推送）
• push main/master：go test + 多架构构建并推送 :latest、:sha-xxxxxxx
• push tag v*：额外推送 :v1.2.3 等

示例（仓库 rose_cat707/Prism，Gitea 在 git.example.com）：

git.example.com/rose_cat707/prism:latest
git.example.com/rose_cat707/prism:sha-35b3b48

目录结构

.gitea/
├── README.md                 # 本文件
├── workflows/
│   └── ci.yml                # 主工作流
└── act-runner/               # runner 部署参考（可选）
    ├── README.md
    ├── config.yaml
    ├── docker-compose.yml
    └── .env.example

本地验证 Registry

host=$(echo "https://你的-gitea-地址/" | sed -e 's|^https://||' -e 's|/.*||')
curl -s -D - "https://${host}/v2/" -o /dev/null | grep -i www-authenticate
docker pull "${host}/owner/image:latest"   # 公开 Registry 无需 login

推送镜像（CI）仍需仓库 Secret REGISTRY_TOKEN（write:package）。仅拉取公开包不需要登录。

realm 应指向公网 Gitea 域名，而非 127.0.0.1。

常见 Registry 错误

报错	原因	处理
Get "https://172.17.0.1:13827/v2/" HTTP/HTTPS	Variable REGISTRY 或 gitea.server_url 为内网地址	设 REGISTRY=git.example.com
token 指向 127.0.0.1	Gitea realm 配置错误	PUBLIC_URL_DETECTION=never + 正确 ROOT_URL