Dandelion 项目技术文档

1. 安装指南

1.1 环境要求

在安装 Dandelion 之前，请确保您的系统已安装 Ruby 2.0.0 或更高版本。

1.2 安装步骤

1. 使用以下命令安装 Dandelion：

   $ gem install dandelion
   

2. 如果您的系统尚未安装 pkg-config 和 cmake，请先安装它们。您可以通过操作系统的包管理器进行安装：

   • 对于 macOS 用户：

     $ brew install pkg-config cmake
     

   • 对于 Debian/Ubuntu 用户：

     $ apt-get install pkg-config cmake
     

3. 如果您使用的是操作系统包管理器安装的 Ruby，可能需要安装 Ruby 头文件：

   • 对于 Debian 用户：

     $ apt-get install ruby-dev
     

   • 对于 Ubuntu 用户：

     $ apt-get install ruby-all-dev
     

2. 项目的使用说明

2.1 配置文件

Dandelion 的配置选项通过 YAML 文件指定。默认情况下，Dandelion 会在 Git 仓库的根目录下查找名为 dandelion.yml 的文件。

示例配置文件：

adapter: sftp
host: example.com
username: user
password: pass
path: path/to/deployment

exclude:
    - .gitignore
    - dandelion.yml
    - dir/

additional:
    - config/auth.yml

配置项说明：

• 必填项：
  • adapter：文件传输适配器（如 sftp、ftp、ftps、s3）。
• 可选项：
  • path：远程文件树的相对路径，默认为根目录。
  • local_path：本地仓库的相对路径，默认为仓库根目录。
  • exclude：排除部署的文件或目录列表。
  • additional：从工作目录中额外部署的文件列表。
  • revision_file：存储修订 SHA 的远程文件，默认为 .revision。

2.2 动态配置

您可以使用环境变量动态设置配置值。例如：

password: <%= ENV['DANDELION_PASSWORD'] %>

3. 项目 API 使用文档

3.1 适配器

Dandelion 支持多种后端文件传输适配器，每个适配器都有其特定的配置参数。

SFTP 适配器

• 必填项：
  • host
  • username
  • password（如果使用 SSH 密钥，则不需要）
• 可选项：
  • port（默认为 22）
  • preserve_permissions（默认为 true）

FTP 适配器

• 必填项：
  • host
  • username
  • password
• 可选项：
  • port（默认为 21）
  • passive（默认为 false）

FTPS 适配器

• 必填项：与 FTP 相同。
• 可选项：
  • port
  • passive
  • ftps_implicit（默认为 false，表示显式 TLS）
  • insecure（默认为 false，允许自签名证书）

Amazon S3 适配器

• 必填项：
  • access_key_id
  • secret_access_key
  • bucket_name
  • host（默认为 s3.amazonaws.com）
• 可选项：
  • preserve_permissions（默认为 true）
  • cache_control（缓存内容的时间，单位为秒）
  • expires（缓存内容的时间，单位为秒）

4. 项目安装方式

4.1 部署命令

在 Git 仓库中运行以下命令进行部署：

$ dandelion deploy

此命令会将本地 HEAD 修订版部署到配置文件中指定的位置。Dandelion 会跟踪当前部署的修订版，以便仅传输已添加/更改/删除的文件。

4.2 指定修订版部署

您可以指定要部署的修订版，Dandelion 将确定需要传输的文件：

$ dandelion deploy <revision>

4.3 查看帮助

要查看完整的用法摘要，请运行：

$ dandelion -h

要查看特定命令的选项，请运行：

$ dandelion <command> -h

4.4 其他命令

• init：初始化 Dandelion 配置。
• status：查看当前部署状态。

通过以上文档，您可以轻松安装、配置和使用 Dandelion 进行 Git 仓库的增量部署。