在马来西亚服务器部署Loki日志系统,单机环境需要配置哪些关键项?
在马来西亚服务器上首次部署 Loki,单机环境真正需要先定下来的不是某一条启动命令,而是数据目录、TSDB 存储格式、WAL、日志保留周期、写入入口、HTTPS、资源限制和服务自启动方式。只让 Loki 监听 3100 端口并看到进程运行,不能算完成稳定上线。
下面以 Ubuntu 22.04/24.04、Loki 3.x 单体进程、单块本地 SSD、Nginx 作为公网入口为例。Loki 使用本地文件系统保存日志,服务本身只监听回环地址,外部采集端通过 HTTPS 访问 Nginx。示例将保留周期设为 7 天,适合小规模或中低写入量场景;如果日志量较大,应先按实际写入量调整磁盘和限流参数。
围绕马来西亚本地业务的日志集中与运行监测,A5idc数据提供马来西亚吉隆坡的物理服务器资源,并有不同CPU、存储与网络线路配置,可为Loki单机服务、日志写入及查询提供部署基础。无论是汇集业务服务日志,还是为区域应用保留运行记录,都能结合相应资源组合安排服务器部署,支持企业构建贴近业务区域的日志管理环境。
部署边界与准备条件
单机方案包含哪些组件
本方案只部署一台 Loki,不涉及集群、对象存储和多副本。各组件的职责如下:

| 组件 | 本文采用的方式 | 需要确认的条件 |
|---|---|---|
| Loki | 单体进程运行 | 通过 systemd 自启动并自动拉起 |
| 日志存储 | 本地文件系统 | 数据盘必须有足够空间,并安排异机备份 |
| 索引格式 | TSDB,schema v13 | 首次写入后不要随意修改历史 schema |
| 日志入口 | Nginx 反向代理 | 对外提供 HTTPS 和基础认证 |
| Loki HTTP 端口 | 127.0.0.1:3100 | 不直接暴露公网 |
| Loki gRPC 端口 | 127.0.0.1:9096 | 单机内部使用,不开放公网 |
| 保留周期 | 示例为 168h | 需要与磁盘预算和业务审计周期匹配 |
| 多租户 | 关闭 Loki 原生认证 | 由 Nginx 基础认证保护单一访问入口 |
auth_enabled: false 只表示 Loki 不启用原生多租户认证,不表示服务可以无保护地暴露到互联网。公网访问仍应通过 HTTPS 和认证网关。
服务器、域名和网络条件
部署前至少准备以下条件:
- 一台可以使用
sudo的 Ubuntu 22.04/24.04 服务器。 - 至少 2 vCPU、4 GB 内存作为轻量示例起点;如果采集多个应用或查询范围较大,可从 4 vCPU、8 GB 内存开始评估。
- 独立 SSD 或独立数据目录,用于
/var/lib/loki。 - 一个解析到服务器公网地址的域名,例如
logs.example.com。 - DNS 中如果存在 AAAA 记录,服务器必须确实能够通过 IPv6 访问 80 和 443 端口,否则证书申请和客户端访问可能出现间歇性失败。
- 防火墙或云平台安全组允许 SSH、HTTP 和 HTTPS,Loki 的 3100、9096 端口不开放公网。
- 服务器和日志采集端启用 NTP,避免时间偏差导致日志被拒收或查询不到。
马来西亚常用本地时区为 UTC+8,但 Loki 保存的是 Unix 时间戳。实施时建议服务器统一使用 UTC,或者保证服务器、应用和采集端都使用一致的时间同步策略。Grafana 展示时可以按浏览器或用户时区显示,不需要通过修改 Loki 存储格式来适配本地时区。
先估算日志磁盘
日志磁盘不能只按系统盘剩余空间判断。可以先用十进制单位估算:
每日原始日志量 = 平均写入速率(MB/s)× 86400
例如平均写入速率为 0.1 MB/s:
- 每日原始量:
0.1 × 86400 = 8640 MB,即约8.64 GB。 - 7 天原始量:
8.64 × 7 = 60.48 GB。 - 加上 30% 的索引、压缩差异、临时文件和维护余量:
60.48 × 1.3 = 78.624 GB。
这里的 0.1 MB/s 等于 0.8 Mb/s,计算时不要把字节单位和比特单位混用。Loki 会对日志块进行压缩,实际占用可能低于原始日志量,但首次部署不应把压缩收益全部计入容量预算。建议至少预留操作系统、Nginx、备份和磁盘告警空间。
第一步:准备系统和 Loki 程序
安装基础软件
以下命令适用于 Ubuntu 22.04/24.04。示例把 Loki 版本固定为 3.5.0,实际生产环境应替换为已经测试过的版本,不建议直接使用 latest。
sudo apt-get update
sudo apt-get install -y ca-certificates curl unzip nginx apache2-utils certbot python3
检查系统时区、时间同步和磁盘:
timedatectl status
df -hT /
df -hT /var
df -i /
如果计划把日志放到单独挂载点,应先确认挂载点已经存在并且重启后能够自动挂载。不要在尚未挂载数据盘时启动 Loki,否则可能把数据写入系统盘下的同名目录。
创建运行用户和目录
以下操作只适用于新目录。如果 /var/lib/loki 已经保存其他版本的数据,先备份并核对目录归属,不要直接执行递归覆盖。
sudo adduser --system --group --home /var/lib/loki --no-create-home loki
sudo install -d -o root -g loki -m 0750 /etc/loki
sudo install -d -o loki -g loki -m 0750 \
/var/lib/loki/chunks \
/var/lib/loki/rules \
/var/lib/loki/wal \
/var/lib/loki/compactor
验证用户和目录:
id loki
sudo find /var/lib/loki -maxdepth 1 -type d -printf '%M %u:%g %p\n'
预期可以看到 loki 用户,并且各数据目录归属于 loki:loki。
下载固定版本并检查文件
根据服务器架构选择发布包:
export LOKI_VERSION=3.5.0
case "$(uname -m)" in
x86_64)
export LOKI_ARCH=amd64
;;
aarch64|arm64)
export LOKI_ARCH=arm64
;;
*)
echo "不支持的架构:$(uname -m)" >&2
exit 1
;;
esac
mkdir -p /tmp/loki-bin
curl -fL --retry 3 \
-o /tmp/loki.zip \
"https://github.com/grafana/loki/releases/download/v${LOKI_VERSION}/loki-linux-${LOKI_ARCH}.zip"
unzip -l /tmp/loki.zip
unzip -j -o /tmp/loki.zip \
"loki-linux-${LOKI_ARCH}" \
-d /tmp/loki-bin
sudo install -o root -g root -m 0755 \
"/tmp/loki-bin/loki-linux-${LOKI_ARCH}" \
/usr/local/bin/loki
生产环境应将下面命令的结果与所采用发布包对应的校验值进行比对:
sha256sum /tmp/loki.zip
sudo /usr/local/bin/loki -version
如果压缩包中没有与架构对应的文件,或版本命令无法正常执行,应先停止部署,核对版本、架构和下载文件,不要把未知文件直接安装到 /usr/local/bin。
第二步:配置本地存储、WAL 和保留周期
创建 Loki 配置文件
使用 sudoedit 创建配置:
sudoedit /etc/loki/config.yml
写入以下示例配置:
auth_enabled: false
server:
http_listen_address: 127.0.0.1
http_listen_port: 3100
grpc_listen_address: 127.0.0.1
grpc_listen_port: 9096
log_level: info
common:
instance_addr: 127.0.0.1
path_prefix: /var/lib/loki
replication_factor: 1
ring:
kvstore:
store: inmemory
storage:
filesystem:
chunks_directory: /var/lib/loki/chunks
rules_directory: /var/lib/loki/rules
schema_config:
configs:
- from: 2024-01-01
store: tsdb
object_store: filesystem
schema: v13
index:
prefix: index_
period: 24h
ingester:
wal:
enabled: true
dir: /var/lib/loki/wal
chunk_idle_period: 5m
chunk_retain_period: 30s
limits_config:
retention_period: 168h
max_query_lookback: 168h
ingestion_rate_mb: 4
ingestion_burst_size_mb: 8
reject_old_samples: true
reject_old_samples_max_age: 168h
compactor:
working_directory: /var/lib/loki/compactor
retention_enabled: true
delete_request_store: filesystem
querier:
max_concurrent: 4
调整配置前,需要理解几个关键项。
http_listen_address和grpc_listen_address都绑定到127.0.0.1,避免 Loki 绕过 Nginx 直接暴露。replication_factor: 1说明单机只有一份数据,服务器磁盘损坏时不能依靠 Loki 自动恢复。store: tsdb和schema: v13是当前示例的存储格式。首次写入后,不要通过覆盖整个schema_config的方式修改历史配置。wal.enabled: true会将尚未完整写入存储的状态保存在 WAL 目录,进程异常退出后可以用于恢复。retention_period: 168h代表 7 天。保留周期缩短后,删除由 compactor 异步执行,不应手动删除chunks、index或wal文件。ingestion_rate_mb和ingestion_burst_size_mb是示例限流值。这里的单位是 MB/s,不是 Mb/s。如果实际写入峰值超过配置,客户端可能收到 HTTP 429。max_query_lookback限制查询时间范围,和 7 天保留周期保持一致。reject_old_samples_max_age会拒绝超过 7 天的旧日志。如果业务存在延迟上报或离线补传,应把这个值调大,但同时要重新评估磁盘。
如果安装时已经超过 2024-01-01,这个日期仍然早于首次写入,可以作为首次 schema 的起始日期。后续增加新 schema 时,应追加新的日期段,而不是改写已有日期段。
设置配置文件权限:
sudo chown root:loki /etc/loki/config.yml
sudo chmod 0640 /etc/loki/config.yml
验证配置文件和目录
先检查 YAML 文件是否可读:
sudo -u loki test -r /etc/loki/config.yml
sudo -u loki test -w /var/lib/loki
Loki 的具体配置字段会随版本变化,配置校验最终以目标版本启动结果为准。首次启动失败时,优先查看日志中的 unknown field、failed parsing config、permission denied 和目录路径错误,不要盲目删除配置项。
第三步:使用 systemd 启动并设置自动恢复
创建服务文件:
sudoedit /etc/systemd/system/loki.service
写入:
[Unit]
Description=Loki log aggregation service
Wants=network-online.target
After=network-online.target
[Service]
Type=simple
User=loki
Group=loki
WorkingDirectory=/var/lib/loki
ExecStart=/usr/local/bin/loki -config.file=/etc/loki/config.yml
Restart=on-failure
RestartSec=5
TimeoutStopSec=120
LimitNOFILE=65536
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=full
[Install]
WantedBy=multi-user.target
加载并启动:
sudo systemctl daemon-reload
sudo systemctl enable --now loki
每次修改 Loki 配置后,先备份配置,再重启服务:
sudo mkdir -p /var/backups/loki
sudo cp -a /etc/loki/config.yml \
"/var/backups/loki/config.yml.$(date +%F-%H%M%S)"
sudo systemctl restart loki
检查服务状态和启动日志:
sudo systemctl status loki --no-pager
sudo journalctl -u loki -n 80 --no-pager
预期状态为 active (running)。随后检查本机健康接口:
curl -fsS http://127.0.0.1:3100/ready
正常时通常返回:
ready
如果 systemd 显示服务反复重启,先不要继续配置 Nginx。先通过 journalctl 解决 Loki 自身的配置、权限或磁盘问题。
检查监听地址:
sudo ss -lntp | grep -E ':(3100|9096)\b'
预期只看到 127.0.0.1:3100 和 127.0.0.1:9096,不应看到 0.0.0.0:3100 或公网地址。
第四步:配置防火墙和 HTTPS 入口
配置 DNS 和防火墙
先将 logs.example.com 的 A 记录指向服务器公网 IPv4 地址。若使用 AAAA 记录,则同时确认服务器 IPv6 路由和防火墙规则。
如果服务器已经由云平台安全组或现有防火墙管理端口,不要为了使用 UFW 而重复启用另一套规则。若确认使用 UFW,应先确认当前 SSH 端口已经放行,再启用防火墙:
sudo ufw status verbose
sudo ufw app list
# 如果 SSH 使用默认 22 端口,可使用 OpenSSH;
# 如果使用其他端口,应改为实际 SSH 端口。
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status numbered
sudo ufw enable
启用前必须保留当前 SSH 会话,并确认服务器控制台可用。错误的防火墙规则可能导致远程失联。3100 和 9096 不需要添加放行规则。
先创建证书申请用的 HTTP 站点
创建 ACME 验证目录:
sudo install -d -o www-data -g www-data -m 0755 \
/var/www/certbot/.well-known/acme-challenge
创建 Nginx 临时配置:
sudoedit /etc/nginx/sites-available/loki
先写入仅用于证书申请的内容:
server {
listen 80;
server_name logs.example.com;
location ^~ /.well-known/acme-challenge/ {
root /var/www/certbot;
}
location / {
return 404;
}
}
将 logs.example.com 换成实际域名,然后启用配置并检查:
sudo ln -s /etc/nginx/sites-available/loki \
/etc/nginx/sites-enabled/loki
sudo nginx -t
sudo systemctl reload nginx
如果默认站点与当前配置冲突,不要直接删除文件。先用 nginx -T 查看实际加载的 server 配置,再决定是否禁用冲突站点,并保留可恢复的备份。
申请证书:
sudo certbot certonly \
--webroot \
-w /var/www/certbot \
-d logs.example.com \
--email admin@example.com \
--agree-tos \
--no-eff-email
证书申请成功后,检查证书目录:
sudo ls -l /etc/letsencrypt/live/logs.example.com/
配置 HTTPS 和基础认证
先创建 Nginx 基础认证账户。密码不要直接写入命令行历史:
sudo htpasswd -c /etc/nginx/.htpasswd-loki lokiadmin
sudo chown root:www-data /etc/nginx/.htpasswd-loki
sudo chmod 0640 /etc/nginx/.htpasswd-loki
将 /etc/nginx/sites-available/loki 替换为最终配置:
server {
listen 80;
server_name logs.example.com;
location ^~ /.well-known/acme-challenge/ {
root /var/www/certbot;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl;
server_name logs.example.com;
ssl_certificate /etc/letsencrypt/live/logs.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/logs.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
client_max_body_size 16m;
location / {
auth_basic "Loki";
auth_basic_user_file /etc/nginx/.htpasswd-loki;
proxy_pass http://127.0.0.1:3100;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_request_buffering off;
proxy_read_timeout 120s;
proxy_send_timeout 120s;
}
}
检查并重新加载:
sudo nginx -t
sudo systemctl reload nginx
sudo certbot renew --dry-run
验证入口:
curl -I http://logs.example.com/ready
curl -u lokiadmin https://logs.example.com/ready
预期结果:
- HTTP 请求返回 301,并跳转到 HTTPS。
- 未携带认证信息的 HTTPS 请求返回 401。
- 输入密码后返回
ready。
基础认证适合单团队或单应用的单机入口。如果需要多个租户、不同团队独立授权或更细的写入与查询权限,应单独设计认证网关和租户方案,不要把所有访问者共用一个 Nginx 账户。
第五步:执行写入和查询验证
通过本机 API 写入测试日志
下面的测试使用当前时间生成纳秒级时间戳,不依赖手工填写时间:
python3 - <<'PY' | curl -sS -X POST \
-H 'Content-Type: application/json' \
--data-binary @- \
-w '\nHTTP %{http_code}\n' \
http://127.0.0.1:3100/loki/api/v1/push
import json
import socket
import time
payload = {
"streams": [
{
"stream": {
"job": "manual-test",
"host": socket.gethostname()
},
"values": [
[
str(time.time_ns()),
"loki single-node smoke test"
]
]
}
]
}
print(json.dumps(payload))
PY
成功时通常返回 HTTP 204,命令退出状态为 0。Loki 的写入接口不一定返回可读的 JSON 正文,因此应以 HTTP 状态码和后续查询为准。
查询刚写入的日志
curl -G -fsS \
http://127.0.0.1:3100/loki/api/v1/query_range \
--data-urlencode 'query={job="manual-test"}' \
--data-urlencode 'since=10m' \
--data-urlencode 'limit=20'
响应中应看到:
"status":"success"data.result中包含job为manual-test的流。- 日志内容中包含
loki single-node smoke test。
如果本机写入和查询成功,再通过公网入口重复验证。将本机 URL 换成 HTTPS 地址,并使用前面创建的认证账户:
curl -u lokiadmin -G -fsS \
https://logs.example.com/loki/api/v1/query_range \
--data-urlencode 'query={job="manual-test"}' \
--data-urlencode 'since=10m' \
--data-urlencode 'limit=20'
此命令会提示输入密码,不建议把真实密码直接写在命令行中。
给采集端的接入参数
远程采集端应使用以下信息:
| 项目 | 配置值或原则 |
|---|---|
| 写入地址 | https://logs.example.com/loki/api/v1/push |
| 查询地址 | https://logs.example.com |
| 认证方式 | Nginx 基础认证或已规划的认证网关 |
| 本机采集地址 | 同机采集可以使用 http://127.0.0.1:3100/loki/api/v1/push |
| 推荐标签 | job、host、service、env |
| 不建议作为标签的字段 | request_id、用户 ID、订单号、完整 URL 参数 |
| 时间要求 | 采集端启用 NTP,发送有效的 RFC3339 或 Unix 纳秒时间戳 |
| 批量要求 | 单批大小应低于 Nginx 的 client_max_body_size |
Loki 的标签会影响索引和查询效率。主机名、服务名和环境通常是低到中等基数标签;请求 ID、用户 ID 和动态 URL 参数会造成高基数,建议保留在日志正文或结构化字段中,不要全部提升为标签。
第六步:检查资源、保留和维护边界
检查磁盘和 inode
本地文件系统模式下,磁盘满和 inode 耗尽都会影响写入:
df -h /var/lib/loki
df -i /var/lib/loki
sudo du -sh /var/lib/loki/*
建议为磁盘使用率设置外部告警,例如在达到 70%、85% 和 90% 时分别通知。告警阈值不是 Loki 配置的一部分,应由服务器监控系统或云平台监控完成。
不要通过手动删除 /var/lib/loki/chunks、索引目录或 WAL 来释放空间。这样可能造成索引与数据块不一致,且无法作为正常回滚手段。空间不足时,优先扩容、暂停非必要采集,或在确认业务影响后调整保留周期。
检查服务日志和指标接口
sudo journalctl -u loki --since "30 minutes ago" --no-pager
curl -fsS http://127.0.0.1:3100/metrics | head
重点关注:
- WAL 恢复是否持续失败。
- 是否频繁出现 429。
- 是否有权限、磁盘或 compactor 错误。
- 查询耗时是否持续增长。
- 服务器内存和文件描述符是否接近上限。
Loki 服务日志写入 journald,Nginx 访问日志写入系统日志目录,二者都可能占用磁盘。应同时检查:
journalctl --disk-usage
sudo du -sh /var/log/nginx
常见异常和处理顺序
故障排查建议从外到内进行,先确认网络入口,再确认 Nginx,最后检查 Loki 和存储目录。
| 现象 | 先检查 | 通常原因和处理方式 |
|---|---|---|
| 域名无法访问 | DNS、云安全组、ufw status | 域名未解析到当前服务器,或 80/443 未放行 |
| HTTP 能访问但证书申请失败 | 80 端口、ACME 目录、AAAA 记录 | HTTP 验证路径被其他站点接管,或 IPv6 不可达 |
| HTTPS 返回 401 | auth_basic 和密码文件 | 认证已生效,检查账户和密码,不要直接关闭认证 |
| HTTPS 返回 502 | curl http://127.0.0.1:3100/ready、Nginx error log | Loki 未运行、监听地址不一致,或 Nginx proxy_pass 写错 |
本机 /ready 失败 | systemctl status loki、journalctl -u loki | 配置解析失败、目录权限错误、磁盘不足或端口占用 |
| Push 返回 429 | Loki 日志和 limits_config | 写入速率或突发量超过限制,先降低采集端并发,再按实测值调整 |
| Push 返回 400 | 请求 JSON、标签、时间戳 | JSON 格式错误、时间戳单位错误或发送了不被接受的旧日志 |
| Push 成功但查询无结果 | 查询时间范围、标签选择器、服务器时间 | 查询范围太短、标签写错、时钟偏差或日志被写入其他实例 |
| 服务重启后日志缺失 | WAL、数据目录、磁盘状态 | WAL 恢复失败或数据目录未挂载,先停止反复重启并保留日志 |
| 配置提示未知字段 | Loki 版本和配置字段 | 配置与二进制版本不匹配,应以当前版本配置说明为准,不要猜字段名 |
遇到磁盘满时,不要立即执行删除命令。先保存 df、du、journalctl 和 Loki 指标结果,再通过扩容或降低后续保留量处理。若必须改变保留周期,先备份配置,修改后重启 Loki,并观察 compactor 是否正常工作。
验收与回滚检查项
验收清单
逐项确认以下结果:
- [ ]
loki用户存在,/var/lib/loki目录归属正确。 - [ ] Loki 二进制版本固定,下载包已完成校验。
- [ ] 配置使用 TSDB v13、本地文件系统和 WAL。
- [ ]
retention_period与磁盘预算相匹配。 - [ ]
systemctl is-enabled loki返回启用状态。 - [ ]
systemctl status loki显示active (running)。 - [ ]
http://127.0.0.1:3100/ready返回ready。 - [ ] 3100 和 9096 只监听回环地址。
- [ ] HTTP 访问会跳转 HTTPS,未认证访问返回 401。
- [ ] 认证后的 HTTPS
/ready请求成功。 - [ ] Push 返回成功状态,Query 能查到测试日志。
- [ ] 云安全组和服务器防火墙未开放 3100、9096。
- [ ] 证书续期演练
certbot renew --dry-run成功。 - [ ]
/var/lib/loki的磁盘和 inode 已接入监控。 - [ ] 本地数据目录已有独立备份或快照方案。
配置或版本回滚
每次修改 Loki 配置前先保存副本:
sudo mkdir -p /var/backups/loki
sudo cp -a /etc/loki/config.yml \
"/var/backups/loki/config.yml.$(date +%F-%H%M%S)"
sudo cp -a /usr/local/bin/loki \
"/var/backups/loki/loki.$(date +%F-%H%M%S)"
如果新配置启动失败,应恢复最近一次可用配置,而不是删除数据目录:
sudo systemctl stop loki
ls -lt /var/backups/loki/
# 将下面路径替换为实际备份文件
sudo cp -a /var/backups/loki/config.yml.YYYY-MM-DD-HHMMSS \
/etc/loki/config.yml
sudo chown root:loki /etc/loki/config.yml
sudo chmod 0640 /etc/loki/config.yml
sudo systemctl start loki
sudo systemctl status loki --no-pager
curl -fsS http://127.0.0.1:3100/ready
如果是二进制升级导致问题,在确认备份文件对应版本后恢复二进制,再启动服务。回滚时不要删除 /var/lib/loki,也不要把新的 schema 配置覆盖成不包含已有日期段的旧配置。
如果需要回滚 Nginx 配置,应先恢复站点文件,再执行:
sudo nginx -t
sudo systemctl reload nginx
如果需要恢复 Loki 数据,先停止服务并确保备份来自一致状态。恢复动作会让查询和写入中断,且可能覆盖当前目录,执行前应保留当前目录副本:
sudo systemctl stop loki
sudo mv /var/lib/loki \
"/var/lib/loki.before-restore.$(date +%F-%H%M%S)"
# 从经过验证的备份中恢复 /var/lib/loki
sudo chown -R loki:loki /var/lib/loki
sudo systemctl start loki
sudo curl -fsS http://127.0.0.1:3100/ready
防火墙回滚前应确保仍有控制台或现有 SSH 会话。若只是撤销本次新增的 80/443 规则,可以使用 ufw status numbered 确认编号后删除对应规则;不要在没有备用登录通道时直接关闭全部防火墙。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9072.html



