Dokku 使用 tar/zip 归档初始化应用仓库：git:from-archive 完整指南

Dokku 使用 tar/zip 归档初始化应用仓库：git:from-archive 完整指南

【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku

导读

dokku git:from-archive是 Dokku 从 0.24.0 版本起提供的一条核心命令，它允许你从一个远程归档文件（tar / tar.gz / zip）或标准输入中初始化、更新应用的 git 仓库，随后触发一次完整的构建部署。本文以 archive.md 为骨架，结合 git 插件 的源码实现与安全测试用例，系统讲解命令用法、归档类型选择、作者信息定制、stdin 管道输入，以及内置的归档安全检查与全局属性调优，帮助你用一条命令把预构建二进制、发布包或指定 commit 的源码快照接入 Dokku 的构建流程。

归档部署的适用场景

git:from-archive的设计初衷是解决"代码仓库与应用构建产物分离"的部署需求。从文档与源码来看，以下场景尤其适合它：

• 预构建二进制归档：例如 Java 的 jar/war 包、Go 编译产物，直接以归档形式发布，Dokku 拿到后将其作为构建上下文执行构建（对应文档原句 "pre-built binary archives, such as java jars or go binaries"）；
• 指定 commit 的直接部署：直接从 GitHub 等平台的 release 下载链接（如https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar）拉取源码快照进行部署；
• 把归档内容当作应用源码：Dokku 会将归档解压后的内容视同仓库内的文件，走与普通 git 推送一致的 builder 流程（"Dokku will build the app as if the repository contained the extracted contents of the specified archive file"）。

从实现上看，git:from-archive最终通过 git-from-directory 触发，将解压得到的目录内容提交进应用仓库，并调用receive-app触发构建（见 internal-functions 中的cmd-git-from-archive）。

基本用法：从归档初始化应用仓库

标准命令格式

dokku git:from-archive <app> <archive-url> [<git-username> <git-email>]

官方示例（来源于 archive.md）：

dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar

执行后，Dokku 会完成以下工作：

1. 使用curl -# -L下载归档文件到临时目录（见 git-from-archive）；
2. 根据归档类型解压并剥离多余的顶层目录层级；
3. 调用git-from-directory触发器：若应用仓库尚不存在，则初始化新仓库并提交Initial commit；若已存在，则对比差异后提交Automated commit @ <timestamp>；
4. 触发构建并尝试部署。

重复构建的幂等行为

文档明确：用同一归档文件重复触发构建时，Dokku 会直接以0退出码提前结束，因为检测不到任何变更。对应实现位于 git-from-directory：执行git diff-index --quiet HEAD --后若无差异，会打印警告 "No changes detected, skipping git commit" 并提示如需强制重建可调用ps:rebuild。

dokku ps:rebuild node-js-app

定制提交作者信息

git:from-archive可选的第三个、第四个参数用于定制提交的user.name与user.email（顺序固定：先用户名后邮箱）：

dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar "Camila" "camila@example.com"

若留空，则回退到默认值Dokku与automated@dokku.sh。该默认值定义于 git-from-archive：

declare APP="$1" ARCHIVE_URL="$2" ARCHIVE_TYPE="$3" USER_NAME="${4:-Dokku}" USER_EMAIL="${4:-automated@dokku.sh}"

注意：源码中USER_EMAIL同样使用了第 4 个参数作为回退值，意味着若只传一个作者参数，它会同时充当用户名与邮箱；因此要正确设置邮箱，必须显式传入两个参数。

归档类型：--archive-type 标志

Dokku 默认把归档类型假定为.tar。若你的归档是其他格式，必须通过--archive-type显式指定，否则会因解压失败而报错。合法取值见 internal-functions：

dokku git:from-archive --archive-type zip node-js-app https://github.com/dokku/smoke-test-app/archive/2.0.0.zip "Camila" "camila@example.com"

源码层面的支持情况：

• 合法类型为tar、tar.gz、zip三种，非法类型会触发Invalid archive type specified, valid archive types include: tar, tar.gz, zip报错；
• tar 类归档在解压时还会自动计算公共顶层目录前缀并剥离（strip components），以兼容 GitHub 生成的repo-1.0.0/这类带版本目录的 tarball（见 git-from-archive）；
• 命令行参数解析中，--archive-type的值由 internal-functions 的循环单独提取，不会进入位置参数序列。

从标准输入读取归档

将归档 URL 位置替换为--，即可通过 stdin 管道传入归档内容。文档示例：

curl -sSL https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar | dokku git:from-archive node-js-app --

实现细节（见 git-from-archive）：当ARCHIVE_URL == "--"时，Dokku 通过tee将 stdin 内容落盘为src.<archive-type>再进入后续流程，并在日志中输出 "Fetching file from stdin"。stdin 模式下同样需要结合--archive-type指定非 tar 格式。

归档安全机制（Archive Safety）

解压前的三重校验

归档内容在解压前会被逐项验证，用于抵御路径穿越与符号链接逃逸攻击（详见 archive-functions）：

1. 绝对路径检查：任何以/开头的条目直接拒绝（rejected_absolute_path）；
2. 父目录穿越检查：包含..目录段的条目直接拒绝（rejected_path_traversal）；
3. 符号链接逃逸检查：通过tar -tvf的 verbose 输出解析每个 symlink 目标，绝对目标或以..开头的相对目标都会被拒绝（rejected_unsafe_symlink）。

解压完成后还会对解压目录再做一次 symlink 兜底校验fn-archive-validate-extracted-symlinks，确保没有任何链接指向解压目录之外。tar 解压时如果系统 tar 支持，还会附加--no-unsafe-links参数（见 archive-functions）。

以上行为均有测试覆盖，例如 tests/unit/archive-security.bats 中的用例：(archive-security) git:from-archive rejects tar with absolute paths、rejects tar with parent traversal、rejects tar with absolute symlink target、rejects tar with relative traversal symlink等。

全局属性：archive-max-size 与 archive-max-files

为防止 zip 炸弹（decompression bomb）一类的资源耗尽攻击，Dokku 提供两个全局 git 属性：

默认值常量定义于 archive-functions。校验逻辑（fn-archive-check-bomb-protection）会先比对归档文件实际大小，再统计 tar 条目数或unzip -l的条目数，超限即拒绝并记录安全事件。

设置属性：

dokku git:set --global archive-max-size 2147483648 dokku git:set --global archive-max-files 20000

恢复默认（不传值即为 unset）：

dokku git:set --global archive-max-size

archive-max-files与archive-max-size被收录在git:set的合法 key 列表VALID_KEYS中（见 subcommands/set），可通过dokku git:set --help查看完整说明。

审计日志

所有安全相关事件（拒绝原因、解压开始/完成）都会以[archive-security]前缀写入 stderr，包含时间戳、执行用户、事件类型、归档类型与来源，便于审计排查（见 archive-functions 的fn-archive-log-security-event）。

查看当前属性配置

通过git:report查看归档相关的全局配置：

dokku git:report --global

输出中会包含Git global archive-max-size、Git global archive-max-files以及计算后的最终生效值。也可以按 key 精确查询：

dokku git:report --global --git-global-archive-max-size dokku git:report --global --git-computed-archive-max-size dokku git:report --global --git-global-archive-max-files dokku git:report --global --git-computed-archive-max-files

上述查询行为均有对应测试用例验证（见 tests/unit/archive-security.bats），包括设置新值后查询能读到更新后的数值、unset 后恢复默认等场景。

补充阅读

• Deployment Methods 总览
• git:sync / git:from-image 等其他仓库初始化方式（git:from-archive与它们同属 git 插件 的能力矩阵）
• 归档校验的完整测试套件：tests/unit/archive-security.bats
• git 插件其余子命令（git:set、git:report、git:from-image、git:sync）的实现位于 plugins/git

【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku