# deploy-services

**Repository Path**: kolonse_zhjsh/deploy-services

## Basic Information

- **Project Name**: deploy-services
- **Description**: No description available
- **Primary Language**: Go
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-07-24
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# deploy-services 项目使用文档

# 一、项目介绍

本项目是一款局域网内一键部署工具，适用于服务数量多、节点分布广的场景。仅需在一台机器上操作，即可完成所有节点的部署工作，同时支持配置统一管理、节点统一管理，大幅降低项目部署的复杂度，提升部署效率。

# 二、配置文件介绍

项目启动时默认加载配置文件 `service.kcfg`；若存在多个配置文件，可通过命令 `deploy-cli use --file 文件名` 指定使用的配置文件，后续启动将自动加载该指定文件。

# 三、核心关键字说明

## 3.1 package 关键字

用于定义项目依赖的压缩包，在执行 commit 操作时，会检查压缩包的大小和修改日期，仅当两者有一项发生变化时，才会对压缩包进行解压缩处理。

```plain text
package {
    test.tar.gz
}
```

## 3.2 public 关键字

用于定义公共资源，可被多个服务共享，减少重复配置和资源冗余。

```plain text
public {
    name test                  # 公共资源名称
    nodes [                    # 公共资源要部署的节点列表
        test
    ]
    
    # source 解压缩后的依赖文件，作为对比基准的目录
    depends [                  # 依赖的目录或文件列表
        test/lib
        test/conf
        test/data
    ]

    # persist 持久化列表，仅同步一次，后续即使依赖包更新也不重复同步
    # 注意：持久化目录必须在 depends 列表中存在
    persist [
        test/data
    ]
    
    after_active {             # 资源激活后执行的 Linux Shell 命令
        cmd ls -la             # 命令1
        cmd pwd                # 命令2
    }
}
```

## 3.3 environment 关键字

用于定义环境变量，若服务指定了依赖的环境变量，在执行启动、停止等命令前，会自动先执行环境变量赋值操作。

```plain text
environment {
    name test                  # 环境变量配置名称
    # 环境变量类型说明：
    # system：路径需格式化，例如 export LD_LIBRARY_PATH=XXX:$LD_LIBRARY_PATH
    # normal：直接赋值，格式为 export TEST="xxx"
    # path：路径类型，会自动转换为绝对路径
    env {
        # 环境变量1：LD_LIBRARY_PATH
        LD_LIBRARY_PATH {
            type system
            value test/lib
        }
        
        # 环境变量2：PATH
        PATH {
            type system
            value test/bin
        }
        
        # 环境变量3：NAME（普通值类型）
        NAME {
            type normal
            value Test
        }
        
        # 环境变量4：NAME2（路径类型）
        NAME2 {
            type path
            value test/bin
        }
    }
}
```

## 3.4 configure 关键字

用于定义配置文件的替换行为，在服务激活时会自动执行配置文件替换操作，支持动态变量替换。

```plain text
configure {
    name test                  # 配置名称
    config {                   # 需要替换的配置文件列表
        # 1. ini 格式配置文件
        test/conf/test.ini {
            type ini
            key a.b true       # 格式：区块名.关键字 值
        }
        
        # 2. json 格式配置文件
        test/conf/common_conf.json {
            type json
            body ```
                {
                    "nacos": {},
                    "redis": {}
                }
            ```               # json 格式内容
        }
        
        # 3. 文本格式配置文件（通过模板替换）
        test/conf/test.conf {
            type text
            template test/test.conf  # 模板文件路径
        }
    }
}
```

补充说明：替换内容支持动态变量，格式为 `{{node.变量名}}` 或 `{{service.变量名}}`，其中 `node` 和 `service` 为固定前缀，变量名可在对应关键字中自定义，服务激活时会自动替换为对应值。

## 3.5 node 关键字

用于定义服务节点信息，可定义多个节点，支持节点分组（名称相同的节点为一组，控制时指定名称即可操作整个分组）。

```plain text
node {
    name test                  # 节点名称（可重复，实现分组）
    record_dir $RECORD_DIR     # 记录目录
    system linux               # 节点系统类型
    base /home/xxx/package     # 数据部署目录
    host a.b.c.d               # 节点IP地址
    local a.b.c.d              # 内网网卡IP
    external a.b.c.d           # 外网网卡IP
    driver {                   # 节点连接方式
        name ssh               # 连接协议（此处为ssh）
        args "$SSH_USER $SSH_PASS"  # 连接参数（用户名 密码）
    }
}
```

补充说明：可给节点定义自定义变量（如 `local`、`external`），在 `configure` 中通过 `{{node.变量名}}` 替换，适配不同节点的配置差异（如节点IP不同的场景）。

## 3.6 service 关键字

用于定义具体的服务信息，包括服务的启动、停止、健康检查等配置，以及依赖的资源、环境变量等。

```plain text
service {
    name test                  # 服务名称
    # 启动命令定义
    start_command {
        bind_env true          # 是否绑定环境变量（true则执行环境变量赋值）
        cmd ```
            export LD_LIBRARY_PATH
            if [[ `pgrep -fc "$(pwd)/$name -ncwait -nonat -base $(pwd)/.."` -gt 0  ]]; then
                echo "$name Running"
                exit 0
            fi	
            $(pwd)/$name -ncwait -nonat -base $(pwd)/..
            echo "$name Started"
        ```
    } 
    # 停止命令定义
    stop_command {
        bind_env true
        cmd ```
            export LD_LIBRARY_PATH
            if [[ `pgrep -fc "$(pwd)/$name -ncwait -nonat -base $(pwd)/.."` -gt 0  ]]; then
                pkill -9 -f "$(pwd)/$name -ncwait -nonat -base $(pwd)/.."
                echo "$name exit"
                exit 0
            fi	
            echo "$name Not Running"
        ```
    }
    # 健康检查命令定义（返回1表示运行正常，0表示未运行）
    health_command {
        bind_env true
        cmd ```
            export LD_LIBRARY_PATH
            if [[ `pgrep -fc "$(pwd)/$name -ncwait -nonat -base $(pwd)/.."` -gt 0  ]]; then
                echo 1
                exit 0
            fi
            echo 0
        ```
    }
    
    nodes [test]               # 服务要部署的节点列表（对应node关键字的name）
    # 依赖文件：检查每个文件的MD5值，变化则上传
    depends [test/bin/test]
    # 可执行文件：激活后自动添加可执行权限
    execute [test/bin/test]
    # 依赖的公共资源：格式为“资源名 资源文件”，必须在public中定义
    public [test test/conf]
    workdir test/bin           # 服务工作目录（bind_env=true时自动设置）
    environment test           # 依赖的环境变量（对应environment关键字的name）
    configure test             # 依赖的配置（对应configure关键字的name）
    # 服务激活后执行的命令
    after_active {
        cmd ```echo "test"```
    }
}
```

补充说明：可给服务定义自定义变量，在 `configure` 中通过 `{{service.变量名}}` 获取，实现配置的动态替换。

## 3.7 include 关键字

当配置文件过大时，可将配置按功能分类拆分到多个文件，通过 `include 配置文件名` 将其他配置文件的内容包含进来，简化配置管理。

## 3.8 crontab 关键字

用于定义计划任务服务，可指定节点、执行时间和具体任务。

```plain text
crontab {
    name test                  # 计划任务名称
    nodes [test]               # 执行计划任务的节点列表
    scripts {scripts/test.py}  # 依赖的外部脚本文件列表
    cron "* * * * *"           # 计划任务时间（标准crontab格式）
    task ```python test.py```   # 计划任务执行的命令
}
```

# 四、启动方式

```bash
# 1. 后台启动（默认方式）
./deploy-services -D 

# 2. 指定服务端口并后台启动
./deploy-services -p 10802 -D
```

# 五、Command 命令列表

可通过 `./deploy-cli -h` 查看所有一级命令列表，以下是常用命令详细说明：

## 5.1 基础配置命令

```bash
# 配置deploy-cli连接的deploy-services服务IP和端口（仅需配置一次）
# 后续使用命令无需再指定-H、-p参数
./deploy-cli config -H [host=127.0.0.1] -p [port=10802]
```

## 5.2 守护进程命令

```bash
# 控制服务守护进程（检测服务退出时自动重启）
# --name：指定服务名称（可选，不指定则控制所有服务）
deploy-cli daemon start/status/stop --name [service name]
# start：开启守护进程；stop：关闭守护进程；status：查看守护进程状态
```

## 5.3 差异查看命令

```bash
# 查看当前service依赖文件的变化列表
deploy-cli diff
```

## 5.4 节点操作命令

```bash
# 1. 在指定节点执行shell命令
deploy-cli node cmd --node [node name] --cmd [执行命令]

# 2. 启用/禁用指定节点
deploy-cli node enable --node [node name] --enable [true/false]

# 3. 显示所有节点信息
deploy-cli node show
```

## 5.5 发布包操作命令

包名列表需在 `package` 关键字中指定（如 `package {a.tar.gz; b.tar.gz}`）。

```bash
# 1. 提交包更新（检测包大小/日期变化，变化则自动解压缩到data目录）
deploy-cli package commit

# 2. 上传文件到package目录
deploy-cli package push --file [file path]
```

## 5.6 公共资源操作命令

适用于公共依赖库、资源文件等更新频率较低的内容管理。

```bash
# 1. 提交公共资源更新
# --name：指定公共资源名称（可选，不指定则提交所有变化的公共资源）
# --force：强制提交（无论是否有变化）
deploy-cli public commit --name [public name] --force

# 2. 激活公共资源（将新提交的资源同步到指定节点）
deploy-cli public active --name [public name] --force

# 3. 显示所有已激活的公共资源（含时间、大小信息）
deploy-cli public show
```

## 5.7 配置重载命令

```bash
# 重新加载配置文件，刷新service文件的MD5值（配置/依赖文件变化后需执行）
deploy-cli reload
```

## 5.8 服务操作命令

可选参数说明：`--node`（指定节点，不填则操作所有相关节点）、`--name`（指定服务，不填则操作所有服务）、`--force`（强制操作）。

```bash
# 1. 提交服务依赖文件变化到远程节点
deploy-cli service commit --name [service name] --force

# 2. 激活远程服务（提交后执行）
deploy-cli service active --name [service name] --force

# 3. 在指定服务的节点上执行shell命令
deploy-cli service cmd --name [service name] --cmd [linux shell]

# 4. 查看指定服务的健康状态
deploy-cli service health --name [service name] --node [node name]

# 5. 查看指定服务的commit历史
deploy-cli service history --name [service name]

# 6. 启动/停止/重启指定服务
deploy-cli service start/stop/restart --name [service name] --node [node name]

# 7. 上传文件到指定服务的工作目录
deploy-cli service push --name [service name] --node [node name] --file [file path]

# 8. 显示指定服务的详细信息（依赖、命令等）
deploy-cli service show --name [service name]

# 9. 服务同步（一键执行停止→公共资源提交→公共资源激活→服务提交→服务激活→启动）
deploy-cli service sync --name [service name]
```

## 5.9 全局同步命令

```bash
# 全局同步（一键执行包提交→公共资源提交→公共资源激活→服务提交→服务激活）
deploy-cli sync
```

## 5.10 配置文件切换命令

```bash
# 指定远端使用的配置文件（多配置文件场景）
deploy-cli use
```

## 5.11 版本管理命令

```bash
# 1. 打tag（发版前执行，用于版本回退）
deploy-cli tag

# 2. 版本回退
deploy-cli rollback

# 3. 清理历史版本（tag和当前激活版本不会被清理）
deploy-cli clean
```

# 六、常见使用场景

## 场景1：更新public资源的某个文件

前提配置（示例）：

```plain text
public {
    name test
    nodes [test]
    depends [test/scripts]
}

service {
    name test
    public [test test/scripts]  # 依赖public资源
}
```

操作步骤：

```bash
# 方式1：分步执行
./deploy-cli public commit --name test --force
./deploy-cli public active --name test --force
./deploy-cli service active --name test --force
./deploy-cli service restart --name test

# 方式2：一键同步（推荐）
./deploy-cli service sync --name test
```

## 场景2：更新服务配置文件

```bash
# 方式1：分步执行
./deploy-cli reload
./deploy-cli service active --name [service name] --force
./deploy-cli service restart --name [service name]

# 方式2：一键同步（推荐）
./deploy-cli service sync --name [service name]
```

## 场景3：更新service依赖文件

```bash
# 方式1：分步执行
./deploy-cli service commit --name [service name]
./deploy-cli service active --name [service name]
./deploy-cli service restart --name [service name]

# 方式2：一键同步（推荐）
./deploy-cli service sync --name [service name]
```

## 场景4：更新public依赖文件

```bash
# 方式1：分步执行
./deploy-cli public commit --name [public name]
./deploy-cli public active --name [public name]
./deploy-cli service active --name [service name]
./deploy-cli service restart --name [service name]

# 方式2：一键同步（推荐）
./deploy-cli service sync --name [service name]
```
> （注：文档部分内容可能由 AI 生成）