xsxiaosa/mfd-monitor-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

✨ feat(agent): 添加 token 鉴权和流程文档

Browse Source 
* 默认监听调整为 0.0.0.0:8080，并要求查询参数 token
* 支持首次 run 自动生成含随机 token 的配置文件
* 补充 HTTP 鉴权、配置校验和相关测试
* 完善代码注释，覆盖缓存、上报、服务和平台采集路径
* 新增架构与开发流程文档，补充一键构建脚本
This commit is contained in:
codex
2026-05-22 06:46:21 +00:00
parent 877e4cf41d
commit de3fd88948
19 changed files with 875 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
internal/config/config.go
View File

@@ -1,45 +1,68 @@
package config
import (
"crypto/rand"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"os"
"strconv"
"time"
)
// DefaultConfigFileName 是未指定 -config 时在工作目录下使用的默认配置文件名。
const DefaultConfigFileName = "config.json"
// Config 包含运行时、上报、采集与服务注册相关的全部配置项。
type Config struct {
HostID string `json:"host_id"`
HTTP HTTPConfig `json:"http"`
// HostID 是对外上报和查询时使用的机器标识；为空时采集器会尽力回退为主机名。
HostID string `json:"host_id"`
// HTTP 控制本地查询 API 的监听与 token 鉴权。
HTTP HTTPConfig `json:"http"`
// Collect 控制后台快照采集周期与单轮超时。
Collect CollectConfig `json:"collect"`
Report ReportConfig `json:"report"`
// Report 控制可选的中心端主动上报流程。
Report ReportConfig `json:"report"`
// Service 控制 Linux systemd unit 与 Windows 服务注册元数据。
Service ServiceConfig `json:"service"`
}
// HTTPConfig 控制本地 HTTP API 的监听地址。
// HTTPConfig 控制本地 HTTP API 的监听地址与查询参数鉴权 token。
type HTTPConfig struct {
// ListenAddress 是 HTTP API 监听地址，默认 0.0.0.0:8080 会暴露到所有网卡。
ListenAddress string `json:"listen_address"`
// Token 用于 GET 请求查询参数 ?token= 的鉴权，禁止为空。
Token string `json:"token"`
}
// CollectConfig 控制周期性主机状态采集。
type CollectConfig struct {
// Interval 是后台刷新 HostStatus 缓存的周期。
Interval Duration `json:"interval"`
Timeout Duration `json:"timeout"`
// Timeout 是单轮聚合采集的整体截止时间。
Timeout Duration `json:"timeout"`
}
// ReportConfig 控制可选的周期性状态 POST 上报。
type ReportConfig struct {
Enabled bool `json:"enabled"`
Endpoint string `json:"endpoint"`
// Enabled 控制是否启动主动上报循环。
Enabled bool `json:"enabled"`
// Endpoint 是中心端接收 HostStatus JSON 的 HTTP URL，启用上报时必填。
Endpoint string `json:"endpoint"`
// Interval 是两次上报尝试之间的周期。
Interval Duration `json:"interval"`
Timeout Duration `json:"timeout"`
// Timeout 是单次 POST 请求的 HTTP 客户端超时。
Timeout Duration `json:"timeout"`
}
// ServiceConfig 控制操作系统服务注册时使用的元数据。
type ServiceConfig struct {
Name string `json:"name"`
// Name 是 systemd unit 名称和 Windows 服务名。
Name string `json:"name"`
// DisplayName 是 Windows 服务管理器中显示的名称。
DisplayName string `json:"display_name"`
// Description 是 systemd unit 与 Windows 服务的说明文本。
Description string `json:"description"`
}
@@ -70,10 +93,10 @@ func (d *Duration) UnmarshalJSON(data []byte) error {
return nil
}
// Default 返回适合本地运行的安全默认配置。
// Default 返回内存中的默认配置（不含 token，需由配置文件或 LoadOrCreate 提供）。
func Default() Config {
return Config{
HTTP: HTTPConfig{ListenAddress: "127.0.0.1:8080"},
HTTP: HTTPConfig{ListenAddress: "0.0.0.0:8080"},
Collect: CollectConfig{
Interval: Duration(30 * time.Second),
Timeout: Duration(10 * time.Second),
@@ -91,25 +114,86 @@ func Default() Config {
}
}
// Load 读取可选的 JSON 配置文件，应用环境变量覆盖，并校验必填项。
// ResolvePath 将 CLI 传入的配置路径解析为实际文件路径。
func ResolvePath(explicit string) string {
if explicit != "" {
return explicit
}
return DefaultConfigFileName
}
// LoadOrCreate 在配置文件不存在时写入含随机 token 的默认配置，再加载。
// 仅供 agent run 使用；服务安装等场景应使用 Load。
func LoadOrCreate(path string) (Config, error) {
if _, err := os.Stat(path); errors.Is(err, os.ErrNotExist) {
cfg := Default()
// 自动生成配置时必须创建强随机 token，避免默认空 token 暴露主机状态 API。
token, err := generateToken()
if err != nil {
return cfg, fmt.Errorf("generate http token: %w", err)
}
cfg.HTTP.Token = token
if err := writeConfigFile(path, cfg); err != nil {
return cfg, err
}
}
return Load(path)
}
// Load 读取 JSON 配置文件，应用环境变量覆盖，并校验必填项。
func Load(path string) (Config, error) {
cfg := Default()
if path != "" {
data, err := os.ReadFile(path)
if err != nil {
return cfg, err
}
if err := json.Unmarshal(data, &cfg); err != nil {
return cfg, err
}
if path == "" {
return cfg, errors.New("config path is required")
}
data, err := os.ReadFile(path)
if err != nil {
return cfg, err
}
if err := json.Unmarshal(data, &cfg); err != nil {
return cfg, err
}
applyEnv(&cfg)
if cfg.Report.Enabled && cfg.Report.Endpoint == "" {
return cfg, errors.New("report endpoint is required when reporting is enabled")
if err := validate(&cfg); err != nil {
return cfg, err
}
return cfg, nil
}
// validate 检查配置中的必填与安全约束。
func validate(cfg *Config) error {
if cfg.HTTP.Token == "" {
return errors.New("http.token is required")
}
if cfg.Report.Enabled && cfg.Report.Endpoint == "" {
return errors.New("report endpoint is required when reporting is enabled")
}
return nil
}
// writeConfigFile 将配置以缩进 JSON 写入 path，权限 0600。
func writeConfigFile(path string, cfg Config) error {
data, err := json.MarshalIndent(cfg, "", " ")
if err != nil {
return fmt.Errorf("marshal config: %w", err)
}
data = append(data, '\n')
// 配置内包含 HTTP token，默认只允许当前用户读写。
if err := os.WriteFile(path, data, 0o600); err != nil {
return fmt.Errorf("write config %s: %w", path, err)
}
return nil
}
// generateToken 生成用于 HTTP 查询参数鉴权的随机十六进制字符串。
func generateToken() (string, error) {
buf := make([]byte, 32)
if _, err := rand.Read(buf); err != nil {
return "", err
}
return hex.EncodeToString(buf), nil
}
// applyEnv 将支持的 MFD_AGENT_* 环境变量覆盖到 cfg 上。
func applyEnv(cfg *Config) {
if value := os.Getenv("MFD_AGENT_HOST_ID"); value != "" {
@@ -118,7 +202,11 @@ func applyEnv(cfg *Config) {
if value := os.Getenv("MFD_AGENT_LISTEN"); value != "" {
cfg.HTTP.ListenAddress = value
}
if value := os.Getenv("MFD_AGENT_TOKEN"); value != "" {
cfg.HTTP.Token = value
}
if value := os.Getenv("MFD_AGENT_REPORT_ENABLED"); value != "" {
// 非法环境变量值保持文件配置不变，避免拼写错误让 agent 无法启动。
if parsed, err := strconv.ParseBool(value); err == nil {
cfg.Report.Enabled = parsed
}

91
internal/config/config_test.go
View File

@@ -1,18 +1,23 @@
package config
import (
"encoding/json"
"os"
"path/filepath"
"testing"
"time"
)
// TestDefaultConfigUsesLocalhostAndSaneIntervals 验证默认配置使用本地监听地址与合理的采集间隔。
func TestDefaultConfigUsesLocalhostAndSaneIntervals(t *testing.T) {
// TestDefaultConfigUsesAllInterfacesAndSaneIntervals 验证默认配置监听所有网卡且采集间隔合理。
func TestDefaultConfigUsesAllInterfacesAndSaneIntervals(t *testing.T) {
cfg := Default()
if cfg.HTTP.ListenAddress != "127.0.0.1:8080" {
if cfg.HTTP.ListenAddress != "0.0.0.0:8080" {
t.Fatalf("listen address = %q", cfg.HTTP.ListenAddress)
}
if cfg.HTTP.Token != "" {
t.Fatalf("default config should not include token")
}
if cfg.Collect.Interval <= 0 || cfg.Collect.Timeout <= 0 {
t.Fatalf("collect intervals must be positive: %+v", cfg.Collect)
}
@@ -21,15 +26,85 @@ func TestDefaultConfigUsesLocalhostAndSaneIntervals(t *testing.T) {
}
}
// TestResolvePathUsesDefaultFileName 验证空路径解析为 config.json。
func TestResolvePathUsesDefaultFileName(t *testing.T) {
if got := ResolvePath(""); got != DefaultConfigFileName {
t.Fatalf("path = %q", got)
}
if got := ResolvePath("/etc/agent.json"); got != "/etc/agent.json" {
t.Fatalf("path = %q", got)
}
}
// TestLoadOrCreateWritesConfigWithToken 验证缺失配置文件时会生成含 token 的 JSON。
func TestLoadOrCreateWritesConfigWithToken(t *testing.T) {
dir := t.TempDir()
path := filepath.Join(dir, "config.json")
cfg, err := LoadOrCreate(path)
if err != nil {
t.Fatal(err)
}
if cfg.HTTP.Token == "" {
t.Fatal("expected generated token")
}
if cfg.HTTP.ListenAddress != "0.0.0.0:8080" {
t.Fatalf("listen address = %q", cfg.HTTP.ListenAddress)
}
info, err := os.Stat(path)
if err != nil {
t.Fatal(err)
}
if info.Mode().Perm() != 0o600 {
t.Fatalf("file mode = %o", info.Mode().Perm())
}
data, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
var onDisk Config
if err := json.Unmarshal(data, &onDisk); err != nil {
t.Fatal(err)
}
if onDisk.HTTP.Token != cfg.HTTP.Token {
t.Fatalf("token mismatch: disk=%q loaded=%q", onDisk.HTTP.Token, cfg.HTTP.Token)
}
}
// TestLoadRejectsEmptyToken 验证未配置 token 时无法启动。
func TestLoadRejectsEmptyToken(t *testing.T) {
file, err := os.CreateTemp(t.TempDir(), "config-*.json")
if err != nil {
t.Fatal(err)
}
_, _ = file.WriteString(`{"http":{"listen_address":"0.0.0.0:8080","token":""}}`)
_ = file.Close()
_, err = Load(file.Name())
if err == nil {
t.Fatal("expected error for empty token")
}
}
// TestLoadAppliesEnvironmentOverrides 验证环境变量可覆盖默认配置。
func TestLoadAppliesEnvironmentOverrides(t *testing.T) {
file, err := os.CreateTemp(t.TempDir(), "config-*.json")
if err != nil {
t.Fatal(err)
}
_, _ = file.WriteString(`{"http":{"listen_address":"0.0.0.0:8080","token":"base-token"}}`)
_ = file.Close()
t.Setenv("MFD_AGENT_LISTEN", "127.0.0.1:9090")
t.Setenv("MFD_AGENT_TOKEN", "env-token")
t.Setenv("MFD_AGENT_REPORT_ENABLED", "true")
t.Setenv("MFD_AGENT_REPORT_ENDPOINT", "http://center/status")
t.Setenv("MFD_AGENT_REPORT_INTERVAL", "2s")
t.Setenv("MFD_AGENT_HOST_ID", "host-a")
cfg, err := Load("")
cfg, err := Load(file.Name())
if err != nil {
t.Fatal(err)
}
@@ -37,6 +112,9 @@ func TestLoadAppliesEnvironmentOverrides(t *testing.T) {
if cfg.HTTP.ListenAddress != "127.0.0.1:9090" {
t.Fatalf("listen address = %q", cfg.HTTP.ListenAddress)
}
if cfg.HTTP.Token != "env-token" {
t.Fatalf("token = %q", cfg.HTTP.Token)
}
if !cfg.Report.Enabled || cfg.Report.Endpoint != "http://center/status" {
t.Fatalf("report config not applied: %+v", cfg.Report)
}
@@ -54,7 +132,7 @@ func TestLoadJSONConfigFile(t *testing.T) {
if err != nil {
t.Fatal(err)
}
_, _ = file.WriteString(`{"http":{"listen_address":"127.0.0.1:7070"},"collect":{"interval":"3s","timeout":"1s"}}`)
_, _ = file.WriteString(`{"http":{"listen_address":"127.0.0.1:7070","token":"secret"},"collect":{"interval":"3s","timeout":"1s"}}`)
_ = file.Close()
cfg, err := Load(file.Name())
@@ -65,6 +143,9 @@ func TestLoadJSONConfigFile(t *testing.T) {
if cfg.HTTP.ListenAddress != "127.0.0.1:7070" {
t.Fatalf("listen address = %q", cfg.HTTP.ListenAddress)
}
if cfg.HTTP.Token != "secret" {
t.Fatalf("token = %q", cfg.HTTP.Token)
}
if cfg.Collect.Interval.Duration() != 3*time.Second || cfg.Collect.Timeout.Duration() != time.Second {
t.Fatalf("collect config = %+v", cfg.Collect)
}