feat(pages): import deployment packages from URL

Add upload-from-url so admins can paste an HTTP(S) link and let the control
plane download the archive with browser-like headers. Private/LAN hosts and
insecure TLS certificates are allowed for internal artifact stores; package
size and format checks reuse the existing local-upload pipeline.

internal/apps/openflare/pages/download_url.go

@@ -0,0 +1,274 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package pages
+
+import (
+	"context"
+	"crypto/sha256"
+	"crypto/tls"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"mime"
+	"net"
+	"net/http"
+	"net/url"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/pkg/pagesarchive"
+)
+
+const (
+	pagesURLDownloadTimeout   = 10 * time.Minute
+	pagesURLMaxRedirects      = 5
+	pagesMagicSniffBytes      = 16
+	pagesURLDialTimeout       = 30 * time.Second
+	pagesURLTLSHandshake      = 15 * time.Second
+	pagesBrowserUserAgent     = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
+	pagesBrowserAccept        = "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7"
+	pagesBrowserAcceptLang    = "zh-CN,zh;q=0.9,en-US;q=0.8,en;q=0.7"
+	pagesBrowserSecCHUA       = `"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"`
+	pagesBrowserSecCHUAMobile = "?0"
+	pagesBrowserSecCHUAPlat   = `"Windows"`
+)
+
+// downloadPagesPackageFromURL fetches a remote archive with browser-like headers
+// and writes it to a temp file. Allows private/LAN hosts and insecure TLS certs
+// (self-signed / internal CA) so operators can pull from internal artifact stores.
+func downloadPagesPackageFromURL(ctx context.Context, rawURL string, maxPackageBytes int64) (tempPath string, checksum string, size int64, format pagesarchive.Format, fileName string, err error) {
+	parsed, err := parseAndValidatePagesDownloadURL(rawURL)
+	if err != nil {
+		return "", "", 0, "", "", err
+	}
+
+	resp, err := doBrowserDownload(ctx, parsed)
+	if err != nil {
+		return "", "", 0, "", "", err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return "", "", 0, "", "", fmt.Errorf("%s: HTTP %d", errPagesPackageURLDownloadFailed, resp.StatusCode)
+	}
+	if resp.ContentLength > 0 && resp.ContentLength > maxPackageBytes {
+		return "", "", 0, "", "", errors.New(errPagesPackageURLTooLarge)
+	}
+
+	fileName = fileNameFromDownload(resp, parsed)
+	format, _ = pagesarchive.DetectFormatFromName(fileName)
+
+	tempPath, checksum, size, err = writeLimitedPackageTemp(resp.Body, format, maxPackageBytes)
+	if err != nil {
+		return "", "", 0, "", "", err
+	}
+	format, fileName, err = ensurePackageFormat(tempPath, format, fileName)
+	if err != nil {
+		_ = os.Remove(tempPath)
+		return "", "", 0, "", "", err
+	}
+	return tempPath, checksum, size, format, fileName, nil
+}
+
+func newPagesURLDownloadClient() *http.Client {
+	transport := &http.Transport{
+		Proxy: http.ProxyFromEnvironment,
+		DialContext: (&net.Dialer{
+			Timeout:   pagesURLDialTimeout,
+			KeepAlive: pagesURLDialTimeout,
+		}).DialContext,
+		ForceAttemptHTTP2:     true,
+		MaxIdleConns:          32,
+		IdleConnTimeout:       90 * time.Second,
+		TLSHandshakeTimeout:   pagesURLTLSHandshake,
+		ExpectContinueTimeout: time.Second,
+		// Allow self-signed / internal certificates for artifact hosts.
+		TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, //nolint:gosec // intentional for internal/dev artifact URLs
+	}
+	client := &http.Client{
+		Timeout:   pagesURLDownloadTimeout,
+		Transport: transport,
+	}
+	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
+		if len(via) >= pagesURLMaxRedirects {
+			return errors.New(errPagesPackageURLDownloadFailed)
+		}
+		if err := validatePagesDownloadURLValue(req.URL); err != nil {
+			return err
+		}
+		applyBrowserDownloadHeaders(req, via[0].URL.String())
+		return nil
+	}
+	return client
+}
+
+func doBrowserDownload(ctx context.Context, parsed *url.URL) (*http.Response, error) {
+	client := newPagesURLDownloadClient()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, parsed.String(), nil)
+	if err != nil {
+		return nil, errors.New(errPagesPackageURLInvalid)
+	}
+	applyBrowserDownloadHeaders(req, "")
+	resp, err := client.Do(req) //nolint:gosec // scheme validated; private hosts and insecure TLS intentionally allowed
+	if err != nil {
+		return nil, fmt.Errorf("%s: %w", errPagesPackageURLDownloadFailed, err)
+	}
+	return resp, nil
+}
+
+func writeLimitedPackageTemp(body io.Reader, format pagesarchive.Format, maxPackageBytes int64) (tempPath, checksum string, size int64, err error) {
+	temp, err := os.CreateTemp("", "openflare-pages-url-*."+safeTempSuffixOrBin(format))
+	if err != nil {
+		return "", "", 0, err
+	}
+	tempPath = temp.Name()
+	defer func() {
+		_ = temp.Close()
+		if err != nil {
+			_ = os.Remove(tempPath)
+		}
+	}()
+
+	hash := sha256.New()
+	written, copyErr := io.Copy(io.MultiWriter(temp, hash), io.LimitReader(body, maxPackageBytes+1))
+	if copyErr != nil {
+		err = fmt.Errorf("%s: %w", errPagesPackageURLDownloadFailed, copyErr)
+		return "", "", 0, err
+	}
+	if written > maxPackageBytes {
+		err = errors.New(errPagesPackageURLTooLarge)
+		return "", "", 0, err
+	}
+	if written == 0 {
+		err = errors.New(errPagesPackageEmpty)
+		return "", "", 0, err
+	}
+	return tempPath, hex.EncodeToString(hash.Sum(nil)), written, nil
+}
+
+func ensurePackageFormat(tempPath string, format pagesarchive.Format, fileName string) (pagesarchive.Format, string, error) {
+	if format != "" {
+		return format, fileName, nil
+	}
+	detected, ok := sniffPackageFormat(tempPath)
+	if !ok {
+		return "", fileName, errors.New(errPagesPackageUnsupported)
+	}
+	if !strings.Contains(strings.ToLower(fileName), ".") {
+		fileName = fileName + "." + pagesarchive.Extension(detected)
+	}
+	return detected, fileName, nil
+}
+
+func sniffPackageFormat(tempPath string) (pagesarchive.Format, bool) {
+	file, err := os.Open(tempPath) //nolint:gosec // temp path created by us
+	if err != nil {
+		return "", false
+	}
+	defer func() { _ = file.Close() }()
+	head := make([]byte, pagesMagicSniffBytes)
+	n, _ := io.ReadFull(file, head)
+	if n <= 0 {
+		return "", false
+	}
+	return pagesarchive.DetectFormatFromBytes(head[:n])
+}
+
+func safeTempSuffixOrBin(format pagesarchive.Format) string {
+	if format == "" {
+		return "bin"
+	}
+	return safeTempSuffix(format)
+}
+
+func applyBrowserDownloadHeaders(req *http.Request, referer string) {
+	if req == nil {
+		return
+	}
+	req.Header.Set("User-Agent", pagesBrowserUserAgent)
+	req.Header.Set("Accept", pagesBrowserAccept)
+	req.Header.Set("Accept-Language", pagesBrowserAcceptLang)
+	req.Header.Set("Cache-Control", "no-cache")
+	req.Header.Set("Pragma", "no-cache")
+	req.Header.Set("Upgrade-Insecure-Requests", "1")
+	req.Header.Set("Sec-Fetch-Dest", "document")
+	req.Header.Set("Sec-Fetch-Mode", "navigate")
+	req.Header.Set("Sec-Fetch-Site", "none")
+	req.Header.Set("Sec-Fetch-User", "?1")
+	req.Header.Set("Sec-Ch-Ua", pagesBrowserSecCHUA)
+	req.Header.Set("Sec-Ch-Ua-Mobile", pagesBrowserSecCHUAMobile)
+	req.Header.Set("Sec-Ch-Ua-Platform", pagesBrowserSecCHUAPlat)
+	if referer != "" {
+		req.Header.Set("Referer", referer)
+		req.Header.Set("Sec-Fetch-Site", "cross-site")
+		return
+	}
+	if req.URL != nil {
+		req.Header.Set("Referer", req.URL.Scheme+"://"+req.URL.Host+"/")
+	}
+}
+
+func parseAndValidatePagesDownloadURL(raw string) (*url.URL, error) {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		return nil, errors.New(errPagesPackageURLRequired)
+	}
+	parsed, err := url.Parse(value)
+	if err != nil {
+		return nil, errors.New(errPagesPackageURLInvalid)
+	}
+	if err := validatePagesDownloadURLValue(parsed); err != nil {
+		return nil, err
+	}
+	return parsed, nil
+}
+
+func validatePagesDownloadURLValue(parsed *url.URL) error {
+	if parsed == nil {
+		return errors.New(errPagesPackageURLInvalid)
+	}
+	scheme := strings.ToLower(strings.TrimSpace(parsed.Scheme))
+	if scheme != "http" && scheme != "https" {
+		return errors.New(errPagesPackageURLInvalid)
+	}
+	if strings.TrimSpace(parsed.Hostname()) == "" {
+		return errors.New(errPagesPackageURLInvalid)
+	}
+	return nil
+}
+
+func fileNameFromDownload(resp *http.Response, parsed *url.URL) string {
+	if name := fileNameFromContentDisposition(resp); name != "" {
+		return name
+	}
+	if parsed != nil {
+		base := path.Base(parsed.Path)
+		if base != "" && base != "." && base != "/" {
+			return base
+		}
+	}
+	return "package.bin"
+}
+
+func fileNameFromContentDisposition(resp *http.Response) string {
+	if resp == nil {
+		return ""
+	}
+	cd := resp.Header.Get("Content-Disposition")
+	if cd == "" {
+		return ""
+	}
+	_, params, err := mime.ParseMediaType(cd)
+	if err != nil {
+		return ""
+	}
+	name := strings.TrimSpace(params["filename"])
+	if name == "" {
+		return ""
+	}
+	return path.Base(filepath.ToSlash(name))
+}

internal/apps/openflare/pages/download_url_test.go

@@ -0,0 +1,110 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package pages
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseAndValidatePagesDownloadURL(t *testing.T) {
+	_, err := parseAndValidatePagesDownloadURL("")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "填写")
+
+	_, err = parseAndValidatePagesDownloadURL("ftp://example.com/a.zip")
+	require.Error(t, err)
+
+	// Private / local hosts are allowed (operator-controlled artifact hosts).
+	for _, raw := range []string{
+		"http://127.0.0.1/a.zip",
+		"https://localhost/a.zip",
+		"http://192.168.1.10:8080/site.tar.gz",
+		"https://example.com/dist/site.tar.gz?x=1",
+	} {
+		parsed, parseErr := parseAndValidatePagesDownloadURL(raw)
+		require.NoError(t, parseErr, raw)
+		assert.NotEmpty(t, parsed.Hostname(), raw)
+	}
+}
+
+func TestDownloadPagesPackageFromURLAllowsPrivateHost(t *testing.T) {
+	var body bytes.Buffer
+	zw := zip.NewWriter(&body)
+	w, err := zw.Create("index.html")
+	require.NoError(t, err)
+	_, err = w.Write([]byte("ok"))
+	require.NoError(t, err)
+	require.NoError(t, zw.Close())
+	zipBytes := body.Bytes()
+
+	var sawBrowserUA bool
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.Contains(r.Header.Get("User-Agent"), "Mozilla") {
+			sawBrowserUA = true
+		}
+		w.Header().Set("Content-Disposition", `attachment; filename="remote-site.zip"`)
+		w.Header().Set("Content-Type", "application/zip")
+		_, _ = w.Write(zipBytes)
+	}))
+	t.Cleanup(server.Close)
+
+	req, err := http.NewRequest(http.MethodGet, server.URL+"/pkg.zip", nil)
+	require.NoError(t, err)
+	applyBrowserDownloadHeaders(req, "")
+	assert.Contains(t, req.Header.Get("User-Agent"), "Mozilla")
+	assert.Contains(t, req.Header.Get("Sec-Fetch-Mode"), "navigate")
+
+	tempPath, checksum, size, format, fileName, err := downloadPagesPackageFromURL(
+		context.Background(),
+		server.URL+"/pkg.zip",
+		10*1024*1024,
+	)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = os.Remove(tempPath) })
+	assert.True(t, sawBrowserUA)
+	assert.NotEmpty(t, checksum)
+	assert.Positive(t, size)
+	assert.Equal(t, "zip", string(format))
+	assert.Equal(t, "remote-site.zip", fileName)
+}
+
+func TestUploadDeploymentFromURLPrivateHost(t *testing.T) {
+	cleanup := setupPagesTestDB(t)
+	defer cleanup()
+	_, disableStorage := setupPagesStorageMock(t)
+	defer disableStorage()
+	ctx := context.Background()
+
+	var body bytes.Buffer
+	zw := zip.NewWriter(&body)
+	w, err := zw.Create("index.html")
+	require.NoError(t, err)
+	_, err = w.Write([]byte("from-url"))
+	require.NoError(t, err)
+	require.NoError(t, zw.Close())
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Disposition", `attachment; filename="from-url.zip"`)
+		_, _ = w.Write(body.Bytes())
+	}))
+	t.Cleanup(server.Close)
+
+	project, err := CreateProject(ctx, Input{Name: "URL Site", Slug: "url-site", Enabled: true})
+	require.NoError(t, err)
+
+	deployment, err := UploadDeploymentFromURL(ctx, project.ID, server.URL+"/from-url.zip", "root")
+	require.NoError(t, err)
+	assert.NotZero(t, deployment.ID)
+	assert.Equal(t, 1, deployment.FileCount)
+}

internal/apps/openflare/pages/errs.go

@@ -14,6 +14,10 @@ const (
 	errPagesDeploymentMismatch       = "pages 部署不属于该项目"
 	errPagesDeleteActiveDeploy       = "不能删除当前激活的 Pages 部署"
 	errPagesPackageMissing           = "缺少 Pages 部署包"
+	errPagesPackageURLRequired       = "请填写部署包下载链接"
+	errPagesPackageURLInvalid        = "部署包下载链接无效，仅支持 http/https"
+	errPagesPackageURLDownloadFailed = "从链接下载部署包失败"
+	errPagesPackageURLTooLarge       = "链接指向的部署包超过大小限制"
 	errPagesPackageNotZip            = "pages 部署包必须是 .zip 文件" // legacy alias kept for tests
 	errPagesPackageUnsupported       = "pages 部署包仅支持 zip、tar.gz、tar.xz、tar.bz2、tar、7z 格式"
 	errPagesPackageInvalidZip        = "pages 部署包不是有效 zip 文件" // legacy alias

internal/apps/openflare/pages/logics.go

@@ -243,7 +243,7 @@ func ListDeploymentFiles(ctx context.Context, deploymentID uint) ([]DeploymentFi
 	return views, nil
 }
 
-// UploadDeployment 上传 Pages 部署包。
+// UploadDeployment 上传 Pages 部署包（本地 multipart 文件）。
 func UploadDeployment(ctx context.Context, projectID uint, fileHeader *multipart.FileHeader, createdBy string) (*DeploymentView, error) {
 	project, err := model.GetPagesProjectByID(ctx, projectID)
 	if err != nil {
@@ -253,16 +253,52 @@ func UploadDeployment(ctx context.Context, projectID uint, fileHeader *multipart
 		return nil, errors.New(errPagesPackageMissing)
 	}
 	limits := resolvePagesLimits(ctx)
-	rootDir, err := validateAndNormalizePagesRootDir(project.RootDir)
-	if err != nil {
-		return nil, err
-	}
-	entryFile := normalizePagesEntryFile(project.EntryFile)
 	tempPath, checksum, _, format, err := persistPagesUploadTemp(fileHeader, limits.PackageBytes)
 	if err != nil {
 		return nil, err
 	}
 	defer func() { _ = os.Remove(tempPath) }()
+	return createDeploymentFromTempPackage(ctx, project, tempPath, checksum, format, fileHeader.Filename, createdBy, limits)
+}
+
+// UploadFromURLInput is the request body for downloading a deployment package from a remote URL.
+type UploadFromURLInput struct {
+	URL string `json:"url"`
+}
+
+// UploadDeploymentFromURL downloads a package from url and creates a deployment.
+func UploadDeploymentFromURL(ctx context.Context, projectID uint, rawURL string, createdBy string) (*DeploymentView, error) {
+	project, err := model.GetPagesProjectByID(ctx, projectID)
+	if err != nil {
+		return nil, err
+	}
+	limits := resolvePagesLimits(ctx)
+	tempPath, checksum, _, format, fileName, err := downloadPagesPackageFromURL(ctx, rawURL, limits.PackageBytes)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = os.Remove(tempPath) }()
+	return createDeploymentFromTempPackage(ctx, project, tempPath, checksum, format, fileName, createdBy, limits)
+}
+
+func createDeploymentFromTempPackage(
+	ctx context.Context,
+	project *model.PagesProject,
+	tempPath string,
+	checksum string,
+	format pagesarchive.Format,
+	fileName string,
+	createdBy string,
+	limits pagesLimits,
+) (*DeploymentView, error) {
+	if project == nil {
+		return nil, errors.New(errPagesProjectNotFound)
+	}
+	rootDir, err := validateAndNormalizePagesRootDir(project.RootDir)
+	if err != nil {
+		return nil, err
+	}
+	entryFile := normalizePagesEntryFile(project.EntryFile)
 	manifest, err := inspectPagesPackage(tempPath, format, rootDir, entryFile, limits)
 	if err != nil {
 		return nil, err
@@ -272,7 +308,7 @@ func UploadDeployment(ctx context.Context, projectID uint, fileHeader *multipart
 		tempPath,
 		checksum,
 		project.Slug,
-		fileHeader.Filename,
+		fileName,
 		format,
 	)
 	if err != nil {
@@ -321,8 +357,6 @@ func UploadDeployment(ctx context.Context, projectID uint, fileHeader *multipart
 	}
 	ingestCommitted = true
 
-	// History prune must not fail the already-committed upload. Log and continue;
-	// a later upload (or a retry pass inside prune) will re-attempt cleanup.
 	if pruneErr := pruneProjectDeploymentHistory(ctx, project.ID, limits.HistoryCount); pruneErr != nil {
 		logger.ErrorF(ctx,
 			"[Pages] prune deployment history failed: project_id=%d keep=%d error=%v",

internal/apps/openflare/pages/routers.go

@@ -190,13 +190,13 @@ func ListDeploymentsHandler(c *gin.Context) {
 
 // UploadDeploymentHandler 上传 Pages 部署包。
 // @Summary 上传 Pages 部署包
-// @Description 为指定项目上传 ZIP 部署包，需要管理员权限
+// @Description 为指定项目上传静态资源压缩包（zip/tar.gz/tar.xz/tar.bz2/tar/7z），需要管理员权限
 // @Tags openflare-pages
 // @Accept multipart/form-data
 // @Produce json
 // @Security SessionCookie
 // @Param id path int true "项目 ID"
-// @Param package formData file true "部署包 ZIP 文件"
+// @Param package formData file true "部署包文件"
 // @Success 200 {object} response.Any{data=pages.DeploymentView} "部署记录"
 // @Failure 400 {object} response.Any "参数错误"
 // @Failure 401 {object} response.Any "未登录"
@@ -221,6 +221,39 @@ func UploadDeploymentHandler(c *gin.Context) {
 	c.JSON(http.StatusOK, response.OK(deployment))
 }
 
+// UploadDeploymentFromURLHandler 从 URL 下载并创建 Pages 部署。
+// @Summary 从 URL 导入 Pages 部署包
+// @Description 从用户提供的 HTTP(S) 链接下载部署包并创建部署记录；服务端使用浏览器伪装请求头拉取，允许内网地址与不安全 TLS 证书，需要管理员权限
+// @Tags openflare-pages
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "项目 ID"
+// @Param request body pages.UploadFromURLInput true "下载链接"
+// @Success 200 {object} response.Any{data=pages.DeploymentView} "部署记录"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 404 {object} response.Any "无权限或不存在"
+// @Failure 404 {object} response.Any "项目不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/d/pages/{id}/deployments/upload-from-url [post]
+func UploadDeploymentFromURLHandler(c *gin.Context) {
+	id, ok := apiutil.IDParam(c)
+	if !ok {
+		return
+	}
+	var req UploadFromURLInput
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, errPagesPackageURLRequired)
+		return
+	}
+	deployment, err := UploadDeploymentFromURL(c.Request.Context(), id, req.URL, "")
+	if handleLogicError(c, err) {
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(deployment))
+}
+
 // ActivateDeploymentHandler 激活 Pages 部署。
 // @Summary 激活 Pages 部署
 // @Description 将指定部署设为项目当前生效版本，需要管理员权限

internal/router/v1/openflare/register_pages.go

@@ -20,6 +20,7 @@ func registerPagesRoutes(apiGroup *gin.RouterGroup) {
 		pagesRoute.POST("/:id/delete", pages.DeleteProjectHandler)
 		pagesRoute.GET("/:id/deployments", pages.ListDeploymentsHandler)
 		pagesRoute.POST("/:id/deployments/upload", pages.UploadDeploymentHandler)
+		pagesRoute.POST("/:id/deployments/upload-from-url", pages.UploadDeploymentFromURLHandler)
 		pagesRoute.POST("/:id/deployments/:deployment_id/activate", pages.ActivateDeploymentHandler)
 		pagesRoute.POST("/:id/deployments/:deployment_id/delete", pages.DeleteDeploymentHandler)
 		pagesRoute.GET("/deployments/:deployment_id/files", pages.ListDeploymentFilesHandler)