Arcane 私有镜像仓库:一键搭建和管理你自己的 Docker Registry
Arcane 私有镜像仓库:一键搭建和管理你自己的 Docker Registry
Arcane 是一款现代 Docker 管理工具(Modern Docker Management, Designed for Everyone),内置了完整的私有镜像仓库(Docker Registry)管理功能:你可以把 Docker Hub、GHCR、Quay、自建 Registry 等镜像源以"凭证中心"的方式集中接入,实现一键添加、连接测试、凭证加密存储、仓库与 Tag 浏览、拉取用量监控,无需在每台机器上手动执行 docker login。
为什么需要集中管理 Docker Registry 凭证?
如果你管理过多台服务器或团队项目,大概率遇到过这些场景:
- 🐳 每台新机器都要手动
docker login,密码/Token 散落各处; - 镜像拉取被限流(Docker Hub 匿名拉取限流),却不知道剩余额度;
- 私有仓库的镜像 Tag 越积越多,清理时只能去 Web 页面逐个删;
- 自建私有仓库用的是 HTTP 而非 HTTPS,客户端到处配置
insecure-registries。
Arcane 的 Registry 模块把这些痛点收敛到一个页面:配置一次,全环境生效,并且凭证在数据库中加密存储,API 返回时只写不读(write-only),避免 Token 泄露。
Registry 管理入口在哪里?
在 Arcane 界面中,Registry 功能位于 Images(镜像)→ Registries 页面:
- 前端页面实现:frontend/src/routes/(app)/images/registries/+page.svelte/images/registries/+page.svelte#L149-L158)
- 详情页(仓库/Tag 浏览):frontend/src/routes/(app)/images/registries/[id]/+page.svelte
页面上直接提供"添加 Registry"、"刷新"、"Registry 信息"(常见公共仓库地址速查:docker.io、ghcr.io、gcr.io、quay.io)等操作按钮,空状态下也有引导入口,新手不会迷路。
三步添加一个私有镜像仓库
📌 点击 Add Registry 后会打开表单(container-registry-sheet.svelte),只需填写:
| 字段 | 说明 |
|---|---|
Registry URL |
如 registry.example.com;留空或填 docker.io 表示 Docker Hub |
Username / Token |
用户名与密码(或 Personal Access Token) |
Insecure |
允许 HTTP(非 TLS)连接,适合内网自建仓库 |
Enabled |
是否启用该仓库参与认证 |
Repository Names |
可选,指定关注的具体仓库名(每行一个) |
保存后,Arcane 会自动用保存的凭证完成登录校验,并在集群多环境(Agents)之间同步配置。
核心逻辑见 backend/internal/registry/service.go:校验 URL 必填、Token 使用 crypto.Encrypt 加密后落库,绝不明文保存。
支持两种 Registry 类型:Generic 与 AWS ECR
Arcane 支持两种类型(types/containerregistry.go):
- Generic (Docker / OCI):适用于 Docker Hub、GHCR、Quay、Harbor 等绝大多数仓库,填用户名 + Token 即可;
- Amazon ECR:只需填 ECR 端点地址和
AWS Region,可选填 Access Key 对;Arcane 会自动生成并自动刷新 ECR 临时令牌(TTL 11 小时,见 ecrTokenTTL 常量),你不需要关心令牌过期问题。
一键"Test":连接与认证连通性测试
每条 Registry 记录都可以执行 test 动作:
- 前端点击后调用
POST /registries/{id}?action=test,路由定义在 backend/internal/registry/module.go; - 后端通过 Docker 守护进程执行
RegistryLogin真实登录验证,ECR 类型则先换取临时令牌再验证(TestRegistry / TestECRRegistry); - 测试失败会返回明确的错误信息(如
Registry test failed: ...),方便排查网络或凭证问题。
💡 提示:GitHub 仓库使用 Personal Access Token 作为密码;Docker Hub 私有仓库必须提供凭证。这些提示内置在页面的 "Registry Information" 弹窗里。
浏览仓库与 Tag,支持批量删除
进入某个 Registry 的详情页后,Arcane 会:
- 列出仓库(Repositories):分页、可搜索;
- 列出 Tag:展示每个 Tag 的大小、创建时间、多平台信息(os/architecture,多架构镜像一目了然);
- 删除 Tag:支持单个删除和批量勾选删除,带二次确认,避免误删。
浏览与删除的 API 实现位于 backend/internal/registry/children/browse/handler.go。
拉取用量统计:谁在消耗你的配额?
很多团队不知道 Docker Hub 限流还剩多少。Arcane 会:
- 自动统计本机观察到的拉取次数(
observedPulls,每次拉镜像时计数,见 RecordImagePull); - 对启用的 Docker Hub 凭证探测速率限制(limit / remaining / used / 窗口时长),结果缓存 30 分钟避免频繁请求。
实现见 GetRegistryPullUsage,界面上直接以徽标展示剩余配额,限流风险提前可见。
用 CLI 管理 Registry:CI/CD 友好
除了 Web 界面,Arcane 还提供 arcane registries 命令组(别名 registry / reg),支持 list、get、create、test、update、delete、usage 等子命令,方便脚本化运维:
- CLI 实现:cli/pkg/registries/cmd.go
- 示例:
arcane registries list可表格化输出 ID、URL、USERNAME、ENABLED、INSECURE 列。
超时与性能优化
Registry 网络操作默认超时 30 秒,Tag 全量列举默认 120 秒,均可在 Settings 中调整:
- 配置定义:backend/internal/settings/model.go
- Digest 查询带 30 分钟缓存 + 失败退避重试(500ms 起步、指数退避、最多 5 次),遇限流自动按
Retry-After等待,详见 InspectImageDigest。
关键源码文件导航
| 模块 | 路径 |
|---|---|
| 后端服务(CRUD/测试/用量) | backend/internal/registry/service.go |
| REST API 路由 | backend/internal/registry/module.go |
| 仓库/Tag 浏览 | backend/internal/registry/children/browse/ |
| 数据模型 | types/containerregistry.go |
| 前端列表页 | frontend/src/routes/(app)/images/registries/+page.svelte/images/registries/+page.svelte) |
| CLI 命令 | cli/pkg/registries/cmd.go |
小结
Arcane 把"私有镜像仓库管理"做成了开箱即用的能力:添加仓库三步完成、连接一键测试、凭证加密存储、Tag 可视化清理、拉取配额透明可见,再配合 ECR 免密自动刷新与 CLI 支持,个人玩家和团队都能快速建立起自己的 Docker Registry 管理体系。打开 Arcane 的 Images → Registries 页面,今天就添加你的第一个私有仓库吧 🚀
