ARTICLE DETAIL

建站实战干货

来自一线的建站与推广经验沉淀，每一条都经过真实交付验证。

首页 / 资讯中心 / 正文

Azkaban单机版安装配置指南：从零搭建开源工作流调度系统

2026/8/7 2:01:58 拓冰建站 浏览量
Azkaban单机版安装配置指南：从零搭建开源工作流调度系统

1. 项目概述：为什么我们需要Azkaban？

在数据开发与运维的日常工作中，任务调度是一个绕不开的核心环节。想象一下，你手头有几十个甚至上百个数据处理脚本，它们之间存在着复杂的依赖关系：脚本B必须在脚本A成功运行后才能启动，而脚本C又依赖于B和另一个脚本D的输出。如果全靠人工手动触发，不仅效率低下，而且极易出错，尤其是在凌晨需要定时执行的任务，对开发人员来说简直是噩梦。

这时，一个可靠的任务调度系统就显得至关重要。Azkaban正是为解决这类问题而生的开源工作流调度器，由LinkedIn开发并开源。它通过简单的Web界面，允许你以可视化的方式定义、调度和监控复杂的工作流。其核心优势在于“配置即代码”的理念，使用易于理解的.job和.flow文件来描述任务及其依赖关系，学习成本相对较低。对于中小型团队或个人开发者而言，从单机版开始部署和试用Azkaban，是理解其工作原理、验证工作流设计的最佳途径。本教程将手把手带你完成Azkaban的下载、安装及单机模式配置，让你能快速搭建起一个可用的本地调度环境，为后续的自动化数据流水线开发打下坚实基础。

2. 环境准备与前置依赖检查

在开始安装Azkaban之前，确保你的服务器或本地开发环境满足基本要求，可以避免后续出现许多令人头疼的兼容性问题。

2.1 系统与Java环境

Azkaban是基于Java构建的，因此一个正确配置的JDK环境是首要条件。

  1. 操作系统：Azkaban兼容主流Linux发行版（如CentOS、Ubuntu）和macOS。在Windows上部署相对复杂，通常建议在WSL2或虚拟机中进行。本教程以Linux环境（Ubuntu 20.04 LTS）为例进行说明。
  2. Java版本：Azkaban 3.x版本需要JDK 8或JDK 11。强烈建议使用JDK 8，因为这是经过最广泛测试的版本。你可以通过以下命令检查：
    java -version
    如果显示版本为1.8.x，则符合要求。如果未安装或版本不对，可以通过包管理器安装（如apt install openjdk-8-jdk）或从Oracle官网下载安装包手动配置。
  3. 环境变量：确保JAVA_HOME环境变量已正确设置。这通常是Azkaban启动脚本寻找Java运行时所必需的。可以通过编辑~/.bashrc或~/.bash_profile文件来设置：
    export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 # 请根据你的实际路径修改 export PATH=$JAVA_HOME/bin:$PATH
    然后执行source ~/.bashrc使配置生效，并通过echo $JAVA_HOME验证。

2.2 数据库准备

Azkaban需要数据库来存储项目、工作流、执行历史等元数据。单机版支持两种内置数据库（H2）和外部数据库（MySQL）。对于学习和测试，内置H2数据库最简单，开箱即用。但对于任何严肃的试用或准生产环境，强烈建议使用MySQL，因为H2是内存数据库，Azkaban服务重启后所有元数据会丢失。

如果你选择MySQL（推荐）：

  1. 安装MySQL服务器（版本5.6或5.7均可，避免使用8.0初期版本以防兼容性问题）：
    sudo apt update sudo apt install mysql-server -y
  2. 启动MySQL并设置开机自启：
    sudo systemctl start mysql sudo systemctl enable mysql
  3. 运行安全安装脚本，设置root密码并移除匿名用户等不安全配置：
    sudo mysql_secure_installation
  4. 登录MySQL，为Azkaban创建专用的数据库和用户：
    mysql -u root -p
    在MySQL提示符下执行：
    CREATE DATABASE azkaban DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'azkaban'@'localhost' IDENTIFIED BY 'YourStrongPassword123!'; -- 请替换为强密码 GRANT ALL PRIVILEGES ON azkaban.* TO 'azkaban'@'localhost'; FLUSH PRIVILEGES; EXIT;

注意：记住这里创建的数据库名、用户名和密码，在后续配置文件中会用到。使用localhost限制连接仅来自本机，更安全。

3. Azkaban安装包下载与解压

Azkaban的发行版主要由三部分组成：Web服务器（Web Server）、执行服务器（Executor Server）和数据库（DB）。单机模式（Solo Server）是将Web Server和Executor Server打包在一个进程中运行，最为简单。

  1. 确定版本：访问Azkaban的GitHub Releases页面（https://github.com/azkaban/azkaban/releases ）。对于新手，建议选择较新且稳定的3.x版本，例如3.90.0。避免使用最新的alpha或beta版。
  2. 下载安装包：你需要下载azkaban-solo-server的压缩包。例如，使用wget命令直接下载：
    wget https://github.com/azkaban/azkaban/releases/download/3.90.0/azkaban-solo-server-3.90.0.tar.gz
    如果下载速度慢，可以尝试寻找国内的镜像源。
  3. 解压与目录规划：选择一个合适的安装目录，例如/opt或/usr/local，然后解压：
    sudo tar -zxvf azkaban-solo-server-3.90.0.tar.gz -C /opt/ cd /opt sudo mv azkaban-solo-server-3.90.0 azkaban # 重命名为简单目录名 sudo chown -R $USER:$USER azkaban # 将目录所有权改为当前用户，避免权限问题 cd azkaban
    解压后的目录结构通常包含：
    • bin/：启动和停止脚本。
    • conf/：配置文件目录。
    • lib/：依赖的Jar包。
    • plugins/：可以放置各种扩展插件（如HDFS、Hive、Email通知等）。
    • web/：Web服务器的静态资源。

4. 单机版核心配置详解

单机版的配置主要集中在conf目录下的几个关键文件。配置前，建议先备份原始文件。

4.1 配置Azkaban内部属性（azkaban.properties）

这是Azkaban最核心的配置文件，位于conf/azkaban.properties。

  1. 配置数据库连接（如果使用MySQL）： 找到并修改以下段落，将占位符替换为你在2.2节中创建的信息：

    # 使用MySQL数据库 database.type=mysql mysql.port=3306 mysql.host=localhost mysql.database=azkaban mysql.user=azkaban mysql.password=YourStrongPassword123! mysql.numconnections=100

    如果坚持使用内置H2数据库，则保持database.type=h2，但务必知晓数据非持久化的风险。

  2. 配置Web服务器：

    # Web服务器的Jetty配置 jetty.port=8081 # 指定Web UI的访问端口，默认8081，确保未被占用 azkaban.webserver.url=http://localhost:${jetty.port} # 定义Web服务器的外部访问URL，单机版通常是localhost

  3. 配置Executor（单机模式下在同一进程）：

    # 执行器配置 executor.port=12321 # Executor的RPC端口 azkaban.executorselector.filters=StaticRemainingFlowSize # 执行器选择策略

  4. 配置邮件报警（可选但重要）： 工作流成功或失败时发送邮件通知非常实用。你需要一个SMTP服务器（如公司邮箱或QQ邮箱的SMTP服务）。

    # 邮件服务器配置 mail.sender=your_email@example.com mail.host=smtp.example.com # SMTP服务器地址 mail.user=your_email@example.com mail.password=your_smtp_password # 可能是授权码，而非登录密码 mail.tls=true # 根据SMTP服务器要求启用 job.failure.email=receiver@example.com # 默认的失败通知接收邮箱 job.success.email=receiver@example.com # 默认的成功通知接收邮箱

  5. 用户管理配置（默认使用简单XML文件管理）： 单机版默认使用conf/azkaban-users.xml文件管理用户。确保以下配置存在：

    user.manager.class=azkaban.user.XmlUserManager user.manager.xml.file=conf/azkaban-users.xml

4.2 配置用户文件（azkaban-users.xml）

编辑conf/azkaban-users.xml，定义可以登录Web UI的用户。密码是明文（生产环境需改用LDAP等），角色定义了权限（admin拥有所有权限）。

<azkaban-users> <user username="admin" password="admin" roles="admin" groups="azkaban" /> <user username="data_engineer" password="engineer123" roles="metrics,execute" /> <role name="admin" permissions="ADMIN" /> <role name="metrics" permissions="METRICS" /> <role name="execute" permissions="EXECUTE" /> </azkaban-users>

这里创建了两个用户：admin（密码admin，全权限）和data_engineer（密码engineer123，仅能查看指标和执行任务）。

4.3 配置日志输出（log4j.properties）

日志对于排查问题至关重要。你可以根据需要调整conf/log4j.properties文件，例如修改日志级别、输出格式和文件路径。默认配置通常已足够用于初步调试。

log4j.rootLogger=INFO, Console, DailyFile log4j.appender.DailyFile=org.apache.log4j.DailyRollingFileAppender log4j.appender.DailyFile.File=logs/azkaban.log # 日志文件路径

5. 启动、验证与基本操作

完成配置后，就可以启动Azkaban单机服务了。

5.1 启动与停止服务

进入Azkaban的安装目录：

cd /opt/azkaban

启动服务：

./bin/start-solo.sh

这个脚本会在后台启动Jetty服务器。你可以查看启动日志来确认是否成功：

tail -f logs/azkaban-webserver.log

当看到类似“Started SelectChannelConnector@0.0.0.0:8081”和“Azkaban Web Server started on port 8081”的日志时，说明启动成功。

停止服务使用：

./bin/shutdown-solo.sh

5.2 访问Web UI并验证

  1. 打开浏览器，访问http://你的服务器IP:8081（本地则为http://localhost:8081）。
  2. 使用在azkaban-users.xml中配置的用户名和密码登录（例如admin/admin）。
  3. 登录后，你应该能看到Azkaban的主仪表盘。可以点击导航栏的“Projects”来管理项目。

5.3 创建并运行第一个工作流

这是验证安装是否完全成功的关键一步。

  1. 创建项目：在Web UI中，点击“Create Project”，输入项目名称（如HelloAzkaban）和描述，然后点击“Create”。
  2. 准备工作流文件：在本地创建一个临时目录，准备两个文件：
    • hello.job：这是一个最简单的Shell任务。
      # hello.job type=command command=echo "Hello, Azkaban! The time is $(date)"
    • basic.flow：定义一个包含一个任务的工作流。
      # basic.flow nodes: - name: hello_task type: command config: command: echo "Hello from Flow!"
  3. 打包与上传：将这两个文件打包成ZIP压缩包（注意：必须直接打包文件，而不是包含它们的文件夹）。在Azkaban项目页面，点击“Upload”，选择这个ZIP包上传。
  4. 执行工作流：上传成功后，点击工作流名称“basic”，然后点击右上角的“Execute Flow”。在弹出窗口中，你可以配置执行参数（这里保持默认），点击“Execute”。
  5. 查看结果：页面会跳转到本次执行的详情页。你可以看到任务的状态从“准备中”变为“运行中”，最后变为“成功”。点击“hello_task”的“Details”或“Logs”，可以查看任务执行的标准输出日志，里面应该有你定义的echo语句输出。

如果能看到“Hello, Azkaban!”或“Hello from Flow!”的输出，并且状态为“SUCCEEDED”，那么恭喜你，Azkaban单机版已经成功安装并运行起来了！

6. 常见问题与深度排查指南

在实际安装和初期使用中，你可能会遇到一些典型问题。以下是一些常见问题的排查思路和解决方法。

6.1 服务启动失败

问题现象：执行./bin/start-solo.sh后很快退出，或者logs/azkaban-webserver.log中出现错误日志。

排查步骤：

  1. 检查Java环境：首先确认java -version和echo $JAVA_HOME输出正确。Azkaban启动脚本对JAVA_HOME非常敏感。
  2. 检查端口占用：Azkaban默认使用8081端口。使用netstat -tlnp | grep 8081或lsof -i:8081检查端口是否被其他进程占用。如果被占用，可以在azkaban.properties中修改jetty.port。
  3. 检查数据库连接：如果使用MySQL，这是最常见的启动失败原因。
    • 确认MySQL服务正在运行：sudo systemctl status mysql。
    • 检查azkaban.properties中的数据库连接参数（主机、端口、库名、用户名、密码）是否完全正确。特别注意密码中的特殊字符是否需要转义。
    • 手动测试连接：mysql -u azkaban -p -h localhost azkaban，输入密码看能否登录。
    • 检查MySQL是否允许localhost连接。有时127.0.0.1和localhost在MySQL权限中被视为不同主机。可以尝试将配置中的localhost改为127.0.0.1，或者在MySQL中同时授予'azkaban'@'127.0.0.1'的权限。
  4. 检查配置文件语法：azkaban.properties和XML文件对格式敏感。确保没有多余的空格（尤其是行末）、使用了正确的等号、属性名拼写正确。可以尝试用cat -A命令查看文件，检查是否有不可见字符。

6.2 Web UI无法访问或登录失败

问题现象：浏览器无法打开页面，或者登录时提示无效用户。

排查步骤：

  1. 防火墙/SELinux：如果是在云服务器或开启了防火墙的本地机器，确保8081端口已开放。对于Ubuntu，可以使用sudo ufw allow 8081/tcp。对于CentOS，可以使用sudo firewall-cmd --permanent --add-port=8081/tcp && sudo firewall-cmd --reload。同时检查SELinux是否处于 enforcing 模式并阻止了访问，可临时设置为permissive模式测试：sudo setenforce 0。
  2. 服务未成功启动：再次检查logs/azkaban-webserver.log，确认是否有启动成功的最终日志。有时Jetty启动较慢，稍等片刻再刷新页面。
  3. 用户认证失败：
    • 确认conf/azkaban-users.xml文件格式正确，且已随服务启动被加载（修改此文件后需要重启Azkaban服务）。
    • 检查登录时输入的用户名和密码是否与XML文件中定义的完全一致（大小写敏感）。
    • 查看logs/azkaban-webserver.log，搜索“Login”或“user”关键词，看是否有相关的错误或认证日志。

6.3 工作流执行失败

问题现象：工作流上传成功，但执行后任务状态为“FAILED”。

排查步骤：

  1. 查看执行日志：这是最直接的排错手段。在Azkaban UI中，进入失败的执行实例，点击失败的任务，查看“Logs”。日志通常会给出明确的错误原因，例如“command not found”（命令未找到）或权限错误。
  2. 检查任务类型和命令：对于type=command的任务，Azkaban会在其自身的进程空间执行命令。确保你写的命令（如echo,python,bash脚本路径）在Azkaban运行用户的环境下是存在的且可执行的。可以使用type command来验证。
  3. 路径问题：如果命令中使用了相对路径，这个路径是相对于Azkaban执行器的工作目录的，通常不是项目上传的目录。最佳实践是使用绝对路径，或者将依赖的脚本/资源文件一并打包到ZIP中，Azkaban会解压到临时目录，你可以通过${job.working.dir}来引用这个目录。
  4. 权限问题：Azkaban执行器通常以启动它的系统用户身份运行命令。如果命令需要读写某些文件或目录，请确保该用户拥有相应的权限。例如，如果你试图写入/tmp以外的系统目录，可能会因权限不足而失败。
  5. 资源限制：检查服务器内存和CPU是否充足。长时间运行或内存消耗大的任务可能导致执行器进程被终止。可以在.job文件中设置内存限制，但单机版资源管理能力有限。

6.4 数据库相关疑难杂症

问题现象：服务启动时报数据库连接错误，或运行一段时间后出现数据库错误。

排查与解决：

  1. 字符集问题：如果日志中出现中文乱码或提示不支持的字符集，请确保MySQL数据库创建时指定了utf8mb4字符集（如2.2节所示）。Azkaban的表默认会继承数据库的字符集。
  2. 时区问题：Azkaban会将时间戳存储到数据库。确保MySQL服务器的时区设置与运行Azkaban的机器时区一致，以避免调度时间出现偏差。可以在MySQL中执行SELECT @@global.time_zone, @@session.time_zone;查看。
  3. 连接数耗尽：在长时间运行或高并发测试后，可能出现“Too many connections”错误。可以适当增加azkaban.properties中的mysql.numconnections值，同时也需要调整MySQL自身的max_connections参数。
  4. 数据清理：Azkaban会积累大量的执行历史记录，可能导致数据库膨胀。Azkaban内置了清理作业，但需要配置。在生产环境中，规划定期的历史数据清理策略（如只保留30天数据）是必要的。

7. 生产环境考量与进阶配置

单机版适合学习和测试，但若想用于更稳定的场景，甚至为小团队提供服务，就需要进行一些增强配置。

7.1 使用独立的MySQL数据库

如前所述，这是从“玩具”走向“工具”的第一步。除了安装MySQL，你还需要初始化Azkaban的表结构。Azkaban安装包的sql目录下提供了创建脚本：

cd /opt/azkaban mysql -u azkaban -p azkaban < sql/create-all-sql-3.90.0.sql # 请匹配你的版本号

执行此脚本后，再启动Azkaban，它就会自动连接到MySQL并使用这些表。

7.2 启用SSL加密（HTTPS访问）

在Web UI中传输密码和敏感信息时，使用HTTPS是基本的安全要求。

  1. 生成或获取SSL证书和私钥（例如，使用Let‘s Encrypt或自签名证书）。
  2. 在azkaban.properties中配置：
    jetty.ssl.port=8443 # HTTPS端口 jetty.ssl.keystore=/path/to/your/keystore jetty.ssl.password=keystore_password jetty.ssl.keypassword=key_password jetty.ssl.truststore=/path/to/your/truststore jetty.ssl.trustpassword=truststore_password
  3. 同时，将azkaban.webserver.url改为https://your-hostname:8443。
  4. 重启Azkaban后，即可通过HTTPS访问。

7.3 配置插件扩展功能

Azkaban的强大之处在于其插件体系。将插件JAR包放入plugins目录下的相应子目录即可启用。

  • 邮件插件（email）：通常已内置，配置azkaban.properties中的邮件参数即可。
  • HDFS查看器插件：允许在UI中直接查看HDFS上的任务日志。需要将插件JAR包放入plugins/jobtype目录，并配置HDFS相关参数。
  • 条件工作流插件：允许基于之前任务的输出状态或参数来动态决定执行路径。
  • 用户自定义通知插件：可以集成企业微信、钉钉、Slack等通知渠道。

安装插件后，通常需要在plugins目录下创建对应的配置文件，并重启Azkaban服务。

7.4 日志与监控

  1. 日志聚合：将logs/azkaban-webserver.log和logs/azkaban-execserver.log（单机版可能合并）接入ELK（Elasticsearch, Logstash, Kibana）或类似日志平台，便于集中查询和分析。
  2. 指标监控：Azkaban内置了Metrics机制，可以通过JMX或HTTP端点（/metrics）暴露运行指标，如队列中的任务数、执行成功/失败率等。可以将这些指标接入Prometheus和Grafana，建立监控仪表盘。
  3. 定期备份：定期备份MySQL中的azkaban数据库。这是恢复服务的最重要保障。

7.5 从单机版迁移到多执行器模式

当单机版成为性能瓶颈（如并发任务太多）时，就需要考虑拆分为独立的Web Server和多个Executor Server的集群模式。这涉及到更复杂的配置，包括：

  • 单独部署Azkaban Web Server和Azkaban Executor Server。
  • 配置数据库让Web Server和Executor都能访问。
  • 在Web Server的配置中指定Executor的地址。
  • 可能需要配置共享存储（如HDFS或NFS）来让Web Server和Executor都能访问项目文件。

这个过程需要详细的规划，建议参考Azkaban官方文档的集群部署部分。