kdeploy 1.2.5 → 1.2.7

data/README.md

@@ -8,147 +8,149 @@
 \/  \/\__,_|\___| .__/|_|\___/ \__, |
                 |_|            |___/
 
-⚡ Lightweight Agentless Deployment Tool
-🚀 Deploy with confidence, scale with ease
+⚡ 轻量级无代理部署工具
+🚀 自信部署，轻松扩展
 ```
 
-A lightweight, agentless deployment automation tool written in Ruby. Kdeploy enables you to deploy applications, manage configurations, and execute tasks across multiple servers using SSH, without requiring any agents or daemons on target machines.
+一个用 Ruby 编写的轻量级、无代理的部署自动化工具。Kdeploy 使您能够使用 SSH 在多个服务器上部署应用程序、管理配置和执行任务，而无需在目标机器上安装任何代理或守护进程。
 
 [![Gem Version](https://img.shields.io/gem/v/kdeploy)](https://rubygems.org/gems/kdeploy)
 [![Ruby](https://github.com/kevin197011/kdeploy/actions/workflows/gem-push.yml/badge.svg)](https://github.com/kevin197011/kdeploy/actions/workflows/gem-push.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Table of Contents
-
-- [Features](#-features)
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [Usage Guide](#-usage-guide)
-- [Configuration](#-configuration)
-- [Advanced Usage](#-advanced-usage)
-- [Error Handling](#-error-handling)
-- [Best Practices](#-best-practices)
-- [Troubleshooting](#-troubleshooting)
-- [Architecture](#-architecture)
-- [Development](#-development)
-- [Contributing](#-contributing)
-- [License](#-license)
-
-## 🌟 Features
-
-### Core Features
-
-- 🔑 **Agentless Remote Deployment**: Uses SSH for secure remote execution, no agents required
-- 📝 **Elegant Ruby DSL**: Simple and expressive task definition syntax
-- 🚀 **Concurrent Execution**: Efficient parallel task processing across multiple hosts
-- 📤 **File Upload Support**: Easy file and template deployment via SCP
-- 📊 **Task Status Tracking**: Real-time execution monitoring with detailed output
-- 🔄 **ERB Template Support**: Dynamic configuration generation with variable substitution
-- 🎯 **Role-based Deployment**: Target specific server roles for organized deployments
-- 🔍 **Dry Run Mode**: Preview tasks before execution without making changes
-- 🎨 **Color-coded Output**: Intuitive color scheme (Green: success, Red: errors, Yellow: warnings)
-- ⚙️ **Flexible Host Targeting**: Execute tasks on specific hosts, roles, or all hosts
-- 🔐 **Multiple Authentication Methods**: Support for SSH keys and password authentication
-- 📈 **Execution Time Tracking**: Monitor task execution duration for performance analysis
-
-### Technical Features
-
-- **Thread-safe Execution**: Built on `concurrent-ruby` for reliable parallel processing
-- **Custom Error Handling**: Detailed error types for better debugging
-- **Configuration Management**: Centralized configuration with sensible defaults
-- **Extensible Architecture**: Modular design for easy extension
-- **Shell Completion**: Auto-completion support for Bash and Zsh
-
-## 📦 Installation
-
-### Requirements
+**语言**: [English](README_EN.md) | [中文](README.md)
+
+## 目录
+
+- [功能特性](#-功能特性)
+- [安装](#-安装)
+- [快速开始](#-快速开始)
+- [使用指南](#-使用指南)
+- [配置](#-配置)
+- [高级用法](#-高级用法)
+- [错误处理](#-错误处理)
+- [最佳实践](#-最佳实践)
+- [故障排除](#-故障排除)
+- [架构](#-架构)
+- [开发](#-开发)
+- [贡献](#-贡献)
+- [许可证](#-许可证)
+
+## 🌟 功能特性
+
+### 核心功能
+
+- 🔑 **无代理远程部署**: 使用 SSH 进行安全的远程执行，无需安装代理
+- 📝 **优雅的 Ruby DSL**: 简单而富有表现力的任务定义语法
+- 🚀 **并发执行**: 跨多个主机的高效并行任务处理
+- 📤 **文件上传支持**: 通过 SCP 轻松部署文件和模板
+- 📊 **任务状态跟踪**: 实时执行监控，提供详细输出
+- 🔄 **ERB 模板支持**: 支持变量替换的动态配置生成
+- 🎯 **基于角色的部署**: 针对特定服务器角色进行有组织的部署
+- 🔍 **试运行模式**: 在执行前预览任务，不进行实际更改
+- 🎨 **彩色输出**: 直观的颜色方案（绿色：成功，红色：错误，黄色：警告）
+- ⚙️ **灵活的主机定位**: 在特定主机、角色或所有主机上执行任务
+- 🔐 **多种身份验证方法**: 支持 SSH 密钥和密码身份验证
+- 📈 **执行时间跟踪**: 监控任务执行持续时间以进行性能分析
+
+### 技术特性
+
+- **线程安全执行**: 基于 `concurrent-ruby` 实现可靠的并行处理
+- **自定义错误处理**: 详细的错误类型，便于调试
+- **配置管理**: 集中式配置，提供合理的默认值
+- **可扩展架构**: 模块化设计，易于扩展
+- **Shell 自动补全**: 支持 Bash 和 Zsh 的自动补全
+
+## 📦 安装
+
+### 要求
 
 - Ruby >= 2.7.0
-- SSH access to target servers
-- SSH keys or password authentication configured
+- 对目标服务器的 SSH 访问权限
+- 已配置 SSH 密钥或密码身份验证
 
-### Install via RubyGems
+### 通过 RubyGems 安装
 
 ```bash
 gem install kdeploy
 ```
 
-### Install via Bundler
+### 通过 Bundler 安装
 
-Add this line to your application's `Gemfile`:
+将以下行添加到应用程序的 `Gemfile` 中：
 
 ```ruby
 gem 'kdeploy'
 ```
 
-And then execute:
+然后执行：
 
 ```bash
 bundle install
 ```
 
-### Verify Installation
+### 验证安装
 
 ```bash
 kdeploy version
 ```
 
-You should see the version information and banner.
+您应该看到版本信息和横幅。
 
-### Shell Completion
+### Shell 自动补全
 
-Kdeploy automatically configures shell completion during installation. If needed, manually add to your shell config:
+Kdeploy 在安装期间自动配置 shell 自动补全。如果需要，可以手动添加到 shell 配置中：
 
-**For Bash** (`~/.bashrc`):
+**对于 Bash** (`~/.bashrc`):
 ```bash
 source "$(gem contents kdeploy | grep kdeploy.bash)"
 ```
 
-**For Zsh** (`~/.zshrc`):
+**对于 Zsh** (`~/.zshrc`):
 ```bash
 source "$(gem contents kdeploy | grep kdeploy.zsh)"
 autoload -Uz compinit && compinit
 ```
 
-After adding the configuration:
-1. For Bash: `source ~/.bashrc`
-2. For Zsh: `source ~/.zshrc`
+添加配置后：
+1. 对于 Bash: `source ~/.bashrc`
+2. 对于 Zsh: `source ~/.zshrc`
 
-Now you can use Tab completion for:
-- Commands: `kdeploy [TAB]`
-- File paths: `kdeploy execute [TAB]`
-- Options: `kdeploy execute deploy.rb [TAB]`
+现在您可以使用 Tab 补全：
+- 命令: `kdeploy [TAB]`
+- 文件路径: `kdeploy execute [TAB]`
+- 选项: `kdeploy execute deploy.rb [TAB]`
 
-## 🚀 Quick Start
+## 🚀 快速开始
 
-### 1. Initialize a New Project
+### 1. 初始化新项目
 
 ```bash
 kdeploy init my-deployment
 ```
 
-This creates a new directory with:
-- `deploy.rb` - Main deployment configuration file
-- `config/` - Directory for configuration files and templates
-- `README.md` - Project documentation
+这将创建一个新目录，包含：
+- `deploy.rb` - 主部署配置文件
+- `config/` - 配置文件和模板目录
+- `README.md` - 项目文档
 
-### 2. Configure Hosts and Tasks
+### 2. 配置主机和任务
 
-Edit `deploy.rb`:
+编辑 `deploy.rb`:
 
 ```ruby
-# Define hosts
+# 定义主机
 host "web01", user: "ubuntu", ip: "10.0.0.1", key: "~/.ssh/id_rsa"
 host "web02", user: "ubuntu", ip: "10.0.0.2", key: "~/.ssh/id_rsa"
 
-# Define roles
+# 定义角色
 role :web, %w[web01 web02]
 
-# Define deployment task
+# 定义部署任务
 task :deploy, roles: :web do
   run <<~SHELL
     sudo systemctl stop nginx
-    echo "Deploying application..."
+    echo "正在部署应用程序..."
   SHELL
 
   upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
@@ -159,64 +161,64 @@ task :deploy, roles: :web do
 end
 ```
 
-### 3. Run Deployment
+### 3. 运行部署
 
 ```bash
 kdeploy execute deploy.rb deploy
 ```
 
-## 📖 Usage Guide
+## 📖 使用指南
 
-### Command Reference
+### 命令参考
 
 #### `kdeploy init [DIR]`
 
-Initialize a new deployment project.
+初始化新的部署项目。
 
 ```bash
-# Initialize in current directory
+# 在当前目录初始化
 kdeploy init .
 
-# Initialize in named directory
+# 在指定目录初始化
 kdeploy init my-deployment
 ```
 
 #### `kdeploy execute TASK_FILE [TASK]`
 
-Execute deployment tasks from a configuration file.
+从配置文件执行部署任务。
 
-**Basic Usage:**
+**基本用法:**
 ```bash
-# Execute all tasks in the file
+# 执行文件中的所有任务
 kdeploy execute deploy.rb
 
-# Execute a specific task
+# 执行特定任务
 kdeploy execute deploy.rb deploy_web
 ```
 
-**Options:**
-- `--limit HOSTS`: Limit execution to specific hosts (comma-separated)
-- `--parallel NUM`: Number of parallel executions (default: 10)
-- `--dry-run`: Preview mode - show what would be done without executing
+**选项:**
+- `--limit HOSTS`: 限制执行到特定主机（逗号分隔）
+- `--parallel NUM`: 并行执行数量（默认: 10）
+- `--dry-run`: 预览模式 - 显示将要执行的操作而不实际执行
 
-**Examples:**
+**示例:**
 ```bash
-# Preview deployment without executing
+# 预览部署而不执行
 kdeploy execute deploy.rb deploy_web --dry-run
 
-# Execute on specific hosts only
+# 仅在特定主机上执行
 kdeploy execute deploy.rb deploy_web --limit web01,web02
 
-# Use custom parallel count
+# 使用自定义并行数量
 kdeploy execute deploy.rb deploy_web --parallel 5
 
-# Combine options
+# 组合选项
 kdeploy execute deploy.rb deploy_web --limit web01 --parallel 3 --dry-run
 ```
 
 #### `kdeploy version`
 
-Show version information.
+显示版本信息。
 
 ```bash
 kdeploy version
@@ -224,34 +226,34 @@ kdeploy version
 
 #### `kdeploy help [COMMAND]`
 
-Show help information.
+显示帮助信息。
 
 ```bash
-# Show general help
+# 显示一般帮助
 kdeploy help
 
-# Show help for specific command
+# 显示特定命令的帮助
 kdeploy help execute
 ```
 
-### Host Definition
+### 主机定义
 
-#### Basic Host Configuration
+#### 基本主机配置
 
 ```ruby
-# Single host with SSH key
+# 使用 SSH 密钥的单个主机
 host "web01",
   user: "ubuntu",
   ip: "10.0.0.1",
   key: "~/.ssh/id_rsa"
 
-# Host with password authentication
+# 使用密码身份验证的主机
 host "web02",
   user: "admin",
   ip: "10.0.0.2",
   password: "your-password"
 
-# Host with custom SSH port
+# 使用自定义 SSH 端口的主机
 host "web03",
   user: "ubuntu",
   ip: "10.0.0.3",
@@ -259,22 +261,22 @@ host "web03",
   port: 2222
 ```
 
-#### Host Configuration Options
+#### 主机配置选项
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `user` | String | Yes | SSH username |
-| `ip` | String | Yes | Server IP address or hostname |
-| `key` | String | No* | Path to SSH private key file |
-| `password` | String | No* | SSH password |
-| `port` | Integer | No | SSH port (default: 22) |
+| 选项 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `user` | String | 是 | SSH 用户名 |
+| `ip` | String | 是 | 服务器 IP 地址或主机名 |
+| `key` | String | 否* | SSH 私钥文件路径 |
+| `password` | String | 否* | SSH 密码 |
+| `port` | Integer | 否 | SSH 端口（默认: 22） |
 
-\* Either `key` or `password` is required for authentication.
+\* 身份验证需要 `key` 或 `password` 之一。
 
-#### Dynamic Host Definition
+#### 动态主机定义
 
 ```ruby
-# Define multiple hosts programmatically
+# 以编程方式定义多个主机
 %w[web01 web02 web03].each do |name|
   host name,
     user: "ubuntu",
@@ -282,7 +284,7 @@ host "web03",
     key: "~/.ssh/id_rsa"
 end
 
-# Define hosts from external source
+# 从外部源定义主机
 require 'yaml'
 hosts_config = YAML.load_file('hosts.yml')
 hosts_config.each do |name, config|
@@ -290,35 +292,35 @@ hosts_config.each do |name, config|
 end
 ```
 
-### Role Management
+### 角色管理
 
-Roles allow you to group hosts and target them collectively in tasks.
+角色允许您对主机进行分组，并在任务中集体定位它们。
 
 ```ruby
-# Define roles
+# 定义角色
 role :web, %w[web01 web02 web03]
 role :db, %w[db01 db02]
 role :cache, %w[cache01]
 role :all, %w[web01 web02 web03 db01 db02 cache01]
 
-# Use roles in tasks
+# 在任务中使用角色
 task :deploy_web, roles: :web do
-  # Executes on all web servers
+  # 在所有 Web 服务器上执行
 end
 
 task :backup_db, roles: :db do
-  # Executes on all database servers
+  # 在所有数据库服务器上执行
 end
 
-# Multiple roles
+# 多个角色
 task :deploy_all, roles: [:web, :cache] do
-  # Executes on web and cache servers
+  # 在 Web 和缓存服务器上执行
 end
 ```
 
-### Task Definition
+### 任务定义
 
-#### Basic Task
+#### 基本任务
 
 ```ruby
 task :hello do
@@ -326,7 +328,7 @@ task :hello do
 end
 ```
 
-#### Role-based Task
+#### 基于角色的任务
 
 ```ruby
 task :deploy_web, roles: :web do
@@ -334,7 +336,7 @@ task :deploy_web, roles: :web do
 end
 ```
 
-#### Host-specific Task
+#### 特定主机任务
 
 ```ruby
 task :maintenance, on: %w[web01] do
@@ -346,44 +348,44 @@ task :maintenance, on: %w[web01] do
 end
 ```
 
-#### Task with Multiple Commands
+#### 多命令任务
 
 ```ruby
 task :deploy, roles: :web do
-  # Stop service
+  # 停止服务
   run "sudo systemctl stop nginx"
 
-  # Upload configuration
+  # 上传配置
   upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
 
-  # Start service
+  # 启动服务
   run "sudo systemctl start nginx"
 
-  # Verify status
+  # 验证状态
   run "sudo systemctl status nginx"
 end
 ```
 
-#### Task Options
+#### 任务选项
 
-| Option | Type | Description |
-|-------|------|-------------|
-| `roles` | Symbol/Array | Execute on hosts with specified role(s) |
-| `on` | Array | Execute on specific host(s) |
+| 选项 | 类型 | 描述 |
+|------|------|------|
+| `roles` | Symbol/Array | 在具有指定角色的主机上执行 |
+| `on` | Array | 在特定主机上执行 |
 
-**Note**: If neither `roles` nor `on` is specified, the task executes on all defined hosts.
+**注意**: 如果未指定 `roles` 或 `on`，任务将在所有已定义的主机上执行。
 
-### Command Types
+### 命令类型
 
-#### `run` - Execute Shell Commands
+#### `run` - 执行 Shell 命令
 
-Execute commands on remote servers.
+在远程服务器上执行命令。
 
 ```ruby
-# Single line command
+# 单行命令
 run "sudo systemctl restart nginx"
 
-# Multi-line command (recommended for complex commands)
+# 多行命令（推荐用于复杂命令）
 run <<~SHELL
   cd /var/www/app
   git pull origin main
@@ -392,24 +394,24 @@ run <<~SHELL
 SHELL
 ```
 
-**Best Practice**: Use heredoc (`<<~SHELL`) for multi-line commands to improve readability.
+**最佳实践**: 对多行命令使用 heredoc (`<<~SHELL`) 以提高可读性。
 
-#### `upload` - Upload Files
+#### `upload` - 上传文件
 
-Upload files to remote servers.
+将文件上传到远程服务器。
 
 ```ruby
 upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
 upload "./scripts/deploy.sh", "/tmp/deploy.sh"
 ```
 
-**Parameters:**
-- `source`: Local file path
-- `destination`: Remote file path
+**参数:**
+- `source`: 本地文件路径
+- `destination`: 远程文件路径
 
-#### `upload_template` - Upload ERB Templates
+#### `upload_template` - 上传 ERB 模板
 
-Upload and render ERB templates with variable substitution.
+上传并渲染 ERB 模板，支持变量替换。
 
 ```ruby
 upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
@@ -418,18 +420,18 @@ upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
   worker_processes: 4
 ```
 
-**Parameters:**
-- `source`: Local ERB template file path
-- `destination`: Remote file path
-- `variables`: Hash of variables for template rendering
+**参数:**
+- `source`: 本地 ERB 模板文件路径
+- `destination`: 远程文件路径
+- `variables`: 用于模板渲染的变量哈希
 
-### Template Support
+### 模板支持
 
-Kdeploy supports ERB (Embedded Ruby) templates for dynamic configuration generation.
+Kdeploy 支持 ERB（嵌入式 Ruby）模板，用于动态配置生成。
 
-#### Creating Templates
+#### 创建模板
 
-Create an ERB template file (e.g., `config/nginx.conf.erb`):
+创建 ERB 模板文件（例如，`config/nginx.conf.erb`）：
 
 ```erb
 user nginx;
@@ -465,7 +467,7 @@ http {
 }
 ```
 
-#### Using Templates
+#### 使用模板
 
 ```ruby
 task :deploy_config do
@@ -477,17 +479,17 @@ task :deploy_config do
 end
 ```
 
-#### Template Features
+#### 模板特性
 
-- Full ERB syntax support
-- Variable substitution
-- Conditional logic
-- Loops and iterations
-- Ruby code execution
+- 完整的 ERB 语法支持
+- 变量替换
+- 条件逻辑
+- 循环和迭代
+- Ruby 代码执行
 
-### Inventory Block
+### 清单块
 
-Use the `inventory` block to organize host definitions:
+使用 `inventory` 块来组织主机定义：
 
 ```ruby
 inventory do
@@ -497,28 +499,28 @@ inventory do
 end
 ```
 
-## ⚙️ Configuration
+## ⚙️ 配置
 
-### Default Configuration
+### 默认配置
 
-Kdeploy uses sensible defaults that can be customized:
+Kdeploy 使用可自定义的合理默认值：
 
-- **Default Parallel Count**: 10 concurrent executions
-- **SSH Timeout**: 30 seconds
-- **Host Key Verification**: Disabled (for convenience, enable in production)
+- **默认并行数量**: 10 个并发执行
+- **SSH 超时**: 30 秒
+- **主机密钥验证**: 禁用（为方便起见，在生产环境中启用）
 
-### Environment Variables
+### 环境变量
 
-You can override defaults using environment variables:
+您可以使用环境变量覆盖默认值：
 
 ```bash
 export KDEPLOY_PARALLEL=5
 export KDEPLOY_SSH_TIMEOUT=60
 ```
 
-### Configuration File
+### 配置文件
 
-For project-specific configuration, create a `.kdeploy.yml`:
+对于项目特定的配置，创建 `.kdeploy.yml`：
 
 ```yaml
 parallel: 5
@@ -526,11 +528,13 @@ ssh_timeout: 60
 verify_host_key: true
 ```
 
-## 🔧 Advanced Usage
+配置文件会自动从当前目录向上查找，直到找到 `.kdeploy.yml` 文件。
 
-### Conditional Execution
+## 🔧 高级用法
 
-Use Ruby conditionals in your deployment files:
+### 条件执行
+
+在部署文件中使用 Ruby 条件：
 
 ```ruby
 task :deploy do
@@ -546,38 +550,38 @@ task :deploy do
 end
 ```
 
-### Looping Over Hosts
+### 循环主机
 
 ```ruby
-# Execute different commands based on host
+# 根据主机执行不同的命令
 task :custom_setup do
   @hosts.each do |name, config|
     if name.start_with?('web')
-      run "echo 'Web server: #{name}'"
+      run "echo 'Web 服务器: #{name}'"
     elsif name.start_with?('db')
-      run "echo 'Database server: #{name}'"
+      run "echo '数据库服务器: #{name}'"
     end
   end
 end
 ```
 
-### Error Handling in Tasks
+### 任务中的错误处理
 
 ```ruby
 task :deploy do
-  run "sudo systemctl stop nginx" || raise "Failed to stop nginx"
+  run "sudo systemctl stop nginx" || raise "停止 nginx 失败"
   upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
-  run "sudo systemctl start nginx" || raise "Failed to start nginx"
+  run "sudo systemctl start nginx" || raise "启动 nginx 失败"
 end
 ```
 
-### Using External Libraries
+### 使用外部库
 
 ```ruby
 require 'yaml'
 require 'json'
 
-# Load configuration from external files
+# 从外部文件加载配置
 config = YAML.load_file('config.yml')
 
 task :deploy do
@@ -587,86 +591,48 @@ task :deploy do
 end
 ```
 
-### Task Dependencies
-
-While Kdeploy doesn't have built-in task dependencies, you can achieve this with Ruby:
-
-```ruby
-task :setup do
-  run "echo 'Setting up...'"
-end
-
-task :deploy do
-  # Manually call setup task
-  self.class.kdeploy_tasks[:setup][:block].call.each do |cmd|
-    case cmd[:type]
-    when :run
-      run cmd[:command]
-    when :upload
-      upload cmd[:source], cmd[:destination]
-    end
-  end
-
-  run "echo 'Deploying...'"
-end
-```
-
-## 🚨 Error Handling
-
-### Error Types
-
-Kdeploy provides specific error types for better debugging:
+## 🚨 错误处理
 
-- `Kdeploy::TaskNotFoundError` - Task not found
-- `Kdeploy::HostNotFoundError` - Host not found
-- `Kdeploy::SSHError` - SSH operation failed
-- `Kdeploy::SCPError` - SCP upload failed
-- `Kdeploy::TemplateError` - Template rendering failed
-- `Kdeploy::ConfigurationError` - Configuration error
-- `Kdeploy::FileNotFoundError` - File not found
+### 错误类型
 
-### Error Output
+Kdeploy 提供特定的错误类型以便更好地调试：
 
-Errors are displayed with:
-- Red color coding
-- Detailed error messages
-- Host information
-- Original error context
+- `Kdeploy::TaskNotFoundError` - 任务未找到
+- `Kdeploy::HostNotFoundError` - 主机未找到
+- `Kdeploy::SSHError` - SSH 操作失败
+- `Kdeploy::SCPError` - SCP 上传失败
+- `Kdeploy::TemplateError` - 模板渲染失败
+- `Kdeploy::ConfigurationError` - 配置错误
+- `Kdeploy::FileNotFoundError` - 文件未找到
 
-### Handling Errors
+### 错误输出
 
-```ruby
-# In your deployment file
-begin
-  task :deploy do
-    run "risky-command"
-  end
-rescue Kdeploy::SSHError => e
-  puts "SSH Error: #{e.message}"
-  # Handle error
-end
-```
+错误显示包括：
+- 红色颜色编码
+- 详细的错误消息
+- 主机信息
+- 原始错误上下文
 
-## 💡 Best Practices
+## 💡 最佳实践
 
-### 1. Use Heredoc for Multi-line Commands
+### 1. 对多行命令使用 Heredoc
 
 ```ruby
-# ✅ Good
+# ✅ 好的做法
 run <<~SHELL
   cd /var/www/app
   git pull origin main
   bundle install
 SHELL
 
-# ❌ Avoid
+# ❌ 避免
 run "cd /var/www/app && git pull origin main && bundle install"
 ```
 
-### 2. Organize with Roles
+### 2. 使用角色进行组织
 
 ```ruby
-# ✅ Good - Use roles for organization
+# ✅ 好的做法 - 使用角色进行组织
 role :web, %w[web01 web02]
 role :db, %w[db01 db02]
 
@@ -674,274 +640,259 @@ task :deploy_web, roles: :web do
   # ...
 end
 
-# ❌ Avoid - Hardcoding host names
+# ❌ 避免 - 硬编码主机名
 task :deploy do
-  # Hard to maintain
+  # 难以维护
 end
 ```
 
-### 3. Use Templates for Dynamic Configuration
+### 3. 使用模板进行动态配置
 
 ```ruby
-# ✅ Good - Use templates
+# ✅ 好的做法 - 使用模板
 upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
   domain_name: "example.com",
   port: 3000
 
-# ❌ Avoid - Hardcoding values
+# ❌ 避免 - 硬编码值
 run "echo 'server_name example.com;' > /etc/nginx/nginx.conf"
 ```
 
-### 4. Validate Before Deployment
+### 4. 部署前验证
 
 ```ruby
 task :deploy do
-  # Validate configuration
-  run "nginx -t" || raise "Nginx configuration is invalid"
+  # 验证配置
+  run "nginx -t" || raise "Nginx 配置无效"
 
-  # Deploy
+  # 部署
   upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
   run "sudo systemctl reload nginx"
 end
 ```
 
-### 5. Use Dry Run for Testing
+### 5. 使用试运行进行测试
 
-Always test with `--dry-run` before actual deployment:
+在实际部署之前，始终使用 `--dry-run` 进行测试：
 
 ```bash
 kdeploy execute deploy.rb deploy_web --dry-run
 ```
 
-### 6. Organize Files Properly
+### 6. 正确组织文件
 
 ```
 project/
-├── deploy.rb              # Main deployment file
-├── config/                # Configuration files
-│   ├── nginx.conf.erb     # Templates
-│   └── app.conf           # Static configs
-└── scripts/               # Helper scripts
+├── deploy.rb              # 主部署文件
+├── config/                # 配置文件
+│   ├── nginx.conf.erb     # 模板
+│   └── app.conf           # 静态配置
+└── scripts/               # 辅助脚本
     └── deploy.sh
 ```
 
-### 7. Version Control
+### 7. 版本控制
 
-- Commit `deploy.rb` and templates
-- Use `.gitignore` for sensitive files
-- Store secrets in environment variables
+- 提交 `deploy.rb` 和模板
+- 使用 `.gitignore` 处理敏感文件
+- 将密钥存储在环境变量中
 
-### 8. Parallel Execution
+### 8. 并行执行
 
-Adjust parallel count based on your infrastructure:
+根据您的基础设施调整并行数量：
 
 ```bash
-# For many hosts, increase parallel count
+# 对于许多主机，增加并行数量
 kdeploy execute deploy.rb deploy --parallel 20
 
-# For limited resources, decrease
+# 对于有限资源，减少
 kdeploy execute deploy.rb deploy --parallel 3
 ```
 
-## 🔍 Troubleshooting
-
-### Common Issues
-
-#### SSH Authentication Failed
+## 🔍 故障排除
 
-**Problem**: `SSH authentication failed`
+### 常见问题
 
-**Solutions**:
-1. Verify SSH key path is correct
-2. Check key permissions: `chmod 600 ~/.ssh/id_rsa`
-3. Test SSH connection manually: `ssh user@host`
-4. Verify username and IP address
+#### SSH 身份验证失败
 
-#### Host Not Found
+**问题**: `SSH authentication failed`
 
-**Problem**: `No hosts found for task`
+**解决方案**:
+1. 验证 SSH 密钥路径是否正确
+2. 检查密钥权限: `chmod 600 ~/.ssh/id_rsa`
+3. 手动测试 SSH 连接: `ssh user@host`
+4. 验证用户名和 IP 地址
 
-**Solutions**:
-1. Verify host names in task match defined hosts
-2. Check role definitions
-3. Verify `--limit` option if used
+#### 主机未找到
 
-#### Command Execution Failed
+**问题**: `No hosts found for task`
 
-**Problem**: Commands fail on remote server
+**解决方案**:
+1. 验证任务中的主机名是否与已定义的主机匹配
+2. 检查角色定义
+3. 如果使用了 `--limit` 选项，请验证
 
-**Solutions**:
-1. Test commands manually on target server
-2. Check user permissions (may need sudo)
-3. Verify command syntax
-4. Check server logs
+#### 命令执行失败
 
-#### Template Rendering Error
+**问题**: 远程服务器上的命令失败
 
-**Problem**: Template upload fails
+**解决方案**:
+1. 在目标服务器上手动测试命令
+2. 检查用户权限（可能需要 sudo）
+3. 验证命令语法
+4. 检查服务器日志
 
-**Solutions**:
-1. Verify ERB syntax in template
-2. Check all required variables are provided
-3. Validate template file exists
-4. Test template rendering locally
+#### 模板渲染错误
 
-#### Connection Timeout
+**问题**: 模板上传失败
 
-**Problem**: SSH connection times out
+**解决方案**:
+1. 验证模板中的 ERB 语法
+2. 检查是否提供了所有必需的变量
+3. 验证模板文件是否存在
+4. 在本地测试模板渲染
 
-**Solutions**:
-1. Check network connectivity
-2. Verify firewall rules
-3. Increase timeout in configuration
-4. Check SSH service on target server
+#### 连接超时
 
-### Debug Mode
+**问题**: SSH 连接超时
 
-Enable verbose output by checking the execution output. Kdeploy provides detailed information about:
-- Task execution status
-- Command output
-- Error messages
-- Execution duration
+**解决方案**:
+1. 检查网络连接
+2. 验证防火墙规则
+3. 在配置中增加超时时间
+4. 检查目标服务器上的 SSH 服务
 
-### Getting Help
+## 🏗️ 架构
 
-- Check [GitHub Issues](https://github.com/kevin197011/kdeploy/issues)
-- Review example projects
-- Read the documentation
-- Ask in discussions
+### 核心组件
 
-## 🏗️ Architecture
+- **CLI** (`cli.rb`): 使用 Thor 的命令行界面
+- **DSL** (`dsl.rb`): 用于任务定义的领域特定语言
+- **Executor** (`executor.rb`): SSH/SCP 执行引擎
+- **Runner** (`runner.rb`): 并发任务执行协调器
+- **CommandExecutor** (`command_executor.rb`): 单个命令执行
+- **CommandGrouper** (`command_grouper.rb`): 命令分组逻辑
+- **Template** (`template.rb`): ERB 模板渲染
+- **Output** (`output.rb`): 输出格式化和显示
+- **Configuration** (`configuration.rb`): 配置管理
+- **Errors** (`errors.rb`): 自定义错误类型
 
-### Core Components
+### 执行流程
 
-- **CLI** (`cli.rb`): Command-line interface using Thor
-- **DSL** (`dsl.rb`): Domain-specific language for task definition
-- **Executor** (`executor.rb`): SSH/SCP execution engine
-- **Runner** (`runner.rb`): Concurrent task execution coordinator
-- **CommandExecutor** (`command_executor.rb`): Individual command execution
-- **CommandGrouper** (`command_grouper.rb`): Command grouping logic
-- **Template** (`template.rb`): ERB template rendering
-- **Output** (`output.rb`): Output formatting and display
-- **Configuration** (`configuration.rb`): Configuration management
-- **Errors** (`errors.rb`): Custom error types
+1. **解析配置**: 加载并解析 `deploy.rb`
+2. **解析主机**: 根据任务定义确定目标主机
+3. **分组命令**: 按类型分组命令以提高执行效率
+4. **并发执行**: 跨主机并行运行任务
+5. **收集结果**: 收集执行结果和状态
+6. **显示输出**: 格式化并向用户显示结果
 
-### Execution Flow
+### 并发模型
 
-1. **Parse Configuration**: Load and parse `deploy.rb`
-2. **Resolve Hosts**: Determine target hosts based on task definition
-3. **Group Commands**: Group commands by type for efficient execution
-4. **Execute Concurrently**: Run tasks in parallel across hosts
-5. **Collect Results**: Gather execution results and status
-6. **Display Output**: Format and display results to user
+Kdeploy 使用带有固定线程池的 `concurrent-ruby`：
+- 默认: 10 个并发执行
+- 可通过 `--parallel` 选项配置
+- 线程安全的结果收集
+- 自动资源清理
 
-### Concurrency Model
+## 🔧 开发
 
-Kdeploy uses `concurrent-ruby` with a fixed thread pool:
-- Default: 10 concurrent executions
-- Configurable via `--parallel` option
-- Thread-safe result collection
-- Automatic resource cleanup
-
-## 🔧 Development
-
-### Setup Development Environment
+### 设置开发环境
 
 ```bash
-# Clone repository
+# 克隆仓库
 git clone https://github.com/kevin197011/kdeploy.git
 cd kdeploy
 
-# Install dependencies
+# 安装依赖
 bundle install
 
-# Run tests
+# 运行测试
 bundle exec rspec
 
-# Run console
+# 运行控制台
 bin/console
 ```
 
-### Project Structure
+### 项目结构
 
 ```
 kdeploy/
 ├── lib/
 │   └── kdeploy/
-│       ├── cli.rb              # CLI interface
-│       ├── dsl.rb              # DSL definition
-│       ├── executor.rb         # SSH/SCP executor
-│       ├── runner.rb           # Task runner
-│       ├── command_executor.rb # Command executor
-│       ├── command_grouper.rb  # Command grouper
-│       ├── template.rb         # Template handler
-│       ├── output.rb           # Output interface
-│       ├── configuration.rb    # Configuration
-│       ├── errors.rb           # Error types
+│       ├── cli.rb              # CLI 接口
+│       ├── dsl.rb              # DSL 定义
+│       ├── executor.rb         # SSH/SCP 执行器
+│       ├── runner.rb           # 任务运行器
+│       ├── command_executor.rb # 命令执行器
+│       ├── command_grouper.rb  # 命令分组器
+│       ├── template.rb         # 模板处理器
+│       ├── output.rb           # 输出接口
+│       ├── configuration.rb    # 配置
+│       ├── errors.rb           # 错误类型
 │       └── ...
-├── spec/                       # Tests
-├── exe/                        # Executables
-├── sample/                     # Example projects
-└── README.md                   # This file
+├── spec/                       # 测试
+├── exe/                        # 可执行文件
+├── sample/                     # 示例项目
+└── README.md                   # 本文档
 ```
 
-### Running Tests
+### 运行测试
 
 ```bash
-# Run all tests
+# 运行所有测试
 bundle exec rspec
 
-# Run specific test file
+# 运行特定测试文件
 bundle exec rspec spec/kdeploy_spec.rb
 
-# Run with coverage
+# 运行覆盖率
 COVERAGE=true bundle exec rspec
 ```
 
-### Building the Gem
+### 构建 Gem
 
 ```bash
-# Build gem
+# 构建 gem
 gem build kdeploy.gemspec
 
-# Install locally
+# 本地安装
 gem install ./kdeploy-*.gem
 ```
 
-### Code Style
+### 代码风格
 
-The project uses RuboCop for code style:
+项目使用 RuboCop 进行代码风格检查：
 
 ```bash
-# Check style
+# 检查风格
 bundle exec rubocop
 
-# Auto-fix issues
+# 自动修复问题
 bundle exec rubocop -a
 ```
 
-## 🤝 Contributing
+## 🤝 贡献
 
-Contributions are welcome! Please follow these steps:
+欢迎贡献！请遵循以下步骤：
 
-1. **Fork the repository**
-2. **Create a feature branch**: `git checkout -b feature/my-new-feature`
-3. **Make your changes**: Follow the code style and add tests
-4. **Commit your changes**: Use conventional commit messages
-5. **Push to the branch**: `git push origin feature/my-new-feature`
-6. **Create a Pull Request**: Provide a clear description of changes
+1. **Fork 仓库**
+2. **创建功能分支**: `git checkout -b feature/my-new-feature`
+3. **进行更改**: 遵循代码风格并添加测试
+4. **提交更改**: 使用约定式提交消息
+5. **推送到分支**: `git push origin feature/my-new-feature`
+6. **创建 Pull Request**: 提供清晰的更改描述
 
-### Contribution Guidelines
+### 贡献指南
 
-- Follow existing code style
-- Add tests for new features
-- Update documentation
-- Ensure all tests pass
-- Follow conventional commit format
+- 遵循现有代码风格
+- 为新功能添加测试
+- 更新文档
+- 确保所有测试通过
+- 遵循约定式提交格式
 
-### Commit Message Format
+### 提交消息格式
 
-Follow [Conventional Commits](https://www.conventionalcommits.org/):
+遵循 [约定式提交](https://www.conventionalcommits.org/):
 
 ```
 <type>(<scope>): <subject>
@@ -951,17 +902,17 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/):
 <footer>
 ```
 
-Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+类型: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
 
-## 📚 Examples
+## 📚 示例
 
-### Example Projects
+### 示例项目
 
-Check out the [example project](https://github.com/kevin197011/kdeploy-app) for a complete deployment setup.
+查看 [示例项目](https://github.com/kevin197011/kdeploy-app) 以获取完整的部署设置。
 
-### Common Deployment Scenarios
+### 常见部署场景
 
-#### Web Application Deployment
+#### Web 应用程序部署
 
 ```ruby
 host "web01", user: "deploy", ip: "10.0.0.1", key: "~/.ssh/id_rsa"
@@ -978,7 +929,7 @@ task :deploy_app, roles: :web do
 end
 ```
 
-#### Database Backup
+#### 数据库备份
 
 ```ruby
 host "db01", user: "postgres", ip: "10.0.0.10", key: "~/.ssh/id_rsa"
@@ -994,7 +945,7 @@ task :backup, roles: :db do
 end
 ```
 
-#### Configuration Management
+#### 配置管理
 
 ```ruby
 task :update_config, roles: :web do
@@ -1007,23 +958,24 @@ task :update_config, roles: :web do
 end
 ```
 
-## 📝 License
+## 📝 许可证
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+该 gem 在 [MIT 许可证](https://opensource.org/licenses/MIT) 条款下作为开源提供。
 
-## 🔗 Links
+## 🔗 链接
 
 - **GitHub**: https://github.com/kevin197011/kdeploy
 - **RubyGems**: https://rubygems.org/gems/kdeploy
 - **Issues**: https://github.com/kevin197011/kdeploy/issues
-- **Example Project**: https://github.com/kevin197011/kdeploy-app
+- **示例项目**: https://github.com/kevin197011/kdeploy-app
 
-## 🙏 Acknowledgments
+## 🙏 致谢
 
-- Built with [Thor](https://github.com/rails/thor) for CLI
-- Uses [net-ssh](https://github.com/net-ssh/net-ssh) for SSH operations
-- Powered by [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) for concurrency
+- 使用 [Thor](https://github.com/rails/thor) 构建 CLI
+- 使用 [net-ssh](https://github.com/net-ssh/net-ssh) 进行 SSH 操作
+- 由 [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) 提供并发支持
 
 ---
 
-**Made with ❤️ for the DevOps community**
+**为 DevOps 社区用 ❤️ 制作**
+