1ms-helper - 毫秒镜像配置助手

8 days ago
1beb0e7

项目概述

1ms-helper 是专为 毫秒镜像（1ms.run） 设计的跨平台命令行工具，旨在帮助开发者和运维人员快速、安全地配置容器镜像加速服务。通过自动化配置流程，让复杂的容器镜像加速设置变得简单易用。

核心价值

一键配置，开箱即用

传统的容器镜像加速配置需要手动编辑配置文件、重启服务、配置认证信息等多个步骤，容易出错且耗时。1ms-helper 将这些复杂操作整合为一条命令，实现：

  • ✅ 自动检测：智能识别系统环境和容器运行时
  • ✅ 智能配置：自动生成和更新配置文件
  • ✅ 无缝重启：安全重启相关服务，确保配置生效
  • ✅ 安全认证：简化镜像仓库账号认证流程

解决痛点

  • 🚫 告别手动编辑：无需手动修改 daemon.json、registries.conf 等配置文件
  • 🚫 避免配置错误：自动生成正确的配置格式，减少人为失误
  • 🚫 简化多环境配置：统一管理 Docker、Podman、K8s、K3s 等多种运行时
  • 🚫 解决网络问题：内置 DNS 诊断和修复功能

核心功能

1. 多容器运行时支持

Docker 支持

  • 一键配置：1ms-helper config:docker
  • 功能覆盖：
    • 自动配置 Docker daemon.json 镜像加速
    • 配置认证信息到 Docker credential helper
    • 支持 Docker Desktop（macOS/Windows）和 Docker Engine（Linux）
    • 智能检测 Docker v2 API 协议支持
  • 分步配置：
    • config:docker:mirror - 仅配置镜像加速
    • config:docker:account - 仅配置账号认证
    • remove:docker:mirror - 移除镜像配置
    • remove:docker:account - 移除账号认证

Podman 支持

  • 一键配置：1ms-helper config:podman
  • 功能覆盖：
    • 自动配置 registries.conf 文件
    • 支持系统级配置（/etc/containers/registries.conf）
    • 支持用户级配置（~/.config/containers/registries.conf）
    • 兼容 Podman Machine（macOS）
  • 分步配置：
    • config:podman:mirror - 仅配置镜像加速
    • config:podman:account - 仅配置账号认证
    • remove:podman:mirror - 移除镜像配置
    • remove:podman:account - 移除账号认证

Kubernetes（K8s）支持

  • 标准集群配置：1ms-helper config:k8s
  • 适用场景：
    • 使用 kubeadm 创建的标准 Kubernetes 集群
    • 需要配置镜像加速的 Control Plane 节点或 Worker 节点
    • 使用 Containerd 作为容器运行时的集群
  • 功能特性：
    • 自动检测 Kubernetes 集群和节点角色
    • 支持 Containerd 新版（>= 1.5）和旧版（< 1.5）配置格式
    • 优先配置 K8s 核心仓库（registry.k8s.io, k8s.gcr.io）
    • 可选择性配置其他云服务商镜像仓库
    • 智能重启服务（containerd 和 kubelet）
  • 注意事项：
    • 需要 root 权限执行
    • 多节点集群需要在每个节点上分别运行
    • Control Plane 节点重启服务可能短暂影响集群调度

K3s 支持

  • 轻量级集群配置：1ms-helper config:k3s
  • 适用场景：
    • K3s 轻量级 Kubernetes 集群
    • 边缘计算场景
    • 资源受限环境（IoT 设备、ARM 架构等）
  • 功能特性：
    • 自动检测 K3s 节点类型（Server/Agent）
    • 生成 /etc/rancher/k3s/registries.yaml 配置文件
    • 支持免费和付费镜像仓库配置
    • 自动重启 K3s 服务使配置生效

2. 智能配置管理

配置文件自动化

  • Docker 配置：

    • 自动备份现有 daemon.json
    • 智能合并现有配置和新配置
    • 配置 registry-mirrors 字段
    • 保留其他自定义配置项

  • Podman/K3s 配置：

    • 自动创建 registries.conf / registries.yaml
    • 配置 mirror 和 credential helper
    • 支持多镜像仓库同时配置

权限管理

  • 自动提权：
    • Linux：自动使用 sudo 提升权限
    • macOS：提示使用管理员权限
    • Windows：检测并请求管理员权限
  • 安全提示：
    • 显示免责声明，要求用户确认
    • 提供源代码审计地址
    • 透明展示所有操作步骤

3. 环境诊断与修复

连接检查

  • 命令：1ms-helper check
  • 检查项目：
    • 毫秒镜像服务连通性
    • 认证状态验证
    • 配置文件完整性
    • Docker/Podman 服务状态

DNS 诊断与修复

  • 命令：1ms-helper check:dns
  • 诊断功能：
    • 检查 Docker daemon.json 中的 DNS 配置
    • 测试 DNS 服务器连通性
    • 验证 Docker 相关域名解析能力
    • 检测常见 DNS 问题（如内网 DNS 不可达）
  • 自动修复：
    • 智能检测 DNS 问题类型
    • 自动配置可用的公共 DNS 服务器（如 8.8.8.8, 114.114.114.114）
    • 优化现有 DNS 配置
    • 提供详细的修复建议和步骤

4. 账号与认证管理

安全登录

  • 支持毫秒镜像账号配置
  • 使用系统 credential helper 安全存储凭证
  • Docker：使用 docker-credential-helper
  • Podman：配置到 auth.json
  • 支持多账号切换

认证配置

  • 自动配置私有仓库认证
  • 支持 Token 和密码认证
  • 安全的凭证存储机制

5. 交互式配置模式

智能引导

  • 命令：1ms-helper config
  • 功能：
    • 自动检测系统中安装的容器运行时
    • 提供友好的菜单选择界面
    • 根据选择自动执行相应配置
    • 适合不熟悉命令行的用户

用户体验优化

  • 彩色终端输出，清晰展示操作进度
  • 每步操作都有详细说明
  • 错误提示友好，提供解决方案
  • 支持配置回滚（通过 remove 命令）

支持的镜像仓库

1ms-helper 支持配置以下主流容器镜像仓库的加速：

仓库名称 原始地址 毫秒镜像加速地址 支持状态
Docker Hub docker.io docker.1ms.run ✅ 完全支持
GitHub Container Registry ghcr.io ghcr.1ms.run ✅ 完全支持
Google Container Registry gcr.io gcr.1ms.run ✅ 完全支持
NVIDIA Container Registry nvcr.io nvcr.1ms.run ✅ 完全支持
Red Hat Quay quay.io quay.1ms.run ✅ 完全支持
Elastic Docker Registry docker.elastic.co elastic.1ms.run ✅ 完全支持
Microsoft Container Registry mcr.microsoft.com mcr.1ms.run ✅ 完全支持
Kubernetes Container Registry registry.k8s.io k8s.1ms.run ✅ 完全支持

平台支持

完全支持的操作系统

Linux

  • 发行版：Ubuntu, Debian, CentOS, RHEL, Fedora, Arch Linux 等
  • 架构：x86_64 (amd64), ARM64 (aarch64)
  • 容器运行时：Docker, Podman, Containerd (K8s/K3s)
  • 安装方式：
    curl -sSL https://static.1ms.run/1ms-helper/install.sh | bash

macOS

  • 版本支持：macOS 10.15+ (Catalina 及更高版本)
  • 架构：Intel (x86_64) 和 Apple Silicon (ARM64)
  • 容器运行时：Docker Desktop, Podman Machine
  • 安装方式：
    curl -sSL https://static.1ms.run/1ms-helper/install.sh | bash

Windows

  • 版本支持：Windows 10/11, Windows Server 2019/2022
  • 架构：x86_64 (amd64), ARM64
  • 容器运行时：Docker Desktop, Podman
  • 安装方式：
    # 以管理员身份运行 PowerShell
irm https://static.1ms.run/1ms-helper/install.ps1 | iex

特殊平台支持

群晖 NAS (Synology DSM)

  • 检测支持：自动识别群晖系统环境
  • 当前状态：
    • ✅ 支持系统检测和环境识别
    • ⚠️ 暂不支持自动配置（由于群晖系统特殊性）
    • 📖 提供详细的手动配置文档引导
  • 使用方式：

技术亮点

单一二进制文件

  • 无依赖部署：基于 Go 语言开发，编译为单一可执行文件
  • 即下即用：无需安装运行时或依赖库
  • 体积小巧：二进制文件体积小，下载和分发快速

智能权限提升

  • 自动检测权限：运行时自动检测是否需要管理员权限
  • 友好提权提示：清晰说明需要提权的原因
  • 安全执行：仅在必要时请求权限，操作透明可审计

跨平台兼容性

  • 统一命令接口：所有平台使用相同的命令行接口
  • 平台自适应：自动适配不同操作系统的配置路径和服务管理方式
  • 架构支持广泛：支持 x86_64、ARM64 等主流架构

配置安全性

  • 备份机制：修改配置前自动备份原始文件
  • 回滚支持：提供 remove 命令快速移除配置
  • 配置验证：应用配置前验证格式正确性
  • 服务平滑重启：智能重启相关服务，最小化停机时间

开源透明

  • 源代码公开：完全开源，可审计安全性
  • 仓库地址：https://cnb.cool/mliev/1ms.run/1ms-helper
  • 免责声明：运行前显示免责声明，用户知情同意
  • 社区支持：接受 Issue 和 Pull Request

使用场景

场景一：开发者本地环境配置

目标用户：使用 Docker Desktop 或 Podman 的本地开发者

痛点：

  • 拉取 Docker Hub 镜像速度慢，影响开发效率
  • 访问 GitHub Container Registry、Google Container Registry 等国外仓库困难
  • 手动配置镜像加速复杂且容易出错

解决方案：

# Docker 用户
1ms-helper config:docker

# Podman 用户
1ms-helper config:podman

效果：

  • ⚡ 镜像拉取速度从分钟级提升到秒级
  • 🌍 可以顺畅访问各大国外镜像仓库
  • 🔄 配置一次，长期受益

场景二：Kubernetes 集群初始化

目标用户：运维工程师、DevOps 团队

痛点：

  • 使用 kubeadm 初始化集群时需要拉取大量镜像
  • registry.k8s.io 和 gcr.io 访问不稳定
  • 多节点集群需要逐个配置镜像加速

解决方案：

# 在每个集群节点上执行
sudo 1ms-helper config:k8s

效果：

  • 🚀 集群初始化时间大幅缩短
  • 📦 系统镜像、组件镜像快速拉取
  • 🔧 节点扩容时自动享受加速效果

场景三：K3s 边缘计算部署

目标用户：边缘计算场景、IoT 开发者

痛点：

  • 边缘节点网络带宽受限
  • K3s 镜像拉取耗时长，影响服务启动
  • 手动配置 registries.yaml 易出错

解决方案：

sudo 1ms-helper config:k3s

效果：

  • 💨 边缘节点快速完成镜像拉取
  • 🏭 适合大规模边缘节点部署
  • 🔌 低带宽环境也能流畅使用

场景四：网络问题诊断与修复

目标用户：遇到 Docker 网络或 DNS 问题的用户

痛点：

  • Docker 容器内无法访问外网
  • DNS 解析失败导致镜像拉取失败
  • 不清楚如何排查和修复 DNS 问题

解决方案：

# 诊断并自动修复 DNS 问题
1ms-helper check:dns

# 检查整体连接状态
1ms-helper check

效果：

  • 🔍 快速定位 DNS 配置问题
  • 🛠️ 自动修复常见 DNS 故障
  • ✅ 验证配置是否生效

场景五：多环境统一管理

目标用户：管理多种容器运行时的团队

痛点：

  • 团队内同时使用 Docker、Podman、K8s、K3s
  • 不同运行时配置方式各异
  • 难以统一管理和维护

解决方案：

# 使用交互式模式，自动检测环境
1ms-helper config

# 或针对具体运行时配置
1ms-helper config:docker    # 配置 Docker
1ms-helper config:podman    # 配置 Podman
1ms-helper config:k8s       # 配置 K8s
1ms-helper config:k3s       # 配置 K3s

效果：

  • 🎯 统一的配置体验
  • 📋 标准化的运维流程
  • 👥 降低团队学习成本

快速开始

安装

选择适合您系统的安装方式：

Linux/macOS:

curl -sSL https://static.1ms.run/1ms-helper/install.sh | bash

Windows PowerShell (管理员):

irm https://static.1ms.run/1ms-helper/install.ps1 | iex

第一次使用

# 1. 检查连接状态
1ms-helper check

# 2. 一键配置（推荐新用户）
1ms-helper config:docker    # Docker 用户
1ms-helper config:podman    # Podman 用户
1ms-helper config:k8s       # K8s 集群
1ms-helper config:k3s       # K3s 集群

# 3. 验证配置
docker pull nginx           # Docker 用户测试
podman pull nginx           # Podman 用户测试

常用命令速查

功能 命令 说明
交互式配置 1ms-helper config 自动检测环境，引导配置
Docker 一键配置 1ms-helper config:docker 配置 Docker 镜像加速和账号
Podman 一键配置 1ms-helper config:podman 配置 Podman 镜像加速和账号
K8s 配置 1ms-helper config:k8s 配置 Kubernetes 集群
K3s 配置 1ms-helper config:k3s 配置 K3s 集群
连接检查 1ms-helper check 检查毫秒镜像连接状态
DNS 诊断 1ms-helper check:dns 检查和修复 DNS 问题
移除 Docker 配置 1ms-helper remove:docker:mirror 移除 Docker 镜像配置
移除 Podman 配置 1ms-helper remove:podman:mirror 移除 Podman 镜像配置
查看帮助 1ms-helper --help 显示所有可用命令

获取支持

如果您在使用过程中遇到问题或有任何建议，欢迎通过以下方式联系我们：

总结

1ms-helper 是一款功能强大、易用性强的容器镜像加速配置工具，具有以下核心优势：

✨ 一键配置：将复杂的镜像加速配置简化为一条命令
🌍 广泛支持：覆盖 Docker、Podman、K8s、K3s 等主流容器运行时
🖥️ 跨平台：支持 Linux、macOS、Windows 三大操作系统
🛡️ 安全可靠：开源透明，自动备份，支持回滚
⚡ 性能卓越：显著提升镜像拉取速度，优化开发和部署效率
🔧 智能诊断：内置网络和 DNS 诊断工具，快速解决常见问题

无论您是本地开发者、运维工程师，还是管理大规模容器集群的团队，1ms-helper 都能帮助您快速配置毫秒镜像加速服务，享受丝滑流畅的容器镜像拉取体验！

立即开始使用： https://1ms.run
获取工具： 下载 1ms-helper