企业官网建设流程全解析

Dokku 高级安装完全指南：从源码安装、定制化引导到无人值守部署与低内存调优

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

本文是 Dokku（A docker-powered PaaS）安装主题的进阶篇，基于官方 advanced-installation.md 展开，并结合仓库内 bootstrap.sh、Makefile、debian/config、debian/templates、debian/postinst 与 Vagrantfile 等源码给出实现级依据。读者读完本文后，将掌握：从master分支直接安装 Dokku、从自己的 fork 仓库定制引导安装、自定义 Herokuish 构建栈、跳过非必要依赖、利用 debconf 实现 Debian 系无人值守安装，以及为低于 1 GB 内存的 VPS 扩容 swap 的完整实战方案。

一、概述：什么时候需要"高级安装"

对于大多数用户，Dokku 官方推荐直接运行bootstrap.sh完成安装。但在以下场景中，标准流程往往不够用：

• 托管在DigitalOcean、DreamHost Cloud、Microsoft Azure等特定云平台，需要额外的平台适配步骤；
• 希望从源码（master分支或指定 tag）安装，而非使用预编译的 Debian 包；
• 基于自己的 fork 仓库构建和引导服务器，携带私有定制；
• 希望跳过 Herokuish等推荐依赖，或自定义构建栈；
• 需要在无交互环境中批量、自动化安装（无人值守）；
• 目标虚拟机内存不足 1 GB，需要预先调整 swap。

这些场景正是本文要覆盖的内容。仓库中的 bootstrap.sh 是理解这一切的钥匙：它是一个"一切皆可覆盖"的引导脚本，几乎所有安装路径都可以通过环境变量重定向。

二、各托管平台与容器化的首选安装路径

原文档明确：某些托管平台有更合适的安装方式，应优先遵循平台专属文档，而不是直接跑通用脚本。仓库内对应文档位于 docs/getting-started/install/ 目录：

• DigitalOcean 安装说明
• DreamHost Cloud 安装说明
• Microsoft Azure 安装说明

与此同时，以下方式用于定制化安装或实验环境：

• Debian 包安装说明：自 0.3.18 起，Dokku 默认以 Debian 包方式安装，这也是bootstrap.sh实际执行的路径之一；
• 基于 Docker 的安装说明：在容器中运行 Dokku，适用于隔离/测试环境；
• Vagrant 安装说明：一键拉起本地虚拟机做开发与实验；
• 高级安装定制：即本文；
• 通过 Ansible 自动化部署（ansible-dokku 项目）。

值得强调的是，Docker 与 Vagrant 两种方式与本文的"源码安装"并不冲突：

• Docker 方式本质上是把 Dokku 封装成dokku/dokku镜像运行，容器首次启动时会自动执行引导（skeleton 还原、核心插件安装、ps:restore等），并通过/var/lib/dokku目录持久化数据；
• Vagrant 方式则直接复用本文介绍的源码安装：从仓库根目录的 Vagrantfile 可以看到，dokku虚拟机通过 NFS 将当前仓库同步到/root/dokku，然后执行make_cmd = "TARGETARCH=$(dpkg --print-architecture) DEBIAN_FRONTEND=noninteractive make -e install"（Vagrantfile），这正是下文"从源码安装"的自动化形态。Vagrant 还支持通过BOX_NAME、BOX_URI、BOX_MEMORY、DOKKU_DOMAIN、DOKKU_IP、FORWARDED_PORT等环境变量定制虚拟机。

三、从源码安装：直接使用 master 分支

Dokku 允许跳过预编译包，直接从最新的（可能不稳定）master分支安装。这是原文档给出的最直接方式：

# 使用分支参数即表示从源码安装 wget -NP . https://dokku.com/install/master/bootstrap.sh; sudo DOKKU_BRANCH=master bash bootstrap.sh

实现原理：查看 bootstrap.sh，install-dokku()函数的判断逻辑是——只要设置了DOKKU_BRANCH，就调用install-dokku-from-source "origin/$DOKKU_BRANCH"；只有当未设置分支、仅设置DOKKU_TAG时才可能走 Debian 包路径。install-dokku-from-source()（bootstrap.sh）的具体动作是：

1. 安装sudo git make等基础工具；
2. 将$DOKKU_REPO（默认https://github.com/dokku/dokku.git）克隆到/root/dokku；
3. git fetch origin后 checkout 指定分支/tag；
4. 执行make install。

因此sudo DOKKU_BRANCH=master bash bootstrap.sh的完整含义是：从默认仓库的master分支拉取源码并执行make install构建安装。脚本同时要求目标主机已设置 hostname（bootstrap.sh），否则会直接报错退出。

四、面向开发：从自己的仓库克隆安装

如果你打算参与 Dokku 开发，最简单的路径是克隆仓库后直接调用安装脚本：

git clone https://github.com/yourusername/dokku.git cd dokku sudo make install

make install的实际目标链定义在 Makefile 中：

install: dependencies version copyfiles plugin-dependencies plugins

即依次执行：apt-update与各类二进制依赖下载（dependencies）→ 写入版本号到/var/lib/dokku/VERSION（version）→ 编译 Go 插件并复制文件（copyfiles）→ 安装核心插件依赖（plugin-dependencies）→ 安装核心插件（plugins）。

覆盖源码 URL 的能力：Makefile允许通过环境变量覆盖默认依赖的下载地址。原文档提到四个关键变量，源码对应关系如下（Makefile）：

原文档给出的覆盖示例：

sudo SSHCOMMAND_URL=https://raw.githubusercontent.com/yourusername/sshcommand/master/sshcommand make install

此外，DOKKU_VERSION、TARGETARCH、PREBUILT_STACK_URL等变量同样可在构建时覆盖。从源码结构看，contrib/dependencies.json集中管理了docker-image-labeler、docker-container-healthchecker、lambda-builder、netrc、procfile-util、sshcommand等依赖的版本与 amd64/arm64 双架构下载地址，是定制安装时的重要参照文件。

五、用你自己的仓库引导一台服务器

bootstrap.sh允许通过DOKKU_REPO环境变量覆盖 Dokku 仓库地址，从而用你的 fork 引导一台全新主机：

wget -NP . https://dokku.com/install/master/bootstrap.sh; chmod +x bootstrap.sh sudo DOKKU_REPO=https://github.com/yourusername/dokku.git DOKKU_BRANCH=master ./bootstrap.sh

实现细节：脚本在main()中设置了export DOKKU_REPO=${DOKKU_REPO:-"https://github.com/dokku/dokku.git"}（bootstrap.sh），即未显式指定时回退到官方仓库；install-dokku-from-source()中直接使用该变量执行git clone "$DOKKU_REPO" /root/dokku（bootstrap.sh）。这意味着你可以：

• 用DOKKU_REPO+DOKKU_BRANCH组合指定任意仓库的任意分支；
• 用DOKKU_TAG指定精确版本标签（此时走"解析 tag → 判断版本 → 选择 Debian 包或源码"逻辑，见 bootstrap.sh）；
• 对 Debian 系主机，还可传递DOKKU_VHOST_ENABLE、DOKKU_HOSTNAME、DOKKU_SKIP_KEY_FILE、DOKKU_KEY_FILE、DOKKU_NGINX_ENABLE等变量，脚本会通过debconf-set-selections预先写入 debconf 选择（见下文"无人值守安装"）。

六、自定义 Herokuish 构建栈

Dokku 默认内置预编译版Herokuish（buildpack 执行组件）。如果你需要构建自己的版本，可通过环境变量指定：

git clone https://github.com/dokku/dokku.git cd dokku sudo BUILD_STACK=true STACK_URL=https://github.com/gliderlabs/herokuish.git make install

源码依据：Makefile中STACK_URL ?= https://github.com/gliderlabs/herokuish.git、PREBUILT_STACK_URL ?= gliderlabs/herokuish:latest-24（Makefile）。stacktarget 的逻辑（Makefile）是：

• 检测到/var/run/docker.sock存在且设置了BUILD_STACK时，执行git clone ${STACK_URL} /tmp/herokuish并从源码构建镜像；
• 未设置BUILD_STACK时，若PREBUILT_STACK_URL是 HTTP/file 地址则docker import，否则直接docker pull gliderlabs/herokuish。

也就是说：BUILD_STACK=true触发"从源码构建"，STACK_URL指向你想构建的 herokuish 仓库。Vagrantfile 中还支持通过本地stack.tgz文件（PREBUILT_STACK_URL='file:///root/dokku/stack.tgz'）离线导入预构建栈，适合网络受限环境。

七、跳过 Herokuish 安装

Herokuish 是推荐但非必需的依赖——如果你不使用 Heroku buildpack 部署，可以跳过它。Debian 系用户可以通过向apt-get传递--no-install-recommends来跳过该推荐依赖：

sudo DOKKU_NO_INSTALL_RECOMMENDS=" --no-install-recommends " bash bootstrap.sh

注意：这会同时跳过其他推荐依赖的安装，请确保你的部署方式（如 Dockerfile、CNB 或 nixpacks 构建）不依赖被跳过的组件。源码中该变量在install-dokku-from-deb-package()中生效：local NO_INSTALL_RECOMMENDS=${DOKKU_NO_INSTALL_RECOMMENDS:=""}，随后拼入apt-get -qq -y $NO_INSTALL_RECOMMENDS install dokku（bootstrap.sh）。另外，若设置了DOKKU_DOCKERFILE环境变量，脚本会自动强制加上--no-install-recommends（bootstrap.sh），以适配 Dockerfile 构建场景的最小化安装。

八、无人值守（Unattended）安装配置

Dokku 安装完成后，还必须配置virtualhost 设置与push 用户，否则安装被视为"未完成"，无法部署应用。Debian 系的无人值守安装依赖debconf机制：安装前通过debconf-set-selections预置选项，安装过程中 debian/config 会读取这些选择并以db_input "high"逐项弹出配置界面（无交互环境下则由预置值直接接管）。

8.1 设置全局域名与通配符解析

在使用 debconf 之前，请先通过域名服务商完成：

• 一个主域名；
• 指向 Dokku 主机的通配符域名（如*.dokku.me）。

全局域名由 domains 插件 管理，部署后应用 URL 会基于该域名生成（如yourapp.dokku.me）。推送用户的 SSH 密钥管理则遵循 用户管理文档：添加 SSH 密钥到 Dokku 用户，或为其他 Unix 账户授予 Dokku 访问权限。

8.2 debconf 预置命令示例

以启用 vhost 部署为例：

echo "dokku dokku/vhost_enable boolean true" | sudo debconf-set-selections

随后正常执行安装流程即可。除vhost_enable外，bootstrap.sh还会把以下环境变量映射为 debconf 选择（bootstrap.sh）：

8.3 完整 debconf 选项表

仓库 debian/templates 中定义了全部 debconf 模板，结合 Debian 安装文档 汇总如下：

其中install_default_site在 debian/templates 中有定义，且仅在debian/config的configure分支（非reconfigure）中被询问（debian/config）。从 debian/postinst 的实现看，该选项为 true 时会根据 nginx 版本（ssl_reject_handshake需要 nginx ≥ 1.19.4）选择default-site.conf或default-site-legacy.conf模板，安装到/etc/nginx/conf.d/00-default-vhost.conf，并移除冲突的 nginx 默认站点。

8.4 无人值守安装的完整流程

# 1. 安装 docker（bootstrap 脚本内部也会做） wget -nv -O - https://get.docker.com/ | sh # 2. 预置 debconf 选择（可按需增删） echo "dokku dokku/vhost_enable boolean true" | sudo debconf-set-selections echo "dokku dokku/hostname string dokku.me" | sudo debconf-set-selections echo "dokku dokku/nginx_enable boolean true" | sudo debconf-set-selections # 3. 添加 Dokku apt 源并安装（程序化探测发行版与代号） wget -qO- https://packagecloud.io/dokku/dokku/gpgkey | sudo tee /etc/apt/trusted.gpg.d/dokku.asc DISTRO="$(awk -F= '$1=="ID" { print tolower($2) ;}' /etc/os-release)" OS_ID="$(awk -F= '$1=="VERSION_CODENAME" { print tolower($2) ;}' /etc/os-release)" echo "deb https://packagecloud.io/dokku/dokku/${DISTRO}/ ${OS_ID} main" | sudo tee /etc/apt/sources.list.d/dokku.list sudo apt-get update -qq >/dev/null sudo apt-get -qq -y install dokku sudo dokku plugin:install-dependencies --core

安装后处理：debian/postinst的configure阶段会依次执行：创建dokku用户并加入 docker 组（setup-user）、创建数据目录（setup-storage）、根据vhost_enable/hostname写入/home/dokku/VHOST文件（dpkg-handling，见 debian/postinst）、启用并安装全部核心插件（setup-plugins）、写入 sshcommand 路径（setup-sshcommand）、启用 Docker live-restore（setup-docker-live-restore）以及可选安装 nginx 默认站点（setup-default-site）。注意：首次安装时若/home/dokku/VHOST已存在，脚本会跳过修改，因此提前写入自定义 VHOST 也是一种预置手段。

密钥自动导入：若dokku/key_file指向的公钥文件存在，dpkg-handling会通过sshcommand acl-add dokku default <"$RET"自动将其加入 Dokku 用户授权（debian/postinst）。若你选择skip_key_file=true，则必须按 用户管理文档 手动添加 SSH 密钥。

九、内存不足 1 GB 的虚拟机处理

Dokku 及其容器需要足够的系统内存，低于1 GB可能导致意外错误，例如部署 NPM 依赖时的! [remote rejected] master -> master (pre-receive hook declined)。bootstrap 脚本对此有主动检测：ensure-environment()会读取/proc/meminfo的MemTotal，当可用内存低于约 1003600 KB（约 1 GB）时打印警告并建议配置 swap（bootstrap.sh）。

原文档给出的缓解方案是：将 Linux swap 文件扩容到物理内存的两倍。以 512 MB 机器扩容到 1 GB 为例：

cd /var touch swap.img chmod 600 swap.img swapoff /var/swap.img dd if=/dev/zero of=/var/swap.img bs=1024k count=1000 mkswap /var/swap.img swapon /var/swap.img free echo "/var/swap.img none swap sw 0 0" >> /etc/fstab

注意事项：

• 若提示设备忙，可能需要显式调用sudo /sbin/swapoff /var/swap.img，再依次执行mkswap与swapon；
• 将 swap 条目写入/etc/fstab可保证重启后自动挂载；
• bs=1024k count=1000表示创建约 1000 MB 的 swap 文件，可根据实际内存按"两倍物理内存"的原则调整；
• 更大的 swap 建议使用dd写入后配合mkswap格式化，避免使用临时文件系统（如某些 VPS 的/tmp挂载）导致数据丢失。

十、FAQ 与排错速查

• pre-receive hook declined错误：最常见原因是内存不足导致构建阶段进程被杀，优先检查内存并按上节扩容 swap；其次确认 hostname 已正确设置（bootstrap.sh会硬性校验）。
• 安装被判定为"不完整"：检查dokku/vhost_enable是否已启用、dokku/hostname是否已设置、SSH 密钥是否已添加。三者缺一不可，否则无法部署应用。
• 如何确认从源码而非包安装：bootstrap 日志中会打印 "Preparing to install ..."，源码路径会克隆到/root/dokku并执行make install；包路径则会添加 packagecloud 的 apt 源。
• 不想弹任何交互：确保所有 debconf 选项都通过debconf-set-selections预置，或在命令前加上DEBIAN_FRONTEND=noninteractive（bootstrap 脚本自身也会导出该变量，见 bootstrap.sh）。
• 需要离线/内网安装：可预先准备stack.tgz供PREBUILT_STACK_URL使用（参考 Vagrantfile 的file://用法），并利用DOKKU_REPO指向内网镜像仓库。

十一、总结

高级安装的核心是理解 bootstrap.sh 与 Makefile 提供的"全链路环境变量覆盖"能力：DOKKU_REPO/DOKKU_BRANCH/DOKKU_TAG决定安装来源，DOCKER_URL/PLUGN_URL/SSHCOMMAND_URL/STACK_URL决定依赖来源，BUILD_STACK/DOKKU_NO_INSTALL_RECOMMENDS决定构建栈行为，而 debconf 系列选项（debian/templates）则让 Debian 系无人值守安装成为可能。无论你是要搭建生产环境的 Dokku 主机、基于 fork 做二次开发，还是在低配 VPS 上压榨性能，本文给出的命令与配置都可以直接落地，配合 Debian 包安装说明、Docker 安装说明 与 Vagrant 安装说明 可覆盖绝大多数安装诉求。

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