Coroot Windows Agent 安装与配置指南在 Windows Server 上接入主机、服务与容器遥测【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/corootCoroot 的 Windows 代理coroot-windows-agent用于将 Windows 主机、Windows 服务以及 DockerWindows容器的指标、日志和 DNS/网络遥测数据回传到已部署的 Coroot 实例从而把 Windows 节点纳入 Coroot 的统一可观测性视图。本文基于仓库内的官方安装文档 windows.md完整覆盖安装前置条件、PowerShell 一键安装与 MSI 静默安装、COROOT_环境变量配置、服务生命周期管理、升级与卸载并结合仓库源码说明代理认证与遥测导出的底层机制帮助你在一台 Windows Server 上完成从安装到数据上线的全流程。Windows 代理的定位与架构边界Coroot Windows 代理是 coroot-node-agent 的 Windows 变体负责在 Windows 主机上采集并上报四类基础遥测指标Metrics以 Prometheus 格式或 Remote Write 协议导出主机、服务与容器的指标日志Logs采集 Windows Event Log 与 DockerWindows容器日志通过 OTLP/HTTP 上报DNS/网络遥测上报容器与服务的 DNS 请求、网络连接等数据Windows 服务监控将 Windows Services 作为被监控对象纳入应用视角。需要特别强调的是架构边界只有代理运行在 Windows 上。Coroot 服务端及其组件Coroot server、ClickHouse、Prometheus均不支持 Windows必须部署在 Linux 主机上Windows 代理以出站连接方式将数据推送到该实例。因此在使用本文档之前你需要已经拥有一套可访问的 Coroot 实例并准备好以下两样东西Coroot 实例的 URL默认端口8080项目 API Key在 Coroot 界面Project Settings → API keys中生成。API Key 是代理向 Coroot 上报数据的身份凭证。在源码层面代理上报时通过 HTTP 头X-API-Key携带该 KeyCoroot 侧由 collector/collector.go 定义的ApiKeyHeader X-API-Key读取并由getProject遍历项目设置中的ApiKeys匹配项目见 collector/collector.go。如果匹配失败请求会被拒绝并返回project not found (x-api-key header is missing or invalid)。API Key 的生成、编辑与删除由 api/api.go 中的ApiKeys处理逻辑完成新 Key 通过utils.RandomString(32)生成为 32 位随机字符串存储于项目设置db/project.go 中ApiKey结构体Key与Description字段。环境要求在开始安装前请确认目标主机满足以下条件要求说明操作系统Windows Server 2016 或更新版本2016 / 2019 / 2022 / 2025x64 或 arm64 架构权限管理员权限安装程序会注册 Windows 服务网络主机到 Coroot 实例的出站 TCP 连通默认端口8080快速安装PowerShell 一键安装官方推荐的安装方式是在**以管理员身份运行Run as administrator**的 PowerShell 中执行安装脚本。脚本会下载最新版本的代理并通过 MSI 包将其安装为名为coroot-windows-agent的 Windows 服务。重新执行该命令即可完成对已有安装的升级。安装前先通过环境变量注入 Coroot 地址与 API Key$env:COROOT_COLLECTOR_ENDPOINT http://COROOT_URL:8080 $env:COROOT_API_KEY API_KEY iwr -useb https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.ps1 | iex执行过程要点COROOT_COLLECTOR_ENDPOINT是 Coroot 实例的基础 URL请将COROOT_URL替换为实际地址COROOT_API_KEY替换为在Project Settings → API keys中生成的 Key默认采集间隔SCRAPE_INTERVAL为15s如需调整可先设置$env:COROOT_SCRAPE_INTERVAL再执行脚本也可以先把install.ps1下载到本地再通过-CollectorEndpoint与-ApiKey命令行参数直接传入代替环境变量方式。手动 MSI 安装如果希望完全掌控安装过程例如在离线环境或通过配置管理系统批量部署可以从 coroot-node-agent 的 releases 页面下载对应架构的 MSI 安装包x64 架构coroot-windows-agent-amd64.msiarm64 架构coroot-windows-agent-arm64.msi下载后使用msiexec进行静默安装并通过 MSI 属性传入连接参数msiexec /i coroot-windows-agent-amd64.msi /qn COLLECTOR_ENDPOINThttp://COROOT_URL:8080 API_KEYAPI_KEY SCRAPE_INTERVAL15s其中/qn表示静默模式不显示安装向导界面。MSI 支持的属性如下MSI 属性说明默认值COLLECTOR_ENDPOINTCoroot 实例的基础 URL必填API_KEY项目 API Key必填SCRAPE_INTERVAL指标采集频率15s配置命令行 Flags 与 COROOT_ 环境变量代理本身使用命令行 flags 进行配置安装器install.ps1 或 MSI只负责设置上述三个核心参数。如需调整其他选项正确做法是设置一个带COROOT_前缀的“机器级”环境变量然后重启服务。Windows 环境变量是全局的为避免与其他软件的环境变量冲突代理将所有变量统一加上COROOT_前缀进行命名空间隔离。设置机器级环境变量并重启服务的示例[Environment]::SetEnvironmentVariable(COROOT_SCRAPE_INTERVAL, 30s, Machine) Restart-Service coroot-windows-agent注意第三个参数Machine表示写入机器级系统级环境变量这样对登录用户切换保持持久生效代理服务启动时即可读取。常用环境变量对照表环境变量对应 Flag说明COROOT_COLLECTOR_ENDPOINT--collector-endpointCoroot 实例的基础 URLCOROOT_API_KEY--api-key项目 API KeyCOROOT_SCRAPE_INTERVAL--scrape-interval指标采集间隔COROOT_INSECURE_SKIP_VERIFY--insecure-skip-verify跳过对 collector 的 TLS 证书校验自签名证书场景使用COROOT_CA_FILE--ca-file自定义 CA 证书文件路径COROOT_DISABLE_LOG_PARSING--disable-log-parsing禁用 Windows Event Log / 容器日志采集COROOT_CONTAINER_DENYLIST--container-denylist需要忽略的服务/容器正则表达式Windows 平台支持的功能子集Windows 代理与 Linux 版 coroot-node-agent 使用相同的 flag 名称例如--scrape-interval但只支持与平台无关的子集。参考 Coroot-node-agent 配置参考 中的说明Linux 专属能力eBPF L7 追踪与 profiling、cgroups、Java/Python/Node.js 插桩、ICMP pinger、systemd 处理、trace/profile 导出等在 Windows 上不适用。Windows 上可用的关键配置还包括Flag环境变量说明--metrics-endpoint/--logs-endpointCOROOT_METRICS_ENDPOINT/COROOT_LOGS_ENDPOINT自定义遥测导出 URL--disable-json-log-parsingCOROOT_DISABLE_JSON_LOG_PARSING禁用从 JSON 格式日志中提取 message、severity 与 attributes--disable-gpu-monitoringCOROOT_DISABLE_GPU_MONITORING禁用 NVIDIA GPU 监控--container-allowlist/--container-denylistCOROOT_CONTAINER_ALLOWLIST/COROOT_CONTAINER_DENYLIST包含/排除服务或容器的正则--provider/--region/--availability-zone/--instance-type/--instance-life-cycleCOROOT_PROVIDER等覆盖node_cloud_info标签--wal-dir/--max-spool-sizeCOROOT_WAL_DIR/COROOT_MAX_SPOOL_SIZEWAL 目录与磁盘 Spool 上限--listenCOROOT_LISTEN本地/metrics监听地址关于--insecure-skip-verify与--ca-file的典型应用场景当 Coroot 实例使用自签名证书或内部 CA 时代理默认会拒绝建立 TLS 连接此时可配置自定义 CA推荐安全性更好或在可控环境中临时使用COROOT_INSECURE_SKIP_VERIFYtrue跳过校验。这与 Coroot 侧 collector 的实现相对应——collector/metrics.go 中分别维护了secureClient默认校验与insecureClientInsecureSkipVerify: true两个 HTTP 客户端。管理代理服务代理安装完成后以 Windows 服务coroot-windows-agent运行常用的管理命令如下Get-Service coroot-windows-agent # 查看服务状态 Restart-Service coroot-windows-agent # 重启服务修改配置后执行 Get-WinEvent -ProviderName coroot-windows-agent -MaxEvents 50 # 查看代理日志Get-Service用于确认服务是否存在以及当前状态Running / Stopped修改任何COROOT_环境变量后都必须重启服务使其生效代理运行日志通过 Windows Event Log 提供Provider 名为coroot-windows-agentGet-WinEvent是排查启动失败、连接异常等问题的主要手段。升级升级方式与安装一致重新运行安装脚本或安装新版本的 MSI 包。MSI 会对现有安装执行就地升级in-place upgrade已有配置服务参数会保留因此升级后通常无需重新配置。# 方式一重新执行一键安装脚本需再次设置 COROOT_COLLECTOR_ENDPOINT / COROOT_API_KEY iwr -useb https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.ps1 | iex # 方式二安装新版 MSI msiexec /i coroot-windows-agent-amd64.msi /qn卸载卸载有两种方式任选其一方式一通过系统设置。打开Settings → Apps设置 → 应用找到Coroot Windows Agent点击卸载。方式二PowerShell 命令Get-Package Coroot Windows Agent | Uninstall-Package卸载完成后coroot-windows-agent服务会随之移除如需彻底清理可再确认机器级环境变量COROOT_*是否保留。底层机制数据如何到达 Coroot理解代理上报链路有助于排查问题。Coroot 侧的数据接收由 collector 包实现代理作为客户端把各类型遥测推送到对应端点指标通过 Prometheus Remote Write 协议发送Coroot 在 collector/metrics.go 的Metrics处理器中按X-API-Key头解析项目再根据项目配置决定写入 ClickHouse 或转发到 Prometheus若项目配置为 ClickHouse 存储指标会进入按batchLimit 10000、batchTimeout 5s组织的批量写入队列见 collector/collector.go日志由 collector/logs.go 的Logs处理器接收同样以 API Key 定位项目并批量写入配置下发--collector-endpoint同时用于向 Coroot 拉取配置如应用插桩配置对应 collector/config.go 的Config处理器。由于 Windows 上不涉及 eBPF 追踪与 profile 导出Windows 代理上报的核心数据流为指标Remote Write 日志OTLP/HTTP。在部署后若发现节点未出现在 Coroot 界面可依次检查出站 TCP 连通性Test-NetConnection COROOT_URL -Port 8080、COROOT_API_KEY是否与项目匹配、代理服务日志中的认证错误以及 Windows 防火墙是否拦截了出站请求。小结本文完整覆盖了 Coroot Windows Agent 的安装与运维流程通过 PowerShell 脚本或 MSI 安装、以COROOT_前缀机器环境变量配置参数、使用 Windows 服务命令管理生命周期以及升级与卸载。关键要点可归纳为代理与 Coroot 服务端分离部署Windows 只跑代理API Key 是唯一认证凭证对应X-API-Key请求头所有配置修改后必须Restart-Service coroot-windows-agent才能生效日志排查入口是Get-WinEvent -ProviderName coroot-windows-agent。更多平台无关的完整 flag 清单与说明可继续阅读 Coroot-node-agent 配置参考 与 Coroot-cluster-agent 配置参考。【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/coroot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Coroot Windows Agent 安装与配置指南：在 Windows Server 上接入主机、服务与容器遥测
Coroot Windows Agent 安装与配置指南在 Windows Server 上接入主机、服务与容器遥测【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/corootCoroot 的 Windows 代理coroot-windows-agent用于将 Windows 主机、Windows 服务以及 DockerWindows容器的指标、日志和 DNS/网络遥测数据回传到已部署的 Coroot 实例从而把 Windows 节点纳入 Coroot 的统一可观测性视图。本文基于仓库内的官方安装文档 windows.md完整覆盖安装前置条件、PowerShell 一键安装与 MSI 静默安装、COROOT_环境变量配置、服务生命周期管理、升级与卸载并结合仓库源码说明代理认证与遥测导出的底层机制帮助你在一台 Windows Server 上完成从安装到数据上线的全流程。Windows 代理的定位与架构边界Coroot Windows 代理是 coroot-node-agent 的 Windows 变体负责在 Windows 主机上采集并上报四类基础遥测指标Metrics以 Prometheus 格式或 Remote Write 协议导出主机、服务与容器的指标日志Logs采集 Windows Event Log 与 DockerWindows容器日志通过 OTLP/HTTP 上报DNS/网络遥测上报容器与服务的 DNS 请求、网络连接等数据Windows 服务监控将 Windows Services 作为被监控对象纳入应用视角。需要特别强调的是架构边界只有代理运行在 Windows 上。Coroot 服务端及其组件Coroot server、ClickHouse、Prometheus均不支持 Windows必须部署在 Linux 主机上Windows 代理以出站连接方式将数据推送到该实例。因此在使用本文档之前你需要已经拥有一套可访问的 Coroot 实例并准备好以下两样东西Coroot 实例的 URL默认端口8080项目 API Key在 Coroot 界面Project Settings → API keys中生成。API Key 是代理向 Coroot 上报数据的身份凭证。在源码层面代理上报时通过 HTTP 头X-API-Key携带该 KeyCoroot 侧由 collector/collector.go 定义的ApiKeyHeader X-API-Key读取并由getProject遍历项目设置中的ApiKeys匹配项目见 collector/collector.go。如果匹配失败请求会被拒绝并返回project not found (x-api-key header is missing or invalid)。API Key 的生成、编辑与删除由 api/api.go 中的ApiKeys处理逻辑完成新 Key 通过utils.RandomString(32)生成为 32 位随机字符串存储于项目设置db/project.go 中ApiKey结构体Key与Description字段。环境要求在开始安装前请确认目标主机满足以下条件要求说明操作系统Windows Server 2016 或更新版本2016 / 2019 / 2022 / 2025x64 或 arm64 架构权限管理员权限安装程序会注册 Windows 服务网络主机到 Coroot 实例的出站 TCP 连通默认端口8080快速安装PowerShell 一键安装官方推荐的安装方式是在**以管理员身份运行Run as administrator**的 PowerShell 中执行安装脚本。脚本会下载最新版本的代理并通过 MSI 包将其安装为名为coroot-windows-agent的 Windows 服务。重新执行该命令即可完成对已有安装的升级。安装前先通过环境变量注入 Coroot 地址与 API Key$env:COROOT_COLLECTOR_ENDPOINT http://COROOT_URL:8080 $env:COROOT_API_KEY API_KEY iwr -useb https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.ps1 | iex执行过程要点COROOT_COLLECTOR_ENDPOINT是 Coroot 实例的基础 URL请将COROOT_URL替换为实际地址COROOT_API_KEY替换为在Project Settings → API keys中生成的 Key默认采集间隔SCRAPE_INTERVAL为15s如需调整可先设置$env:COROOT_SCRAPE_INTERVAL再执行脚本也可以先把install.ps1下载到本地再通过-CollectorEndpoint与-ApiKey命令行参数直接传入代替环境变量方式。手动 MSI 安装如果希望完全掌控安装过程例如在离线环境或通过配置管理系统批量部署可以从 coroot-node-agent 的 releases 页面下载对应架构的 MSI 安装包x64 架构coroot-windows-agent-amd64.msiarm64 架构coroot-windows-agent-arm64.msi下载后使用msiexec进行静默安装并通过 MSI 属性传入连接参数msiexec /i coroot-windows-agent-amd64.msi /qn COLLECTOR_ENDPOINThttp://COROOT_URL:8080 API_KEYAPI_KEY SCRAPE_INTERVAL15s其中/qn表示静默模式不显示安装向导界面。MSI 支持的属性如下MSI 属性说明默认值COLLECTOR_ENDPOINTCoroot 实例的基础 URL必填API_KEY项目 API Key必填SCRAPE_INTERVAL指标采集频率15s配置命令行 Flags 与 COROOT_ 环境变量代理本身使用命令行 flags 进行配置安装器install.ps1 或 MSI只负责设置上述三个核心参数。如需调整其他选项正确做法是设置一个带COROOT_前缀的“机器级”环境变量然后重启服务。Windows 环境变量是全局的为避免与其他软件的环境变量冲突代理将所有变量统一加上COROOT_前缀进行命名空间隔离。设置机器级环境变量并重启服务的示例[Environment]::SetEnvironmentVariable(COROOT_SCRAPE_INTERVAL, 30s, Machine) Restart-Service coroot-windows-agent注意第三个参数Machine表示写入机器级系统级环境变量这样对登录用户切换保持持久生效代理服务启动时即可读取。常用环境变量对照表环境变量对应 Flag说明COROOT_COLLECTOR_ENDPOINT--collector-endpointCoroot 实例的基础 URLCOROOT_API_KEY--api-key项目 API KeyCOROOT_SCRAPE_INTERVAL--scrape-interval指标采集间隔COROOT_INSECURE_SKIP_VERIFY--insecure-skip-verify跳过对 collector 的 TLS 证书校验自签名证书场景使用COROOT_CA_FILE--ca-file自定义 CA 证书文件路径COROOT_DISABLE_LOG_PARSING--disable-log-parsing禁用 Windows Event Log / 容器日志采集COROOT_CONTAINER_DENYLIST--container-denylist需要忽略的服务/容器正则表达式Windows 平台支持的功能子集Windows 代理与 Linux 版 coroot-node-agent 使用相同的 flag 名称例如--scrape-interval但只支持与平台无关的子集。参考 Coroot-node-agent 配置参考 中的说明Linux 专属能力eBPF L7 追踪与 profiling、cgroups、Java/Python/Node.js 插桩、ICMP pinger、systemd 处理、trace/profile 导出等在 Windows 上不适用。Windows 上可用的关键配置还包括Flag环境变量说明--metrics-endpoint/--logs-endpointCOROOT_METRICS_ENDPOINT/COROOT_LOGS_ENDPOINT自定义遥测导出 URL--disable-json-log-parsingCOROOT_DISABLE_JSON_LOG_PARSING禁用从 JSON 格式日志中提取 message、severity 与 attributes--disable-gpu-monitoringCOROOT_DISABLE_GPU_MONITORING禁用 NVIDIA GPU 监控--container-allowlist/--container-denylistCOROOT_CONTAINER_ALLOWLIST/COROOT_CONTAINER_DENYLIST包含/排除服务或容器的正则--provider/--region/--availability-zone/--instance-type/--instance-life-cycleCOROOT_PROVIDER等覆盖node_cloud_info标签--wal-dir/--max-spool-sizeCOROOT_WAL_DIR/COROOT_MAX_SPOOL_SIZEWAL 目录与磁盘 Spool 上限--listenCOROOT_LISTEN本地/metrics监听地址关于--insecure-skip-verify与--ca-file的典型应用场景当 Coroot 实例使用自签名证书或内部 CA 时代理默认会拒绝建立 TLS 连接此时可配置自定义 CA推荐安全性更好或在可控环境中临时使用COROOT_INSECURE_SKIP_VERIFYtrue跳过校验。这与 Coroot 侧 collector 的实现相对应——collector/metrics.go 中分别维护了secureClient默认校验与insecureClientInsecureSkipVerify: true两个 HTTP 客户端。管理代理服务代理安装完成后以 Windows 服务coroot-windows-agent运行常用的管理命令如下Get-Service coroot-windows-agent # 查看服务状态 Restart-Service coroot-windows-agent # 重启服务修改配置后执行 Get-WinEvent -ProviderName coroot-windows-agent -MaxEvents 50 # 查看代理日志Get-Service用于确认服务是否存在以及当前状态Running / Stopped修改任何COROOT_环境变量后都必须重启服务使其生效代理运行日志通过 Windows Event Log 提供Provider 名为coroot-windows-agentGet-WinEvent是排查启动失败、连接异常等问题的主要手段。升级升级方式与安装一致重新运行安装脚本或安装新版本的 MSI 包。MSI 会对现有安装执行就地升级in-place upgrade已有配置服务参数会保留因此升级后通常无需重新配置。# 方式一重新执行一键安装脚本需再次设置 COROOT_COLLECTOR_ENDPOINT / COROOT_API_KEY iwr -useb https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.ps1 | iex # 方式二安装新版 MSI msiexec /i coroot-windows-agent-amd64.msi /qn卸载卸载有两种方式任选其一方式一通过系统设置。打开Settings → Apps设置 → 应用找到Coroot Windows Agent点击卸载。方式二PowerShell 命令Get-Package Coroot Windows Agent | Uninstall-Package卸载完成后coroot-windows-agent服务会随之移除如需彻底清理可再确认机器级环境变量COROOT_*是否保留。底层机制数据如何到达 Coroot理解代理上报链路有助于排查问题。Coroot 侧的数据接收由 collector 包实现代理作为客户端把各类型遥测推送到对应端点指标通过 Prometheus Remote Write 协议发送Coroot 在 collector/metrics.go 的Metrics处理器中按X-API-Key头解析项目再根据项目配置决定写入 ClickHouse 或转发到 Prometheus若项目配置为 ClickHouse 存储指标会进入按batchLimit 10000、batchTimeout 5s组织的批量写入队列见 collector/collector.go日志由 collector/logs.go 的Logs处理器接收同样以 API Key 定位项目并批量写入配置下发--collector-endpoint同时用于向 Coroot 拉取配置如应用插桩配置对应 collector/config.go 的Config处理器。由于 Windows 上不涉及 eBPF 追踪与 profile 导出Windows 代理上报的核心数据流为指标Remote Write 日志OTLP/HTTP。在部署后若发现节点未出现在 Coroot 界面可依次检查出站 TCP 连通性Test-NetConnection COROOT_URL -Port 8080、COROOT_API_KEY是否与项目匹配、代理服务日志中的认证错误以及 Windows 防火墙是否拦截了出站请求。小结本文完整覆盖了 Coroot Windows Agent 的安装与运维流程通过 PowerShell 脚本或 MSI 安装、以COROOT_前缀机器环境变量配置参数、使用 Windows 服务命令管理生命周期以及升级与卸载。关键要点可归纳为代理与 Coroot 服务端分离部署Windows 只跑代理API Key 是唯一认证凭证对应X-API-Key请求头所有配置修改后必须Restart-Service coroot-windows-agent才能生效日志排查入口是Get-WinEvent -ProviderName coroot-windows-agent。更多平台无关的完整 flag 清单与说明可继续阅读 Coroot-node-agent 配置参考 与 Coroot-cluster-agent 配置参考。【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/coroot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
