Release v1

.codelf/_changelog.md

@@ -0,0 +1,58 @@
+## 2024-12-19 16:00:00
+
+### 1. 优化 GitHub Actions 工作流，支持自动触发和默认配置
+
+**Change Type**: feature
+
+> **Purpose**: 优化镜像同步工作流，实现 images.txt 文件变更时自动触发，并提供更好的用户体验
+> **Detailed Description**: 
+> 1. 添加了智能配置系统，支持自动触发时使用默认配置，手动触发时使用自定义参数
+> 2. 改进了镜像列表读取逻辑，支持注释行和空行过滤
+> 3. 增强了镜像处理流程，提供详细的步骤日志和错误处理
+> 4. 优化了结果统计和状态反馈机制
+> 5. 更新了 images.txt 文件格式，添加了详细的使用说明和示例
+> 6. 重写了 README.md，提供更清晰的使用指南和功能介绍
+> **Reason for Change**: 用户反馈希望 images.txt 文件变更时能自动触发镜像同步，提高使用便利性
+> **Impact Scope**: 影响整个工作流的执行逻辑，但保持向后兼容性
+> **API Changes**: 工作流输入参数保持不变，新增环境变量支持
+> **Configuration Changes**: 
+> - 工作流新增默认配置逻辑
+> - images.txt 文件格式优化，支持注释和示例
+> - README.md 完全重写
+> **Performance Impact**: 提高了工作流的健壮性和用户体验，无负面性能影响
+
+   ```
+   root
+   - .github/workflows/
+     - docker-pull.yml    // refact - 重构工作流，支持自动触发和智能配置
+   - images.txt           // refact - 优化格式，添加注释和使用说明
+   - README.md            // refact - 完全重写，提供详细的使用指南
+   ```
+
+## 2024-12-19 15:30:00
+
+### 1. 初始化 .codelf 项目文档目录
+
+**Change Type**: docs
+
+> **Purpose**: 为 Docker 镜像拉取推送项目建立完整的项目文档体系
+> **Detailed Description**: 创建了 .codelf 目录并初始化了三个核心文档文件：project.md（项目概述）、attention.md（开发指南）、_changelog.md（变更日志）。详细分析了项目结构、技术栈、开发规范和安全要求。
+> **Reason for Change**: 项目缺乏系统性的文档，需要建立标准化的项目信息管理体系，便于后续开发和维护
+> **Impact Scope**: 不影响现有功能，仅增加文档支持
+> **API Changes**: 无 API 变更
+> **Configuration Changes**: 新增 .codelf 目录及相关 markdown 文件
+> **Performance Impact**: 无性能影响，仅为文档变更
+
+   ```
+   root
+   - .codelf/           // add - 项目文档目录
+     - project.md       // add - 项目概述和结构说明
+     - attention.md     // add - 开发指南和最佳实践
+     - _changelog.md    // add - 变更日志记录
+   - .github/           // - GitHub Actions 配置目录
+     - workflows/       // - 工作流定义目录
+       - docker-pull.yml // - 镜像拉取推送主工作流
+   - .gitignore         // - Git 忽略文件配置
+   - README.md          // - 项目使用说明
+   - images.txt         // - 镜像列表配置文件
+   ```

.codelf/attention.md

@@ -0,0 +1,116 @@
+## Development Guidelines
+
+### Framework and Language
+> 本项目主要基于 GitHub Actions 和 Shell 脚本，专注于 Docker 镜像同步的自动化流程。
+
+**GitHub Actions 框架考虑：**
+- 版本兼容性：使用稳定版本的 Actions（如 actions/checkout@v2），避免使用过新的版本导致兼容性问题
+- 功能利用：充分利用 GitHub Actions 的工作流特性，如手动触发、文件变更触发等
+- 性能模式：合理使用 continue-on-error 确保工作流的健壮性
+- 升级策略：定期检查 Actions 版本更新，但要确保向后兼容性
+- 框架重要注意事项：
+	* GitHub Actions 有运行时间限制，大量镜像同步需要考虑分批处理
+	* Secrets 管理要严格，避免密码泄露
+	* 网络连接稳定性影响镜像拉取成功率
+
+**Shell 脚本最佳实践：**
+- 错误处理：使用适当的错误检查和 continue-on-error 机制
+- 变量安全：正确处理包含特殊字符的镜像名称和标签
+- 日志输出：提供清晰的执行状态反馈
+- 脚本可读性：使用有意义的变量名和注释
+
+### Code Abstraction and Reusability
+> 本项目虽然结构简单，但在 GitHub Actions 工作流设计上体现了良好的模块化思想。优先使用现有的 Actions 组件而不是重新发明轮子。
+> 当前项目的组件结构和功能模块划分如下：
+
+
+**模块化设计原则：**
+- 单一职责：每个步骤只负责一个特定功能（检出代码、登录、拉取推送等）
+- 高内聚低耦合：相关操作集中在同一个 job 中，减少步骤间的依赖
+- 稳定接口：使用标准的 GitHub Actions 输入输出接口
+
+**可复用组件结构：**
+```
+root
+- .github/workflows/
+    - docker-pull.yml     // 主工作流，包含以下可复用模块：
+        - 代码检出模块     // 使用 actions/checkout@v2
+        - 镜像列表读取模块  // 读取并解析 images.txt 文件
+        - Docker 登录模块  // 处理各种镜像仓库的登录认证
+        - 镜像处理模块     // 拉取、标记、推送的核心逻辑
+        - 错误处理模块     // 统一的成功/失败状态检查
+- images.txt             // 配置文件，支持批量镜像定义
+- README.md             // 使用说明，可作为模板复用到其他类似项目
+```
+
+### Coding Standards and Tools
+**GitHub Actions 工作流规范：**
+- YAML 格式规范：使用一致的缩进（2个空格）和结构
+- 命名规范：使用中文名称提高可读性（如 "拉取镜像推送"）
+- 步骤命名：使用描述性的中文名称（如 "检出代码库"、"登录到 Docker 仓库"）
+
+**Shell 脚本编码规范：**
+- 变量命名：使用大写字母和下划线（如 TARGET_REGISTRY）
+- 错误处理：每个关键操作都要有相应的错误检查
+- 日志输出：提供清晰的中文状态信息
+
+**配置文件规范：**
+- images.txt：每行一个镜像，格式为 image:tag
+- 注释规范：在 YAML 文件中使用适当的注释说明复杂逻辑
+- 目录结构：遵循 GitHub Actions 标准目录结构
+
+### 镜像同步协作标准
+**镜像仓库集成规范：**
+- 支持多种镜像仓库
+	* Docker Hub、阿里云、腾讯云等主流镜像仓库
+	* 统一的登录认证机制
+	* 标准化的镜像命名和标签处理
+- 及时的状态反馈
+	* 登录成功/失败状态检查
+	* 镜像推送成功/失败状态检查
+	* 详细的错误信息输出
+- 统一的错误处理规范
+	* 使用 continue-on-error 确保工作流健壮性
+	* 提供清晰的中文错误信息
+
+**数据流处理：**
+- 清晰的镜像列表管理
+	* 从 images.txt 文件读取镜像列表
+	* 支持批量处理多个镜像
+	* 自动解析镜像名称和标签
+- 镜像数据验证
+	* 验证镜像名称格式的正确性
+	* 检查目标仓库的可访问性
+	* 确保架构参数的有效性
+- 标准化的异步操作处理
+	* 使用 GitHub Actions 的并发控制
+	* 合理的超时设置和重试机制
+
+### Performance and Security
+**性能优化重点：**
+- 镜像传输优化
+	* 使用多架构支持减少不必要的镜像拉取
+	* 合理设置并发数量避免网络拥塞
+	* 利用 Docker 层缓存机制提高效率
+- 工作流执行优化
+	* 使用 continue-on-error 避免单个镜像失败影响整体流程
+	* 合理的超时设置防止长时间等待
+	* 批量处理镜像减少工作流启动开销
+- 适当的缓存策略
+	* 利用 GitHub Actions 的缓存机制
+	* Docker 镜像层的本地缓存利用
+	* 避免重复拉取相同的基础镜像
+
+**安全措施：**
+- 输入验证和过滤
+	* 验证镜像名称和标签的格式正确性
+	* 防止恶意镜像名称注入
+	* 检查目标仓库地址的合法性
+- 敏感信息保护
+	* 使用 GitHub Secrets 安全存储仓库凭据
+	* 避免在日志中暴露密码和令牌
+	* 定期轮换仓库访问凭据
+- 访问控制机制
+	* 限制工作流的手动触发权限
+	* 使用最小权限原则配置仓库访问
+	* 监控异常的镜像同步活动

.codelf/project.md

@@ -0,0 +1,64 @@
+## Docker 镜像拉取推送工具 (Docker Image Pull & Push Tool)
+
+> 一个基于 GitHub Actions 的 Docker 镜像拉取和推送自动化工具，支持从任意镜像仓库拉取镜像并推送到目标仓库
+
+> 项目目的：解决 Docker 镜像在不同仓库间同步的问题，特别是从国外镜像仓库同步到国内镜像仓库，提高镜像拉取速度和可用性
+
+> 项目状态：活跃开发中，支持多架构镜像同步
+
+> 项目团队：个人开源项目
+
+> 技术栈：GitHub Actions、Docker、Shell 脚本、YAML 配置
+
+
+
+## Dependencies (GitHub Actions 和 Docker 依赖)
+
+* actions/checkout@v2: GitHub Actions 官方代码检出动作
+* Docker Engine: 容器运行时环境，用于镜像拉取、标记和推送操作
+* Ubuntu Latest Runner: GitHub Actions 运行环境
+
+
+## Development Environment
+
+> 开发和运行环境要求
+
+**必需环境：**
+- GitHub 账号和仓库
+- Docker 仓库账号（如 Docker Hub、阿里云、腾讯云等）
+- 网络连接（能够访问源镜像仓库和目标镜像仓库）
+
+**配置要求：**
+- 在 GitHub 仓库的 Settings -> Secrets and variables -> Actions 中配置：
+  - DOCKER_USERNAME: Docker 仓库用户名
+  - DOCKER_PASSWORD: Docker 仓库密码
+
+**运行方式：**
+- 手动触发：在 Actions 页面点击 "Run workflow"
+- 自动触发：当 images.txt 文件发生变化时自动运行
+
+
+## Structure (项目结构详细分析)
+
+> 项目结构简洁明了，主要包含 GitHub Actions 工作流配置和镜像列表文件
+
+```
+root
+- .github/                          # GitHub 特定配置目录
+    - workflows/                     # GitHub Actions 工作流目录
+        - docker-pull.yml           # 【核心文件】主要的镜像拉取推送工作流
+                                     # 功能：定义完整的镜像同步流程
+                                     # 支持多架构：amd64, arm64, arm/v7, arm/v6, 386, s390x, ppc64le
+                                     # 工作流程：检出代码 -> 读取镜像列表 -> 登录仓库 -> 拉取标记推送镜像
+                                     # 输入参数：镜像文件路径、目标仓库地址、空间名称、系统架构
+                                     # 错误处理：包含登录失败和推送失败的检查机制
+- .gitignore                        # Git 忽略文件配置
+- README.md                         # 【重要文件】项目说明文档
+                                     # 包含详细的使用方法和配置步骤
+                                     # 说明如何 Fork 项目、配置密钥、运行工作流
+                                     # 提供了完整的操作示例和注意事项
+- images.txt                        # 【核心文件】镜像列表配置文件
+                                     # 格式：每行一个镜像，格式为 image:tag
+                                     # 当前包含：goharbor/harbor-portal:v2.12.1, goharbor/harbor-core:v2.12.1
+                                     # 文件变更会自动触发工作流执行
+```