在 Linux 系统上以独立二进制包的方式部署 Grafana Alloy，重点覆盖离线环境下的完整部署流程，包括目录规划、用户权限、systemd 服务配置、启动验证及日志管理。
适用场景：无法使用包管理器联网安装、需要严格管控软件来源的生产环境、以及需要自定义安装路径的场景。
准备工作
系统要求
| 项目 | 要求 |
|---|
| 操作系统 | Linux（推荐 Ubuntu 20.04+、CentOS 7+、RHEL 8+） |
| 架构 | AMD64 或 ARM64 |
| 权限 | root 或具备 sudo 权限的用户 |
| 依赖 | 无外部依赖，二进制包为静态编译 |
获取安装包
在线环境
从 GitHub Release 页面获取最新稳定版：
# 查看最新版本号（当前稳定版为 v1.13.x）
# 下载 AMD64 版本
ALLOY_VERSION="v1.13.2"
ARCH="amd64"
wget -O alloy-linux-${ARCH}.zip \
"https://github.com/grafana/alloy/releases/download/${ALLOY_VERSION}/alloy-linux-${ARCH}.zip"
# 下载校验文件
wget -O alloy-linux-${ARCH}.zip.sha256 \
"https://github.com/grafana/alloy/releases/download/${ALLOY_VERSION}/alloy-linux-${ARCH}.zip.sha256"
离线环境
在有网络的机器上提前下载以下文件，再通过内网传输至目标服务器：
alloy-linux-amd64.zip # AMD64 主程序包（约 120MB）
alloy-linux-amd64.zip.sha256 # SHA256 校验文件
ARM64 架构（如鲲鹏、飞腾等国产服务器）则下载对应的 alloy-linux-arm64.zip。
BoringCrypto 版本说明：如果所在环境有 FIPS 合规要求，可下载 alloy-boringcrypto-linux-amd64.zip，该版本使用经过认证的加密模块，目前处于 Public Preview 阶段。
安装部署
校验包完整性
# 校验 SHA256，输出 OK 表示文件完整
sha256sum -c alloy-linux-amd64.zip.sha256
解压与安装二进制
# 解压
unzip alloy-linux-amd64.zip
# 赋予可执行权限
chmod +x alloy-linux-amd64
# 安装到系统路径
sudo mv alloy-linux-amd64 /usr/local/bin/alloy
# 验证版本
alloy --version
规划目录结构
采用清晰的目录布局，便于运维管理：
/usr/local/bin/alloy # 主二进制文件
/etc/alloy/ # 配置目录
config.alloy # 主配置文件
conf.d/ # 可选：拆分配置目录
/var/lib/alloy/ # 数据目录（WAL、持久化缓存）
/var/log/alloy/ # 日志目录（可选，默认输出到 stdout）
/etc/default/alloy # 服务环境变量文件
创建所需目录：
# 创建配置目录
sudo mkdir -p /etc/alloy/conf.d
# 创建数据目录（存储 WAL 等持久化数据）
sudo mkdir -p /var/lib/alloy
# 创建日志目录（可选）
sudo mkdir -p /var/log/alloy
创建专用用户
为 Alloy 创建无登录权限的系统用户，遵循最小权限原则：
# 创建系统用户 alloy，不创建 home 目录，不允许登录
sudo useradd --system \
--no-create-home \
--shell /sbin/nologin \
--comment "Grafana Alloy" \
alloy
设置目录权限：
# 配置目录：root 所有，alloy 可读
sudo chown -R root:alloy /etc/alloy
sudo chmod -R 750 /etc/alloy
# 数据目录：alloy 完全控制
sudo chown -R alloy:alloy /var/lib/alloy
sudo chmod -R 755 /var/lib/alloy
# 日志目录（如使用）
sudo chown -R alloy:alloy /var/log/alloy
编写配置文件
最小可用配置
以下是一份最小化的配置示例，验证服务是否能正常启动：
// /etc/alloy/config.alloy
// 最小配置示例：采集本机 Node Exporter 指标并上报 Prometheus
// 服务发现：静态定义采集目标
prometheus.exporter.unix "node" {
// 使用默认配置，采集系统指标
}
// 采集配置
prometheus.scrape "node" {
targets = prometheus.exporter.unix.node.targets
forward_to = [prometheus.remote_write.default.receiver]
scrape_interval = "15s"
}
// 远端写入
prometheus.remote_write "default" {
endpoint {
url = "http://prometheus:9090/api/v1/write"
// 离线或无认证场景可去掉 basic_auth 块
// basic_auth {
// username = "user"
// password = "pass"
// }
}
}
配置语法说明：Alloy 使用 .alloy 格式（基于 River 语法），块之间通过 组件类型.实例名.导出字段 的方式引用，形成数据管道。详细语法见第二篇文章。
格式校验与语法检查
# 格式化配置文件（类似 gofmt）
alloy fmt /etc/alloy/config.alloy
# 语法校验
alloy validate /etc/alloy/config.alloy
配置 systemd 服务
创建环境变量文件
sudo tee /etc/default/alloy > /dev/null <<'EOF'
## Grafana Alloy 服务环境变量
## 修改此文件后需执行：sudo systemctl restart alloy
# 配置文件路径
CONFIG_FILE="/etc/alloy/config.alloy"
# 额外的命令行参数（多个参数用空格分隔）
# 示例：暴露 UI 给外部访问
# CUSTOM_ARGS="--server.http.listen-addr=0.0.0.0:12345"
CUSTOM_ARGS=""
# 升级时是否自动重启（默认 true）
RESTART_ON_UPGRADE=true
EOF
创建 systemd Unit 文件
sudo tee /etc/systemd/system/alloy.service > /dev/null <<'EOF'
[Unit]
Description=Vendor-neutral programmable observability pipelines
Documentation=https://grafana.com/docs/alloy/
# 等待网络就绪后启动
Wants=network-online.target
After=network-online.target
[Service]
Type=simple
Restart=always
RestartSec=5s
User=alloy
Group=alloy
# 注入主机名环境变量，可在配置中通过 sys.env("HOSTNAME") 引用
Environment=HOSTNAME=%H
# 读取环境变量文件
EnvironmentFile=/etc/default/alloy
# 数据目录（WAL 及持久化缓存存放位置）
WorkingDirectory=/var/lib/alloy
# 启动命令：$CUSTOM_ARGS 和 $CONFIG_FILE 来自 EnvironmentFile
ExecStart=/usr/local/bin/alloy run \
$CUSTOM_ARGS \
--storage.path=/var/lib/alloy \
$CONFIG_FILE
# 热重载：向主进程发送 HUP 信号触发配置重载（无需重启服务）
ExecReload=/usr/bin/env kill -HUP $MAINPID
# 优雅停止超时（等待进程完成当前工作）
TimeoutStopSec=20s
# 安全加固（可选）
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
[Install]
WantedBy=multi-user.target
EOF
重要参数说明
| 参数 | 说明 |
|---|
| --storage.path | WAL（Write-Ahead Log）及组件持久化数据目录，重要，不要指向 tmpfs |
| --server.http.listen-addr | UI 及 API 监听地址，默认 127.0.0.1:12345 |
| --cluster.enabled | 是否开启集群模式（详见第四篇） |
| --disable-reporting | 禁用匿名使用数据上报至 Grafana Labs |
完整的禁用遥测数据上报示例：
CUSTOM_ARGS="--disable-reporting"
启动与管理
启动服务
# 重新加载 systemd 配置
sudo systemctl daemon-reload
# 设置开机自启
sudo systemctl enable alloy
# 启动服务
sudo systemctl start alloy
# 查看运行状态
sudo systemctl status alloy
正常运行时输出示例：
alloy.service - Vendor-neutral programmable observability pipelines
Loaded: loaded (/etc/systemd/system/alloy.service; enabled)
Active: active (running) since Mon 2025-03-10 10:00:00 CST; 5s ago
Main PID: 12345 (alloy)
常用管理命令
# 停止服务
sudo systemctl stop alloy
# 重启服务
sudo systemctl restart alloy
# 热重载配置（不中断数据采集，推荐用于配置变更）
sudo systemctl reload alloy
# 或直接发送信号
sudo kill -HUP $(pidof alloy)
# 查看实时日志
sudo journalctl -u alloy -f
# 查看最近 100 行日志
sudo journalctl -u alloy -n 100 --no-pager
# 查看指定时间段日志
sudo journalctl -u alloy --since "2025-03-10 09:00" --until "2025-03-10 10:00"
访问内置 UI
Alloy 内置了 Web 调试界面，默认仅监听本地：
# 在目标服务器上通过浏览器或 curl 访问
curl http://127.0.0.1:12345
如需从其他机器访问，修改 /etc/default/alloy：
CUSTOM_ARGS="--server.http.listen-addr=0.0.0.0:12345"
然后重启服务，在浏览器中访问 http://<服务器IP>:12345，可以看到：
- Graph 视图：可视化展示组件之间的数据流
- 组件状态：每个组件的健康状态和导出值
- Live Debugging：实时查看流经各组件的数据
升级与版本管理
升级流程
# 1. 下载新版本二进制（离线时同样适用此流程）
wget -O alloy-linux-amd64-new.zip \
"https://github.com/grafana/alloy/releases/download/v1.14.0/alloy-linux-amd64.zip"
# 2. 校验完整性
sha256sum -c alloy-linux-amd64-new.zip.sha256
# 3. 解压
unzip alloy-linux-amd64-new.zip -d /tmp/alloy-new
# 4. 停止服务
sudo systemctl stop alloy
# 5. 备份旧版本
sudo cp /usr/local/bin/alloy /usr/local/bin/alloy.bak
# 6. 替换二进制
sudo cp /tmp/alloy-new/alloy-linux-amd64 /usr/local/bin/alloy
sudo chmod +x /usr/local/bin/alloy
# 7. 启动服务
sudo systemctl start alloy
# 8. 验证版本
alloy --version
回滚
sudo systemctl stop alloy
sudo cp /usr/local/bin/alloy.bak /usr/local/bin/alloy
sudo systemctl start alloy
卸载
# 停止并禁用服务
sudo systemctl stop alloy
sudo systemctl disable alloy
# 删除 systemd 配置
sudo rm /etc/systemd/system/alloy.service
sudo systemctl daemon-reload
# 删除二进制文件
sudo rm /usr/local/bin/alloy
# 删除配置与数据（谨慎操作，WAL 数据将丢失）
sudo rm -rf /etc/alloy
sudo rm -rf /var/lib/alloy
sudo rm -rf /var/log/alloy
# 删除用户
sudo userdel alloy
常见问题排查
服务无法启动
现象：systemctl status alloy 显示 failed
排查步骤：
# 查看详细错误信息
sudo journalctl -u alloy -n 50 --no-pager
# 手动以 alloy 用户运行，便于直接看到错误输出
sudo -u alloy /usr/local/bin/alloy run --storage.path=/var/lib/alloy /etc/alloy/config.alloy
常见原因：
| 错误信息 | 原因 | 解决方案 |
|---|
| permission denied on /var/lib/alloy | 数据目录权限不对 | chown -R alloy:alloy /var/lib/alloy |
| config file not found | 配置文件路径错误 | 检查 CONFIG_FILE 环境变量 |
| unknown flag: --config.file | 错误使用了旧版参数格式 | Alloy 使用 run 而非 --config.file |
| address already in use | 12345 端口被占用 | 修改 --server.http.listen-addr 端口 |
配置热重载不生效
# 确认进程收到了信号
sudo journalctl -u alloy -f
# 然后执行 reload
sudo systemctl reload alloy
# 日志中应出现 "config reloaded" 字样
若日志无输出，检查配置文件是否有语法错误：
alloy validate /etc/alloy/config.alloy
WAL 数据过大
WAL（Write-Ahead Log）默认不自动清理超龄数据，在 prometheus.remote_write 组件中配置 WAL 保留时间：
prometheus.remote_write "default" {
endpoint {
url = "http://prometheus:9090/api/v1/write"
}
wal {
// 最大保留时长，默认 4h，可根据网络稳定性调整
max_keepalive_time = "8h"
// 最小保留时长
min_keepalive_time = "5m"
}
}
内存占用过高
Alloy 内存占用主要来自 WAL 缓冲和 series 缓存。估算公式：
内存 ≈ 活跃 Series 数 × 10KB + WAL 缓冲
若内存持续增长，检查是否有 label cardinality 过高的问题，可在 UI 的 Graph 视图查看各组件的 series 数量。
