xperimental/nextcloud-exporter

nextcloud-exporter

一个Prometheus导出器，用于获取Nextcloud服务器实例的相关指标。

安装

Docker镜像

使用nextcloud-exporter的推荐方式是运行提供的Docker镜像。目前可在Docker Hub和GitHub Container Registry获取：

plain
docker pull ghcr.io/xperimental/nextcloud-exporter:latest
docker pull xperimental/nextcloud-exporter:latest

除了指向master分支当前版本的latest标签外，也提供带版本号的标签。

从源码安装

如果您有较新版本（>= 1.16）的Go环境和GNU Make，获取二进制文件的步骤如下：

bash
git clone https://github.com/xperimental/nextcloud-exporter.git
cd nextcloud-exporter
make

完成后，当前目录下会生成nextcloud-exporter二进制文件。

客户端凭证

导出器支持两种与Nextcloud服务器认证的方式：

• 令牌认证（需要Nextcloud 22或更高版本）
• 用户名和密码

如果您使用Nextcloud 22或更高版本，建议使用令牌认证，因为它不需要具有管理员权限的普通用户账户。

如果配置中同时指定了令牌和用户名/密码，令牌将优先生效。

令牌认证

Nextcloud 22及更高版本支持服务器信息的“令牌认证”。通过这种方式，访问服务器信息不需要具有管理员权限的普通用户账户。您可以将令牌设置为任意值，但建议设置为长随机数：

bash
# 生成随机值（例如使用openssl）
TOKEN=$(openssl rand -hex 32)
# 设置令牌（使用occ控制台应用）
occ config:app:set serverinfo token --value "$TOKEN"

然后，您可以在导出器配置中使用此生成的令牌，而非用户名和密码。

用户名和密码认证

要访问serverinfo API，您需要管理员用户的凭证。建议为此创建一个单独的用户。导出器还可以生成“应用密码”，这样配置中就无需保存真实用户密码，且导出器会作为已连接的应用显示在用户的安全面板中。

要让nextcloud-exporter创建应用密码，请使用--login参数启动：

bash
nextcloud-exporter --login --server https://nextcloud.example.com

导出器会生成一个登录URL，您需要在浏览器中打开。如果为导出器创建了专用用户，请确保使用该用户登录，因为应用密码将绑定到登录用户。在浏览器中授予访问权限后，导出器会输出需要填入配置的用户名和密码。

登录流程完成后，可以在用户设置中禁用生成令牌的文件系统访问权限：

!允许文件系统访问复选框

---

也可以使用Docker容器进行交互式登录：

bash
docker run --rm -it ghcr.io/xperimental/nextcloud-exporter --login --server https://nextcloud.example.com

登录流程至少需要Nextcloud 16才能正常工作。

用法

plain
$ nextcloud-exporter --help
Usage of nextcloud-exporter:
  -a, --addr string          用于监听连接的地址。（默认值：":9205"）
      --auth-token string    认证令牌。使用Nextcloud 22或更高版本时可替代用户名和密码。
  -c, --config-file string   YAML配置文件路径。
      --login                使用交互式登录创建应用密码。
  -p, --password string      连接Nextcloud的密码。
  -s, --server string        Nextcloud服务器URL。
  -t, --timeout duration     获取服务器信息文档的超时时间。（默认值：5s）
      --tls-skip-verify      跳过Nextcloud服务器的证书验证。
  -u, --username string      连接Nextcloud的用户名。
  -V, --version              显示版本信息并退出。

启动后，服务器会在/metrics端点提供指标，可作为Prometheus的目标。

配置方法

有三种配置nextcloud-exporter的方法（优先级从高到低）：

• 环境变量
• 配置文件
• 命令行参数

环境变量

所有设置也可通过环境变量指定：

配置文件

可使用--config-file选项从YAML文件读取配置：

yaml
# 必填
server: "https://example.com"
# 令牌认证必填
authToken: "example-token"
# 用户名/密码认证必填
username: "example"
password: "example"
# 可选
listenAddress: ":9205"
timeout: "5s"
tlsSkipVerify: false

从文件加载凭证

认证令牌和密码均可选择从单独的文件读取，而非直接通过上述输入方法获取。

只需将值设置为文件路径并前缀@，例如：

bash
# 认证令牌
nextcloud-exporter -c config-without-token.yml --auth-token @/path/to/tokenfile
# 密码
nextcloud-exporter -c config-without-password.yml -p @/path/to/passwordfile

当密码或令牌通过其他配置方式（配置文件或环境变量）设置时，此方法同样适用。

其他信息

Info URL

导出器通过Nextcloud服务器的“serverinfo”API读取指标。您可以在管理员设置的“监控”部分找到此API的URL，格式如下：

plain
https://example.com/ocs/v2.php/apps/serverinfo/api/v1/info

路径会自动添加到您提供的服务器URL中，因此上述示例中只需设置--server https://example.com即可。

在浏览器中打开此URL，您将看到导出器将使用的XML结构信息。

Scrape配置

导出器会在每次被Prometheus抓取时查询Nextcloud服务器。如果要减少Nextcloud服务器负载，需相应调整抓取间隔：

yml
scrape_configs:
  - job_name: 'nextcloud'
    scrape_interval: 90s
    static_configs:
      - targets: ['localhost:9205']

导出的指标

nextcloud-exporter导出以下指标：