kdeploy 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce9866219dbabbb49ab4ca2d3e8413e329700d245784f4017dd539dfbe17607c
-  data.tar.gz: 26dee30c428f7e5e41eedb84450589e647b49d42817017e7d69e698aacae1226
+  metadata.gz: f3be52250612f3eb627a5044db454c87f7258396f9a0c066be85df9ff8f33b9d
+  data.tar.gz: c802622e109e4e5d0620456a732e2b8b870b77ec0e422fe461ff1edf6993cd7e
 SHA512:
-  metadata.gz: 75a4b65a35a267710f8f6bbc8f93f8687aef976bd7d2f5212658b966c2bf427fb858f0b8fc40b3752a6575872ff4da587db65096a30a7b8edba955c68015da99
-  data.tar.gz: 14352a49dbaad173560e910d5c7dd68932b63b6c1c0cff4fcf05f4c6b429939e2ffb9ba40d0828ca4159493c9f0344da07c7dd25cce655ed3c90a4f2e617a1d4
+  metadata.gz: cc0fba2a35c4bff14238ef9c4f088d1f2fc52f1625e3c7e38394d5100d57db3556fc634af21afcb4b991b1f24e6339c1649c8cc52a58a20a29eb0b8e24d8e956
+  data.tar.gz: 52cb3084e8bf51f50e92556b13e241451dd6c6bfa6df7ed9041a042ea96eb4f1fe5c8d310af9e706a3e2396eea963f0bc552e6c72efb5aa29eead6da014f553b

data/README.md

@@ -1,43 +1,17 @@
 # Kdeploy
 
-```
-          _            _
-  /\ /\__| | ___ _ __ | | ___  _   _
- / //_/ _` |/ _ \ '_ \| |/ _ \| | | |
-/ __ \ (_| |  __/ |_) | | (_) | |_| |
-\/  \/\__,_|\___| .__/|_|\___/ \__, |
-                |_|            |___/
-
-  ⚡ Lightweight Agentless Deployment Tool
-  🚀 Deploy with confidence, scale with ease
-```
+A lightweight agentless deployment automation tool written in Ruby.
 
-[![Gem Version](https://badge.fury.io/rb/kdeploy.svg)](https://rubygems.org/gems/kdeploy)
-[![CI](https://github.com/kevin197011/kdeploy/actions/workflows/ci.yml/badge.svg)](https://github.com/kevin197011/kdeploy/actions/workflows/ci.yml)
-
-Kdeploy is a modern, lightweight agentless deployment tool similar to Chef, Puppet, and Ansible. It uses an elegant Ruby DSL syntax and supports concurrent execution, statistical analysis, and complete deployment lifecycle management.
-
-[中文文档](README_CN.md)
-
-## ✨ Features
-
-- 🚀 **Lightweight**: No agent installation required on target servers, SSH-based connections
-- 🎨 **Modern Interface**: Beautiful ASCII art and colored output interface
-- 🔧 **DSL Syntax**: Concise and elegant Ruby DSL configuration syntax
-- ⚡ **Concurrent Execution**: Support for multi-host parallel operations and intelligent concurrency control
-- 🛠️ **Batch Operations**: Efficient batch Shell command execution
-- 🔒 **Secure Connection**: SSH-based secure connections with key authentication
-- 📝 **Real-time Output**: Command execution results with real-time display and detailed timing statistics
-- 🎯 **Role Management**: Flexible role-based host grouping management
-- 📋 **Inventory Management**: Powerful YAML format host inventory with group and variable inheritance
-- 🧩 **Heredoc Syntax**: Support for multi-line Shell scripts using heredoc syntax
-- 🎨 **ERB Templates**: Built-in ERB template engine for dynamic configuration file generation
-- 🏷️ **Variable Substitution**: Support for both `{{variable}}` and `${variable}` template syntax
-- 🖥️ **Mixed Execution**: Support for local command execution and hybrid deployment scenarios
-- 📊 **Statistics Analysis**: Automatic deployment statistics collection with performance analysis and trend monitoring
-- 🔄 **Script Library**: Rich pre-made script templates covering the complete deployment lifecycle
-- 🧩 **Modular Architecture**: Support for modular script organization with reusable task components
-- 🛡️ **Error Recovery**: Intelligent error handling and automatic retry mechanism
+## 🌟 Features
+
+- 🔑 **Agentless Remote Deployment**: Uses SSH for secure remote execution
+- 📝 **Elegant Ruby DSL**: Simple and expressive task definition
+- 🚀 **Concurrent Execution**: Efficient parallel task processing
+- 📤 **File Upload Support**: Easy file and template deployment
+- 📊 **Task Status Tracking**: Real-time execution monitoring
+- 🔄 **ERB Template Support**: Dynamic configuration generation
+- 🎯 **Role-based Deployment**: Target specific server roles
+- 🔍 **Dry Run Mode**: Preview tasks before execution
 
 ## 📦 Installation
 
@@ -47,345 +21,175 @@ Add this line to your application's Gemfile:
 gem 'kdeploy'
 ```
 
-Then execute:
+And then execute:
 
 ```bash
-bundle install
+$ bundle install
 ```
 
-Or install it directly:
+Or install it yourself as:
 
 ```bash
-gem install kdeploy
+$ gem install kdeploy
 ```
 
 ## 🚀 Quick Start
 
-### 1. Initialize Project
+1. Initialize a new project:
 
 ```bash
-kdeploy init myapp
-cd myapp
+$ kdeploy init my-deployment
 ```
 
-Kdeploy will automatically create a complete project structure with several useful script examples:
+2. Edit the deployment configuration:
 
-```
-myapp/
-├── deploy.rb                    # Main deployment script
-├── inventory.yml               # Host inventory configuration
-├── config/                     # Configuration directory
-│   └── kdeploy.yml            # Global configuration file
-├── scripts/                   # 🆕 Complete script library
-│   ├── common_tasks.rb        # 🆕 Common task module (reusable)
-│   ├── setup.rb              # Server initialization
-│   ├── database.rb            # Database management
-│   ├── backup.rb              # Backup operations
-│   ├── monitoring.rb          # Monitoring and health checks
-│   ├── rollback.rb            # Rollback operations
-│   └── cleanup.rb             # Cleanup maintenance
-└── templates/                 # ERB template files
-    ├── nginx.conf.erb         # Nginx configuration template
-    ├── app.service.erb        # Systemd service template
-    ├── deploy.sh.erb          # Deployment script template
-    └── backup.sh.erb          # Backup script template
-```
-
-### 2. Configure Server Inventory
-
-Edit `inventory.yml` to configure host inventory:
-
-```yaml
-# Global variables
-vars:
-  application: myapp
-  version: 1.0.0
-  deploy_to: /opt/myapp
-  environment: production
-
-# Host groups
-groups:
-  webservers:
-    hosts:
-      - web1.example.com
-      - web2.example.com
-    vars:
-      nginx_port: 80
-      app_port: 3000
-
-  databases:
-    hosts:
-      - db1.example.com
-    vars:
-      postgres_port: 5432
-      backup_enabled: true
-
-  production:
-    children:
-      - webservers
-      - databases
-    vars:
-      environment: production
-
-# Host configurations
-hosts:
-  web1.example.com:
-    user: deploy
-    port: 22
-    roles: [web, app]
-    ssh:
-      key_file: ~/.ssh/id_rsa
-      verify_host_key: false
-    vars:
-      server_id: 1
-
-  web2.example.com:
-    user: deploy
-    port: 22
-    roles: [web, app]
-    ssh:
-      key_file: ~/.ssh/id_rsa
-      verify_host_key: false
-    vars:
-      server_id: 2
-
-  db1.example.com:
-    user: deploy
-    port: 22
-    roles: [database]
-    ssh:
-      key_file: ~/.ssh/id_rsa
-      verify_host_key: false
-    vars:
-      server_id: 3
-      master: true
-```
+```ruby
+# deploy.rb
 
-### 3. Use Pre-made Scripts
+# 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"
 
-Kdeploy provides a complete script library covering various deployment stages:
+# Define roles
+role :web, %w[web01 web02]
 
-#### 🔧 Server Initialization
-```bash
-# Execute before first deployment to install dependencies and configure environment
-kdeploy deploy scripts/setup.rb
+# Define tasks
+task :deploy, roles: :web do
+  run "sudo systemctl stop nginx"
+  upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
+    domain_name: "example.com",
+    port: 3000
+  run "sudo systemctl start nginx"
+end
 ```
 
-#### 💾 Database Management
-```bash
-# Database operations
-kdeploy deploy scripts/database.rb  # Create database, migrate, backup
-```
+3. Run the deployment:
 
-#### 🚀 Application Deployment
 ```bash
-# Main application deployment
-kdeploy deploy deploy.rb
+$ kdeploy execute deploy.rb
 ```
 
-#### 📊 Health Monitoring
-```bash
-# System and application health checks
-kdeploy deploy scripts/monitoring.rb
-```
+## 📖 Usage Guide
 
-#### 💾 Backup Operations
-```bash
-# Application and data backup
-kdeploy deploy scripts/backup.rb
-```
-
-#### 🔙 Rollback Operations
-```bash
-# Emergency rollback and recovery
-kdeploy deploy scripts/rollback.rb
-```
-
-#### 🧹 Cleanup Maintenance
-```bash
-# System cleanup and maintenance
-kdeploy deploy scripts/cleanup.rb
-```
+### Host Definition
 
-#### 🧩 Common Task Module
-```bash
-# Use common task module for basic setup
-kdeploy deploy scripts/common_tasks.rb --task setup_environment
+```ruby
+# Single host
+host "web01",
+  user: "ubuntu",
+  ip: "10.0.0.1",
+  key: "~/.ssh/id_rsa"
 
-# Execute security hardening
-kdeploy deploy scripts/common_tasks.rb --task security_hardening
+# Multiple hosts
+%w[web01 web02 web03].each do |name|
+  host name,
+    user: "ubuntu",
+    ip: "10.0.0.#{name[-1]}",
+    key: "~/.ssh/id_rsa"
+end
 ```
 
-### 4. Deployment Workflow Example
-
-```bash
-# 1. Validate configuration
-kdeploy validate deploy.rb
-
-# 2. First-time server setup
-kdeploy deploy scripts/setup.rb
-
-# 3. Setup database
-kdeploy deploy scripts/database.rb
+### Role Management
 
-# 4. Execute application deployment
-kdeploy deploy deploy.rb --verbose
+```ruby
+# Define roles
+role :web, %w[web01 web02]
+role :db, %w[db01 db02]
+role :all, %w[web01 web02 db01 db02]
 
-# 5. Health check
-kdeploy deploy scripts/monitoring.rb
+# Use roles in tasks
+task :deploy_web, roles: :web do
+  # Tasks for web servers
+end
 
-# 6. View statistics
-kdeploy stats summary
+task :backup_db, roles: :db do
+  # Tasks for database servers
+end
 ```
 
-## 📊 Statistics and Monitoring
-
-Kdeploy provides powerful built-in statistics functionality that automatically tracks all deployment activities:
-
-### 📈 Automatically Collected Statistics
-
-- ✅ **Success/Failure Statistics**: Success rates at deployment, task, and command levels
-- ⏱️ **Performance Metrics**: Detailed execution time and performance data
-- 📅 **Historical Trends**: Performance trend analysis grouped by date
-- 🎯 **Failure Analysis**: Identify most common failing tasks and error patterns
-- 🌍 **Global Statistics**: Cumulative statistics across sessions
-
-### 🔍 Statistics Commands
-
-```bash
-# View statistics summary
-kdeploy stats summary
+### Task Definition
 
-# View deployment statistics
-kdeploy stats deployments
-
-# View task statistics
-kdeploy stats tasks
-
-# View failure statistics
-kdeploy stats failures
+```ruby
+# Basic task
+task :simple do
+  run "echo 'Hello, World!'"
+end
 
-# View performance trends
-kdeploy stats trends
+# Role-based task
+task :deploy, roles: :web do
+  run "sudo systemctl stop nginx"
+  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
+  run "sudo systemctl start nginx"
+end
 
-# View global statistics
-kdeploy stats global
+# Host-specific task
+task :maintenance, on: %w[web01] do
+  run "sudo apt-get update"
+  run "sudo apt-get upgrade -y"
+end
+```
 
-# Export statistics data
-kdeploy stats export --export monthly_report.json
+### Template Support
 
-# Clear statistics data
-kdeploy stats clear
+Create an ERB template (`config/nginx.conf.erb`):
 
-# Specify time range (days)
-kdeploy stats summary --days 7
+```erb
+server {
+    listen 80;
+    server_name <%= domain_name %>;
 
-# JSON format output
-kdeploy stats tasks --format json
+    location / {
+        proxy_pass http://localhost:<%= port %>;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
 ```
 
-### 📊 Statistics Output Example
+Use the template in your task:
 
-```bash
-kdeploy stats summary
-
-📊 Kdeploy Statistics Summary (Last 30 days)
-=====================================================
-
-📦 Deployment Summary:
-  Total Deployments: 15
-  Successful: 13 (86.7%)
-  Failed: 2 (13.3%)
-  Average Duration: 45.2s
-
-🔧 Task Summary:
-  Total Tasks: 89
-  Successful: 84 (94.4%)
-  Failed: 5 (5.6%)
-  Average Duration: 12.8s
-
-🌍 Global Statistics:
-  Total Deployments: 156
-  Session Duration: 2h 34m
-  Most Active Day: 2025-06-28 (8 deployments)
+```ruby
+task :deploy_config do
+  upload_template "./config/nginx.conf.erb", "/etc/nginx/sites-available/myapp.conf",
+    domain_name: "example.com",
+    port: 3000
+end
 ```
 
-## 🔧 Troubleshooting
-
-### Common Issues
-
-1. **SSH Connection Failed**
-   ```bash
-   # Check SSH connection
-   ssh -vvv user@hostname
-
-   # Verify keys
-   ssh-add -l
-   ```
-
-2. **Permission Issues**
-   ```ruby
-   # Use sudo for commands
-   run 'sudo systemctl restart nginx'
-
-   # Check file permissions
-   run 'ls -la {{deploy_to}}'
-   ```
-
-3. **Timeout Issues**
-   ```ruby
-   # Increase timeout
-   run 'long_command', timeout: 300
-
-   # Or set in configuration file
-   command_timeout: 600
-   ```
-
-### Debugging Tips
+### Command Line Options
 
 ```bash
-# Verbose output mode
-kdeploy deploy script.rb --verbose
-
-# Dry run mode
-kdeploy deploy script.rb --dry-run
+# Execute with dry run
+kdeploy execute deploy.rb --dry-run
 
-# View configuration
-kdeploy config
+# Limit to specific hosts
+kdeploy execute deploy.rb --limit web01,web02
 
-# Validate script
-kdeploy validate script.rb
+# Set parallel execution count
+kdeploy execute deploy.rb --parallel 5
 
-# View logs
-tail -f kdeploy.log
+# Execute specific task
+kdeploy execute deploy.rb deploy_web
 ```
 
-## 🤝 Contributing
-
-We welcome community contributions! Please follow these guidelines:
-
-1. Fork the project
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Create a Pull Request
+## 🔧 Development
 
-## 📄 License
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+To install this gem onto your local machine, run `bundle exec rake install`.
 
-## 🔗 Links
+## 🤝 Contributing
 
-- [Project Homepage](https://github.com/kevin197011/kdeploy)
-- [Documentation](https://github.com/kevin197011/kdeploy/wiki)
-- [Issue Tracker](https://github.com/kevin197011/kdeploy/issues)
-- [Release Notes](https://github.com/kevin197011/kdeploy/releases)
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a new Pull Request
 
-## 💬 Community Support
+## 📝 License
 
-- GitHub Issues: [Report Issues](https://github.com/kevin197011/kdeploy/issues)
-- GitHub Discussions: [Community Discussions](https://github.com/kevin197011/kdeploy/discussions)
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
----
+## 🔍 Code of Conduct
 
-**Kdeploy** - Making deployment simple and powerful 🚀
+Everyone interacting in the Kdeploy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/kdeploy/blob/main/CODE_OF_CONDUCT.md).

data/exe/kdeploy

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "kdeploy"
+
+Kdeploy::CLI.start(ARGV)

data/k.md

@@ -0,0 +1,149 @@
+以下是将 Kdeploy 项目的开发需求整理成的标准 Markdown 格式文档，可保存为 `dev_requirements.md`：
+
+---
+
+```markdown
+# 📦 Kdeploy 开发需求文档
+
+> **项目名称**：Kdeploy
+> **项目类型**：Ruby Gem
+> **定位**：轻量级 agentless 运维部署工具
+> **灵感来源**：Ansible、Chef、Puppet
+> **目标用户**：DevOps、SRE、系统运维工程师
+
+---
+
+## 🧭 项目目标
+
+- 提供 **无 agent** 的远程部署解决方案
+- 使用 **优雅的 Ruby DSL** 编写部署任务
+- 支持任务的 **并发执行**
+- 能够进行任务 **状态统计与结果输出**
+- 管理 **完整的部署生命周期**（准备、执行、清理、回滚等）
+- 简洁、轻量、便于嵌入其他工具链
+- 可支持 **多主机、多环境配置管理**
+
+---
+
+## 📁 项目结构
+
+```
+
+kdeploy/
+├── bin/
+│   └── kdeploy             # 主执行文件
+├── lib/
+│   ├── kdeploy/
+│   │   ├── dsl.rb          # DSL 定义
+│   │   ├── executor.rb     # 并发执行器
+│   │   ├── inventory.rb    # 主机清单管理
+│   │   ├── lifecycle.rb    # 生命周期管理
+│   │   ├── logger.rb       # 日志与输出
+│   │   └── version.rb
+│   └── kdeploy.rb          # 主入口
+├── tasks/
+│   └── deploy.rb           # 示例任务（用户自定义）
+├── spec/
+│   └── kdeploy\_spec.rb     # RSpec 测试
+├── kdeploy.gemspec
+└── README.md
+
+````
+
+---
+
+## 🔧 功能模块设计
+
+### 1. DSL 任务定义
+
+```ruby
+host 'web01', user: 'ubuntu', ip: '10.0.0.1'
+
+task :deploy_web do
+  run 'sudo systemctl stop nginx'
+  upload './nginx.conf', '/etc/nginx/nginx.conf'
+  run 'sudo systemctl start nginx'
+end
+````
+
+### 2. 并发执行器
+
+* 线程池并发执行远程任务
+* 自动记录成功/失败状态
+* 支持最大并发数限制
+
+### 3. 生命周期管理
+
+* `prepare`：初始化（如环境检查）
+* `run`：主要任务执行
+* `cleanup`：清理临时文件或状态
+* `rollback`：失败回滚（可选）
+
+### 4. 主机清单
+
+支持静态或动态清单，如：
+
+```ruby
+inventory do
+  host 'web01', user: 'ubuntu', ip: '10.0.0.1'
+  host 'db01', user: 'root', ip: '10.0.0.2'
+end
+```
+
+### 5. 输出日志与状态统计
+
+* 控制台美化输出（使用 `pastel`、`tty-table` 等）
+* 最终报告：执行成功/失败主机、任务耗时、回滚信息等
+
+---
+
+## 🖥️ 命令行工具设计
+
+执行文件：`bin/kdeploy`
+
+```bash
+kdeploy run tasks/deploy.rb --limit web01,web02 --parallel 5 --dry-run
+```
+
+| 参数            | 说明            |
+| ------------- | ------------- |
+| `run`         | 执行某个 DSL 任务文件 |
+| `--limit`     | 限定主机          |
+| `--parallel`  | 设置并发线程数       |
+| `--dry-run`   | 预览任务，不真正执行    |
+| `--rollback`  | 启动回滚          |
+| `--inventory` | 使用特定主机清单文件    |
+
+---
+
+## 🧩 可扩展性设计
+
+* 支持插件机制：可注册自定义任务类型
+* 可支持其他协议（如 WinRM、Docker、Kubernetes 等）
+* 日后可支持多环境配置（dev/stage/prod）
+* 支持本地/远程日志聚合
+
+---
+
+## 📦 开发计划建议
+
+| 阶段         | 内容                                        |
+| ---------- | ----------------------------------------- |
+| 1️⃣ 初始化    | 使用 `bundle gem .` 生成项目骨架，添加执行文件     |
+| 2️⃣ DSL 实现 | 定义基本任务语法（`host`, `task`, `run`, `upload`） |
+| 3️⃣ SSH 执行 | 实现基础 SSH 执行器（使用 `net-ssh`）                |
+| 4️⃣ 并发执行   | 引入线程池或 `concurrent-ruby`                  |
+| 5️⃣ 生命周期   | 支持 prepare/run/cleanup/rollback 阶段        |
+| 6️⃣ 状态统计   | 记录执行状态并输出汇总表                              |
+| 7️⃣ CLI 工具 | 实现 `bin/kdeploy` 命令入口                     |
+| 8️⃣ 测试与发布  | 使用 RSpec 添加测试，推送到 RubyGems                |
+
+---
+
+## 📝 初始化命令
+
+```bash
+bundle gem . --test=rspec --mit --coc --no-ext
+```
+
+