Skip to content
opskatPublic

About

镜像代理工具

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

katch

多上游镜像代理站。把 container registry、APT 源、Go module proxy、GitHub 静态资源 统一收到一个域名下,路径的第一段就是上游主机名。

对于已经支持的协议,或者满足 static 条件的上游,使用者只需要记一条规则:把 https:// 换成 https://<katch>/,其余照抄。元数据包含绝对外链的包仓库需要额外的 客户端配置或协议适配器,具体见公开包镜像加速兼容性。

docker pull katch.example.com/docker.io/library/redis:7
curl -fLO https://katch.example.com/raw.githubusercontent.com/foo/bar/main/x.sh
# /etc/apt/sources.list
deb https://katch.example.com/deb.debian.org/debian bookworm main

# Go
export GOPROXY=https://katch.example.com/proxy.golang.org

整条原始 URL 直接粘在后面也认(GitHub 代理通行的「前缀 + 原始 URL」写法), registry 的 /v2 跟在主机名后面同样可以:

curl -fLO https://katch.example.com/https://raw.githubusercontent.com/foo/bar/main/x.sh
curl -fL https://katch.example.com/ghcr.io/v2/foo/bar/manifests/latest

符合上述条件时,加一个新上游只需在界面上加一条记录,不是加一条路径前缀约定, 也不需要重启进程。需要解释或改写元数据的上游还需要对应的协议适配器。

它解决什么

受限网络下,容器镜像、系统软件包、Go 模块、GitHub 资源的加速各自要配一套方案: 四套配置、四个域名、四种故障模式,新机器初始化要重复一遍。katch 把它们收到一个 入口下,并且给这些内容寻址的对象加一层本地缓存——同一个镜像层、同一个 deb 包、 同一个模块版本只从上游取一次。

一条硬约束:katch 不是开放代理。只有上游表里启用的主机可被访问,不在表里、 已停用、协议类别对不上的一律返回同一个空 404。

部署形态

单个静态二进制。前端产物经 //go:embed 编进二进制,由后端同源提供, 不需要另外部署 nginx——起一个进程就是全部。

katch (单进程, :8080)
├─ /                      前端 SPA(embed 进二进制的 dist)
├─ /api/v1/...            管理接口(/admin/* 需密钥)
├─ /metrics               Prometheus 端点
├─ /v2/...                container registry 协议
└─ /<上游主机名>/...       其余上游(APT / Go proxy / GitHub 等)

分辨保留段和上游段的规则是点号:第一段含 . 的是上游主机名,不含 . 的是 katch 自己的保留路径。默认数据库是 sqlite(纯 Go 的 modernc.org/sqlite,不需要 cgo),落地就是一个文件;缓存对象按内容摘要落在磁盘目录里。

跑起来

Docker Compose

cp deploy/config.yaml.example deploy/config.yaml   # 改掉 admin.initialKey
docker compose -f deploy/docker-compose.yml up -d

Kubernetes

helm install katch deploy/helm/katch --namespace katch --create-namespace \
  --set config.admin.initialKey=$(openssl rand -hex 24)

不想用 Helm 就 kubectl apply -k deploy/kubernetes/(先改 secret.yaml 里的密钥)。

两条路的细节、以及为什么只能跑一个副本,都在 docs/deploy.md。

从源码

make install-deps   # 安装前端依赖
make build          # 前端构建 → 拷进 internal/web/dist → CGO_ENABLED=0 编译
cp configs/config.yaml.example configs/config.yaml   # 自己那一份配置,改完再起
./bin/katch -config ./configs/config.yaml

入库的是 configs/config.yaml.example;configs/config.yaml 是本地那一份, 被 .gitignore 挡着,改管理密钥和 DSN 不会弄脏工作区。make dev 会在缺失时 自动拷一份,已存在的不覆盖。

打开 http://localhost:8080 就是首页,http://localhost:8080/admin 是管理后台, 密钥用 configs/config.yaml 里的 admin.initialKey。

开发

make dev   # 前端 vite :5173(/api 与 /metrics 转发到 :8080)+ 后端 go run

开发模式下前端由 vite 自己提供,二进制里挂的是占位文件。

首次配置

上游表出厂是空的,而这张表同时就是白名单——不加记录,任何主机都是 404。 在管理后台「上游 → 添加上游」里加,或者走接口:

KEY=change-me-before-exposing-katch

curl -X POST http://localhost:8080/api/v1/admin/upstreams \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{
        "host": "docker.io",
        "protocols": ["registry"],
        "origin": "https://registry-1.docker.io",
        "enabled": true,
        "library_completion": true,
        "mutable_ttl_seconds": 300
      }'

curl -X POST http://localhost:8080/api/v1/admin/upstreams \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{
        "host": "deb.debian.org",
        "protocols": ["static"],
        "origin": "https://deb.debian.org",
        "enabled": true,
        "package_profile": "apt",
        "immutable_patterns": ["/pool/"],
        "mutable_ttl_seconds": 300
      }'

protocols 是这条上游开着的协议集合,取值为 registry、static、git 的任意非空子集——一条记录可以同时开几种,比如 github.com 既服务 git clone 也服务 release 资产下载。

package_profile 是包管理器协议语义,取值由后端已注册的适配器提供;none 表示只用 通用传输。非 none profile 必须同时开启 static。后台会用当前草稿、site_domain 和适配器声明的 companion 上游计算就绪状态,并逐项指出缺少、停用、transport 不匹配或 profile 不匹配的主机。npm/PyPI/Cargo/NuGet 等元数据会跳到附属域名,只给主上游选 profile 不算配置完成。

客户端配置只从已保存的 site_domain 生成,不能从请求 Host 或转发头猜。12 个内建 package profile 已在 coding.local 的阻断公网矩阵中通过,API 返回 runtime_verified=true;公开页和后台仅在 profile 已验证且当前 site_domain、主上游及 companion 全部就绪时提供可复制配置。Docker、Podman 与 Git 的共享链路回归也使用真实客户端 完成。实现边界、companion 清单、精确客户端版本与验收方法见 公开包镜像加速兼容性。

缓存策略

不可变判定分两类,边界不重叠:

  • registry 按协议自动判定,不需要也不看 immutable_patterns:blob 与按 digest 寻址的 manifest(.../blobs/sha256:...、.../manifests/sha256:...)是内容寻址 对象,自动长期缓存、只由 LRU 淘汰;tag manifest、referrers 与 tags/list 会变, 按 mutable_ttl_seconds 过期。
  • static 与 git 路径只认显式模式,不存在按 URL 里像不像 hash 的外观推断: immutable_patterns 为空则全部按 TTL;非空时命中的对象长期缓存,其余仍按 mutable_ttl_seconds。模式对整条上游侧路径做子串匹配(不锚定首尾):不含 通配符时直接找子串,* 匹配任意多个字符(含 /),? 匹配任意一个字符。

管理界面「缓存策略」里的预设只是把下表的模式填进 immutable_patterns,保存的是 模式本身而不是预设名称——已登记的上游不会因为预设调整而静默改变;「自定义」可以 逐行编辑任意模式。

预设 写入的模式 判为不可变 仍按 TTL 的可变例外
APT 软件包 /pool/ pool/ 下的 deb 包与源码包 dists/ 下的 InRelease、Release、Packages* 等索引
Go Module Proxy /@v/*.info、/@v/*.mod、/@v/*.zip 具体版本文件 @v/list、@latest
Git commit 静态文件 一整段 40 个 ?(commit SHA) 路径中含 40 位 commit 的对象 分支名、tag、HEAD、info/refs 这类会移动的引用
PyPI 文件 /packages/??/??/ + 64 个 ? hash 目录下的包文件 /simple/ 索引与 JSON API

命中验证

X-Katch-Cache: HIT|MISS|REVALIDATED 说明这一次有没有回源:HIT 没问上游,MISS 整份取自上游,REVALIDATED 问过上游、上游答 304,正文出自本地副本(见下文过期续期)。要看到完整的 MISS → HIT,必须用 GET 读完整响应体再比对:普通 HEAD 和可本地求值的条件请求在命中时同样报 HIT, 但 HEAD 没有响应体、条件请求可能只拿到 304,单看一次命中说明不了本地那份副本 完整;MISS → HIT 加上两次内容逐字节相同才是完整证据。

请求的对象没有副本(或可变对象已过 TTL,此时上游若答 304 则是 REVALIDATED)时第一次才是 MISS;已在 TTL 内或不可变 对象一上手就是 HIT,换一个没缓存过的路径再验。

URL=http://localhost:8080/deb.debian.org/debian/dists/bookworm/InRelease

curl -s -D /tmp/first.h -o /tmp/first.b "$URL"
grep -i '^x-katch-cache' /tmp/first.h            # MISS:这一次回源

curl -s -D /tmp/second.h -o /tmp/second.b "$URL"
grep -i '^x-katch-cache' /tmp/second.h           # HIT:这一次由本地副本应答
cmp /tmp/first.b /tmp/second.b                   # 命中内容与回源逐字节相同

# 新鲜副本上的 HEAD:本地 200、无响应体、命中
curl -sI "$URL" | grep -i '^x-katch-cache'                              # HIT
# 条件请求命中:星号问的是「还有没有这份表示」,本地 304
curl -s -o /dev/null -w '%{http_code}\n' -H 'If-None-Match: *' "$URL"   # 304

TTL 内的副本由本地应答,命中响应原样回放上游保存下来的 ETag/Last-Modified (registry 对象没有上游 ETag 时退回内容摘要推导)。由此:

  • 普通 HEAD:本地 200,状态与响应头同一套,只是不带响应体,X-Katch-Cache: HIT;
  • 条件请求:If-None-Match 按弱比较、逗号列表与 * 求值,命中返回本地 304 (也是 HIT),明确不匹配则本地 200;只有没有 If-None-Match 时才看 If-Modified-Since,日期不晚于请求时间即 304;
  • 副本缺少求值所需的 validator(上游从未给过 ETag/Last-Modified,或副本是加 该字段之前写下的历史记录):本地不猜,这一次透传上游(MISS);
  • Range 支持单段、多段和后缀范围;完整新鲜副本可以本地返回 206,非法或不可满足 范围返回 416。If-Range 匹配才返回范围,不匹配则返回完整 200。

手上没有副本(冷请求)时,条件与 Range 请求透传且不写缓存——它们可能拿到 206、304、 412 或 416,不能当成一份完整副本存下来。普通 static HEAD 和 registry blob HEAD 同样透传;仅无条件、无范围的 registry manifest HEAD 会以同一 Accept 变体的 identity GET 填充缓存,再返回无正文的 GET 等价元数据。

过期续期。 可变对象过期(或上游标了 Cache-Control: no-cache)后,如果记录里存有 上游自己给过的 ETag/Last-Modified,回源那一次带上 If-None-Match/If-Modified-Since: 上游答 304 就按它更新新鲜期、复用盘上的字节,响应标 X-Katch-Cache: REVALIDATED; 上游答 200 就整份替换(MISS);上游出错则照常透传,过期副本不会被当成新鲜的发出去。 这一跳总是 canonical identity GET:客户端发的是 HEAD、Range 或自己的条件请求时,这些 不转发给上游,刷新之后按本地副本求值,与命中时一样。 转换过的元数据(npm packument、PyPI Simple 等)回放的是 katch 自己算的 ETag,续期时发给 上游的仍是上游那一串。过期但带着上游 validator 的对象不被定时清理删除,留着等下一次 续期,由配额回收按 LRU 收走;没有 validator 的过期对象照旧由定时清理删除。

git clone

开了 git 协议的上游,仓库地址照同一条规则改写:

git clone http://localhost:8080/github.com/CodFrm/katch.git

第一次拉取原样穿透上游,katch 同时在后台把这个仓库镜像到本地;镜像建成之后, 之后的 clone / fetch 由本地那份应答,一个字节都不再问上游。这一次是谁答的写在 响应头 X-Katch-Git 上,取值 local 或 passthrough:

curl -sI "http://localhost:8080/github.com/CodFrm/katch.git/info/refs?service=git-upload-pack" \
  | grep -i x-katch-git

refs 的新鲜度按上游记录上的 mutable_ttl_seconds 算:TTL 内直接用本地那份, 超了先增量同步一次再广播,同步失败就这一次穿透上游,本地镜像照旧可用。

几件本地答不了的事会自动降级为穿透,不会失败:--depth(浅克隆)、 --filter(部分克隆),以及体积超过单仓上限的仓库。push 一律 403——katch 是 镜像不是代码托管。镜像占多少盘由设置里的 git_mirror_quota_bytes 管着。

管理界面

页面 内容
首页 拉取助手:写下 redis:7 直接给出可执行的命令;站点命中率、已缓存体积、支持的上游
概览 请求量与命中率曲线、回源原因分布、上游健康矩阵、事件流、最近请求
上游 增删改、启停、选择包管理器 profile,实时查看 site_domain、transport、profile 与 companion 主机的就绪状态;改完下一个请求就生效
缓存对象 搜索、清理、锁定单个对象
git 镜像 已建成的仓库镜像:状态、体积、最后同步与最后访问时间,可删除单个镜像
设置 站点名片、首页是否公开、缓存配额与回收水位、回源并发/超时/重试、git 镜像配额与单仓上限、管理密钥轮换

访问规则分全局与上游内两层,同层内按具体度排序、首个匹配者决定结果; 保存前可以用规则测试器验证某个具体地址会被哪条规则决定。

配置的边界

configs/config.yaml 只放「进程起不来就没法从界面改的东西」:监听地址、 数据库 DSN、日志、缓存目录、初始管理密钥。配额、TTL、并发这些进程跑起来之后才 生效的参数一律落 setting 表,改完不用重启。

入库的只有 configs/config.yaml.example(出厂默认值 + 每一项为什么这么写的注释)。 实际读的 configs/config.yaml 从它拷一份,不入库——否则每个人改自己的密钥和 DSN 都会留下一片待提交的改动,真密钥被顺手带进历史只是时间问题。Docker 镜像里的那份 同样来自 .example。

管理密钥以 bcrypt 哈希存在库里,admin.initialKey 只在库中尚无密钥时落一次; 之后的轮换在界面上完成,改配置文件不会把已轮换的密钥覆盖回去。留空则不设密钥: 管理接口全量 401,拉取路径照常服务。

切 MySQL 只改 db 段的 driver 与 dsn。

开发命令

make test       # test-backend + test-frontend,唯一的测试入口
make lint       # golangci-lint v2 + eslint
make fmt        # golangci-lint fmt + prettier
make smoke      # 启动真实二进制验证基本行为(需先 make build)
make mock       # go generate ./...(mockgen)

make smoke 除了验启动路径,还守着扩展点那条边界:只经管理接口加一条上游记录, 就要能拉通并在第二次命中缓存,全程不改代码、不重启进程。

文档

About

镜像代理工具

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages