kdeploy 1.2.38 → 1.2.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29a2ac38f02097f22a48646d3d6483b4e3fd65513f01eb6044ba7efd85f9e51f
-  data.tar.gz: 27d6af727a2929a8fe7ec7bca6e7b63a8b2acc6a373ab73baa89b536fbb76941
+  metadata.gz: a38f6cd05a9b367146a9589800c65ebbc62a1c4192b6be8347d1156031c54d6b
+  data.tar.gz: 1cde973c19e35e14d299fbc2c8e307f2a69093d8a442d542a9db262f057213a4
 SHA512:
-  metadata.gz: 6ec34aac0c945e25101d9a3d91b68121660a5ab16d47cb7d8cb736805d83ef4f09fd92701351051449ecf6427f85f955a93384ef99cffebebeae09cf1b9a11e1
-  data.tar.gz: 416f3adfc65db0a5534cafc2853296fe585742470a482802ad08156f13acb1259ff86bf33c5a10c6c5d671eaae2b04b5a8de3c1f2bdfb0e82646a58bc3512cfd
+  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
 ```
 
@@ -636,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
 ```
 
@@ -703,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
 ```
 
@@ -734,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
 ```
 
@@ -814,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"
@@ -827,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
 ```
 
@@ -1070,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            # 执行
+```
 
 ### 常见部署场景
 
@@ -1111,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
 ```
 
@@ -1124,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
 ```
 
@@ -1146,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 配置）
 
 ## 🙏 致谢
 

data/README_EN.md

@@ -97,6 +97,12 @@ kdeploy version
 
 You should see the version information and banner.
 
+**If `kdeploy` is not found**: the gem executable directory may not be in your PATH. Add to `~/.zshrc` or `~/.bashrc` then run `source ~/.zshrc`:
+
+```bash
+export PATH="$(ruby -e 'puts Gem.bindir'):$PATH"
+```
+
 ### Shell Completion
 
 Kdeploy automatically configures shell completion during installation. If needed, manually add to your shell config:
@@ -136,35 +142,30 @@ This creates a new directory with:
 
 ### 2. Configure Hosts and Tasks
 
-Edit `deploy.rb`:
+Edit `deploy.rb` (using Chef-style resource DSL):
 
 ```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..."
-  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. Run Deployment
 
 ```bash
-kdeploy execute deploy.rb deploy
+kdeploy execute deploy.rb deploy_web
 ```
 
 ## 📖 Usage Guide
@@ -355,7 +356,7 @@ end
 
 ```ruby
 task :deploy_web, roles: :web do
-  run "sudo systemctl restart nginx"
+  service "nginx", action: :restart
 end
 ```
 
@@ -363,29 +364,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
 ```
 
 #### 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"
+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
 ```
 
@@ -542,8 +536,8 @@ task :deploy_nginx, roles: :web do
   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]
+  run "nginx -t", sudo: true
+  service "nginx", action: %i[enable restart]
 end
 ```
 
@@ -593,11 +587,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
 ```
 
@@ -658,15 +649,11 @@ Use Ruby conditionals in your deployment files:
 
 ```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
 ```
 
@@ -689,9 +676,10 @@ end
 
 ```ruby
 task :deploy do
-  run "sudo systemctl stop nginx" || raise "Failed to stop nginx"
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
-  run "sudo systemctl start nginx" || raise "Failed to start nginx"
+  service "nginx", action: :stop
+  file "/etc/nginx/nginx.conf", source: "./config/nginx.conf"
+  run "nginx -t", sudo: true  # run raises on invalid config
+  service "nginx", action: :start
 end
 ```
 
@@ -807,10 +795,9 @@ end
 ### 3. Use Templates for Dynamic Configuration
 
 ```ruby
-# ✅ Good - Use templates
-upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
-  domain_name: "example.com",
-  port: 3000
+# ✅ Good - Use template resource
+template "/etc/nginx/nginx.conf", source: "./config/nginx.conf.erb",
+  variables: { domain_name: "example.com", port: 3000 }
 
 # ❌ Avoid - Hardcoding values
 run "echo 'server_name example.com;' > /etc/nginx/nginx.conf"
@@ -820,12 +807,10 @@ run "echo 'server_name example.com;' > /etc/nginx/nginx.conf"
 
 ```ruby
 task :deploy do
-  # Validate configuration
-  run "nginx -t" || raise "Nginx configuration is invalid"
-
-  # Deploy
-  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 raises on invalid config
+  service "nginx", action: :reload
 end
 ```
 
@@ -1076,9 +1061,16 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
 
 ## 📚 Examples
 
-### Example Projects
+### Example Project
+
+The [sample/](sample/) directory in this repo provides a complete example with Nginx, Node Exporter, directory sync tasks, and Vagrant support for local testing:
 
-Check out the [example project](https://github.com/kevin197011/kdeploy-app) for a complete deployment setup.
+```bash
+cd sample
+vagrant up
+kdeploy execute deploy.rb deploy_web --dry-run  # Preview
+kdeploy execute deploy.rb deploy_web            # Execute
+```
 
 ### Common Deployment Scenarios
 
@@ -1119,12 +1111,21 @@ 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']
+  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
+```
+
+#### Directory Sync Deployment
 
-  run "sudo systemctl reload app"
+```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"]
+  service "app", action: :restart
 end
 ```
 
@@ -1137,7 +1138,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 - **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
+- **Sample**: [sample/](sample/) directory (includes Vagrant config)
 
 ## 🙏 Acknowledgments
 

data/lib/kdeploy/executor.rb

@@ -232,10 +232,12 @@ module Kdeploy
       # 如果命令已经以 sudo 开头，不重复添加
       return command if command.strip.start_with?('sudo')
 
-      # 对于多行命令或包含 shell 控制结构的命令，使用 bash -c 包装
-      is_multiline = command.include?("\n") || command.match?(/\b(if|for|while|case|function)\b/)
+      # 多行、shell 控制结构、或包含 && / || / ; 的复合命令需整段在 sudo 下执行
+      needs_wrap = command.include?("\n") ||
+                   command.match?(/\b(if|for|while|case|function)\b/) ||
+                   command.match?(/\s(&&|\|\||;)\s/)
 
-      if is_multiline
+      if needs_wrap
         # 转义命令中的单引号，然后用 bash -c 执行
         escaped_command = command.gsub("'", "'\"'\"'")
         if @sudo_password

data/lib/kdeploy/version.rb

@@ -2,5 +2,5 @@
 
 # Kdeploy module for version management
 module Kdeploy
-  VERSION = '1.2.38' unless const_defined?(:VERSION)
+  VERSION = '1.2.39' unless const_defined?(:VERSION)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kdeploy
 version: !ruby/object:Gem::Version
-  version: 1.2.38
+  version: 1.2.39
 platform: ruby
 authors:
 - Kk