Server 配置(nettact-server)

nettact-server 是自托管的单二进制 Server:HTTP API + 内置 Web 控制台 + 本地 存储(SQLite 存配置与状态,tsdb/ 目录存指标时序,两者同属一个数据集)。它通过 命令行 flag 和少量环境变量配置,其中包括 NETTACT_SERVER_ADDR 以及用于前端下载的可选变量(见 Web 控制台前端);Docker Compose 部署时,常用项通过 .env 映射为 flag(见 .env 变量对照)。

本页与 nettact-server --help 逐项对应;若两者不一致,以 --help 为准并请报告。

---

Flag 参考

Flag	默认值	说明
-addr	:12450	监听地址([host]:port)。显式传入时会覆盖 NETTACT_SERVER_ADDR 和控制台设置,见监听地址。
-db	./nettact.db	SQLite 数据库路径(会同时产生 -wal/-shm 伴生文件,并在同目录创建存放指标时序的 tsdb/ 文件夹——备份时两者一起拷)。
-webui-dir	空(= <db 目录>/webui)	Web 控制台前端的下载/安装目录,版本装到 <webui-dir>/<version>/。
-dev	false	开发模式:对 Vite 开发源(web-console)开放 CORS,会话 Cookie 不带 Secure。生产勿用。
-admin-user	空	可选;仅首次运行生效。省略则首启自动创建 admin 账号并生成随机密码(打印一次)。
-admin-pass	空	可选;仅首次运行生效。省略则首启自动生成初始密码并打印(仅一次)。
-tls-cert	空	TLS 证书路径;与 -tls-key 同时提供时原生服务 HTTPS/WSS。
-tls-key	空	TLS 私钥路径;必须与 -tls-cert 成对出现,只给一个则拒绝启动(避免误退回明文)。
-secure-cookie	auto	会话 Cookie 的 Secure 属性:auto / true / false,见会话 Cookie。

另有一个子命令:

nettact-server passwd -db <路径>     # 离线重置管理员密码(找回密码用)

见管理员凭据与改密。

---

.env 变量对照(Docker Compose)

Compose 部署时不直接写 flag,而是在 .env 里设变量,由 docker-compose.yml 映射(改了 .env 需 docker compose up -d 重建才生效):

.env 变量	默认值	作用
NETTACT_HTTP_PORT	12450	发布到宿主机的端口(容器内固定监听 :12450,此变量只改端口映射的宿主机侧)。因为改的是宿主机侧,也可以写成地址加端口把控制台限制在某张网卡上,例如 10.0.0.5:12450。
NETTACT_SECURE_COOKIE	auto	映射为 -secure-cookie;前置 TLS 终止反代时设 true。
NETTACT_TZ	UTC	映射为容器的 TZ,决定给人看的时间怎么打印(通知正文、邮件页脚、日志)。填任意 IANA 时区名如 Asia/Shanghai;镜像无需装 tzdata。
NETTACT_SERVER_VERSION	latest	Server 镜像 tag(建议钉住 vX.Y.Z 便于可复现升级)。
NETTACT_AGENT_VERSION	latest	Agent 镜像 tag(与 Server 独立发版)。
NETTACT_SERVER_IMAGE	ghcr.io/nettact/nettact-server	覆盖 Server 镜像地址(如本地构建测试)。
NETTACT_AGENT_IMAGE	ghcr.io/nettact/nettact-agent	覆盖 Agent 镜像地址。

数据库路径、TLS 等其余 flag 在 docker-compose.yml 的 command: 里 按需直接增删(TLS 的注释行已备好,同时要换 https 版 healthcheck,见 部署篇)。

---

监听地址

监听地址有四个来源,优先级从高到低:

1. 显式传入的 -addr flag;
2. NETTACT_SERVER_ADDR(设置为非空的 [host]:port 时);
3. 控制台里保存的监听地址(Settings → Listen address,存在数据库);
4. 内置默认 :12450。

显式传入 -addr 时,其值始终生效。当 -addr 或 NETTACT_SERVER_ADDR 管理监听地址时, Settings 页会保留编辑控件但将其禁用,并显示需要修改的外部来源;设置 API 也会拒绝直接 写入 listen_addr。移除对应参数或变量并重启后,数据库中保存的值会重新生效;若保存值无法绑定 (端口被占等),Server 会自动回退到内置默认地址并在日志与 server-info 里报告,格式非法 则记日志并忽略。flag 或环境变量本身若格式非法或无法绑定,Server 会启动失败,不会静默 改用其他来源。

Docker 部署实际上不会用到该设置:Compose 文件以 -addr :12450(且 network_mode: isolated)启动 Server,按上面的优先级,flag 始终管理监听地址——Settings 控件保持禁用,API 拒绝写入 listen_addr,任何已保存的值都处于休眠。宿主机侧的端口映射由 NETTACT_HTTP_PORT 决定,与这个设置无关;数据库里遗留的旧保存值在 flag 存在期间不起作用。

---

管理员凭据与改密

单用户(单管理员)模型,无多用户/租户。

• 首次运行(数据库为空):自动创建管理员。若省略 -admin-user/-admin-pass, 用户名为 admin,密码随机生成并在启动日志里打印一次(NetTact first run 区块);compose 部署用 docker compose logs server 读取。
• -admin-user / -admin-pass 只在首次运行时用于指定初始账号;之后的运行忽略 这两个 flag,不能用它们改密。
• 修改密码(任选其一):
  • 控制台:登录后 Settings 页修改;
  • 命令行:nettact-server passwd -db <路径>(compose: docker compose exec server nettact-server passwd -db /data/nettact.db)。 交互式输入新密码(不经命令行参数,不进 shell 历史);重置后所有已登录 会话立即失效,服务端在运行中则建议重启一次。
• 密码策略:至少 8 个字符。

---

数据保留

指标存储分四层:原始采样、1 分钟聚合、1 小时聚合、1 天聚合。保留窗口固定、不可 配置:原始采样 2 天、1 分钟聚合 30 天、1 小时聚合 2 年,1 天聚合永久保留。

图表按查询范围自动选层:≤2 小时的范围读原始数据,更长范围读聚合——所以原始 采样只承担"最近两小时"级别的细节回看,长期趋势由聚合层保证。原始采样保留窗口 短是刻意的:按 1s 探测间隔计,每多留一天原始数据就要在 tsdb 目录里多占数百 MB, 而同样的问题聚合层能用零头的空间回答。

---

TLS

-tls-cert 与 -tls-key 同时提供时,Server 原生服务 HTTPS(控制台)与 WSS (Agent 连接),监听变为 TLS-only(不再接受明文 HTTP)。只提供其中一个则 启动失败——防止挂载的证书路径写错时静默退回明文、暴露令牌与遥测。

另一种做法是前置 TLS 终止反向代理(Caddy/Nginx/Traefik),Server 保持明文, 此时把 -secure-cookie 设为 true(见下节)。

---

会话 Cookie

浏览器只在 HTTPS 页面上发送带 Secure 的 Cookie,所以这个属性配错的症状是 登录成功后立刻掉线(localhost 除外)。-secure-cookie 三个取值:

取值	行为	适用场景
auto(默认)	本进程启用 TLS 时才带 Secure	绝大多数场景;纯 HTTP 部署开箱可登录
true	恒带 Secure	TLS 终止反代在前(浏览器侧 https,Server 明文)
false	恒不带	不推荐

-dev 模式下恒不带 Secure(本地 Vite 走明文)。

---

Web 控制台前端

前端(web-console)不打包进二进制/镜像,由 Server 运行时自动下载:编译时 烧入精确的前端版本号,首启检测到缺失就从 NetTact 下载中心 下载(SHA256 校验)到 -webui-dir (默认 <db 目录>/webui),下载完成前非 /api 路径返回内置占位页(503),API 与探针 不受影响,失败后台重试。默认下载路径为 https://d.nettact.org/web-console/<tag>/<asset>。下载中心的 Cloudflare Worker 负责访问官方 GitHub Release(包括私有仓库),Server 无需配置 GitHub Token。

两个可选环境变量覆盖此行为(开发/内网场景):

环境变量	作用
NETTACT_WEBUI_LOCAL	直接服务本地目录里的 dist(如 ../web-console/dist);开发构建(Version=dev,未烧版本)不自动下载,用这个。
NETTACT_WEBUI_BASE_URL	覆盖下载源;源必须提供 <base>/<tag>/<asset> 布局。也可以完全离线——把前端预置到 <webui-dir>/<version>/。