Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
ChronoFrame
Languages: English | 中文
ChronoFrame 是一个可以自行部署的照片画廊。上传照片后,应用会提取 EXIF、生成预览并整理拍摄地点;访客可以按时间、相册或地图浏览,也能查看大图和播放实况照片。
✨ 功能
- 照片浏览:瀑布流、筛选与排序、WebGL 大图缩放和分块渲染、照片直方图、原图下载与分享预览。
- 动态照片:支持 Apple Live Photo 和 Motion Photo,照片与视频自动配对,支持悬停或长按播放。
- 相册:组织照片、调整相册及照片顺序,支持隐藏相册和密码相册。
- 后台管理:批量上传、编辑元数据、评分、批量下载和重新索引;查看处理队列、实时日志与最近活动。
- 存储:支持本地文件系统、S3 兼容对象存储和 OpenList,可在后台管理存储方案和 CDN 地址。
- 地图与地点:MapLibre / Mapbox 地图,反向地理编码和可选的地名语言。
- 设置向导:首次启动在网页中创建管理员、设置站点与存储;日常设置在后台修改,无需维护一长串环境变量。
- 多语言与登录:后台语言切换,邮箱密码登录,可选 GitHub OAuth;支持自定义统计脚本和上传隐私设置。
☁️ ChronoFrame Cloud
ChronoFrame Cloud 无需部署或维护服务器。在官网注册或登录账号,创建画廊,即可在浏览器中上传和管理照片。
🐳 部署
推荐使用 Docker。创建 docker-compose.yml:
services:
chronoframe:
image: ghcr.io/hoshinosuzumi/chronoframe:latest
container_name: chronoframe
restart: unless-stopped
ports:
- '3000:3000'
volumes:
- ./data:/app/data
docker compose up -d
也可以使用 Docker Hub 镜像 hoshinosuzumi/chronoframe:latest。需要固定版本时,将标签换成 v1.0.0。
直接使用 Docker 启动:
docker run -d --name chronoframe --restart unless-stopped \
-p 3000:3000 -v "$(pwd)/data:/app/data" \
ghcr.io/hoshinosuzumi/chronoframe:latest
打开 http://localhost:3000,按设置向导创建管理员并选择存储。使用本地存储时填写 /app/data/storage。地图令牌可以稍后补充,不影响先完成部署和上传照片。
请保留 ./data 挂载,其中包含数据库、设置、会话密钥,以及采用上述路径时的本地照片。
部署到公网时使用 HTTPS。反向代理、数据备份和旧版迁移见快速开始和升级指南。
📖 使用
登录后进入 /dashboard 上传和整理照片。上传完成后,任务队列会继续处理 EXIF、缩略图、地点和实况照片,失败任务可以查看原因并重试。
Apple Live Photo 的图片和 MOV 文件需要相同文件名,例如 IMG_1234.heic 和 IMG_1234.mov,上传顺序不限。照片支持 JPEG、PNG、WebP、GIF、BMP、TIFF、HEIC / HEIF 等格式。
密码相册限制的是通过 ChronoFrame 访问的内容。如果 S3、OpenList 或 CDN 提供公开的图片直链,需要同时管理外部服务的权限。详见日常使用。
📸 截图

🛠️ 开发
使用 Node.js 22 和项目指定的 pnpm 10.34.6:
corepack enable
pnpm install --frozen-lockfile
pnpm dev
打开 http://localhost:3000,通过向导完成本地初始化。本地存储可以使用 ./data/storage。
pnpm lint # Oxlint
pnpm fmt:check # Oxfmt
pnpm build:deps # 构建 WebGL 包
pnpm build # 构建应用
pnpm docs:build # 构建文档
修改数据库 schema 后,使用 pnpm db:generate 生成迁移并检查 SQL。仅启动项目时无需生成迁移。更多说明见贡献指南。
📄 许可证
ChronoFrame 默认采用 AGPL-3.0-only,包括 Self-hosted 与 SaaS 实现;
packages/contracts 和 packages/webgl-image 保留 MIT。适用范围、历史 MIT 权利及向 ChronoFrame
咨询商业授权的方式见 LICENSE 和 LICENSING.md。满足适用 AGPL 义务的收费托管是允许的。
🤝 贡献与交流
如发现疑似安全漏洞,请按照安全政策私下报告。
欢迎提交问题和 Pull Request。请说明问题、改动后的行为和验证结果;文档改动请同步维护中文和英文。
GitHub Issues · Discussions · Discord
🙏 致谢
感谢 Nuxt、Vue、Tailwind CSS、Drizzle ORM 及其他开源项目的维护者,也感谢参与测试、翻译和开发的贡献者。