Total Pageviews

Saturday, 14 March 2026

基于nodejs的相册程序Afilmory


A modern, high-performance photo gallery platform for photographers

Official SaaS • Documentation • Live Examples • Self-Hosting

Afilmory (/əˈfɪlməri/, "uh-FIL-muh-ree") is a comprehensive photo gallery solution that combines Auto Focus (AF), Aperture (light control), Film (vintage medium), and Memory (captured moments). Built with React + TypeScript, it offers automatic photo synchronization from multiple storage sources, high-performance WebGL rendering, and professional EXIF metadata display.

🚀 Quick Start

Option 1: Official SaaS (Recommended)

👉 Get Started at afilmory.art - Zero setup, live in minutes!

The easiest way to create your photo gallery. No deployment, no servers, no maintenance required.

Why Choose SaaS?

  • ✅ Zero Configuration - Sign up and go live immediately
  • ✅ Live CMS - Edit photos, titles, and metadata in real-time
  • ✅ Custom Domains - Bind your own domain with DNS verification
  • ✅ Auto Updates - Always running the latest features
  • ✅ Managed Infrastructure - We handle scaling, backups, and maintenance

Start Your Gallery Now →

Option 2: Self-Hosting

For developers who need full control over their deployment:

Docker (Recommended)

# See our Docker deployment guide
https://github.com/Afilmory/docker

Manual Installation

# 1. Clone and install
git clone https://github.com/Afilmory/Afilmory.git
cd Afilmory
pnpm install

# 2. Configure
cp config.example.json config.json
cp builder.config.default.ts builder.config.ts
# Edit both files with your settings

# 3. Build manifest and thumbnails
pnpm run build:manifest

# 4. Start the application
pnpm dev

For detailed self-hosting instructions, see DEVELOPMENT.md and Documentation.

📸 Live Galleries

See Afilmory in action:

✨ Features

Core Capabilities

  • 🖼️ High-Performance WebGL Renderer - Custom WebGL image viewer with smooth zoom, pan, and gesture support
  • 📱 Responsive Masonry Layout - Powered by Masonic, adapts seamlessly to any screen size
  • 🎨 Modern UI/UX - Built with Tailwind CSS and Radix UI for accessibility and aesthetics
  • ⚡ Incremental Sync - Smart change detection processes only new or modified photos
  • 🌐 Internationalization - Multi-language support with i18next
  • 🔗 Social Sharing - OpenGraph metadata for rich social media previews

Image Processing

  • 🔄 Format Support - Automatic conversion of HEIC/HEIF and TIFF formats
  • 🖼️ Smart Thumbnails - Multi-size thumbnail generation for optimized loading
  • 📊 Complete EXIF Display - Camera model, focal length, aperture, ISO, and more
  • 🌈 Blurhash Placeholders - Elegant progressive loading experience
  • 📱 Live Photos - Detection and display of iPhone Live Photos
  • ☀️ HDR Images - Full HDR image support
  • 🎛️ Fujifilm Recipes - Display Fujifilm film simulation settings

Advanced Features

  • 🗂️ Multi-Storage Support - S3-compatible storage, GitHub, Eagle, and local file system
  • 🏷️ File System Tags - Auto-generated tags based on directory structure
  • ⚡ Concurrent Processing - Multi-process/multi-thread support for fast builds
  • 🗺️ Interactive Map - Geographic visualization with GPS coordinates using MapLibre
  • 🔍 Fullscreen Viewer - Immersive image viewing with gesture controls
  • 📷 Share & Embed - Share images to social media or embed in your website

🏗️ Architecture

Monorepo Structure

afilmory/
├── apps/
│   ├── web/              # React SPA (Vite + React Router 7)
│   ├── ssr/              # Next.js SSR wrapper for SEO/OG
│   ├── docs/             # Documentation site (VitePress)
├── be/                   # Backend services (Hono-based)
│   ├── apps/
│   │   ├── core/         # Core API server
│   │   ├── dashboard/    # Admin dashboard backend
│   │   └── oauth-gateway/# OAuth authentication gateway
│   └── packages/
│       ├── framework/    # Hono enterprise framework
│       ├── db/           # Database schemas (Drizzle ORM)
│       ├── redis/        # Redis client
│       └── websocket/    # WebSocket gateway
├── packages/
│   ├── builder/          # Photo processing pipeline
│   ├── webgl-viewer/     # WebGL image viewer component
│   ├── ui/               # Shared UI components
│   ├── hooks/            # React hooks library
│   ├── sdk/              # API client SDK
│   ├── utils/            # Utility functions
│   └── data/             # Shared data types
└── plugins/              # Builder plugins

Frontend Stack

  • React 19 - Latest React with Compiler
  • TypeScript - Full type safety
  • Vite - Lightning-fast build tool
  • React Router 7 - Modern routing
  • Tailwind CSS - Utility-first CSS framework
  • Radix UI - Accessible component primitives
  • Jotai - Atomic state management
  • TanStack Query - Data fetching and caching
  • i18next - Internationalization

Backend Stack

  • Hono - Ultra-fast web framework
  • Drizzle ORM - Type-safe database toolkit
  • PostgreSQL - Primary database
  • Redis - Caching and pub/sub
  • WebSocket - Real-time communication

Build Pipeline

  • Node.js - Server-side runtime
  • Sharp - High-performance image processing
  • AWS SDK - S3 storage operations
  • Worker Threads/Cluster - Parallel processing
  • EXIF-Reader - Metadata extraction

Storage Adapters

Designed with adapter pattern for flexibility:

  • S3-Compatible - AWS S3, MinIO, Backblaze B2, Alibaba Cloud OSS
  • GitHub - Use GitHub repository as storage
  • Eagle - Import from Eagle app library
  • Local File System - For development and testing

🛠️ Development

Prerequisites

  • Node.js 18+
  • pnpm 10+
  • TypeScript 5.9+

Project Setup

# Install dependencies
pnpm install

# Copy configuration files
cp config.example.json config.json
cp builder.config.default.ts builder.config.ts

# Set up environment variables
cp .env.template .env
# Edit .env with your credentials

Common Commands

# Development
pnpm dev                    # Start web + SSR
pnpm dev:be                 # Start backend services
pnpm --filter web dev       # Web app only
pnpm --filter @afilmory/ssr dev  # SSR only

# Build
pnpm build                  # Build production web app
pnpm build:manifest         # Generate photo manifest (incremental)
pnpm build:manifest -- --force  # Full rebuild

# Documentation
pnpm docs:dev               # Start docs dev server
pnpm docs:build             # Build documentation

# Code Quality
pnpm lint                   # Lint and fix
pnpm format                 # Format code
pnpm type-check             # Type checking

Configuration Files

config.json - Site presentation config:

{
  "name": "My Gallery",
  "title": "My Photography",
  "description": "Capturing beautiful moments",
  "url": "https://gallery.example.com",
  "accentColor": "#007bff",
  "author": {
    "name": "Your Name",
    "url": "https://example.com",
    "avatar": "https://example.com/avatar.jpg"
  },
  "social": {
    "github": "username",
    "twitter": "username"
  },
  "map": ["maplibre"],
  "mapStyle": "builtin",
  "mapProjection": "mercator"
}

builder.config.ts - Photo processing config:

import { defineBuilderConfig } from '@afilmory/builder'

export default defineBuilderConfig(() => ({
  storage: {
    provider: 's3',
    bucket: 'my-photos',
    region: 'us-east-1',
    // ... other S3 settings
  },
  system: {
    processing: {
      defaultConcurrency: 10,
      enableLivePhotoDetection: true,
    },
    observability: {
      showProgress: true,
      showDetailedStats: true,
    },
  },
}))

🔌 Extending Afilmory

Custom Storage Provider

Implement the StorageProvider interface:

import { StorageProvider } from '@afilmory/builder'

class MyStorageProvider implements StorageProvider {
  async getFile(key: string): Promise<Buffer | null> {
    // Your implementation
  }

  async listImages(): Promise<StorageObject[]> {
    // Your implementation
  }

  // ... other required methods
}

Custom Builder Plugin

Create a plugin for the build pipeline:

import { BuilderPlugin } from '@afilmory/builder'

export const myPlugin = (): BuilderPlugin => ({
  name: 'my-plugin',
  async onBeforeBuild(context) {
    // Pre-build hook
  },
  async onAfterBuild(context) {
    // Post-build hook
  },
})

📚 Documentation

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests and linting (pnpm test && pnpm lint)
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

📄 License

Attribution Network License (ANL) v1.0 © 2025 Afilmory Team

See LICENSE for more details.

🔗 Links

from  https://github.com/Afilmory/afilmory

Posted by at
Labels:

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)