feat: 解决 CDC 去重、集中备份与首次初始化问题 (#105)

实现 CDC 内容寻址仓库、远程 Agent 中央中转备份与首次初始化体验，并补充安全校验、测试及双语文档。

Closes #94
Closes #101
Closes #104

server/internal/http/agent_handler.go

@@ -156,6 +156,44 @@ func (h *AgentHandler) UpdateRecord(c *gin.Context) {
 	response.Success(c, gin.H{"status": "ok"})
 }
 
+// UploadArtifact streams a remote source artifact into storage mounted only on
+// the Master. The request body is never buffered as a whole in memory or disk.
+func (h *AgentHandler) UploadArtifact(c *gin.Context) {
+	node, err := h.agentService.AuthenticatedNode(c.Request.Context(), extractToken(c))
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	recordID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	targetID, err := strconv.ParseUint(c.Param("targetId"), 10, 32)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	if c.Request.ContentLength < 0 {
+		c.JSON(stdhttp.StatusLengthRequired, gin.H{"code": "CONTENT_LENGTH_REQUIRED", "message": "artifact content length is required"})
+		return
+	}
+	if err := h.agentService.UploadArtifact(
+		c.Request.Context(),
+		node,
+		uint(recordID),
+		uint(targetID),
+		c.GetHeader("X-BackupX-Object-Key"),
+		c.Request.ContentLength,
+		c.GetHeader("X-BackupX-SHA256"),
+		c.Request.Body,
+	); err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, gin.H{"status": "ok"})
+}
+
 // GetRestoreSpec Agent 拉取恢复规格。
 func (h *AgentHandler) GetRestoreSpec(c *gin.Context) {
 	if h.restoreService == nil {
@@ -208,6 +246,34 @@ func (h *AgentHandler) UpdateRestore(c *gin.Context) {
 	response.Success(c, gin.H{"status": "ok"})
 }
 
+// DownloadRestoreArtifact streams a Master-local backup back to its source
+// Agent for restore without exposing the local storage configuration.
+func (h *AgentHandler) DownloadRestoreArtifact(c *gin.Context) {
+	if h.restoreService == nil {
+		c.JSON(stdhttp.StatusServiceUnavailable, gin.H{"code": "RESTORE_SERVICE_DISABLED", "message": "restore service is not enabled"})
+		return
+	}
+	node, err := h.agentService.AuthenticatedNode(c.Request.Context(), extractToken(c))
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	restoreID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	artifact, err := h.restoreService.DownloadAgentArtifact(c.Request.Context(), node, uint(restoreID))
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	c.DataFromReader(stdhttp.StatusOK, artifact.Size, "application/octet-stream", artifact.Reader, nil)
+	if err := artifact.Reader.Close(); err != nil {
+		_ = c.Error(err)
+	}
+}
+
 // Self 返回当前 Agent token 所属节点的状态，供安装脚本末尾探活。
 func (h *AgentHandler) Self(c *gin.Context) {
 	node, err := h.agentService.AuthenticatedNode(c.Request.Context(), extractToken(c))

server/internal/http/router.go

@@ -322,7 +322,9 @@ func NewRouter(deps RouterDependencies) *gin.Engine {
 			agent.POST("/commands/:id/result", agentHandler.SubmitCommandResult)
 			agent.GET("/tasks/:id", agentHandler.GetTaskSpec)
 			agent.POST("/records/:id", agentHandler.UpdateRecord)
+			agent.PUT("/records/:id/artifacts/:targetId", agentHandler.UploadArtifact)
 			agent.GET("/restores/:id/spec", agentHandler.GetRestoreSpec)
+			agent.GET("/restores/:id/artifact", agentHandler.DownloadRestoreArtifact)
 			agent.POST("/restores/:id", agentHandler.UpdateRestore)
 
 			// Agent v1（安装脚本探活用），仅 Self 端点