VictoriaMetrics vmanomaly Server 组件完全指南：REST API、Web UI、并发控制与自动调优

VictoriaMetrics vmanomaly Server 组件完全指南：REST API、Web UI、并发控制与自动调优

【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics

VictoriaMetrics Anomaly Detection（vmanomaly）是 VictoriaMetrics 生态中负责时序数据异常检测的服务，其server组件是该服务对外暴露能力的核心门户：它承载 REST API（如/metrics指标端点）、Web UI（/vmui/），以及面向 UI、MCP 和自动化工作流的时序分析与自动调优 API。本文以官方组件文档 docs/anomaly-detection/components/server.md 为主体，结合仓库内的完整配置示例与相关组件文档，系统讲解server段的全部配置参数、访问方式、自监控集成以及 v1.30.0 起引入的时序特征分析与共享异步自动调优 API，帮助你从零搭建并调优vmanomaly的对外服务层。

Server 组件在 vmanomaly 中的角色

vmanomaly由多个可配置组件构成：负责拉取数据的 Reader、执行检测的 Model、调度执行时机的 Scheduler、写出结果的 Writer，以及可选的 Monitoring、Settings 与 Server 段。其中 Server 组件（配置段说明）负责：

• 提供 REST API 端点，例如/metrics；
• 托管异常检测的 Web UI（/vmui/）；
• 当在配置中设置了 Server 段时，它还同时充当指标发布端点，供 VictoriaMetrics Agent 或其他 Prometheus 兼容抓取器采集 self-monitoring metrics——这种情况下无需再单独配置monitoring.pull；
• 从 v1.30.0 起，额外暴露面向 UI、MCP 与自动化工作流的时序分析（timeseries characteristics）与共享异步自动调优（autotune）API。

从 components 总览 的示例配置看，server是可选段，但一旦启用，port、path_prefix、max_concurrent_tasks等参数就直接决定 UI 与 API 的可用性和承载能力。

Server 段全部参数详解

所有参数均配置在 vmanomaly 配置文件的server:段下，各参数及其默认值如下：

addr 与 port：监听地址与端口

addr决定服务绑定的网卡，port决定对外端口。默认监听0.0.0.0:8490，这意味着容器内外（如 compose 编排示例 中ports: "8490:8490"）均可通过 8490 端口访问 UI 与 API。需要说明的是，monitoring.pull段的默认端口是8080，与server段的8490相互独立——如果同时启用两者，它们各自监听不同端口，这点在排查“指标到底暴露在哪个端口”时很容易混淆。

path_prefix：统一路由前缀

path_prefix为所有 HTTP 路由增加统一前缀，适合将vmanomaly部署在反向代理子路径下（例如/vmanomaly）。设path_prefix: '/vmanomaly'后：

• UI 地址变为<vmanomaly-host>:8490/vmanomaly/vmui/；
• /metrics变为<vmanomaly-host>:8490/vmanomaly/metrics。

前缀可带也可不带前导斜杠（my-app与/my-app等价），便于与代理配置保持一致。

max_concurrent_tasks：并发任务上限

该参数限制后端同时处理的异常检测任务（例如对查询结果执行检测）的数量，防止多个用户同时操作 UI 时压垮服务。默认值为2；超过上限的多余任务会被取消。在 UI 文档的资源优化建议 中，官方给出的典型调优示例为：

server: # Port for the UI server (default: 8490) port: 8490 # Limit on concurrent tasks to manage UI load (default: 2) max_concurrent_tasks: 2

同时该文档也指出：max_concurrent_tasks限制任务数量，而settings.n_workers控制单个任务内部的并行度，二者配合使用才能合理分配资源——例如快速实验场景可提高n_workers，多人共享 UI 场景则应调低max_concurrent_tasks以保护后端。

uvicorn_config：Uvicorn 服务器配置

vmanomaly基于 Python 的 Uvicorn ASGI 服务器对外提供 HTTP 服务，uvicorn_config是一个透传给 Uvicorn 的配置字典，默认值为{"log_level": "warning"}。常用做法是通过它调整访问日志与错误日志的详细程度，例如：

uvicorn_config: log_level: 'warning'

需要更详细的请求日志时可改为'info'或'debug'（注意会显著增加日志量）。

ui_default_state：预置 UI 默认状态

自 v1.28.5 起，可以通过 URL 编码的ui_default_state预配置/vmui/打开时的默认状态（模型设置、时间范围、查询等），让用户打开即直达指定视图，适合内部团队分享视图或快速实验。该值必须 URL 编码且以#/?开头，例如：

ui_default_state: '#/?anomaly_threshold=1.0&anomaly_consecutive=true&fit_window=3d'

访问http://<vmanomaly-host>:<port>/vmui/后，UI 会自动带上anomaly_threshold=1.0、连续异常模式开启、fit_window=3d等预置状态（详见 UI 文档 Default State 一节）。如何从当前 UI 状态构造出这样的 URL？在 UI 的 URL Sharing 功能中复制状态 URL 即可，例如 UI.md 中给出的完整示例 URL 就包含anomaly_threshold、fit_window、g0.range_input、model_config等大量编码后的参数。

需要注意：默认状态是静态的，修改后需要重启服务或启用--watch热加载才会生效。

use_reader_connection_settings：复用 Reader 连接设置

自 v1.29.2 起可用。默认情况下，UI 前端直接连接数据源时无法访问需要认证（BasicAuth、Bearer Token）或 TLS 校验的数据源，常规解法是在 UI 与数据源之间架设vmauth。开启该参数后，UI 在向后端发起数据请求时会复用 Reader 段 中的datasource_url、user/password或bearer_token、verify_tls等连接设置，从而省去vmauth这一中间层。

完整示例配置

以下是 server.md 提供的完整配置示例，涵盖了上述全部参数以及与 Reader 段的联动：

server: addr: '0.0.0.0' port: 8490 path_prefix: '/vmanomaly' # optional path prefix for all HTTP routes # see https://docs.victoriametrics.com/anomaly-detection/ui/#default-state section for details on constructing the value from UI state ui_default_state: '#/?anomaly_threshold=1.0&anomaly_consecutive=true&fit_window=3d' # optional default UI state opened on /vmui/ max_concurrent_tasks: 4 # maximum number of concurrent anomaly detection tasks processed by backend uvicorn_config: # optional Uvicorn server configuration log_level: 'warning' use_reader_connection_settings: true # if set to true, UI will use connection settings from reader configuration below when connecting to data sources, allowing it to connect with the same credentials, TLS settings, etc. without requiring having vmauth in front of both UI and data sources. # other vmanomaly configuration sections, like reader, scheduler, models, etc. reader: datasource_url: %{DS_URL} user: %{DS_USER} password: %{DS_PASSWORD} # or # bearer_token: %{DS_BEARER_TOKEN} verify_tls: false

示例中%{DS_URL}、%{DS_USER}这类占位符是 vmanomaly 自 v1.25.0 起支持的环境变量引用语法：配置文件中可直接用%{ENV_NAME}引用环境变量，便于把 API Key、数据库凭据等敏感信息移出配置文件。如果引用的环境变量未设置或拼写有误，占位符不会被替换，可能引发配置校验失败或端点探测错误，部署前务必确认相关环境变量已就绪。

此外，仓库 components 总览 中的示例还展示了简化写法：use_reader_connection_settings: True（布尔值大小写不敏感），且将server段与其他段（settings、schedulers、models、reader、writer、monitoring）编排在同一个配置文件中。

热加载对 Server 配置的影响

启用--watch后，vmanomaly 支持配置热加载（详见 components 总览的 Hot reload 一节），server段中的参数变更（如path_prefix、ui_default_state、max_concurrent_tasks）可以在不重启进程的情况下自动生效。其机制要点：

• 自 v1.29.5 起，文件系统事件触发的热加载已弃用，改为按-configCheckInterval（默认30s）进行内容轮询，规避 Kubernetes ConfigMap symlink 轮换等场景下事件投递不可靠的问题；
• 检测到内容变化后，服务会重建全局配置并重新初始化各组件，vmanomaly_config_reloads_total指标以status="success"/status="failure"记录结果；
• 若重载失败，上一次有效配置继续生效，服务保持稳定运行，直至配置问题修复后成功重载；
• 启动时可加--dryRun参数对配置文件做解析与 schema 校验（不启动服务、无需 license），上线前建议先跑一遍。

在分片（sharded）部署场景中，每次全局配置变更都会重新计算当前分片的任务分配；而分片拓扑（分片数、成员索引、副本因子、分配策略）由进程启动时的环境变量决定，变更需要编排层面的 rollout 或进程重启。

访问 Server：UI 与 REST API 端点

以上述配置启动vmanomaly后：

• Web UI：访问http://localhost:8490/vmanomaly/vmui/（若未设置path_prefix则为http://localhost:8490/vmui/）。UI 用于交互式配置模型、查看检测结果、导出生产级 YAML 配置（在模型配置面板的 "YAML" Tab 或 "Show Config" → "Download" 获取，详见 UI 文档 YAML Configuration 一节）；
• REST API：例如/metrics端点位于http://localhost:8490/vmanomaly/metrics（未设前缀则为http://localhost:8490/metrics）。该端点暴露 vmanomaly 自身运行指标（vmanomaly_*前缀），供 VictoriaMetrics Agent 等 Prometheus 兼容抓取器采集；
• OpenAPI 文档：运行中的实例在/docs端点提供当前版本的 OpenAPI schema，可据此探查各 API 的请求/响应结构。

在 docker 集成示例 中，vmanomaly 服务以ports: "8490:8490"暴露端口，配置卷挂载./vmanomaly_config.yml:/config.yaml，命令为/config.yaml --licenseFile=/license，可作为本地复现与验证 UI/API 访问方式的参考。

Server 作为自监控指标端点

设置server段后，vmanomaly自身即成为指标发布端点：Prometheus 兼容的抓取器直接抓取/metrics即可获得 self-monitoring metrics，无需再配置monitoring.pull。这对需要统一从服务端口抓取指标的场景特别方便。

若选择走monitoring段的 push/pull 模型，则需注意端口区分：monitoring.pull默认端口为8080，与server段的8490是两套独立的监听端点。push 模式下指标默认仅在fit/infer/fit_infer等阶段完成后推送，可通过push_frequency（默认15m）增加周期性推送，避免低频调度下指标陈旧。

时序分析与自动调优 API（v1.30.0+）

自 v1.30.0 起，server 组件额外暴露一组有界（bounded）端点，供 UI、MCP（Model Context Protocol）与自动化工作流使用：

自 v1.30.1 起，季节性分析在采样点相对整 step 边界有偏移时仍会保留原始时间戳网格，避免因时间戳在配置采样区间内偏移而漏检每日/每周模式。

推荐的共享异步自动调优工作流

该工作流让 Agent、UI 或外部自动化在不向生产配置添加auto包装器的情况下，对一个有界查询结果样本调优共享配置（详见 models 文档 Shared asynchronous autotune workflow 一节）：

1. 用GET /api/v1/timeseries/characteristics检查查询特征，识别趋势、日历季节性、变点、缺口与间歇性行为；
2. 用POST /api/v1/autotune/tasks启动任务，提交实际查询、候选模型类、与生产一致的查询step，以及有界的limit；
3. 轮询GET /api/v1/autotune/tasks/{task_id}直至status为done；对不必要的任务用DELETE取消；
4. 校验并部署result_data.data.modelConfig——即所选模型类的具体配置。

以在线模型（如temporal_envelope）为例，models.md 给出的请求体形如：

{ "query": "sum(rate(http_requests_total[5m])) by (service)", "tuned_class_name": "temporal_envelope", "anomaly_percentage": 0.01, "step": "5m", "limit": 100, "use_profile_hints": true, "optimization_params": { "exact": true, "n_splits": 3, "n_trials": 64, "timeout": 60, "optimize_complexity": true }, "frozen_params": { "holidays": {"countries": ["US"], "group": true} } }

几点实现语义值得注意：

• anomaly_percentage被视为告警量约束而非每个验证折（fold）都必须达成的目标；
• frozen_params用于固定模型特有的、不应参与搜索的上下文参数（如已配置的节假日、多变量groupby），嵌套字典会递归合并；
• 对在线模型，exact: true通常在“生产推理是因果式（predict 后立即用新数据更新状态）”时能给出最具代表性的选择；
• 自动调优有明确限制：不能作用于自定义模型（custom model），也不能对自身递归调优（tuned_class_name不得为model.auto.AutoTunedModel）。

实用调优建议与注意事项

• 并发与负载：多人共用 UI 时调低max_concurrent_tasks，快速实验场景可配合settings.n_workers提升单任务并行度；注意n_workers <= 0表示“使用可用 CPU 核数”，且这些 worker 会与生产检测任务共享资源（见 UI.md 资源优化一节）。
• 连接凭据：数据源需要认证时，优先开启use_reader_connection_settings: true复用 Reader 凭据，省去额外的vmauth部署；敏感值用%{ENV_VAR}占位符注入。
• 配置变更：ui_default_state等静态状态变更需要重启或--watch热加载；热加载失败时旧配置继续生效，可结合--dryRun在发布前校验配置。
• 端口规划：牢记server段（UI/API，默认 8490）与monitoring.pull（默认 8080）是两套监听端点；抓取自监控指标前先确认目标端口与路径前缀。
• API 探测：运行实例的/docs端点提供 OpenAPI schema，对接 UI、MCP 或自动化脚本前可先在此核对当前版本的请求/响应结构。

通过合理配置server段，你可以让vmanomaly同时胜任“交互式异常检测工作台”（UI + 自动调优 API）与“自监控指标源”（/metrics）两个角色，并安全地接入需要认证的数据源，是搭建可观测性告警链路时不可或缺的一环。

【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics