kdeploy 1.2.33 → 1.2.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba776f38e5a34ec7e6dac606aac7202391fdab2e4869aec08f526b3228bc8deb
-  data.tar.gz: aaa348b87ad83b9c8c1ad3291a2e45395594b922c1594fa82d54cd2a9b7c6d30
+  metadata.gz: a38f6cd05a9b367146a9589800c65ebbc62a1c4192b6be8347d1156031c54d6b
+  data.tar.gz: 1cde973c19e35e14d299fbc2c8e307f2a69093d8a442d542a9db262f057213a4
 SHA512:
-  metadata.gz: 7d731fd05fddc4b03c0aaef558e5200b6584772159262405d80cf807eae5f096689201e60aad944f0dd51b2a5e0db7d1d883476ec945cd3984a19383c840830c
-  data.tar.gz: 6ce986d5b3a60685ed51340298a0d0fbe22d25c2ee7c7cf584b3870d23174d004597e5135c7bb52a2f2f1d1006806c552d49ddcdb92080808348a580ec865947
+  metadata.gz: 9db48da0d7a90fa51389c2311b0aaea919cc87d4e47360ce3323f5202a96d3998e955819a5d39528f998f9edb2d4f90808bfd5dfdab1b2ea47c4f443a57452b5
+  data.tar.gz: 98d5a5c755f1a75e2491f4a8d09e1842851bf077316f6a50f11f964ebaef334f6b6666017d8a78b4918dcef4f17d8e181e4d60e5867212db3bea163d6c860c0e

data/README.md

@@ -98,6 +98,12 @@ kdeploy version
 
 您应该看到版本信息和横幅。
 
+**若找不到 `kdeploy` 命令**：gem 的可执行目录可能不在 PATH 中。将以下内容加入 `~/.zshrc` 或 `~/.bashrc` 后执行 `source ~/.zshrc`：
+
+```bash
+export PATH="$(ruby -e 'puts Gem.bindir'):$PATH"
+```
+
 ### Shell 自动补全
 
 Kdeploy 在安装期间自动配置 shell 自动补全。如果需要，可以手动添加到 shell 配置中：
@@ -137,35 +143,30 @@ kdeploy init my-deployment
 
 ### 2. 配置主机和任务
 
-编辑 `deploy.rb`:
+编辑 `deploy.rb`（使用 Chef 风格资源 DSL）:
 
 ```ruby
 # 定义主机
 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"
-
-# 定义角色
 role :web, %w[web01 web02]
 
 # 定义部署任务
-task :deploy, roles: :web do
-  run <<~SHELL
-    sudo systemctl stop nginx
-    echo "正在部署应用程序..."
-  SHELL
-
-  upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
-    domain_name: "example.com",
-    port: 3000
-
-  run "sudo systemctl start nginx"
+task :deploy_web, roles: :web do
+  package "nginx"
+  directory "/etc/nginx/conf.d"
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb",
+    variables: { domain_name: "example.com", port: 3000 }
+  file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+  run "nginx -t", sudo: true
+  service "nginx", action: %i[enable restart]
 end
 ```
 
 ### 3. 运行部署
 
 ```bash
-kdeploy execute deploy.rb deploy
+kdeploy execute deploy.rb deploy_web
 ```
 
 ## 📖 使用指南
@@ -356,7 +357,7 @@ end
 
 ```ruby
 task :deploy_web, roles: :web do
-  run "sudo systemctl restart nginx"
+  service "nginx", action: :restart
 end
 ```
 
@@ -364,29 +365,22 @@ end
 
 ```ruby
 task :maintenance, on: %w[web01] do
-  run <<~SHELL
-    sudo systemctl stop nginx
-    sudo apt-get update && sudo apt-get upgrade -y
-    sudo systemctl start nginx
-  SHELL
+  service "nginx", action: :stop
+  run "apt-get update && apt-get upgrade -y", sudo: true
+  service "nginx", action: %i[start enable]
 end
 ```
 
 #### 多命令任务
 
 ```ruby
-task :deploy, roles: :web do
-  # 停止服务
-  run "sudo systemctl stop nginx"
-
-  # 上传配置
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
-
-  # 启动服务
-  run "sudo systemctl start nginx"
-
-  # 验证状态
-  run "sudo systemctl status nginx"
+task :deploy_web, roles: :web do
+  package "nginx"
+  directory "/etc/nginx/conf.d"
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb", variables: { port: 3000 }
+  file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+  run "nginx -t", sudo: true
+  service "nginx", action: %i[enable restart]
 end
 ```
 
@@ -529,6 +523,67 @@ sync "./config", "/etc/app",
 - 同步静态资源文件
 - 保持本地和远程目录结构一致
 
+### Chef 风格资源 DSL
+
+Kdeploy 提供类似 Chef 的声明式资源 DSL，可替代或与底层原语（`run`、`upload`、`upload_template`）混用。
+
+#### `package` - 安装系统包
+
+```ruby
+package "nginx"
+package "nginx", version: "1.18"
+package "nginx", platform: :yum  # CentOS/RHEL
+```
+
+默认使用 apt（Ubuntu/Debian）；`platform: :yum` 生成 yum 命令。
+
+#### `service` - 管理系统服务（systemd）
+
+```ruby
+service "nginx", action: [:enable, :start]
+service "nginx", action: :restart
+service "nginx", action: [:stop, :disable]
+```
+
+支持 `:start`、`:stop`、`:restart`、`:reload`、`:enable`、`:disable`。
+
+#### `template` - 部署 ERB 模板
+
+```ruby
+template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb", variables: { port: 3000 }
+# 或 block 语法
+template "/etc/app.conf" do
+  source "./config/app.erb"
+  variables(domain: "example.com")
+end
+```
+
+#### `file` - 上传本地文件
+
+```ruby
+file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+```
+
+#### `directory` - 确保远程目录存在
+
+```ruby
+directory "/etc/nginx/conf.d"
+directory "/var/log/app", mode: "0755"
+```
+
+**示例：使用资源 DSL 部署 Nginx**
+
+```ruby
+task :deploy_nginx, roles: :web do
+  package "nginx"
+  directory "/etc/nginx/conf.d"
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb", variables: { port: 3000 }
+  file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+  run "nginx -t"
+  service "nginx", action: [:enable, :restart]
+end
+```
+
 ### 模板支持
 
 Kdeploy 支持 ERB（嵌入式 Ruby）模板，用于动态配置生成。
@@ -575,11 +630,8 @@ http {
 
 ```ruby
 task :deploy_config do
-  upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
-    domain_name: "example.com",
-    port: 3000,
-    worker_processes: 4,
-    worker_connections: 2048
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb",
+    variables: { domain_name: "example.com", port: 3000, worker_processes: 4, worker_connections: 2048 }
 end
 ```
 
@@ -642,15 +694,11 @@ verify_host_key: true
 
 ```ruby
 task :deploy do
-  if ENV['ENVIRONMENT'] == 'production'
-    run "sudo systemctl stop nginx"
-  end
+  service "nginx", action: :stop if ENV['ENVIRONMENT'] == 'production'
 
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
+  file "/etc/nginx/nginx.conf", source: "./config/nginx.conf"
 
-  if ENV['ENVIRONMENT'] == 'production'
-    run "sudo systemctl start nginx"
-  end
+  service "nginx", action: :start if ENV['ENVIRONMENT'] == 'production'
 end
 ```
 
@@ -673,9 +721,10 @@ end
 
 ```ruby
 task :deploy do
-  run "sudo systemctl stop nginx" || raise "停止 nginx 失败"
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
-  run "sudo systemctl start nginx" || raise "启动 nginx 失败"
+  service "nginx", action: :stop
+  file "/etc/nginx/nginx.conf", source: "./config/nginx.conf"
+  run "nginx -t" || raise "Nginx 配置无效"
+  service "nginx", action: :start
 end
 ```
 
@@ -753,10 +802,9 @@ end
 ### 3. 使用模板进行动态配置
 
 ```ruby
-# ✅ 好的做法 - 使用模板
-upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
-  domain_name: "example.com",
-  port: 3000
+# ✅ 好的做法 - 使用 template 资源
+template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb",
+  variables: { domain_name: "example.com", port: 3000 }
 
 # ❌ 避免 - 硬编码值
 run "echo 'server_name example.com;' > /etc/nginx/nginx.conf"
@@ -766,12 +814,10 @@ run "echo 'server_name example.com;' > /etc/nginx/nginx.conf"
 
 ```ruby
 task :deploy do
-  # 验证配置
-  run "nginx -t" || raise "Nginx 配置无效"
-
-  # 部署
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
-  run "sudo systemctl reload nginx"
+  template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb", variables: { port: 3000 }
+  file "/etc/nginx/conf.d/app.conf", source: "./config/app.conf"
+  run "nginx -t", sudo: true  # 配置无效时 run 会抛异常
+  service "nginx", action: :reload
 end
 ```
 
@@ -875,7 +921,6 @@ kdeploy execute deploy.rb deploy --parallel 3
 - **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`): 配置管理
@@ -885,10 +930,9 @@ kdeploy execute deploy.rb deploy --parallel 3
 
 1. **解析配置**: 加载并解析 `deploy.rb`
 2. **解析主机**: 根据任务定义确定目标主机
-3. **分组命令**: 按类型分组命令以提高执行效率
-4. **并发执行**: 跨主机并行运行任务
-5. **收集结果**: 收集执行结果和状态
-6. **显示输出**: 格式化并向用户显示结果
+3. **并发执行**: 跨主机并行运行任务，按序执行每台主机上的命令
+4. **收集结果**: 收集执行结果和状态
+5. **显示输出**: 格式化并向用户显示结果
 
 ### 并发模型
 
@@ -928,7 +972,6 @@ kdeploy/
 │       ├── executor.rb         # SSH/SCP 执行器
 │       ├── runner.rb           # 任务运行器
 │       ├── command_executor.rb # 命令执行器
-│       ├── command_grouper.rb  # 命令分组器
 │       ├── template.rb         # 模板处理器
 │       ├── output.rb           # 输出接口
 │       ├── configuration.rb    # 配置
@@ -1012,7 +1055,14 @@ bundle exec rubocop -a
 
 ### 示例项目
 
-查看 [示例项目](https://github.com/kevin197011/kdeploy-app) 以获取完整的部署设置。
+本仓库的 [sample/](sample/) 目录提供完整示例，包含 Nginx、Node Exporter、目录同步等任务，支持 Vagrant 本地测试：
+
+```bash
+cd sample
+vagrant up
+kdeploy execute deploy.rb deploy_web --dry-run  # 预览
+kdeploy execute deploy.rb deploy_web            # 执行
+```
 
 ### 常见部署场景
 
@@ -1053,12 +1103,9 @@ end
 
 ```ruby
 task :update_config, roles: :web do
-  upload_template "./config/app.yml.erb", "/etc/app/config.yml",
-    environment: "production",
-    database_url: ENV['DATABASE_URL'],
-    redis_url: ENV['REDIS_URL']
-
-  run "sudo systemctl reload app"
+  template "/etc/app/config.yml", source: "./config/app.yml.erb",
+    variables: { environment: "production", database_url: ENV['DATABASE_URL'], redis_url: ENV['REDIS_URL'] }
+  service "app", action: :reload
 end
 ```
 
@@ -1066,16 +1113,11 @@ end
 
 ```ruby
 task :deploy_app, roles: :web do
-  # 同步应用程序代码，忽略开发文件
   sync "./app", "/var/www/app",
     ignore: [".git", "*.log", "node_modules", ".env.local", "*.tmp"],
     delete: true
-
-  # 同步配置文件
-  sync "./config", "/etc/app",
-    exclude: ["*.example", "*.bak"]
-
-  run "sudo systemctl restart app"
+  sync "./config", "/etc/app", exclude: ["*.example", "*.bak"]
+  service "app", action: :restart
 end
 ```
 
@@ -1088,7 +1130,7 @@ end
 - **GitHub**: https://github.com/kevin197011/kdeploy
 - **RubyGems**: https://rubygems.org/gems/kdeploy
 - **Issues**: https://github.com/kevin197011/kdeploy/issues
-- **示例项目**: https://github.com/kevin197011/kdeploy-app
+- **示例**: [sample/](sample/) 目录（含 Vagrant 配置）
 
 ## 🙏 致谢