安装与升级

运行要求

场景	要求
主服务 / Wasm 分析	Linux；预编译安装包，无需 Go、Rust 或单独 Wasm 运行时
网络采集	可见的接口及有效抓包权限；建议限定镜像范围
OpenSSL / Go TLS	Linux ≥ 5.15、内核 BTF、root 探针及受支持的目标运行时
Go QUIC / HTTP/3	Linux ≥ 5.17、目标 ELF 符号和 DWARF、受支持的 quic-go 版本

当前指南对应最新 0.3.0-dev 开发快照，构建标识 0.3.0-dev-20261018-5e1320d3。已有 Linux arm64 / OrbStack 运行记录；amd64 仅交叉编译，本页未提供完整安装包，不能据此推断运行兼容。历史预览见版本下载，限制见支持边界。

主程序为静态 Go 二进制；最新包中的 eCapture 辅助探针还需要 glibc ≥ 2.34 和系统 libpcap.so.0.8。已验证的参考环境为 Debian 13，安装器不自动安装系统库。解压后可用 ldd lib/ecapture-probe 检查是否出现 not found；其他发行版仍需验证内核、库及探针兼容性。

安装候选包

从版本下载取得完整包的全部分片，按该页命令校验并合并成 netflowscout-linux-arm64.tar.gz。如果已按下载页解压，进入相应 nfs-版本 目录直接运行 sudo sh deploy/install.sh。以下适用于只完成合并、尚未解压的情况：

sha256sum -c netflowscout-linux-arm64.tar.gz.sha256
mkdir netflowscout-package
tar -xzf netflowscout-linux-arm64.tar.gz -C netflowscout-package
cd netflowscout-package
sudo sh deploy/install.sh

将文件名中的 arm64 换为实际交付架构。安装器核对包内 SHA256SUMS，创建系统用户及目录，安装服务和插件，不自动启动采集。校验和提供完整性核对，不是发布者签名。

路径	用途
`/usr/local/bin/netflowscout`	CLI 和主程序
`/usr/local/lib/netflowscout/plugins`	管理员安装的 Wasm 包
`/etc/netflowscout/netflowscout.json`	主配置，root:netflowscout / 0640
`/etc/netflowscout/endpoints/`	端点配置，root / 0600
`/var/lib/netflowscout/`	私有 WAL 和本地事件

配置并启动

首次安装向导

sudo netflowscout init --lang zh

英文使用 sudo netflowscout init --lang en。

首次安装器不写入占位配置，也不自动运行向导。向导逐项选择服务名、探针 ID、端点或网络采集、本地文件或本地加 Dataway 输出。端点配置选择真实可执行文件、探针、协议和角色；网络配置显示本机网卡，要求显式选择接口和过滤范围。开始提问前先检查安装身份、已有文件及目录可写性；可写性检查仅创建并删除一个私有临时文件，不创建目标配置目录。过滤器按正式采集语法即时检查，错误时可原位重填，保留此前答案。回车接受默认值，选项不区分大小写；保存可输入 yes/no、y/n 或是/否，:quit、Ctrl+C 或 EOF 取消。选择协议来自已安装插件并保留声明名称；若两个名称仅大小写不同，须原样输入以消除歧义。

向导先在私有临时目录验证 Wasm、schema、规则和配置，再展示路径、采集及输出摘要；最后默认 不保存，输入 yes 才生成主配置、rules-observability.nfs，端点模式还生成 endpoints/app.json。主配置和规则为 root:netflowscout / 0640，端点为 root / 0600。事件默认脱敏，原始留存和验证 canary 保持关闭，规则阈值可后续调整。每个文件先写入同目录私有临时文件并同步，再不覆盖地原子发布，主配置最后发布；保存失败时按文件身份清理本次产物，多文件保存仍不是断电事务。此步骤不证明已经抓到流量或完成投递。

Dataway 只填写不含凭据的基础 URL 和环境变量名。之后在 root 管理的 /etc/netflowscout/output.env（0600）设置变量值，供 systemd 读取；向导不索取 token。doctor 检查当前命令环境，不会自动读取该文件。

已有文件一律拒绝覆盖，包括旧安装器留下的示例配置；已有安装请使用 netflowscout tui --control 或按变更流程编辑。可以用 init --dir /新目录 --plugins /绝对路径/plugins 生成独立参考配置，文件为 0600；它仍使用部署用的 /run/netflowscout、/var/lib/netflowscout，不是隔离运行沙盒，默认 systemd 单元也不会使用自定义目录。向导不给出参考配置的直接启动命令；运行前先安装配置，或设置独立 socket、WAL、输出路径及单元。自动化生成继续使用 configure。

保存阶段不启动服务；默认目录的交互终端可确认继续 setup，或之后单独运行。详见接入工作流。也可手动预检再启动：

sudo netflowscout check --config /etc/netflowscout/netflowscout.json
sudo netflowscout doctor --config /etc/netflowscout/netflowscout.json \
  --endpoint-config /etc/netflowscout/endpoints/app.json
sudo systemctl enable --now netflowscout.service netflowscout-analyzer.service
sudo systemctl enable --now netflowscout-discovery@app.service

网络模式不需要 discovery 单元。端点模式按端点指南配置；启动后必须等待 attached，再做真实业务验证。

升级与回退

sudo netflowscout upgrade --package /path/netflowscout-linux-arm64.tar.gz
sudo netflowscout rollback

升级先校验包和完整候选插件/规则，再备份并停止原活动单元，更新程序、探针、BPF、插件和单元，恢复原活动服务；失败尝试恢复备份。管理员插件保留，但冲突会在停服前拒绝。

回退恢复上一版本及原配置；WAL、兼容规则检查点和日志不被替换。任意版本间的数据迁移不作保证。不要手动混搭旧探针、新 BPF 或不相容 schema。重启会产生采集空档，历史流量无法补采。

初始化支持 :back、摘要 edit 及运行应用/服务选择；细节见接入与调查。

安装与升级 ​

运行要求 ​

安装候选包 ​

配置并启动 ​