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

* 默认监听调整为 0.0.0.0:8080，并要求查询参数 token
* 支持首次 run 自动生成含随机 token 的配置文件
* 补充 HTTP 鉴权、配置校验和相关测试
* 完善代码注释，覆盖缓存、上报、服务和平台采集路径
* 新增架构与开发流程文档，补充一键构建脚本

internal/httpapi/server.go

@@ -1,6 +1,7 @@
 package httpapi
 
 import (
+	"crypto/subtle"
 	"encoding/json"
 	"net/http"
 
@@ -24,8 +25,9 @@ func (p StaticProvider) Get() (status.HostStatus, bool) {
 	return p.Snapshot, p.OK
 }
 
-// New 创建提供 health 与 status 端点的 HTTP API 处理器。
-func New(provider Provider) http.Handler {
+// New 创建提供 health 与 status 端点的 HTTP API 处理器；token 用于查询参数 ?token= 鉴权。
+// 两个端点都只读取 provider 缓存，不会在请求路径上触发实时系统扫描。
+func New(provider Provider, token string) http.Handler {
 	mux := http.NewServeMux()
 	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodGet {
@@ -58,10 +60,32 @@ func New(provider Provider) http.Handler {
 		}
 		writeJSON(w, http.StatusOK, snapshot)
 	})
-	return mux
+	return withQueryTokenAuth(token, mux)
 }
 
-// writeJSON 以给定状态码将 value 序列化为 JSON 响应。
+// withQueryTokenAuth 校验 GET 请求中的 token 查询参数，失败时返回 401。
+func withQueryTokenAuth(expected string, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// 空 token 一律拒绝，配合配置校验避免无鉴权暴露主机状态。
+		if !queryTokenValid(r.URL.Query().Get("token"), expected) {
+			writeJSON(w, http.StatusUnauthorized, map[string]string{
+				"error": "unauthorized",
+			})
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// queryTokenValid 以恒定时间比较查询参数 token 与配置值，避免时序侧信道。
+func queryTokenValid(got, want string) bool {
+	if got == "" || want == "" {
+		return false
+	}
+	return subtle.ConstantTimeCompare([]byte(got), []byte(want)) == 1
+}
+
+// writeJSON 以给定状态码将 value 序列化为 JSON 响应；编码失败时连接会被动结束。
 func writeJSON(w http.ResponseWriter, code int, value any) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(code)

internal/httpapi/server_test.go

@@ -10,15 +10,22 @@ import (
 	"mfd-monitor-agent/internal/status"
 )
 
+const testToken = "test-token"
+
+// withToken 为请求 URL 附加鉴权查询参数。
+func withToken(path string) string {
+	return path + "?token=" + testToken
+}
+
 // TestStatusReturnsCachedSnapshot 验证 /status 读取提供者缓存。
 func TestStatusReturnsCachedSnapshot(t *testing.T) {
 	provider := StaticProvider{Snapshot: status.HostStatus{
 		Agent: status.AgentInfo{Version: "test", SnapshotAt: time.Now(), SnapshotStatus: "ok"},
 		Host:  status.HostInfo{Hostname: "host-a"},
 	}, OK: true}
-	server := New(provider)
+	server := New(provider, testToken)
 
-	req := httptest.NewRequest(http.MethodGet, "/status", nil)
+	req := httptest.NewRequest(http.MethodGet, withToken("/status"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -39,9 +46,9 @@ func TestHealthReportsSnapshotMetadata(t *testing.T) {
 	provider := StaticProvider{Snapshot: status.HostStatus{
 		Agent: status.AgentInfo{Version: "test", SnapshotAt: time.Unix(10, 0), SnapshotStatus: "partial"},
 	}, OK: true}
-	server := New(provider)
+	server := New(provider, testToken)
 
-	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	req := httptest.NewRequest(http.MethodGet, withToken("/health"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -59,9 +66,9 @@ func TestHealthReportsSnapshotMetadata(t *testing.T) {
 
 // TestStatusReturnsServiceUnavailableBeforeSnapshot 验证 /status 不会在请求时实时采集。
 func TestStatusReturnsServiceUnavailableBeforeSnapshot(t *testing.T) {
-	server := New(StaticProvider{OK: false})
+	server := New(StaticProvider{OK: false}, testToken)
 
-	req := httptest.NewRequest(http.MethodGet, "/status", nil)
+	req := httptest.NewRequest(http.MethodGet, withToken("/status"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -72,9 +79,9 @@ func TestStatusReturnsServiceUnavailableBeforeSnapshot(t *testing.T) {
 
 // TestHealthReturnsStartingBeforeSnapshot 验证 /health 在启动阶段暴露 starting 状态。
 func TestHealthReturnsStartingBeforeSnapshot(t *testing.T) {
-	server := New(StaticProvider{OK: false})
+	server := New(StaticProvider{OK: false}, testToken)
 
-	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	req := httptest.NewRequest(http.MethodGet, withToken("/health"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -92,9 +99,9 @@ func TestHealthReturnsStartingBeforeSnapshot(t *testing.T) {
 
 // TestStatusRejectsNonGET 验证 /status 仅接受 GET 请求。
 func TestStatusRejectsNonGET(t *testing.T) {
-	server := New(StaticProvider{OK: true})
+	server := New(StaticProvider{OK: true}, testToken)
 
-	req := httptest.NewRequest(http.MethodPost, "/status", nil)
+	req := httptest.NewRequest(http.MethodPost, withToken("/status"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -105,9 +112,9 @@ func TestStatusRejectsNonGET(t *testing.T) {
 
 // TestHealthRejectsNonGET 验证 /health 仅接受 GET 请求。
 func TestHealthRejectsNonGET(t *testing.T) {
-	server := New(StaticProvider{OK: true})
+	server := New(StaticProvider{OK: true}, testToken)
 
-	req := httptest.NewRequest(http.MethodPost, "/health", nil)
+	req := httptest.NewRequest(http.MethodPost, withToken("/health"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -115,3 +122,29 @@ func TestHealthRejectsNonGET(t *testing.T) {
 		t.Fatalf("status code = %d", rec.Code)
 	}
 }
+
+// TestMissingTokenReturnsUnauthorized 验证缺少 token 时返回 401。
+func TestMissingTokenReturnsUnauthorized(t *testing.T) {
+	server := New(StaticProvider{OK: true}, testToken)
+
+	req := httptest.NewRequest(http.MethodGet, "/status", nil)
+	rec := httptest.NewRecorder()
+	server.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status code = %d", rec.Code)
+	}
+}
+
+// TestWrongTokenReturnsUnauthorized 验证错误 token 时返回 401。
+func TestWrongTokenReturnsUnauthorized(t *testing.T) {
+	server := New(StaticProvider{OK: true}, testToken)
+
+	req := httptest.NewRequest(http.MethodGet, "/status?token=wrong", nil)
+	rec := httptest.NewRecorder()
+	server.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status code = %d", rec.Code)
+	}
+}