migrate

Wavelet/internal/apps/openflare/pages/errs.go

@@ -0,0 +1,23 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package pages
+
+const (
+	errPagesProjectNotFound      = "Pages 项目不存在"
+	errPagesSlugExists           = "Pages 项目标识已存在"
+	errPagesNameRequired         = "Pages 项目名称不能为空"
+	errPagesSlugInvalid          = "Pages 项目标识只能包含小写字母、数字和连字符"
+	errPagesDeleteReferenced     = "Pages 项目已被规则引用，不能删除"
+	errPagesDeploymentNotFound   = "Pages 部署不存在"
+	errPagesDeploymentMismatch   = "Pages 部署不属于该项目"
+	errPagesDeleteActiveDeploy   = "不能删除当前激活的 Pages 部署"
+	errPagesPackageMissing       = "缺少 Pages 部署包"
+	errPagesPackageNotZip        = "Pages 部署包必须是 .zip 文件"
+	errPagesPackageInvalidZip    = "Pages 部署包不是有效 zip 文件"
+	errPagesPackageEmpty         = "Pages 部署包不能为空"
+	errPagesAPIProxyPathRequired = "启用 API 反代时，匹配路径不能为空"
+	errPagesAPIProxyPathPrefix   = "API 反代匹配路径必须以 '/' 开头"
+	errPagesAPIProxyPassRequired = "启用 API 反代时，后端服务地址不能为空"
+	errPagesAPIProxyPassInvalid  = "API 反代后端服务地址必须是有效的 HTTP/HTTPS URL"
+)

Wavelet/internal/apps/openflare/pages/helpers.go

@@ -0,0 +1,355 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package pages
+
+import (
+	"archive/zip"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"os"
+	"path"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/model"
+)
+
+const (
+	pagesMaxDeploymentFiles  = 1000
+	pagesMaxDeploymentBytes  = 100 * 1024 * 1024
+	defaultPagesEntryFile    = "index.html"
+	defaultPagesFallbackPath = "/index.html"
+)
+
+var pagesSlugPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9-]{0,126}[a-z0-9]$|^[a-z0-9]$`)
+
+type deploymentManifest struct {
+	Files     []model.PagesDeploymentFile
+	FileCount int
+	TotalSize int64
+	EntryFile string
+}
+
+func isUniqueConstraintError(err error) bool {
+	if err == nil {
+		return false
+	}
+	return strings.Contains(strings.ToLower(err.Error()), "unique")
+}
+
+func normalizePagesSlug(raw string) string {
+	value := strings.ToLower(strings.TrimSpace(raw))
+	var builder strings.Builder
+	lastDash := false
+	for _, r := range value {
+		valid := (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9')
+		if valid {
+			builder.WriteRune(r)
+			lastDash = false
+			continue
+		}
+		if !lastDash {
+			builder.WriteByte('-')
+			lastDash = true
+		}
+	}
+	return strings.Trim(builder.String(), "-")
+}
+
+func validateAndNormalizePagesRootDir(raw string) (string, error) {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		return "", nil
+	}
+	if len(value) > 512 {
+		return "", errors.New("Pages 根目录长度不能超过 512")
+	}
+	if strings.Contains(value, "\\") || strings.ContainsAny(value, "\"';") {
+		return "", errors.New("Pages 根目录包含不支持的字符")
+	}
+	for _, r := range value {
+		if r <= 0x20 || r == 0x7f {
+			return "", errors.New("Pages 根目录不能包含空白或控制字符")
+		}
+	}
+	cleaned := path.Clean(filepath.ToSlash(value))
+	if cleaned == "." || cleaned == "/" {
+		return "", nil
+	}
+	for _, segment := range strings.Split(cleaned, "/") {
+		if segment == "." || segment == ".." {
+			return "", errors.New("Pages 根目录不能包含 . 或 .. 路径段")
+		}
+	}
+	return strings.TrimPrefix(cleaned, "/"), nil
+}
+
+func normalizePagesFallbackPath(raw string) (string, error) {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		value = defaultPagesFallbackPath
+	}
+	if len(value) > 512 {
+		return "", errors.New("SPA fallback 回退路径长度不能超过 512")
+	}
+	if !strings.HasPrefix(value, "/") {
+		return "", errors.New("SPA fallback 回退路径必须以 / 开头")
+	}
+	if value == "/" || strings.HasSuffix(value, "/") {
+		return "", errors.New("SPA fallback 回退路径必须指向具体文件")
+	}
+	if strings.Contains(value, "\\") || strings.ContainsAny(value, "\"';") {
+		return "", errors.New("SPA fallback 回退路径包含不支持的字符")
+	}
+	for _, r := range value {
+		if r <= 0x20 || r == 0x7f {
+			return "", errors.New("SPA fallback 回退路径不能包含空白或控制字符")
+		}
+	}
+	for _, segment := range strings.Split(value, "/") {
+		if segment == "." || segment == ".." {
+			return "", errors.New("SPA fallback 回退路径不能包含 . 或 .. 路径段")
+		}
+	}
+	cleaned := path.Clean(value)
+	if cleaned == "." || !strings.HasPrefix(cleaned, "/") {
+		return "", errors.New("SPA fallback 回退路径不合法")
+	}
+	if cleaned == "/" || strings.HasSuffix(cleaned, "/") {
+		return "", errors.New("SPA fallback 回退路径必须指向具体文件")
+	}
+	return cleaned, nil
+}
+
+func normalizeStoredPagesFallbackPath(value string) string {
+	normalized, err := normalizePagesFallbackPath(value)
+	if err != nil {
+		return defaultPagesFallbackPath
+	}
+	return normalized
+}
+
+func normalizePagesEntryFile(raw string) string {
+	value := path.Clean(strings.TrimSpace(filepath.ToSlash(raw)))
+	if value == "." || value == "/" {
+		return defaultPagesEntryFile
+	}
+	return strings.TrimPrefix(value, "/")
+}
+
+func persistPagesUploadTemp(fileHeader *multipart.FileHeader) (string, string, error) {
+	file, err := fileHeader.Open()
+	if err != nil {
+		return "", "", err
+	}
+	defer file.Close()
+	temp, err := os.CreateTemp("", "openflare-pages-*.zip")
+	if err != nil {
+		return "", "", err
+	}
+	defer temp.Close()
+	hash := sha256.New()
+	limited := io.LimitReader(file, pagesMaxDeploymentBytes+1)
+	written, err := io.Copy(io.MultiWriter(temp, hash), limited)
+	if err != nil {
+		_ = os.Remove(temp.Name())
+		return "", "", err
+	}
+	if written > pagesMaxDeploymentBytes {
+		_ = os.Remove(temp.Name())
+		return "", "", fmt.Errorf("Pages 部署包不能超过 %d MiB", pagesMaxDeploymentBytes/1024/1024)
+	}
+	return temp.Name(), hex.EncodeToString(hash.Sum(nil)), nil
+}
+
+func findCommonRootPrefix(files []*zip.File) (string, error) {
+	var firstFilePath string
+	hasMultipleFiles := false
+	for _, item := range files {
+		normalizedPath, skip, err := normalizePagesZipPath(item.Name)
+		if err != nil {
+			return "", err
+		}
+		if skip {
+			continue
+		}
+		if firstFilePath == "" {
+			firstFilePath = normalizedPath
+		} else {
+			hasMultipleFiles = true
+		}
+	}
+	if firstFilePath == "" {
+		return "", nil
+	}
+	parts := strings.Split(firstFilePath, "/")
+	if len(parts) <= 1 {
+		return "", nil
+	}
+	commonPrefix := parts[0] + "/"
+	if hasMultipleFiles {
+		for _, item := range files {
+			normalizedPath, skip, err := normalizePagesZipPath(item.Name)
+			if err != nil {
+				return "", err
+			}
+			if skip {
+				continue
+			}
+			if !strings.HasPrefix(normalizedPath, commonPrefix) {
+				return "", nil
+			}
+		}
+	}
+	return commonPrefix, nil
+}
+
+func inspectPagesZip(zipPath string, rootDir string, entryFile string) (*deploymentManifest, error) {
+	reader, err := zip.OpenReader(zipPath)
+	if err != nil {
+		return nil, errors.New(errPagesPackageInvalidZip)
+	}
+	defer reader.Close()
+
+	commonPrefix, err := findCommonRootPrefix(reader.File)
+	if err != nil {
+		return nil, err
+	}
+
+	manifest := &deploymentManifest{
+		Files:     []model.PagesDeploymentFile{},
+		EntryFile: entryFile,
+	}
+	targetEntryPath := entryFile
+	if rootDir != "" {
+		targetEntryPath = path.Join(rootDir, entryFile)
+	}
+	entrySeen := false
+	for _, item := range reader.File {
+		normalizedPath, skip, err := normalizePagesZipPath(item.Name)
+		if err != nil {
+			return nil, err
+		}
+		if skip {
+			continue
+		}
+		if commonPrefix != "" {
+			normalizedPath = strings.TrimPrefix(normalizedPath, commonPrefix)
+		}
+		if item.FileInfo().Mode()&os.ModeSymlink != 0 {
+			return nil, fmt.Errorf("Pages 部署包不支持符号链接: %s", normalizedPath)
+		}
+		if item.UncompressedSize64 > pagesMaxDeploymentBytes {
+			return nil, fmt.Errorf("Pages 文件过大: %s", normalizedPath)
+		}
+		manifest.FileCount++
+		if manifest.FileCount > pagesMaxDeploymentFiles {
+			return nil, fmt.Errorf("Pages 部署文件数不能超过 %d", pagesMaxDeploymentFiles)
+		}
+		manifest.TotalSize += int64(item.UncompressedSize64)
+		if manifest.TotalSize > pagesMaxDeploymentBytes {
+			return nil, fmt.Errorf("Pages 部署展开后不能超过 %d MiB", pagesMaxDeploymentBytes/1024/1024)
+		}
+		checksum, err := checksumZipFile(item)
+		if err != nil {
+			return nil, err
+		}
+		if normalizedPath == targetEntryPath {
+			entrySeen = true
+		}
+		manifest.Files = append(manifest.Files, model.PagesDeploymentFile{
+			Path:     normalizedPath,
+			Size:     int64(item.UncompressedSize64),
+			Checksum: checksum,
+		})
+	}
+	if manifest.FileCount == 0 {
+		return nil, errors.New(errPagesPackageEmpty)
+	}
+	if !entrySeen {
+		return nil, fmt.Errorf("Pages 部署包缺少入口文件 %s", targetEntryPath)
+	}
+	return manifest, nil
+}
+
+func normalizePagesZipPath(raw string) (string, bool, error) {
+	name := strings.TrimSpace(filepath.ToSlash(raw))
+	if name == "" {
+		return "", true, nil
+	}
+	if strings.HasSuffix(name, "/") {
+		return "", true, nil
+	}
+	if strings.HasPrefix(name, "/") || path.IsAbs(name) {
+		return "", false, fmt.Errorf("Pages 部署包不能包含绝对路径: %s", raw)
+	}
+	cleaned := path.Clean(name)
+	if cleaned == "." {
+		return "", true, nil
+	}
+	if cleaned == ".." || strings.HasPrefix(cleaned, "../") || strings.Contains(cleaned, "/../") {
+		return "", false, fmt.Errorf("Pages 部署包路径不能逃逸目录: %s", raw)
+	}
+	return cleaned, false, nil
+}
+
+func checksumZipFile(item *zip.File) (string, error) {
+	file, err := item.Open()
+	if err != nil {
+		return "", err
+	}
+	defer file.Close()
+	hash := sha256.New()
+	if _, err = io.Copy(hash, file); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(hash.Sum(nil)), nil
+}
+
+func pagesArtifactPath(projectSlug string, checksum string) (string, error) {
+	root, err := pagesStorageRoot()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(root, "artifacts", projectSlug, checksum+".zip"), nil
+}
+
+func pagesStorageRoot() (string, error) {
+	cfg := config.Config.Database
+	if cfg.Enabled {
+		return filepath.Abs(filepath.Join("data", "pages"))
+	}
+	dbPath := strings.TrimSpace(cfg.SQLitePath)
+	if dbPath == "" || dbPath == ":memory:" {
+		return filepath.Abs(filepath.Join("data", "pages"))
+	}
+	dir := filepath.Dir(dbPath)
+	if dir == "." || dir == "" {
+		dir = "data"
+	}
+	return filepath.Abs(filepath.Join(dir, "pages"))
+}
+
+func copyFile(src string, dst string) error {
+	input, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer input.Close()
+	output, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o644)
+	if err != nil {
+		return err
+	}
+	defer output.Close()
+	if _, err = io.Copy(output, input); err != nil {
+		return err
+	}
+	return output.Sync()
+}

Wavelet/internal/apps/openflare/pages/logics.go

@@ -0,0 +1,485 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package pages
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"mime/multipart"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"gorm.io/gorm"
+)
+
+// Input Pages 项目创建/更新请求。
+type Input struct {
+	Name               string `json:"name"`
+	Slug               string `json:"slug"`
+	Description        string `json:"description"`
+	Enabled            bool   `json:"enabled"`
+	SPAFallbackEnabled bool   `json:"spa_fallback_enabled"`
+	SPAFallbackPath    string `json:"spa_fallback_path"`
+	APIProxyEnabled    bool   `json:"api_proxy_enabled"`
+	APIProxyPath       string `json:"api_proxy_path"`
+	APIProxyPass       string `json:"api_proxy_pass"`
+	APIProxyRewrite    string `json:"api_proxy_rewrite"`
+	RootDir            string `json:"root_dir"`
+	EntryFile          string `json:"entry_file"`
+}
+
+// DeploymentView Pages 部署视图。
+type DeploymentView struct {
+	ID               uint       `json:"id"`
+	ProjectID        uint       `json:"project_id"`
+	DeploymentNumber int        `json:"deployment_number"`
+	Checksum         string     `json:"checksum"`
+	Status           string     `json:"status"`
+	FileCount        int        `json:"file_count"`
+	TotalSize        int64      `json:"total_size"`
+	CreatedBy        string     `json:"created_by"`
+	CreatedAt        time.Time  `json:"created_at"`
+	ActivatedAt      *time.Time `json:"activated_at"`
+}
+
+// DeploymentFileView Pages 部署文件视图。
+type DeploymentFileView struct {
+	ID           uint      `json:"id"`
+	DeploymentID uint      `json:"deployment_id"`
+	Path         string    `json:"path"`
+	Size         int64     `json:"size"`
+	Checksum     string    `json:"checksum"`
+	CreatedAt    time.Time `json:"created_at"`
+}
+
+// View Pages 项目视图。
+type View struct {
+	ID                 uint            `json:"id"`
+	Name               string          `json:"name"`
+	Slug               string          `json:"slug"`
+	Description        string          `json:"description"`
+	Enabled            bool            `json:"enabled"`
+	SPAFallbackEnabled bool            `json:"spa_fallback_enabled"`
+	SPAFallbackPath    string          `json:"spa_fallback_path"`
+	APIProxyEnabled    bool            `json:"api_proxy_enabled"`
+	APIProxyPath       string          `json:"api_proxy_path"`
+	APIProxyPass       string          `json:"api_proxy_pass"`
+	APIProxyRewrite    string          `json:"api_proxy_rewrite"`
+	RootDir            string          `json:"root_dir"`
+	EntryFile          string          `json:"entry_file"`
+	ActiveDeploymentID *uint           `json:"active_deployment_id"`
+	ActiveDeployment   *DeploymentView `json:"active_deployment,omitempty"`
+	DeploymentCount    int64           `json:"deployment_count"`
+	CreatedAt          time.Time       `json:"created_at"`
+	UpdatedAt          time.Time       `json:"updated_at"`
+}
+
+// ListProjects 列出全部 Pages 项目。
+func ListProjects(ctx context.Context) ([]View, error) {
+	projects, err := model.ListPagesProjects(ctx)
+	if err != nil {
+		return nil, err
+	}
+	views := make([]View, 0, len(projects))
+	for _, project := range projects {
+		view, err := buildProjectView(ctx, &project)
+		if err != nil {
+			return nil, err
+		}
+		views = append(views, *view)
+	}
+	return views, nil
+}
+
+// GetProject 获取 Pages 项目详情。
+func GetProject(ctx context.Context, id uint) (*View, error) {
+	project, err := model.GetPagesProjectByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	return buildProjectView(ctx, project)
+}
+
+// CreateProject 创建 Pages 项目。
+func CreateProject(ctx context.Context, input Input) (*View, error) {
+	project, err := buildProject(nil, input)
+	if err != nil {
+		return nil, err
+	}
+	if err = model.CreatePagesProjectRecord(ctx, project); err != nil {
+		if isUniqueConstraintError(err) {
+			return nil, errors.New(errPagesSlugExists)
+		}
+		return nil, err
+	}
+	return buildProjectView(ctx, project)
+}
+
+// UpdateProject 更新 Pages 项目。
+func UpdateProject(ctx context.Context, id uint, input Input) (*View, error) {
+	project, err := model.GetPagesProjectByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	project, err = buildProject(project, input)
+	if err != nil {
+		return nil, err
+	}
+	if err = db.DB(ctx).Model(project).Updates(map[string]any{
+		"name":                 project.Name,
+		"slug":                 project.Slug,
+		"description":          project.Description,
+		"enabled":              project.Enabled,
+		"spa_fallback_enabled": project.SPAFallbackEnabled,
+		"spa_fallback_path":    project.SPAFallbackPath,
+		"api_proxy_enabled":    project.APIProxyEnabled,
+		"api_proxy_path":       project.APIProxyPath,
+		"api_proxy_pass":       project.APIProxyPass,
+		"api_proxy_rewrite":    project.APIProxyRewrite,
+		"root_dir":             project.RootDir,
+		"entry_file":           project.EntryFile,
+	}).Error; err != nil {
+		if isUniqueConstraintError(err) {
+			return nil, errors.New(errPagesSlugExists)
+		}
+		return nil, err
+	}
+	return buildProjectView(ctx, project)
+}
+
+// DeleteProject 删除 Pages 项目。
+func DeleteProject(ctx context.Context, id uint) error {
+	project, err := model.GetPagesProjectByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	routeCount, err := model.CountProxyRoutesByPagesProjectID(ctx, project.ID)
+	if err != nil {
+		return err
+	}
+	if routeCount > 0 {
+		return errors.New(errPagesDeleteReferenced)
+	}
+	deployments, err := model.ListPagesDeployments(ctx, project.ID)
+	if err != nil {
+		return err
+	}
+	return db.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Where(
+			"deployment_id IN (?)",
+			tx.Model(&model.PagesDeployment{}).Select("id").Where("project_id = ?", project.ID),
+		).Delete(&model.PagesDeploymentFile{}).Error; err != nil {
+			return err
+		}
+		if err := tx.Where("project_id = ?", project.ID).Delete(&model.PagesDeployment{}).Error; err != nil {
+			return err
+		}
+		if err := tx.Delete(project).Error; err != nil {
+			return err
+		}
+		for _, deployment := range deployments {
+			_ = os.Remove(deployment.ArtifactPath)
+		}
+		return nil
+	})
+}
+
+// ListProjectDeployments 列出项目的全部部署。
+func ListProjectDeployments(ctx context.Context, projectID uint) ([]DeploymentView, error) {
+	if _, err := model.GetPagesProjectByID(ctx, projectID); err != nil {
+		return nil, err
+	}
+	deployments, err := model.ListPagesDeployments(ctx, projectID)
+	if err != nil {
+		return nil, err
+	}
+	views := make([]DeploymentView, 0, len(deployments))
+	for _, deployment := range deployments {
+		views = append(views, buildDeploymentView(&deployment))
+	}
+	return views, nil
+}
+
+// ListDeploymentFiles 列出部署文件清单。
+func ListDeploymentFiles(ctx context.Context, deploymentID uint) ([]DeploymentFileView, error) {
+	if _, err := model.GetPagesDeploymentByID(ctx, deploymentID); err != nil {
+		return nil, err
+	}
+	files, err := model.ListPagesDeploymentFiles(ctx, deploymentID)
+	if err != nil {
+		return nil, err
+	}
+	views := make([]DeploymentFileView, 0, len(files))
+	for _, file := range files {
+		views = append(views, DeploymentFileView{
+			ID:           file.ID,
+			DeploymentID: file.DeploymentID,
+			Path:         file.Path,
+			Size:         file.Size,
+			Checksum:     file.Checksum,
+			CreatedAt:    file.CreatedAt,
+		})
+	}
+	return views, nil
+}
+
+// UploadDeployment 上传 Pages 部署包。
+func UploadDeployment(ctx context.Context, projectID uint, fileHeader *multipart.FileHeader, createdBy string) (*DeploymentView, error) {
+	project, err := model.GetPagesProjectByID(ctx, projectID)
+	if err != nil {
+		return nil, err
+	}
+	if fileHeader == nil {
+		return nil, errors.New(errPagesPackageMissing)
+	}
+	if !strings.EqualFold(filepath.Ext(fileHeader.Filename), ".zip") {
+		return nil, errors.New(errPagesPackageNotZip)
+	}
+	rootDir, err := validateAndNormalizePagesRootDir(project.RootDir)
+	if err != nil {
+		return nil, err
+	}
+	entryFile := normalizePagesEntryFile(project.EntryFile)
+	tempPath, checksum, err := persistPagesUploadTemp(fileHeader)
+	if err != nil {
+		return nil, err
+	}
+	defer os.Remove(tempPath)
+	manifest, err := inspectPagesZip(tempPath, rootDir, entryFile)
+	if err != nil {
+		return nil, err
+	}
+	artifactPath, err := pagesArtifactPath(project.Slug, checksum)
+	if err != nil {
+		return nil, err
+	}
+	if err = os.MkdirAll(filepath.Dir(artifactPath), 0o755); err != nil {
+		return nil, fmt.Errorf("创建 Pages 存储目录失败: %w", err)
+	}
+	if err = copyFile(tempPath, artifactPath); err != nil {
+		return nil, err
+	}
+	deployment := &model.PagesDeployment{}
+	err = db.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		var maxNumber int
+		if err := tx.Model(&model.PagesDeployment{}).
+			Where("project_id = ?", project.ID).
+			Select("COALESCE(MAX(deployment_number), 0)").
+			Scan(&maxNumber).Error; err != nil {
+			return err
+		}
+		deployment = &model.PagesDeployment{
+			ProjectID:        project.ID,
+			DeploymentNumber: maxNumber + 1,
+			Checksum:         checksum,
+			Status:           model.PagesDeploymentStatusUploaded,
+			ArtifactPath:     artifactPath,
+			FileCount:        manifest.FileCount,
+			TotalSize:        manifest.TotalSize,
+			CreatedBy:        strings.TrimSpace(createdBy),
+		}
+		if err := tx.Create(deployment).Error; err != nil {
+			return err
+		}
+		for index := range manifest.Files {
+			manifest.Files[index].DeploymentID = deployment.ID
+		}
+		if len(manifest.Files) > 0 {
+			if err := tx.Create(&manifest.Files).Error; err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		_ = os.Remove(artifactPath)
+		return nil, err
+	}
+	view := buildDeploymentView(deployment)
+	return &view, nil
+}
+
+// ActivateDeployment 激活 Pages 部署。
+func ActivateDeployment(ctx context.Context, projectID uint, deploymentID uint) (*View, error) {
+	project, err := model.GetPagesProjectByID(ctx, projectID)
+	if err != nil {
+		return nil, err
+	}
+	deployment, err := model.GetPagesDeploymentByID(ctx, deploymentID)
+	if err != nil {
+		return nil, err
+	}
+	if deployment.ProjectID != project.ID {
+		return nil, errors.New(errPagesDeploymentMismatch)
+	}
+	now := time.Now()
+	if err = db.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Model(&model.PagesDeployment{}).
+			Where("project_id = ?", project.ID).
+			Update("status", model.PagesDeploymentStatusUploaded).Error; err != nil {
+			return err
+		}
+		if err := tx.Model(deployment).Updates(map[string]any{
+			"status":       model.PagesDeploymentStatusActive,
+			"activated_at": &now,
+		}).Error; err != nil {
+			return err
+		}
+		return tx.Model(project).Updates(map[string]any{
+			"active_deployment_id": deployment.ID,
+		}).Error
+	}); err != nil {
+		return nil, err
+	}
+	return GetProject(ctx, project.ID)
+}
+
+// DeleteDeployment 删除 Pages 部署。
+func DeleteDeployment(ctx context.Context, projectID uint, deploymentID uint) error {
+	project, err := model.GetPagesProjectByID(ctx, projectID)
+	if err != nil {
+		return err
+	}
+	deployment, err := model.GetPagesDeploymentByID(ctx, deploymentID)
+	if err != nil {
+		return err
+	}
+	if deployment.ProjectID != project.ID {
+		return errors.New(errPagesDeploymentMismatch)
+	}
+	if project.ActiveDeploymentID != nil && *project.ActiveDeploymentID == deployment.ID {
+		return errors.New(errPagesDeleteActiveDeploy)
+	}
+	return db.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Where("deployment_id = ?", deployment.ID).Delete(&model.PagesDeploymentFile{}).Error; err != nil {
+			return err
+		}
+		if err := tx.Delete(deployment).Error; err != nil {
+			return err
+		}
+		_ = os.Remove(deployment.ArtifactPath)
+		return nil
+	})
+}
+
+func buildProject(existing *model.PagesProject, input Input) (*model.PagesProject, error) {
+	name := strings.TrimSpace(input.Name)
+	if name == "" {
+		return nil, errors.New(errPagesNameRequired)
+	}
+	slug := normalizePagesSlug(input.Slug)
+	if slug == "" {
+		slug = normalizePagesSlug(name)
+	}
+	if !pagesSlugPattern.MatchString(slug) {
+		return nil, errors.New(errPagesSlugInvalid)
+	}
+	if existing == nil {
+		existing = &model.PagesProject{}
+	}
+	existing.Name = name
+	existing.Slug = slug
+	existing.Description = strings.TrimSpace(input.Description)
+	existing.Enabled = input.Enabled
+	existing.SPAFallbackEnabled = input.SPAFallbackEnabled
+	fallbackPath, err := normalizePagesFallbackPath(input.SPAFallbackPath)
+	if err != nil {
+		return nil, err
+	}
+	existing.SPAFallbackPath = fallbackPath
+
+	existing.APIProxyEnabled = input.APIProxyEnabled
+	apiProxyPath := strings.TrimSpace(input.APIProxyPath)
+	apiProxyPass := strings.TrimSpace(input.APIProxyPass)
+	apiProxyRewrite := strings.TrimSpace(input.APIProxyRewrite)
+
+	if existing.APIProxyEnabled {
+		if apiProxyPath == "" {
+			return nil, errors.New(errPagesAPIProxyPathRequired)
+		}
+		if !strings.HasPrefix(apiProxyPath, "/") {
+			return nil, errors.New(errPagesAPIProxyPathPrefix)
+		}
+		if apiProxyPass == "" {
+			return nil, errors.New(errPagesAPIProxyPassRequired)
+		}
+		parsedURL, err := url.Parse(apiProxyPass)
+		if err != nil || (parsedURL.Scheme != "http" && parsedURL.Scheme != "https") || parsedURL.Host == "" {
+			return nil, errors.New(errPagesAPIProxyPassInvalid)
+		}
+	}
+	existing.APIProxyPath = apiProxyPath
+	existing.APIProxyPass = apiProxyPass
+	existing.APIProxyRewrite = apiProxyRewrite
+
+	rootDir, err := validateAndNormalizePagesRootDir(input.RootDir)
+	if err != nil {
+		return nil, err
+	}
+	existing.RootDir = rootDir
+	existing.EntryFile = normalizePagesEntryFile(input.EntryFile)
+
+	return existing, nil
+}
+
+func buildProjectView(ctx context.Context, project *model.PagesProject) (*View, error) {
+	if project == nil {
+		return nil, errors.New(errPagesProjectNotFound)
+	}
+	view := &View{
+		ID:                 project.ID,
+		Name:               project.Name,
+		Slug:               project.Slug,
+		Description:        project.Description,
+		Enabled:            project.Enabled,
+		SPAFallbackEnabled: project.SPAFallbackEnabled,
+		SPAFallbackPath:    normalizeStoredPagesFallbackPath(project.SPAFallbackPath),
+		APIProxyEnabled:    project.APIProxyEnabled,
+		APIProxyPath:       project.APIProxyPath,
+		APIProxyPass:       project.APIProxyPass,
+		APIProxyRewrite:    project.APIProxyRewrite,
+		RootDir:            project.RootDir,
+		EntryFile:          project.EntryFile,
+		ActiveDeploymentID: project.ActiveDeploymentID,
+		CreatedAt:          project.CreatedAt,
+		UpdatedAt:          project.UpdatedAt,
+	}
+	count, err := model.CountPagesDeploymentsByProjectID(ctx, project.ID)
+	if err != nil {
+		return nil, err
+	}
+	view.DeploymentCount = count
+	if project.ActiveDeploymentID != nil && *project.ActiveDeploymentID != 0 {
+		deployment, err := model.GetPagesDeploymentByID(ctx, *project.ActiveDeploymentID)
+		if err == nil {
+			active := buildDeploymentView(deployment)
+			view.ActiveDeployment = &active
+		}
+	}
+	return view, nil
+}
+
+func buildDeploymentView(deployment *model.PagesDeployment) DeploymentView {
+	if deployment == nil {
+		return DeploymentView{}
+	}
+	return DeploymentView{
+		ID:               deployment.ID,
+		ProjectID:        deployment.ProjectID,
+		DeploymentNumber: deployment.DeploymentNumber,
+		Checksum:         deployment.Checksum,
+		Status:           deployment.Status,
+		FileCount:        deployment.FileCount,
+		TotalSize:        deployment.TotalSize,
+		CreatedBy:        deployment.CreatedBy,
+		CreatedAt:        deployment.CreatedAt,
+		ActivatedAt:      deployment.ActivatedAt,
+	}
+}

Wavelet/internal/apps/openflare/pages/logics_test.go

@@ -0,0 +1,84 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package pages
+
+import (
+	"context"
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/glebarez/sqlite"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+)
+
+func setupPagesTestDB(t *testing.T) func() {
+	t.Helper()
+
+	sqliteDB, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{
+		DisableForeignKeyConstraintWhenMigrating: true,
+	})
+	require.NoError(t, err)
+	require.NoError(t, sqliteDB.AutoMigrate(
+		&model.PagesProject{},
+		&model.PagesDeployment{},
+		&model.PagesDeploymentFile{},
+	))
+
+	db.SetDB(sqliteDB)
+	return func() {
+		db.SetDB(nil)
+	}
+}
+
+func TestCreateProject(t *testing.T) {
+	cleanup := setupPagesTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	project, err := CreateProject(ctx, Input{
+		Name:               "Marketing Site",
+		Slug:               "marketing-site",
+		Description:        "public site",
+		Enabled:            true,
+		SPAFallbackEnabled: true,
+		SPAFallbackPath:    "/index.html",
+		EntryFile:          "index.html",
+	})
+	require.NoError(t, err)
+	assert.NotZero(t, project.ID)
+	assert.Equal(t, "Marketing Site", project.Name)
+	assert.Equal(t, "marketing-site", project.Slug)
+	assert.Equal(t, "public site", project.Description)
+	assert.True(t, project.Enabled)
+	assert.True(t, project.SPAFallbackEnabled)
+	assert.Equal(t, "/index.html", project.SPAFallbackPath)
+	assert.Equal(t, "index.html", project.EntryFile)
+	assert.Equal(t, int64(0), project.DeploymentCount)
+
+	_, err = CreateProject(ctx, Input{
+		Name: "Duplicate Slug",
+		Slug: "marketing-site",
+	})
+	require.Error(t, err)
+	assert.Equal(t, errPagesSlugExists, err.Error())
+}
+
+func TestCreateProjectRejectsUnsafeFallbackPath(t *testing.T) {
+	cleanup := setupPagesTestDB(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	_, err := CreateProject(ctx, Input{
+		Name:               "Unsafe Fallback",
+		Slug:               "unsafe-fallback",
+		Enabled:            true,
+		SPAFallbackEnabled: true,
+		SPAFallbackPath:    "/index.html; proxy_pass http://evil",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "回退路径")
+}

Wavelet/internal/apps/openflare/pages/routers.go

@@ -0,0 +1,180 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package pages
+
+import (
+	"errors"
+	"strconv"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/openflare/compat"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+func handleLogicError(c *gin.Context, err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		compat.Fail(c, errPagesProjectNotFound)
+		return true
+	}
+	compat.Fail(c, err.Error())
+	return true
+}
+
+func deploymentIDParam(c *gin.Context) (uint, bool) {
+	raw := c.Param("deployment_id")
+	if raw == "" {
+		compat.Fail(c, "无效的 ID")
+		return 0, false
+	}
+	id64, err := strconv.ParseUint(raw, 10, 64)
+	if err != nil || id64 == 0 {
+		compat.Fail(c, "无效的 ID")
+		return 0, false
+	}
+	return uint(id64), true
+}
+
+// ListProjectsHandler 列出全部 Pages 项目。
+func ListProjectsHandler(c *gin.Context) {
+	projects, err := ListProjects(c.Request.Context())
+	if handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, projects)
+}
+
+// GetProjectHandler 获取 Pages 项目详情。
+func GetProjectHandler(c *gin.Context) {
+	id, ok := compat.IDParam(c)
+	if !ok {
+		return
+	}
+	project, err := GetProject(c.Request.Context(), id)
+	if handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, project)
+}
+
+// CreateProjectHandler 创建 Pages 项目。
+func CreateProjectHandler(c *gin.Context) {
+	var input Input
+	if !compat.BindJSON(c, &input) {
+		return
+	}
+	project, err := CreateProject(c.Request.Context(), input)
+	if handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, project)
+}
+
+// UpdateProjectHandler 更新 Pages 项目。
+func UpdateProjectHandler(c *gin.Context) {
+	id, ok := compat.IDParam(c)
+	if !ok {
+		return
+	}
+	var input Input
+	if !compat.BindJSON(c, &input) {
+		return
+	}
+	project, err := UpdateProject(c.Request.Context(), id, input)
+	if handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, project)
+}
+
+// DeleteProjectHandler 删除 Pages 项目。
+func DeleteProjectHandler(c *gin.Context) {
+	id, ok := compat.IDParam(c)
+	if !ok {
+		return
+	}
+	if err := DeleteProject(c.Request.Context(), id); handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, nil)
+}
+
+// ListDeploymentsHandler 列出项目的全部部署。
+func ListDeploymentsHandler(c *gin.Context) {
+	id, ok := compat.IDParam(c)
+	if !ok {
+		return
+	}
+	deployments, err := ListProjectDeployments(c.Request.Context(), id)
+	if handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, deployments)
+}
+
+// UploadDeploymentHandler 上传 Pages 部署包。
+func UploadDeploymentHandler(c *gin.Context) {
+	id, ok := compat.IDParam(c)
+	if !ok {
+		return
+	}
+	file, err := c.FormFile("package")
+	if err != nil {
+		compat.Fail(c, errPagesPackageMissing)
+		return
+	}
+	deployment, err := UploadDeployment(c.Request.Context(), id, file, "")
+	if handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, deployment)
+}
+
+// ActivateDeploymentHandler 激活 Pages 部署。
+func ActivateDeploymentHandler(c *gin.Context) {
+	projectID, ok := compat.IDParam(c)
+	if !ok {
+		return
+	}
+	deploymentID, ok := deploymentIDParam(c)
+	if !ok {
+		return
+	}
+	project, err := ActivateDeployment(c.Request.Context(), projectID, deploymentID)
+	if handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, project)
+}
+
+// DeleteDeploymentHandler 删除 Pages 部署。
+func DeleteDeploymentHandler(c *gin.Context) {
+	projectID, ok := compat.IDParam(c)
+	if !ok {
+		return
+	}
+	deploymentID, ok := deploymentIDParam(c)
+	if !ok {
+		return
+	}
+	if err := DeleteDeployment(c.Request.Context(), projectID, deploymentID); handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, nil)
+}
+
+// ListDeploymentFilesHandler 列出部署文件清单。
+func ListDeploymentFilesHandler(c *gin.Context) {
+	deploymentID, ok := deploymentIDParam(c)
+	if !ok {
+		return
+	}
+	files, err := ListDeploymentFiles(c.Request.Context(), deploymentID)
+	if handleLogicError(c, err) {
+		return
+	}
+	compat.OK(c, files)
+}