refactor(repo): consolidate openflare-server to root and move subprojects to internal/apps

- Merge all files inside openflare-server to the repository root directory. - Relocate agent, relay, and flared subprojects from internal/ to internal/apps/. - Combine docker-compose files and update build context paths to root. - Update GitHub workflows and Dockerfiles to refer to new directories and package names. - Rewrite Go package imports across all files. - Resolve database renew test race condition and clean up docs.
2026-10-07 16:16:37 +08:00 · 2026-06-19 14:23:29 +08:00
parent 19d476ed7f
commit 63cd906cfc
1064 changed files with 366 additions and 1397 deletions
@@ -0,0 +1,636 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package observability
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+)
+
+const (
+	defaultAccessLogPageSize   = 20
+	maxAccessLogPageSize       = 200
+	defaultAccessLogSortBy     = "logged_at"
+	defaultAccessLogSortOrder  = "desc"
+	defaultAccessLogFoldMinute = 3
+	defaultIPTrendHours        = 24
+	defaultIPTrendBucketMinute = 30
+	maxIPTrendHours            = 168
+	nodeAccessLogRetentionDays = 90
+)
+
+var nodeAccessLogRetentionWindow = nodeAccessLogRetentionDays * 24 * time.Hour
+
+// AccessLogQuery filters access log list queries.
+type AccessLogQuery struct {
+	NodeID      string `json:"node_id"`
+	RemoteAddr  string `json:"remote_addr"`
+	Host        string `json:"host"`
+	Path        string `json:"path"`
+	Page        int    `json:"page"`
+	PageSize    int    `json:"page_size"`
+	SortBy      string `json:"sort_by"`
+	SortOrder   string `json:"sort_order"`
+	FoldMinutes int    `json:"fold_minutes"`
+}
+
+// AccessLogView is a single access log row.
+type AccessLogView struct {
+	ID         uint      `json:"id"`
+	NodeID     string    `json:"node_id"`
+	NodeName   string    `json:"node_name"`
+	LoggedAt   time.Time `json:"logged_at"`
+	RemoteAddr string    `json:"remote_addr"`
+	Region     string    `json:"region"`
+	Host       string    `json:"host"`
+	Path       string    `json:"path"`
+	StatusCode int       `json:"status_code"`
+}
+
+// AccessLogList is a paginated access log response.
+type AccessLogList struct {
+	Items       []AccessLogView `json:"items"`
+	Page        int             `json:"page"`
+	PageSize    int             `json:"page_size"`
+	HasMore     bool            `json:"has_more"`
+	TotalRecord int64           `json:"total_record"`
+	TotalIP     int64           `json:"total_ip"`
+}
+
+// FoldedAccessLogView is a folded access log bucket.
+type FoldedAccessLogView struct {
+	BucketStartedAt  time.Time `json:"bucket_started_at"`
+	RequestCount     int64     `json:"request_count"`
+	UniqueIPCount    int64     `json:"unique_ip_count"`
+	UniqueHostCount  int64     `json:"unique_host_count"`
+	SuccessCount     int64     `json:"success_count"`
+	ClientErrorCount int64     `json:"client_error_count"`
+	ServerErrorCount int64     `json:"server_error_count"`
+}
+
+// FoldedAccessLogList is a paginated folded access log response.
+type FoldedAccessLogList struct {
+	Items       []FoldedAccessLogView `json:"items"`
+	Page        int                   `json:"page"`
+	PageSize    int                   `json:"page_size"`
+	HasMore     bool                  `json:"has_more"`
+	TotalBucket int64                 `json:"total_bucket"`
+	TotalRecord int64                 `json:"total_record"`
+	TotalIP     int64                 `json:"total_ip"`
+	FoldMinutes int                   `json:"fold_minutes"`
+}
+
+// FoldedAccessLogIPQuery filters folded IP summary queries.
+type FoldedAccessLogIPQuery struct {
+	NodeID          string `json:"node_id"`
+	RemoteAddr      string `json:"remote_addr"`
+	Host            string `json:"host"`
+	Path            string `json:"path"`
+	BucketStartedAt string `json:"bucket_started_at"`
+	FoldMinutes     int    `json:"fold_minutes"`
+	Page            int    `json:"page"`
+	PageSize        int    `json:"page_size"`
+	SortBy          string `json:"sort_by"`
+	SortOrder       string `json:"sort_order"`
+}
+
+// FoldedAccessLogIPView is a folded IP row.
+type FoldedAccessLogIPView struct {
+	RemoteAddr       string    `json:"remote_addr"`
+	RequestCount     int64     `json:"request_count"`
+	SuccessCount     int64     `json:"success_count"`
+	ClientErrorCount int64     `json:"client_error_count"`
+	ServerErrorCount int64     `json:"server_error_count"`
+	LastSeenAt       time.Time `json:"last_seen_at"`
+}
+
+// FoldedAccessLogIPList is a paginated folded IP response.
+type FoldedAccessLogIPList struct {
+	Items           []FoldedAccessLogIPView `json:"items"`
+	Page            int                     `json:"page"`
+	PageSize        int                     `json:"page_size"`
+	HasMore         bool                    `json:"has_more"`
+	TotalIP         int64                   `json:"total_ip"`
+	BucketStartedAt time.Time               `json:"bucket_started_at"`
+	FoldMinutes     int                     `json:"fold_minutes"`
+	SortBy          string                  `json:"sort_by"`
+	SortOrder       string                  `json:"sort_order"`
+}
+
+// AccessLogIPSummaryQuery filters IP summary list queries.
+type AccessLogIPSummaryQuery struct {
+	NodeID     string `json:"node_id"`
+	RemoteAddr string `json:"remote_addr"`
+	Host       string `json:"host"`
+	Page       int    `json:"page"`
+	PageSize   int    `json:"page_size"`
+	SortBy     string `json:"sort_by"`
+	SortOrder  string `json:"sort_order"`
+}
+
+// AccessLogIPSummaryView is an IP summary row.
+type AccessLogIPSummaryView struct {
+	RemoteAddr     string    `json:"remote_addr"`
+	TotalRequests  int64     `json:"total_requests"`
+	RecentRequests int64     `json:"recent_requests"`
+	LastSeenAt     time.Time `json:"last_seen_at"`
+}
+
+// AccessLogIPSummaryList is a paginated IP summary response.
+type AccessLogIPSummaryList struct {
+	Items     []AccessLogIPSummaryView `json:"items"`
+	Page      int                      `json:"page"`
+	PageSize  int                      `json:"page_size"`
+	HasMore   bool                     `json:"has_more"`
+	TotalIP   int64                    `json:"total_ip"`
+	SortBy    string                   `json:"sort_by"`
+	SortOrder string                   `json:"sort_order"`
+}
+
+// AccessLogIPTrendQuery filters IP trend queries.
+type AccessLogIPTrendQuery struct {
+	NodeID        string `json:"node_id"`
+	RemoteAddr    string `json:"remote_addr"`
+	Host          string `json:"host"`
+	Hours         int    `json:"hours"`
+	BucketMinutes int    `json:"bucket_minutes"`
+}
+
+// AccessLogIPTrendPoint is an IP trend bucket.
+type AccessLogIPTrendPoint struct {
+	BucketStartedAt time.Time `json:"bucket_started_at"`
+	RequestCount    int64     `json:"request_count"`
+}
+
+// AccessLogIPTrendView is the IP trend response.
+type AccessLogIPTrendView struct {
+	RemoteAddr    string                  `json:"remote_addr"`
+	Hours         int                     `json:"hours"`
+	BucketMinutes int                     `json:"bucket_minutes"`
+	Points        []AccessLogIPTrendPoint `json:"points"`
+}
+
+// AccessLogCleanupInput is the cleanup request payload.
+type AccessLogCleanupInput struct {
+	RetentionDays int `json:"retention_days"`
+}
+
+// AccessLogCleanupResult is the cleanup response payload.
+type AccessLogCleanupResult struct {
+	RetentionDays int       `json:"retention_days"`
+	DeletedCount  int64     `json:"deleted_count"`
+	Cutoff        time.Time `json:"cutoff"`
+}
+
+// ListAccessLogs returns paginated access logs.
+func ListAccessLogs(ctx context.Context, input AccessLogQuery) (*AccessLogList, error) {
+	normalized := normalizeAccessLogQuery(input)
+	modelQuery := buildModelAccessLogQuery(normalized)
+	logs, err := model.ListOpenFlareAccessLogs(ctx, modelQuery)
+	if err != nil {
+		return nil, err
+	}
+	totalRecords, totalIPs, err := model.CountOpenFlareAccessLogs(ctx, modelQuery)
+	if err != nil {
+		return nil, err
+	}
+	nodeNames, err := listNodeNameMap(ctx, logs)
+	if err != nil {
+		return nil, err
+	}
+	views := make([]AccessLogView, 0, len(logs))
+	for _, item := range logs {
+		if item == nil {
+			continue
+		}
+		views = append(views, AccessLogView{
+			ID:         item.ID,
+			NodeID:     item.NodeID,
+			NodeName:   nodeNames[item.NodeID],
+			LoggedAt:   item.LoggedAt,
+			RemoteAddr: item.RemoteAddr,
+			Region:     item.Region,
+			Host:       item.Host,
+			Path:       item.Path,
+			StatusCode: item.StatusCode,
+		})
+	}
+	return &AccessLogList{
+		Items:       views,
+		Page:        normalized.Page,
+		PageSize:    normalized.PageSize,
+		HasMore:     int64((normalized.Page+1)*normalized.PageSize) < totalRecords,
+		TotalRecord: totalRecords,
+		TotalIP:     totalIPs,
+	}, nil
+}
+
+// ListFoldedAccessLogs returns paginated folded access logs.
+func ListFoldedAccessLogs(ctx context.Context, input AccessLogQuery) (*FoldedAccessLogList, error) {
+	normalized := normalizeAccessLogQuery(input)
+	foldMinutes, err := normalizeFoldMinutes(normalized.FoldMinutes)
+	if err != nil {
+		return nil, err
+	}
+	modelQuery := buildModelAccessLogQuery(normalized)
+	bucketQuery := model.OpenFlareAccessLogBucketQuery{
+		NodeID:      modelQuery.NodeID,
+		RemoteAddr:  modelQuery.RemoteAddr,
+		Host:        modelQuery.Host,
+		Path:        modelQuery.Path,
+		Since:       modelQuery.Since,
+		Page:        normalized.Page,
+		PageSize:    normalized.PageSize,
+		SortBy:      normalizeFoldSortBy(input.SortBy),
+		SortOrder:   normalized.SortOrder,
+		FoldMinutes: foldMinutes,
+	}
+	items, err := model.ListOpenFlareAccessLogBuckets(ctx, bucketQuery)
+	if err != nil {
+		return nil, err
+	}
+	totalBuckets, err := model.CountOpenFlareAccessLogBuckets(ctx, bucketQuery)
+	if err != nil {
+		return nil, err
+	}
+	totalRecords, totalIPs, err := model.CountOpenFlareAccessLogs(ctx, modelQuery)
+	if err != nil {
+		return nil, err
+	}
+	views := make([]FoldedAccessLogView, 0, len(items))
+	for _, item := range items {
+		if item == nil {
+			continue
+		}
+		views = append(views, FoldedAccessLogView{
+			BucketStartedAt:  time.Unix(item.BucketEpoch, 0).UTC(),
+			RequestCount:     item.RequestCount,
+			UniqueIPCount:    item.UniqueIPCount,
+			UniqueHostCount:  item.UniqueHostCount,
+			SuccessCount:     item.SuccessCount,
+			ClientErrorCount: item.ClientErrorCount,
+			ServerErrorCount: item.ServerErrorCount,
+		})
+	}
+	return &FoldedAccessLogList{
+		Items:       views,
+		Page:        normalized.Page,
+		PageSize:    normalized.PageSize,
+		HasMore:     int64((normalized.Page+1)*normalized.PageSize) < totalBuckets,
+		TotalBucket: totalBuckets,
+		TotalRecord: totalRecords,
+		TotalIP:     totalIPs,
+		FoldMinutes: foldMinutes,
+	}, nil
+}
+
+// ListFoldedAccessLogIPs returns paginated folded IP summaries.
+func ListFoldedAccessLogIPs(ctx context.Context, input FoldedAccessLogIPQuery) (*FoldedAccessLogIPList, error) {
+	normalized, bucketStartedAt, err := normalizeFoldedAccessLogIPQuery(input)
+	if err != nil {
+		return nil, err
+	}
+	modelQuery := model.OpenFlareAccessLogBucketIPQuery{
+		NodeID:          normalized.NodeID,
+		RemoteAddr:      normalized.RemoteAddr,
+		Host:            normalized.Host,
+		Path:            normalized.Path,
+		BucketStartedAt: bucketStartedAt,
+		FoldMinutes:     normalized.FoldMinutes,
+		Page:            normalized.Page,
+		PageSize:        normalized.PageSize,
+		SortBy:          normalized.SortBy,
+		SortOrder:       normalized.SortOrder,
+	}
+	items, err := model.ListOpenFlareAccessLogBucketIPs(ctx, modelQuery)
+	if err != nil {
+		return nil, err
+	}
+	totalIP, err := model.CountOpenFlareAccessLogBucketIPs(ctx, modelQuery)
+	if err != nil {
+		return nil, err
+	}
+	views := make([]FoldedAccessLogIPView, 0, len(items))
+	for _, item := range items {
+		if item == nil {
+			continue
+		}
+		views = append(views, FoldedAccessLogIPView{
+			RemoteAddr:       item.RemoteAddr,
+			RequestCount:     item.RequestCount,
+			SuccessCount:     item.SuccessCount,
+			ClientErrorCount: item.ClientErrorCount,
+			ServerErrorCount: item.ServerErrorCount,
+			LastSeenAt:       time.Unix(item.LastSeenEpoch, 0).UTC(),
+		})
+	}
+	return &FoldedAccessLogIPList{
+		Items:           views,
+		Page:            normalized.Page,
+		PageSize:        normalized.PageSize,
+		HasMore:         int64((normalized.Page+1)*normalized.PageSize) < totalIP,
+		TotalIP:         totalIP,
+		BucketStartedAt: bucketStartedAt,
+		FoldMinutes:     normalized.FoldMinutes,
+		SortBy:          normalized.SortBy,
+		SortOrder:       normalized.SortOrder,
+	}, nil
+}
+
+// ListAccessLogIPSummaries returns paginated IP summaries.
+func ListAccessLogIPSummaries(ctx context.Context, input AccessLogIPSummaryQuery) (*AccessLogIPSummaryList, error) {
+	normalized := normalizeAccessLogIPSummaryQuery(input)
+	since := time.Now().UTC().Add(-nodeAccessLogRetentionWindow)
+	recentSince := time.Now().UTC().Add(-3 * time.Hour)
+	query := model.OpenFlareAccessLogIPSummaryQuery{
+		NodeID:     strings.TrimSpace(normalized.NodeID),
+		RemoteAddr: strings.TrimSpace(normalized.RemoteAddr),
+		Host:       strings.TrimSpace(normalized.Host),
+		Since:      since,
+		Page:       normalized.Page,
+		PageSize:   normalized.PageSize,
+		SortBy:     normalized.SortBy,
+		SortOrder:  normalized.SortOrder,
+	}
+	items, err := model.ListOpenFlareAccessLogIPSummaries(ctx, query, recentSince)
+	if err != nil {
+		return nil, err
+	}
+	totalIP, err := model.CountOpenFlareAccessLogIPSummaries(ctx, query)
+	if err != nil {
+		return nil, err
+	}
+	views := make([]AccessLogIPSummaryView, 0, len(items))
+	for _, item := range items {
+		if item == nil {
+			continue
+		}
+		views = append(views, AccessLogIPSummaryView{
+			RemoteAddr:     item.RemoteAddr,
+			TotalRequests:  item.TotalRequests,
+			RecentRequests: item.RecentRequests,
+			LastSeenAt:     time.Unix(item.LastSeenEpoch, 0).UTC(),
+		})
+	}
+	return &AccessLogIPSummaryList{
+		Items:     views,
+		Page:      normalized.Page,
+		PageSize:  normalized.PageSize,
+		HasMore:   int64((normalized.Page+1)*normalized.PageSize) < totalIP,
+		TotalIP:   totalIP,
+		SortBy:    normalized.SortBy,
+		SortOrder: normalized.SortOrder,
+	}, nil
+}
+
+// GetAccessLogIPTrend returns IP request trend points.
+func GetAccessLogIPTrend(ctx context.Context, input AccessLogIPTrendQuery) (*AccessLogIPTrendView, error) {
+	normalized, err := normalizeAccessLogIPTrendQuery(input)
+	if err != nil {
+		return nil, err
+	}
+	points, err := model.ListOpenFlareAccessLogIPTrend(ctx, model.OpenFlareAccessLogIPTrendQuery{
+		NodeID:        strings.TrimSpace(normalized.NodeID),
+		RemoteAddr:    strings.TrimSpace(normalized.RemoteAddr),
+		Host:          strings.TrimSpace(normalized.Host),
+		Since:         time.Now().UTC().Add(-time.Duration(normalized.Hours) * time.Hour),
+		BucketMinutes: normalized.BucketMinutes,
+	})
+	if err != nil {
+		return nil, err
+	}
+	pointMap := make(map[int64]int64, len(points))
+	for _, item := range points {
+		if item == nil {
+			continue
+		}
+		pointMap[item.BucketEpoch] = item.RequestCount
+	}
+	bucketDuration := time.Duration(normalized.BucketMinutes) * time.Minute
+	start := time.Now().UTC().Add(-time.Duration(normalized.Hours) * time.Hour).Truncate(bucketDuration)
+	end := time.Now().UTC().Truncate(bucketDuration)
+	views := make([]AccessLogIPTrendPoint, 0, int(end.Sub(start)/bucketDuration)+1)
+	for cursor := start; !cursor.After(end); cursor = cursor.Add(bucketDuration) {
+		views = append(views, AccessLogIPTrendPoint{
+			BucketStartedAt: cursor,
+			RequestCount:    pointMap[cursor.Unix()],
+		})
+	}
+	return &AccessLogIPTrendView{
+		RemoteAddr:    normalized.RemoteAddr,
+		Hours:         normalized.Hours,
+		BucketMinutes: normalized.BucketMinutes,
+		Points:        views,
+	}, nil
+}
+
+// CleanupAccessLogs removes access logs older than retention days.
+func CleanupAccessLogs(ctx context.Context, input AccessLogCleanupInput) (*AccessLogCleanupResult, error) {
+	if input.RetentionDays <= 0 || input.RetentionDays > nodeAccessLogRetentionDays {
+		return nil, errors.New("retention_days 必须在 1 到 90 之间")
+	}
+	cutoff := time.Now().UTC().Add(-time.Duration(input.RetentionDays) * 24 * time.Hour)
+	deleted, err := model.DeleteOpenFlareAccessLogsBefore(ctx, cutoff)
+	if err != nil {
+		return nil, err
+	}
+	return &AccessLogCleanupResult{
+		RetentionDays: input.RetentionDays,
+		DeletedCount:  deleted,
+		Cutoff:        cutoff,
+	}, nil
+}
+
+func buildModelAccessLogQuery(input AccessLogQuery) model.OpenFlareAccessLogQuery {
+	return model.OpenFlareAccessLogQuery{
+		NodeID:     strings.TrimSpace(input.NodeID),
+		RemoteAddr: strings.TrimSpace(input.RemoteAddr),
+		Host:       strings.TrimSpace(input.Host),
+		Path:       strings.TrimSpace(input.Path),
+		Since:      time.Now().UTC().Add(-nodeAccessLogRetentionWindow),
+		Page:       input.Page,
+		PageSize:   input.PageSize,
+		SortBy:     input.SortBy,
+		SortOrder:  input.SortOrder,
+	}
+}
+
+func listNodeNameMap(ctx context.Context, logs []*model.OpenFlareAccessLog) (map[string]string, error) {
+	nodeIDs := make([]string, 0, len(logs))
+	seen := make(map[string]struct{}, len(logs))
+	for _, item := range logs {
+		if item == nil || item.NodeID == "" {
+			continue
+		}
+		if _, exists := seen[item.NodeID]; exists {
+			continue
+		}
+		seen[item.NodeID] = struct{}{}
+		nodeIDs = append(nodeIDs, item.NodeID)
+	}
+	if len(nodeIDs) == 0 {
+		return map[string]string{}, nil
+	}
+	nodes, err := model.ListOpenFlareNodesByNodeIDs(ctx, nodeIDs)
+	if err != nil {
+		return nil, err
+	}
+	result := make(map[string]string, len(nodes))
+	for _, node := range nodes {
+		result[node.NodeID] = node.Name
+	}
+	return result, nil
+}
+
+func normalizeAccessLogQuery(input AccessLogQuery) AccessLogQuery {
+	return AccessLogQuery{
+		NodeID:      strings.TrimSpace(input.NodeID),
+		RemoteAddr:  strings.TrimSpace(input.RemoteAddr),
+		Host:        strings.TrimSpace(input.Host),
+		Path:        strings.TrimSpace(input.Path),
+		Page:        normalizeAccessLogPage(input.Page),
+		PageSize:    normalizeAccessLogPageSize(input.PageSize),
+		SortBy:      normalizeAccessLogSortBy(input.SortBy),
+		SortOrder:   normalizeAccessLogSortOrder(input.SortOrder),
+		FoldMinutes: input.FoldMinutes,
+	}
+}
+
+func normalizeAccessLogIPSummaryQuery(input AccessLogIPSummaryQuery) AccessLogIPSummaryQuery {
+	return AccessLogIPSummaryQuery{
+		NodeID:     strings.TrimSpace(input.NodeID),
+		RemoteAddr: strings.TrimSpace(input.RemoteAddr),
+		Host:       strings.TrimSpace(input.Host),
+		Page:       normalizeAccessLogPage(input.Page),
+		PageSize:   normalizeAccessLogPageSize(input.PageSize),
+		SortBy:     normalizeIPSummarySortBy(input.SortBy),
+		SortOrder:  normalizeAccessLogSortOrder(input.SortOrder),
+	}
+}
+
+func normalizeFoldedAccessLogIPQuery(input FoldedAccessLogIPQuery) (FoldedAccessLogIPQuery, time.Time, error) {
+	foldMinutes, err := normalizeFoldMinutes(input.FoldMinutes)
+	if err != nil {
+		return FoldedAccessLogIPQuery{}, time.Time{}, err
+	}
+	bucketStartedAt, err := time.Parse(time.RFC3339, strings.TrimSpace(input.BucketStartedAt))
+	if err != nil {
+		return FoldedAccessLogIPQuery{}, time.Time{}, errors.New("bucket_started_at 必须为 RFC3339 时间")
+	}
+	normalizedSortBy := strings.TrimSpace(input.SortBy)
+	switch normalizedSortBy {
+	case "last_seen_at", "remote_addr":
+	default:
+		normalizedSortBy = "request_count"
+	}
+	return FoldedAccessLogIPQuery{
+		NodeID:          strings.TrimSpace(input.NodeID),
+		RemoteAddr:      strings.TrimSpace(input.RemoteAddr),
+		Host:            strings.TrimSpace(input.Host),
+		Path:            strings.TrimSpace(input.Path),
+		BucketStartedAt: strings.TrimSpace(input.BucketStartedAt),
+		FoldMinutes:     foldMinutes,
+		Page:            normalizeAccessLogPage(input.Page),
+		PageSize:        normalizeAccessLogPageSize(input.PageSize),
+		SortBy:          normalizedSortBy,
+		SortOrder:       normalizeAccessLogSortOrder(input.SortOrder),
+	}, bucketStartedAt.UTC(), nil
+}
+
+func normalizeAccessLogIPTrendQuery(input AccessLogIPTrendQuery) (AccessLogIPTrendQuery, error) {
+	remoteAddr := strings.TrimSpace(input.RemoteAddr)
+	if remoteAddr == "" {
+		return AccessLogIPTrendQuery{}, errors.New("remote_addr 不能为空")
+	}
+	hours := input.Hours
+	if hours <= 0 {
+		hours = defaultIPTrendHours
+	}
+	if hours > maxIPTrendHours {
+		hours = maxIPTrendHours
+	}
+	bucketMinutes := input.BucketMinutes
+	if bucketMinutes <= 0 {
+		bucketMinutes = defaultIPTrendBucketMinute
+	}
+	switch bucketMinutes {
+	case 5, 10, 15, 30, 60:
+	default:
+		return AccessLogIPTrendQuery{}, errors.New("bucket_minutes 仅支持 5、10、15、30、60")
+	}
+	return AccessLogIPTrendQuery{
+		NodeID:        strings.TrimSpace(input.NodeID),
+		RemoteAddr:    remoteAddr,
+		Host:          strings.TrimSpace(input.Host),
+		Hours:         hours,
+		BucketMinutes: bucketMinutes,
+	}, nil
+}
+
+func normalizeAccessLogPage(page int) int {
+	if page < 0 {
+		return 0
+	}
+	return page
+}
+
+func normalizeAccessLogPageSize(pageSize int) int {
+	if pageSize <= 0 {
+		return defaultAccessLogPageSize
+	}
+	if pageSize > maxAccessLogPageSize {
+		return maxAccessLogPageSize
+	}
+	return pageSize
+}
+
+func normalizeAccessLogSortBy(sortBy string) string {
+	switch strings.TrimSpace(sortBy) {
+	case "status_code", "remote_addr", "host", "path":
+		return strings.TrimSpace(sortBy)
+	default:
+		return defaultAccessLogSortBy
+	}
+}
+
+func normalizeAccessLogSortOrder(sortOrder string) string {
+	if strings.EqualFold(strings.TrimSpace(sortOrder), "asc") {
+		return "asc"
+	}
+	return defaultAccessLogSortOrder
+}
+
+func normalizeFoldSortBy(sortBy string) string {
+	switch strings.TrimSpace(sortBy) {
+	case "request_count":
+		return "request_count"
+	default:
+		return "bucket_started_at"
+	}
+}
+
+func normalizeIPSummarySortBy(sortBy string) string {
+	switch strings.TrimSpace(sortBy) {
+	case "recent_requests", "last_seen_at", "remote_addr":
+		return strings.TrimSpace(sortBy)
+	default:
+		return "total_requests"
+	}
+}
+
+func normalizeFoldMinutes(value int) (int, error) {
+	if value <= 0 {
+		return defaultAccessLogFoldMinute, nil
+	}
+	switch value {
+	case 3, 5:
+		return value, nil
+	default:
+		return 0, errors.New("fold_minutes 仅支持 3 或 5")
+	}
+}
@@ -0,0 +1,482 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package observability
+
+import (
+	"encoding/json"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+)
+
+const observabilityTrendBuckets = 24
+
+const (
+	healthEventStatusActive   = "active"
+	healthEventStatusResolved = "resolved"
+	healthSeverityCritical    = "critical"
+	healthSeverityWarning     = "warning"
+)
+
+// DistributionItem is a key/value distribution entry.
+type DistributionItem struct {
+	Key   string `json:"key"`
+	Value int64  `json:"value"`
+}
+
+// TrafficDistributions groups traffic distribution charts.
+type TrafficDistributions struct {
+	StatusCodes     []DistributionItem `json:"status_codes"`
+	TopDomains      []DistributionItem `json:"top_domains"`
+	SourceCountries []DistributionItem `json:"source_countries"`
+}
+
+// TrafficWindowSummary summarizes a traffic reporting window.
+type TrafficWindowSummary struct {
+	WindowStartedAt    time.Time `json:"window_started_at"`
+	WindowEndedAt      time.Time `json:"window_ended_at"`
+	RequestCount       int64     `json:"request_count"`
+	UniqueVisitorCount int64     `json:"unique_visitor_count"`
+	ErrorCount         int64     `json:"error_count"`
+	EstimatedQPS       float64   `json:"estimated_qps"`
+	ErrorRatePercent   float64   `json:"error_rate_percent"`
+}
+
+// HealthSummary summarizes node health alerts and risks.
+type HealthSummary struct {
+	ActiveAlerts    int  `json:"active_alerts"`
+	CriticalAlerts  int  `json:"critical_alerts"`
+	WarningAlerts   int  `json:"warning_alerts"`
+	InfoAlerts      int  `json:"info_alerts"`
+	ResolvedAlerts  int  `json:"resolved_alerts"`
+	HasCapacityRisk bool `json:"has_capacity_risk"`
+	HasTrafficRisk  bool `json:"has_traffic_risk"`
+	HasRuntimeRisk  bool `json:"has_runtime_risk"`
+}
+
+// TrafficTrendPoint is a traffic trend bucket.
+type TrafficTrendPoint struct {
+	BucketStartedAt    time.Time `json:"bucket_started_at"`
+	RequestCount       int64     `json:"request_count"`
+	ErrorCount         int64     `json:"error_count"`
+	UniqueVisitorCount int64     `json:"unique_visitor_count"`
+}
+
+// CapacityTrendPoint is a capacity trend bucket.
+type CapacityTrendPoint struct {
+	BucketStartedAt           time.Time `json:"bucket_started_at"`
+	AverageCPUUsagePercent    float64   `json:"average_cpu_usage_percent"`
+	AverageMemoryUsagePercent float64   `json:"average_memory_usage_percent"`
+	ReportedNodes             int       `json:"reported_nodes"`
+}
+
+// NetworkTrendPoint is a network trend bucket.
+type NetworkTrendPoint struct {
+	BucketStartedAt  time.Time `json:"bucket_started_at"`
+	NetworkRxBytes   int64     `json:"network_rx_bytes"`
+	NetworkTxBytes   int64     `json:"network_tx_bytes"`
+	OpenrestyRxBytes int64     `json:"openresty_rx_bytes"`
+	OpenrestyTxBytes int64     `json:"openresty_tx_bytes"`
+	ReportedNodes    int       `json:"reported_nodes"`
+}
+
+// DiskIOTrendPoint is a disk IO trend bucket.
+type DiskIOTrendPoint struct {
+	BucketStartedAt time.Time `json:"bucket_started_at"`
+	DiskReadBytes   int64     `json:"disk_read_bytes"`
+	DiskWriteBytes  int64     `json:"disk_write_bytes"`
+	ReportedNodes   int       `json:"reported_nodes"`
+}
+
+type distributionAccumulator map[string]int64
+
+type capacityTrendAccumulator struct {
+	cpuSum   float64
+	cpuCount int
+	memSum   float64
+	memCount int
+	nodes    map[string]struct{}
+}
+
+type snapshotTrendAccumulator struct {
+	nodes map[string]struct{}
+}
+
+type diskCounterState struct {
+	read  int64
+	write int64
+	seen  bool
+}
+
+func buildTrafficWindowSummary(report *model.OpenFlareRequestReport) TrafficWindowSummary {
+	if report == nil {
+		return TrafficWindowSummary{}
+	}
+	summary := TrafficWindowSummary{
+		WindowStartedAt:    report.WindowStartedAt,
+		WindowEndedAt:      report.WindowEndedAt,
+		RequestCount:       report.RequestCount,
+		UniqueVisitorCount: report.UniqueVisitorCount,
+		ErrorCount:         report.ErrorCount,
+	}
+	if duration := report.WindowEndedAt.Sub(report.WindowStartedAt).Seconds(); duration > 0 {
+		summary.EstimatedQPS = float64(report.RequestCount) / duration
+	}
+	if report.RequestCount > 0 {
+		summary.ErrorRatePercent = (float64(report.ErrorCount) / float64(report.RequestCount)) * 100
+	}
+	return summary
+}
+
+// BuildTrafficDistributions aggregates traffic distribution charts.
+func BuildTrafficDistributions(
+	reports []*model.OpenFlareRequestReport,
+	accessLogRegions []*model.OpenFlareAccessLogRegionCount,
+	limit int,
+) TrafficDistributions {
+	statusCodes := make(distributionAccumulator)
+	topDomains := make(distributionAccumulator)
+	reportSourceCountries := make(distributionAccumulator)
+	for _, report := range reports {
+		mergeJSONCounts(statusCodes, report.StatusCodesJSON)
+		mergeJSONCounts(topDomains, report.TopDomainsJSON)
+		mergeJSONCounts(reportSourceCountries, report.SourceCountriesJSON)
+	}
+	sourceCountries := reportSourceCountries
+	if len(accessLogRegions) > 0 {
+		sourceCountries = make(distributionAccumulator, len(accessLogRegions))
+		for _, item := range accessLogRegions {
+			if item == nil || strings.TrimSpace(item.Region) == "" || item.Count <= 0 {
+				continue
+			}
+			sourceCountries[item.Region] = item.Count
+		}
+	}
+	return TrafficDistributions{
+		StatusCodes:     toDistributionItems(statusCodes, limit),
+		TopDomains:      toDistributionItems(topDomains, limit),
+		SourceCountries: toDistributionItems(sourceCountries, limit),
+	}
+}
+
+func buildHealthSummary(
+	snapshot *model.OpenFlareMetricSnapshot,
+	report *model.OpenFlareRequestReport,
+	events []*model.OpenFlareHealthEvent,
+) HealthSummary {
+	summary := HealthSummary{}
+	for _, event := range events {
+		if event == nil {
+			continue
+		}
+		if event.Status == healthEventStatusResolved {
+			summary.ResolvedAlerts++
+			continue
+		}
+		summary.ActiveAlerts++
+		switch event.Severity {
+		case healthSeverityCritical:
+			summary.CriticalAlerts++
+		case healthSeverityWarning:
+			summary.WarningAlerts++
+		default:
+			summary.InfoAlerts++
+		}
+	}
+	if snapshot != nil {
+		memoryUsage := Percentage(snapshot.MemoryUsedBytes, snapshot.MemoryTotalBytes)
+		storageUsage := Percentage(snapshot.StorageUsedBytes, snapshot.StorageTotalBytes)
+		summary.HasCapacityRisk = snapshot.CPUUsagePercent >= 80 || memoryUsage >= 85 || storageUsage >= 85
+	}
+	if report != nil && report.RequestCount >= 100 {
+		summary.HasTrafficRisk = (float64(report.ErrorCount) / float64(report.RequestCount)) >= 0.05
+	}
+	summary.HasRuntimeRisk = summary.ActiveAlerts > 0 || summary.HasCapacityRisk || summary.HasTrafficRisk
+	return summary
+}
+
+// BuildTrafficTrendPoints builds 24h traffic trend buckets.
+func BuildTrafficTrendPoints(now time.Time, reports []*model.OpenFlareRequestReport) []TrafficTrendPoint {
+	start := trendWindowStart(now)
+	points := make([]TrafficTrendPoint, observabilityTrendBuckets)
+	for index := range points {
+		points[index].BucketStartedAt = start.Add(time.Duration(index) * time.Hour)
+	}
+	for _, report := range reports {
+		index, ok := trendBucketIndex(report.WindowEndedAt, start)
+		if !ok {
+			continue
+		}
+		points[index].RequestCount += report.RequestCount
+		points[index].ErrorCount += report.ErrorCount
+		points[index].UniqueVisitorCount += report.UniqueVisitorCount
+	}
+	return points
+}
+
+// BuildCapacityTrendPoints builds 24h capacity trend buckets.
+func BuildCapacityTrendPoints(now time.Time, snapshots []*model.OpenFlareMetricSnapshot) []CapacityTrendPoint {
+	start := trendWindowStart(now)
+	points := make([]CapacityTrendPoint, observabilityTrendBuckets)
+	accumulators := make([]capacityTrendAccumulator, observabilityTrendBuckets)
+	for index := range points {
+		points[index].BucketStartedAt = start.Add(time.Duration(index) * time.Hour)
+		accumulators[index].nodes = make(map[string]struct{})
+	}
+	for _, snapshot := range snapshots {
+		index, ok := trendBucketIndex(snapshot.CapturedAt, start)
+		if !ok {
+			continue
+		}
+		if snapshot.CPUUsagePercent > 0 {
+			accumulators[index].cpuSum += snapshot.CPUUsagePercent
+			accumulators[index].cpuCount++
+		}
+		if memoryUsage := Percentage(snapshot.MemoryUsedBytes, snapshot.MemoryTotalBytes); memoryUsage > 0 {
+			accumulators[index].memSum += memoryUsage
+			accumulators[index].memCount++
+		}
+		if snapshot.NodeID != "" {
+			accumulators[index].nodes[snapshot.NodeID] = struct{}{}
+		}
+	}
+	for index := range points {
+		if accumulators[index].cpuCount > 0 {
+			points[index].AverageCPUUsagePercent = accumulators[index].cpuSum / float64(accumulators[index].cpuCount)
+		}
+		if accumulators[index].memCount > 0 {
+			points[index].AverageMemoryUsagePercent = accumulators[index].memSum / float64(accumulators[index].memCount)
+		}
+		points[index].ReportedNodes = len(accumulators[index].nodes)
+	}
+	return points
+}
+
+// BuildNetworkTrendPoints builds 24h network trend buckets.
+func BuildNetworkTrendPoints(
+	now time.Time,
+	snapshots []*model.OpenFlareMetricSnapshot,
+	openrestyObs []*model.OpenFlareNodeObservationOpenresty,
+) []NetworkTrendPoint {
+	start := trendWindowStart(now)
+	points := make([]NetworkTrendPoint, observabilityTrendBuckets)
+	accumulators := make([]snapshotTrendAccumulator, observabilityTrendBuckets)
+	for index := range points {
+		points[index].BucketStartedAt = start.Add(time.Duration(index) * time.Hour)
+		accumulators[index].nodes = make(map[string]struct{})
+	}
+	for _, snapshot := range snapshots {
+		index, ok := trendBucketIndex(snapshot.CapturedAt, start)
+		if !ok {
+			continue
+		}
+		points[index].NetworkRxBytes += snapshot.NetworkRxBytes
+		points[index].NetworkTxBytes += snapshot.NetworkTxBytes
+		if snapshot.NodeID != "" {
+			accumulators[index].nodes[snapshot.NodeID] = struct{}{}
+		}
+	}
+	for _, obs := range openrestyObs {
+		index, ok := trendBucketIndex(obs.CapturedAt, start)
+		if !ok {
+			continue
+		}
+		points[index].OpenrestyRxBytes += obs.OpenrestyRxBytes
+		points[index].OpenrestyTxBytes += obs.OpenrestyTxBytes
+		if obs.NodeID != "" {
+			accumulators[index].nodes[obs.NodeID] = struct{}{}
+		}
+	}
+	for index := range points {
+		points[index].ReportedNodes = len(accumulators[index].nodes)
+	}
+	return points
+}
+
+// BuildDiskIOTrendPoints builds 24h disk IO trend buckets.
+func BuildDiskIOTrendPoints(now time.Time, snapshots []*model.OpenFlareMetricSnapshot) []DiskIOTrendPoint {
+	start := trendWindowStart(now)
+	points := make([]DiskIOTrendPoint, observabilityTrendBuckets)
+	accumulators := make([]snapshotTrendAccumulator, observabilityTrendBuckets)
+	for index := range points {
+		points[index].BucketStartedAt = start.Add(time.Duration(index) * time.Hour)
+		accumulators[index].nodes = make(map[string]struct{})
+	}
+	sort.Slice(snapshots, func(i int, j int) bool {
+		if snapshots[i].CapturedAt.Equal(snapshots[j].CapturedAt) {
+			return snapshots[i].NodeID < snapshots[j].NodeID
+		}
+		return snapshots[i].CapturedAt.Before(snapshots[j].CapturedAt)
+	})
+	previousByNode := make(map[string]diskCounterState, len(snapshots))
+	for _, snapshot := range snapshots {
+		nodeKey := snapshot.NodeID
+		if nodeKey == "" {
+			nodeKey = "__unknown__"
+		}
+		previous := previousByNode[nodeKey]
+		previousByNode[nodeKey] = diskCounterState{
+			read:  snapshot.DiskReadBytes,
+			write: snapshot.DiskWriteBytes,
+			seen:  true,
+		}
+		if !previous.seen {
+			continue
+		}
+		index, ok := trendBucketIndex(snapshot.CapturedAt, start)
+		if !ok {
+			continue
+		}
+		readDelta := snapshot.DiskReadBytes - previous.read
+		writeDelta := snapshot.DiskWriteBytes - previous.write
+		if readDelta < 0 {
+			readDelta = 0
+		}
+		if writeDelta < 0 {
+			writeDelta = 0
+		}
+		points[index].DiskReadBytes += readDelta
+		points[index].DiskWriteBytes += writeDelta
+		if snapshot.NodeID != "" {
+			accumulators[index].nodes[snapshot.NodeID] = struct{}{}
+		}
+	}
+	for index := range points {
+		points[index].ReportedNodes = len(accumulators[index].nodes)
+	}
+	return points
+}
+
+func latestMetricSnapshot(snapshots []*model.OpenFlareMetricSnapshot) *model.OpenFlareMetricSnapshot {
+	for _, snapshot := range snapshots {
+		if snapshot != nil {
+			return snapshot
+		}
+	}
+	return nil
+}
+
+func latestTrafficReport(reports []*model.OpenFlareRequestReport) *model.OpenFlareRequestReport {
+	for _, report := range reports {
+		if report != nil {
+			return report
+		}
+	}
+	return nil
+}
+
+// LatestMetricSnapshotsByNode returns the latest snapshot per node.
+func LatestMetricSnapshotsByNode(snapshots []*model.OpenFlareMetricSnapshot) map[string]*model.OpenFlareMetricSnapshot {
+	result := make(map[string]*model.OpenFlareMetricSnapshot, len(snapshots))
+	for _, snapshot := range snapshots {
+		if snapshot == nil || snapshot.NodeID == "" {
+			continue
+		}
+		if existing, ok := result[snapshot.NodeID]; ok && !snapshot.CapturedAt.After(existing.CapturedAt) {
+			continue
+		}
+		result[snapshot.NodeID] = snapshot
+	}
+	return result
+}
+
+// LatestTrafficReportsByNode returns the latest traffic report per node.
+func LatestTrafficReportsByNode(reports []*model.OpenFlareRequestReport) map[string]*model.OpenFlareRequestReport {
+	result := make(map[string]*model.OpenFlareRequestReport, len(reports))
+	for _, report := range reports {
+		if report == nil || report.NodeID == "" {
+			continue
+		}
+		if existing, ok := result[report.NodeID]; ok && !report.WindowEndedAt.After(existing.WindowEndedAt) {
+			continue
+		}
+		result[report.NodeID] = report
+	}
+	return result
+}
+
+// ActiveHealthEventsByNode groups active health events by node id.
+func ActiveHealthEventsByNode(events []*model.OpenFlareHealthEvent) map[string][]*model.OpenFlareHealthEvent {
+	result := make(map[string][]*model.OpenFlareHealthEvent)
+	for _, event := range events {
+		if event == nil || event.NodeID == "" {
+			continue
+		}
+		result[event.NodeID] = append(result[event.NodeID], event)
+	}
+	return result
+}
+
+// Percentage returns used/total as a percentage.
+func Percentage(used int64, total int64) float64 {
+	if used <= 0 || total <= 0 {
+		return 0
+	}
+	return (float64(used) / float64(total)) * 100
+}
+
+func mergeJSONCounts(target distributionAccumulator, raw string) {
+	if len(target) == 0 && strings.TrimSpace(raw) == "" {
+		return
+	}
+	values := parseJSONCounts(raw)
+	for key, value := range values {
+		if strings.TrimSpace(key) == "" || value <= 0 {
+			continue
+		}
+		target[key] += value
+	}
+}
+
+func parseJSONCounts(raw string) map[string]int64 {
+	if strings.TrimSpace(raw) == "" {
+		return nil
+	}
+	values := make(map[string]int64)
+	if err := json.Unmarshal([]byte(raw), &values); err != nil {
+		return nil
+	}
+	return values
+}
+
+func toDistributionItems(values distributionAccumulator, limit int) []DistributionItem {
+	if len(values) == 0 {
+		return []DistributionItem{}
+	}
+	items := make([]DistributionItem, 0, len(values))
+	for key, value := range values {
+		if strings.TrimSpace(key) == "" || value <= 0 {
+			continue
+		}
+		items = append(items, DistributionItem{Key: key, Value: value})
+	}
+	sort.Slice(items, func(i int, j int) bool {
+		if items[i].Value == items[j].Value {
+			return items[i].Key < items[j].Key
+		}
+		return items[i].Value > items[j].Value
+	})
+	if limit > 0 && len(items) > limit {
+		items = items[:limit]
+	}
+	return items
+}
+
+func trendWindowStart(now time.Time) time.Time {
+	return now.Truncate(time.Hour).Add(-(observabilityTrendBuckets - 1) * time.Hour)
+}
+
+func trendBucketIndex(timestamp time.Time, start time.Time) (int, bool) {
+	if timestamp.Before(start) {
+		return 0, false
+	}
+	delta := timestamp.Sub(start)
+	index := int(delta / time.Hour)
+	if index < 0 || index >= observabilityTrendBuckets {
+		return 0, false
+	}
+	return index, true
+}
@@ -0,0 +1,246 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package observability
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"gorm.io/gorm"
+)
+
+const (
+	defaultObservabilityWindow = 24 * time.Hour
+	defaultObservabilityLimit  = 120
+	maxObservabilityLimit      = 500
+)
+
+// NodeQuery filters node observability data.
+type NodeQuery struct {
+	Hours int `json:"hours"`
+	Limit int `json:"limit"`
+}
+
+// NodeAnalytics groups node observability analytics.
+type NodeAnalytics struct {
+	Traffic       TrafficWindowSummary `json:"traffic"`
+	Distributions TrafficDistributions `json:"distributions"`
+	Health        HealthSummary        `json:"health"`
+}
+
+// NodeTrends groups node observability trend series.
+type NodeTrends struct {
+	Traffic24h  []TrafficTrendPoint  `json:"traffic_24h"`
+	Capacity24h []CapacityTrendPoint `json:"capacity_24h"`
+	Network24h  []NetworkTrendPoint  `json:"network_24h"`
+	DiskIO24h   []DiskIOTrendPoint   `json:"disk_io_24h"`
+}
+
+// RelayDashboardSnapshot summarizes tunnel relay status.
+type RelayDashboardSnapshot struct {
+	TotalProxies     int              `json:"total_proxies"`
+	OnlineProxies    int              `json:"online_proxies"`
+	OfflineProxies   int              `json:"offline_proxies"`
+	Proxies          []RelayProxyStat `json:"proxies"`
+	TotalConnections int              `json:"total_connections"`
+	ClientCounts     int              `json:"client_counts"`
+}
+
+// RelayProxyStat is a single relay proxy entry.
+type RelayProxyStat struct {
+	Name          string `json:"name"`
+	Type          string `json:"type"`
+	Status        string `json:"status"`
+	ClientVersion string `json:"client_version"`
+	LastStartTime string `json:"last_start_time"`
+	LastCloseTime string `json:"last_close_time"`
+	ClientAddr    string `json:"client_addr"`
+}
+
+// NodeView is the node observability API response.
+type NodeView struct {
+	NodeID          string                            `json:"node_id"`
+	Profile         *model.OpenFlareNodeSystemProfile `json:"profile"`
+	MetricSnapshots []*model.OpenFlareMetricSnapshot  `json:"metric_snapshots"`
+	TrafficReports  []*model.OpenFlareRequestReport   `json:"traffic_reports"`
+	HealthEvents    []*model.OpenFlareHealthEvent     `json:"health_events"`
+	Analytics       NodeAnalytics                     `json:"analytics"`
+	Trends          NodeTrends                        `json:"trends"`
+	RelayDashboard  *RelayDashboardSnapshot           `json:"relay_dashboard,omitempty"`
+}
+
+// HealthEventCleanupResult reports health event cleanup outcome.
+type HealthEventCleanupResult struct {
+	NodeID       string `json:"node_id"`
+	DeletedCount int64  `json:"deleted_count"`
+}
+
+// GetNodeObservability returns observability details for a node.
+func GetNodeObservability(ctx context.Context, id uint, query NodeQuery) (*NodeView, error) {
+	now := time.Now()
+	node, err := model.GetOpenFlareNodeByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	limit := normalizeObservabilityLimit(query.Limit)
+	since := now.Add(-normalizeObservabilityWindow(query.Hours))
+
+	profile, err := model.GetOpenFlareNodeSystemProfile(ctx, node.NodeID)
+	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, err
+	}
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		profile = nil
+	}
+
+	snapshots, err := model.ListOpenFlareMetricSnapshotsSince(ctx, node.NodeID, since, limit)
+	if err != nil {
+		return nil, err
+	}
+	reports, err := model.ListOpenFlareRequestReportsSince(ctx, node.NodeID, since, limit)
+	if err != nil {
+		return nil, err
+	}
+	accessLogRegions, err := model.ListOpenFlareAccessLogRegionCounts(ctx, node.NodeID, since, 8)
+	if err != nil {
+		return nil, err
+	}
+	trendSnapshots, err := model.ListOpenFlareMetricSnapshotsSince(ctx, node.NodeID, now.Add(-24*time.Hour), 0)
+	if err != nil {
+		return nil, err
+	}
+	trendOpenresty, err := model.ListOpenFlareNodeObservationOpenresty(ctx, node.NodeID, now.Add(-24*time.Hour), 0)
+	if err != nil {
+		return nil, err
+	}
+	trendReports, err := model.ListOpenFlareRequestReportsSince(ctx, node.NodeID, now.Add(-24*time.Hour), 0)
+	if err != nil {
+		return nil, err
+	}
+	events, err := model.ListOpenFlareHealthEvents(ctx, node.NodeID, false, limit)
+	if err != nil {
+		return nil, err
+	}
+
+	view := &NodeView{
+		NodeID:          node.NodeID,
+		Profile:         profile,
+		MetricSnapshots: snapshots,
+		TrafficReports:  reports,
+		HealthEvents:    events,
+		Analytics: NodeAnalytics{
+			Traffic:       buildTrafficWindowSummary(latestTrafficReport(reports)),
+			Distributions: BuildTrafficDistributions(reports, accessLogRegions, 8),
+			Health:        buildHealthSummary(latestMetricSnapshot(snapshots), latestTrafficReport(reports), events),
+		},
+		Trends: NodeTrends{
+			Traffic24h:  BuildTrafficTrendPoints(now, trendReports),
+			Capacity24h: BuildCapacityTrendPoints(now, trendSnapshots),
+			Network24h:  BuildNetworkTrendPoints(now, trendSnapshots, trendOpenresty),
+			DiskIO24h:   BuildDiskIOTrendPoints(now, trendSnapshots),
+		},
+	}
+	if node.NodeType == "tunnel_relay" {
+		frpsObs, frpsErr := model.ListOpenFlareNodeObservationFrps(ctx, node.NodeID, time.Time{}, 1)
+		if frpsErr != nil {
+			return nil, frpsErr
+		}
+		var latestFrps *model.OpenFlareNodeObservationFrps
+		if len(frpsObs) > 0 {
+			latestFrps = frpsObs[0]
+		}
+		view.RelayDashboard = buildRelayDashboardSnapshot(node, latestFrps)
+	}
+	return view, nil
+}
+
+// CleanupHealthEvents removes all health events for a node.
+func CleanupHealthEvents(ctx context.Context, id uint) (*HealthEventCleanupResult, error) {
+	node, err := model.GetOpenFlareNodeByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	deletedCount, err := model.DeleteOpenFlareHealthEventsByNodeID(ctx, node.NodeID)
+	if err != nil {
+		return nil, err
+	}
+	return &HealthEventCleanupResult{
+		NodeID:       node.NodeID,
+		DeletedCount: deletedCount,
+	}, nil
+}
+
+func buildRelayDashboardSnapshot(node *model.OpenFlareNode, obs *model.OpenFlareNodeObservationFrps) *RelayDashboardSnapshot {
+	if node == nil {
+		return nil
+	}
+	totalProxies := 0
+	totalConnections := 0
+	clientCounts := 0
+	proxies := []RelayProxyStat{}
+
+	if obs != nil {
+		totalProxies = obs.FrpsProxyCount
+		totalConnections = obs.FrpsConnections
+		clientCounts = obs.FrpsClientCount
+		if obs.FrpsProxies != "" {
+			var decoded []RelayProxyStat
+			if err := json.Unmarshal([]byte(obs.FrpsProxies), &decoded); err == nil {
+				proxies = decoded
+			}
+		}
+	}
+	if totalProxies < 0 {
+		totalProxies = 0
+	}
+	onlineProxies := 0
+	for _, proxy := range proxies {
+		if proxy.Status == "online" {
+			onlineProxies++
+		}
+	}
+	if len(proxies) == 0 {
+		onlineProxies = totalProxies
+		if node.RelayStatus != "healthy" {
+			onlineProxies = 0
+		}
+	}
+
+	return &RelayDashboardSnapshot{
+		TotalProxies:     totalProxies,
+		OnlineProxies:    onlineProxies,
+		OfflineProxies:   totalProxies - onlineProxies,
+		Proxies:          proxies,
+		TotalConnections: maxInt(totalConnections, 0),
+		ClientCounts:     maxInt(clientCounts, 0),
+	}
+}
+
+func maxInt(a int, b int) int {
+	if a > b {
+		return a
+	}
+	return b
+}
+
+func normalizeObservabilityLimit(limit int) int {
+	if limit <= 0 {
+		return defaultObservabilityLimit
+	}
+	if limit > maxObservabilityLimit {
+		return maxObservabilityLimit
+	}
+	return limit
+}
+
+func normalizeObservabilityWindow(hours int) time.Duration {
+	if hours <= 0 {
+		return defaultObservabilityWindow
+	}
+	return time.Duration(hours) * time.Hour
+}
@@ -0,0 +1,223 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package observability
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/openflare/apiutil"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/gin-gonic/gin"
+)
+
+// GetAccessLogsHandler 分页列出访问日志。
+// @Summary 列出访问日志
+// @Description 分页返回 OpenFlare 访问日志，支持按节点、IP、主机与路径筛选，需要管理员权限
+// @Tags openflare-observability
+// @Produce json
+// @Security SessionCookie
+// @Param node_id query string false "节点 ID"
+// @Param remote_addr query string false "客户端 IP"
+// @Param host query string false "请求 Host"
+// @Param path query string false "请求路径"
+// @Param p query int false "页码"
+// @Param page_size query int false "每页条数"
+// @Param sort_by query string false "排序字段"
+// @Param sort_order query string false "排序方向"
+// @Success 200 {object} response.Any{data=observability.AccessLogList} "访问日志列表"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 404 {object} response.Any "无权限或不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/d/access-logs [get]
+func GetAccessLogsHandler(c *gin.Context) {
+	logs, err := ListAccessLogs(c.Request.Context(), readAccessLogQuery(c))
+	if apiutil.AbortBadRequestOnError(c, err) {
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(logs))
+}
+
+// getFoldedAccessLogsHandler 分页列出折叠访问日志。
+// @Summary 列出折叠访问日志
+// @Description 按时间桶聚合访问日志并分页返回，需要管理员权限
+// @Tags openflare-observability
+// @Produce json
+// @Security SessionCookie
+// @Param node_id query string false "节点 ID"
+// @Param remote_addr query string false "客户端 IP"
+// @Param host query string false "请求 Host"
+// @Param path query string false "请求路径"
+// @Param fold_minutes query int false "折叠时间窗口（分钟）"
+// @Param p query int false "页码"
+// @Param page_size query int false "每页条数"
+// @Param sort_by query string false "排序字段"
+// @Param sort_order query string false "排序方向"
+// @Success 200 {object} response.Any{data=observability.FoldedAccessLogList} "折叠访问日志列表"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 404 {object} response.Any "无权限或不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/d/access-logs/folds [get]
+func GetFoldedAccessLogsHandler(c *gin.Context) {
+	query := readAccessLogQuery(c)
+	query.FoldMinutes = readQueryInt(c, "fold_minutes")
+	logs, err := ListFoldedAccessLogs(c.Request.Context(), query)
+	if apiutil.AbortBadRequestOnError(c, err) {
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(logs))
+}
+
+// getFoldedAccessLogIPsHandler 列出折叠桶内的 IP 汇总。
+// @Summary 列出折叠访问日志 IP 汇总
+// @Description 在指定时间桶内按 IP 聚合访问统计，需要管理员权限
+// @Tags openflare-observability
+// @Produce json
+// @Security SessionCookie
+// @Param node_id query string false "节点 ID"
+// @Param remote_addr query string false "客户端 IP"
+// @Param host query string false "请求 Host"
+// @Param path query string false "请求路径"
+// @Param bucket_started_at query string false "时间桶起始时间"
+// @Param fold_minutes query int false "折叠时间窗口（分钟）"
+// @Param p query int false "页码"
+// @Param page_size query int false "每页条数"
+// @Param sort_by query string false "排序字段"
+// @Param sort_order query string false "排序方向"
+// @Success 200 {object} response.Any{data=observability.FoldedAccessLogIPList} "折叠 IP 汇总列表"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 404 {object} response.Any "无权限或不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/d/access-logs/folds/ip-summary [get]
+func GetFoldedAccessLogIPsHandler(c *gin.Context) {
+	result, err := ListFoldedAccessLogIPs(c.Request.Context(), FoldedAccessLogIPQuery{
+		NodeID:          c.Query("node_id"),
+		RemoteAddr:      c.Query("remote_addr"),
+		Host:            c.Query("host"),
+		Path:            c.Query("path"),
+		BucketStartedAt: c.Query("bucket_started_at"),
+		FoldMinutes:     readQueryInt(c, "fold_minutes"),
+		Page:            readQueryInt(c, "p"),
+		PageSize:        readQueryInt(c, "page_size"),
+		SortBy:          c.Query("sort_by"),
+		SortOrder:       c.Query("sort_order"),
+	})
+	if apiutil.AbortBadRequestOnError(c, err) {
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(result))
+}
+
+// getAccessLogIPSummariesHandler 列出访问日志 IP 汇总。
+// @Summary 列出访问日志 IP 汇总
+// @Description 按 IP 聚合访问日志统计并分页返回，需要管理员权限
+// @Tags openflare-observability
+// @Produce json
+// @Security SessionCookie
+// @Param node_id query string false "节点 ID"
+// @Param remote_addr query string false "客户端 IP"
+// @Param host query string false "请求 Host"
+// @Param p query int false "页码"
+// @Param page_size query int false "每页条数"
+// @Param sort_by query string false "排序字段"
+// @Param sort_order query string false "排序方向"
+// @Success 200 {object} response.Any{data=observability.AccessLogIPSummaryList} "IP 汇总列表"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 404 {object} response.Any "无权限或不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/d/access-logs/ip-summary [get]
+func GetAccessLogIPSummariesHandler(c *gin.Context) {
+	result, err := ListAccessLogIPSummaries(c.Request.Context(), AccessLogIPSummaryQuery{
+		NodeID:     c.Query("node_id"),
+		RemoteAddr: c.Query("remote_addr"),
+		Host:       c.Query("host"),
+		Page:       readQueryInt(c, "p"),
+		PageSize:   readQueryInt(c, "page_size"),
+		SortBy:     c.Query("sort_by"),
+		SortOrder:  c.Query("sort_order"),
+	})
+	if apiutil.AbortBadRequestOnError(c, err) {
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(result))
+}
+
+// getAccessLogIPTrendHandler 获取 IP 访问趋势。
+// @Summary 获取访问日志 IP 趋势
+// @Description 返回指定 IP 在时间范围内的访问趋势数据，需要管理员权限
+// @Tags openflare-observability
+// @Produce json
+// @Security SessionCookie
+// @Param node_id query string false "节点 ID"
+// @Param remote_addr query string false "客户端 IP"
+// @Param host query string false "请求 Host"
+// @Param hours query int false "统计时间范围（小时）"
+// @Param bucket_minutes query int false "时间桶粒度（分钟）"
+// @Success 200 {object} response.Any{data=observability.AccessLogIPTrendView} "IP 访问趋势"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 404 {object} response.Any "无权限或不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/d/access-logs/ip-summary/trend [get]
+func GetAccessLogIPTrendHandler(c *gin.Context) {
+	result, err := GetAccessLogIPTrend(c.Request.Context(), AccessLogIPTrendQuery{
+		NodeID:        c.Query("node_id"),
+		RemoteAddr:    c.Query("remote_addr"),
+		Host:          c.Query("host"),
+		Hours:         readQueryInt(c, "hours"),
+		BucketMinutes: readQueryInt(c, "bucket_minutes"),
+	})
+	if apiutil.AbortBadRequestOnError(c, err) {
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(result))
+}
+
+// cleanupAccessLogsHandler 清理过期访问日志。
+// @Summary 清理访问日志
+// @Description 按保留天数清理过期访问日志记录，需要管理员权限
+// @Tags openflare-observability
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body observability.AccessLogCleanupInput true "清理参数"
+// @Success 200 {object} response.Any{data=observability.AccessLogCleanupResult} "清理结果"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 404 {object} response.Any "无权限或不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/d/access-logs/cleanup [post]
+func CleanupAccessLogsHandler(c *gin.Context) {
+	var input AccessLogCleanupInput
+	if !apiutil.BindJSON(c, &input) {
+		return
+	}
+	result, err := CleanupAccessLogs(c.Request.Context(), input)
+	if apiutil.AbortBadRequestOnError(c, err) {
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(result))
+}
+
+func readAccessLogQuery(c *gin.Context) AccessLogQuery {
+	return AccessLogQuery{
+		NodeID:     c.Query("node_id"),
+		RemoteAddr: c.Query("remote_addr"),
+		Host:       c.Query("host"),
+		Path:       c.Query("path"),
+		Page:       readQueryInt(c, "p"),
+		PageSize:   readQueryInt(c, "page_size"),
+		SortBy:     c.Query("sort_by"),
+		SortOrder:  c.Query("sort_order"),
+	}
+}
+
+func readQueryInt(c *gin.Context, key string) int {
+	value, _ := strconv.Atoi(c.DefaultQuery(key, "0"))
+	return value
+}