DOCSEARCHbyAlgolia
Submit Docs

PixelPunk Documentation

repository·main·Indexed 19 days ago

https://github.com/cooperjiang/pixelpunk

A full-stack intelligent image hosting and resource management platform featuring AI-driven automation, vector search, and robust access controls. The documentation covers deployment via CLI and interactive menus, environment management (Test and Production), and a plugin-based storage adapter architecture supporting Local, COS, OSS, and S3-compatible providers.

Tokens
56.6K
Snippets
187
Records
245
Agent score
66%

What's inside pixelpunk

  1. Overview of PixelPunk Storage Adapter Architecture

    main

    PixelPunk uses a plugin-based storage adapter architecture to support multiple backends, including local storage and various cloud services. All adapters implement a unified StorageAdapter interface, allowing for seamless switching between storage providers without changing business logic.

    Key design principles include:

    • Unified Interface: All adapters follow the same specification.
    • Plugin-based: Supports dynamic loading and switching of backends.
    • Configuration-driven: Parameters are managed via configuration files.
    • Standardized Error Handling: Consistent error types across all adapters.

  2. Standardize object keys and URLs with pkg/storage/path

    main
    The pkg/storage/path package provides tools to standardize object keys and URLs. This prevents manual path concatenation errors and ensures consistent path formatting across the application. Use these tools to convert between full URLs, logical paths, and standardized object keys.

  3. Configure Object Key paths for multi-tenancy

    main

    PixelPunk uses a standardized object key structure to ensure tenant isolation and support both logged-in users and guests.

    Key Patterns

    • Logged-in Users: Uses an alias and shard directory.
      • Original: images/<shard>/<alias>/(folder)/file
      • Thumbnail: thumbnails/<shard>/<alias>/(folder)/file
    • Guests (userID=0): Uses a fixed directory.
      • Original: images/guest/file
      • Thumbnail: thumbnails/guest/file

    Best Practices

    Do not manually concatenate strings to build object keys. Instead, use the provided utility methods:

    • tenant.BuildObjectKey(userID, folder, file)
    • tenant.BuildThumbObjectKey(userID, folder, file)
    • path.EnsureObjectKey(userID, input, isThumb) (use this when the input is a logical path or a full URL).

  4. Manage Object Keys using the path and tenant utilities

    main

    Do not manually construct object keys. Use the provided utilities to ensure consistent pathing and sharding.

    Key Construction

    • For Users: Keys are constructed using a stable alias and a two-digit shard.
      • Original images: images/<shard>/<alias>/(folder)/file
      • Thumbnails: thumbnails/<shard>/<alias>/(folder)/file
    • For Guests (userID=0): Uses a simplified fixed directory.
      • Original images: images/guest/file
      • Thumbnails: thumbnails/guest/file

    Recommended Methods

    • tenant.BuildObjectKey(userID, folder, file): Build a standard object key.
    • tenant.BuildThumbObjectKey(userID, folder, file): Build a thumbnail object key.
    • path.EnsureObjectKey(userID, input, isThumb): Converts a logical path or URL into a valid object key.
    • path.CleanObjectPath(p): Cleans slashes and redundancy from an object key.
    • path.ExtractObjectPathFromURL(s): Extracts the object key from a full URL.
    • path.IsHTTPURL(s): Checks if a string is an http or https URL.

  5. Understand the PixelPunk performance and caching architecture

    main

    PixelPunk employs a multi-layered caching strategy to optimize request handling and reduce database load. The hierarchy is as follows:

    1. Browser Cache: Utilizes CDN for static assets.
    2. Redis Cache: Stores hot data including:
      • User sessions
      • Search results
      • Image metadata
    3. Database Query: The final layer involving MySQL (relational data) and Qdrant (vector data).

    When a cache miss occurs at any level, the system queries the database and subsequently writes the result back to the cache (cache warming) to optimize future requests.

    ┌─────────────────────────────────────────────────────────┐
│                      请求处理                            │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
              ┌──────────────────┐
              │  1. 浏览器缓存    │  静态资源 (CDN)
              └─────────┬────────┘
                        │ Miss
                        ▼
              ┌──────────────────┐
              │  2. Redis 缓存    │  热点数据
              │   • 用户会话      │
              │   • 搜索结果      │
              │   • 图片元数据    │
              └─────────┬────────┘
                        │ Miss
                        ▼
              ┌──────────────────┐
              │  3. 数据库查询    │  • MySQL
              │                  │  • Qdrant
              └─────────┬────────┘
                        │
                        ▼
              ┌──────────────────┐
              │  写入缓存         │  缓存预热
              └─────────┬────────┘
                        │
                        ▼
              ┌──────────────────┐
              │  返回数据         │
              └──────────────────┘

  6. Adhere to Frontend (Vue 3 + TypeScript) coding standards

    main

    Frontend code uses Vue 3 and TypeScript. Developers should follow these rules:

    • Use ESLint and Prettier for linting and formatting.
    • Use the <script setup> syntax for components.
    • Explicitly define types for Props and Emits.
    • Avoid using the any type.

    Example of a well-typed component:

    <script setup lang="ts">
import { ref } from 'vue'

interface Props {
  title: string
  count?: number
}

interface Emits {
  (e: 'update', value: number): void
}

const props = withDefaults(defineProps<Props>(), {
  count: 0
})

const emit = defineEmits<Emits>()
</script>

  7. Configure WebP version requirements

    main

    To use the WebP Version of the backend, your environment must meet the following requirements:

    1. Docker Environment

    • Mac: Docker Desktop or OrbStack.
    • Linux: Docker Engine.

    2. Required Docker Images

    The system requires the following images (which will be downloaded on the first run):

    • golang:1.23 (for the compilation environment)
    • ubuntu:22.04 (for the runtime environment)

    Note: Once the images are downloaded, you can perform completely offline builds.

  8. Understand the image upload and processing pipeline

    main

    When an image is uploaded to PixelPunk, it undergoes a rigorous 12-step automated pipeline to ensure quality, security, and searchability:

    1. Frontend Pre-processing: Client-side compression, size checks, and format validation.
    2. Server Reception: Handled via HTTP Multipart with temporary storage and security checks.
    3. Format Validation: MIME type detection, file header (magic number) verification, and malicious file interception.
    4. Basic Image Processing: Conversion to WebP, quality compression (85%), EXIF extraction, and color space conversion.
    5. Thumbnail Generation: Creation of Small (150x150), Medium (600x600), and Large (1200x1200) versions while maintaining aspect ratio.
    6. File Storage: Original and thumbnail storage with path generation and Hash-based deduplication.
    7. AI Image Analysis: Integration with Vision APIs for classification, object recognition, and scene detection.
    8. AI Smart Tagging: Automatic keyword extraction, tag generation, description text generation, and color theme analysis.
    9. NSFW Content Moderation: Detection of adult content, violence, and sensitive information.
    10. AI Vectorization: Generation of image embeddings using embedding models and storage in Qdrant for semantic indexing.
    11. Database Storage: Metadata is saved to MySQL, while vector data is saved to Qdrant.
    12. Post-processing: Generation of sharing links, triggering WebSocket notifications, updating user quotas, and logging operations.

  9. How the Intelligent Search Architecture works

    main

    PixelPunk employs a hybrid search strategy that combines traditional keyword matching with modern semantic vector search to provide high-relevance results.

    1. Keyword Search (MySQL): Handles exact matches for titles, tags, and descriptions, as well as full-text retrieval.
    2. Semantic Search (Qdrant): Uses vector similarity to understand user intent, support cross-language searches, and perform image-based similarity searches.
    3. Result Fusion: The system merges results from both engines using weight calculation, relevance ranking, deduplication, and pagination.
    4. Cache Optimization (Redis): Enhances performance by caching popular searches, result sets, and implementing prefetch strategies.

    This architecture allows users to search via text, semantics, images, tags, or combinations thereof.

    [Search Flow]
User Input -> (Keyword Search [MySQL] | Semantic Search [Qdrant]) 
             -> Result Fusion (Weighting/Ranking/Deduplication) 
             -> Cache Optimization (Redis) 
             -> Return Results (Images/Recommendations/Suggestions)

  10. How the Security Architecture protects requests

    main

    PixelPunk implements a multi-layered security model to protect the application and its data. Every user request passes through the following security checkpoints in order:

    1. SSL/TLS: Ensures encrypted transmission via HTTPS.
    2. CORS Check: Validates cross-origin requests.
    3. Rate Limiting: Prevents abuse and brute-force attacks.
    4. JWT Verification: Authenticates user identity using JSON Web Tokens.
    5. Permission Check: Enforces Role-Based Access Control (RBAC).
    6. Parameter Validation: Filters and validates all incoming input.
    7. Business Logic: Executes secure business operations.
    8. Audit Logging: Tracks and records operations for traceability.
    [Security Layers]
Request -> SSL/TLS -> CORS -> Rate Limit -> JWT -> RBAC -> Parameter Validation -> Business Logic -> Audit Log -> Response

  11. Understand the PixelPunk storage abstraction architecture

    main

    The pkg/storage module provides a unified abstraction for storage, covering adapter registration, selection, scheduling, path rules, and URL generation. This architecture allows adding new third-party storage channels easily while maintaining consistent behavior across the system.

    Core Workflow

    • Upload: storage.Storage.Upload $\rightarrow$ manager.StorageManager.Upload $\rightarrow$ adapter.Upload
    • Delete: storage.Storage.Delete $\rightarrow$ manager.Delete $\rightarrow$ adapter.Delete
    • URL Generation: storage.Storage.GetURL/GetFullURL/GetCDNURL $\rightarrow$ manager $\rightarrow$ adapter.GetURL/...
    • Base64 Encoding: Handled centrally at the manager layer. Adapters only need to implement ReadFile; the manager handles the encoding to ensure consistency.

  12. Understand the asynchronous image upload processing flow

    main

    To ensure high responsiveness, PixelPunk handles heavy image processing tasks asynchronously using a Redis-backed queue and worker pattern:

    1. Immediate Response: Upon receiving an upload request, the system saves the file and immediately returns a success response to the user.
    2. Task Queuing: The request is added to a Redis Queue for background processing.
    3. Parallel Worker Execution: Multiple workers concurrently handle tasks such as:
      • Thumbnail generation
      • AI analysis
      • Vectorization
    4. Completion Notification: Once processing is finished, the system notifies the user via WebSocket.
    ┌─────────────────────────────────────────────────────────┐
│                    图片上传请求                          │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
              ┌──────────────────┐
              │  1. 快速响应      │  立即返回上传成功
              │     (文件保存)    │
              └─────────┬────────┘
                        │
                        ▼
              ┌──────────────────┐
              │  2. 任务入队      │  Redis Queue
              │   • 缩略图生成    │
              │   • AI 分析       │
              │   • 向量化        │
              └─────────┬────────┘
                        │
           ┌────────────┼────────────┐
           │            │            │
           ▼            ▼            ▼
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │ Worker 1 │ │ Worker 2 │ │ Worker 3 │  并行处理
    └─────┬────┘ └─────┬────┘ └─────┬────┘
          │            │            │
          └────────────┼────────────┘
                       │
                       ▼
              ┌──────────────────┐
              │  3. 处理完成      │  WebSocket 通知用户
              └──────────────────┘