ChronoFrame画廊部署教程
1. 拉取镜像
ChronoFrame 镜像托管在 GitHub Container Registry (GHCR) 和 Docker Hub，可根据网络情况选择：
# 从 GHCR 拉取（推荐）
docker pull ghcr.io/hoshinosuzumi/chronoframe:latest
# 或从 Docker Hub 拉取
docker pull hoshinosuzumi/chronoframe:latest
2. 配置环境变量
在执行部署命令的工作目录创建 .env 文件并配置必要参数，完整配置项可参考 官方文档。
# ===================== 核心必填项 =====================
# 初始管理员邮箱（必须配置，且需匹配登录用的GitHub账户邮箱）
CFRAME_ADMIN_EMAIL=your-admin@example.com
# 会话加密密码（必须配置，32位随机字符串，用于会话安全）
NUXT_SESSION_PASSWORD=你的32位随机字符串（如：8f9e7d6c5b4a3s2d1f8g9h7j6k5l4m3n2）
# 存储提供者（必须配置，可选值：local / s3 / openlist）
NUXT_STORAGE_PROVIDER=local
# ===================== 管理员可选配置 =====================
# 初始管理员用户名（可选，默认值：ChronoFrame）
CFRAME_ADMIN_NAME=管理员名称
# 初始管理员密码（可选，默认值：CF1234@!）
CFRAME_ADMIN_PASSWORD=你的管理员密码
# ===================== 站点信息（可选） =====================
# 应用标题（页面标题/导航栏显示）
NUXT_PUBLIC_APP_TITLE=ChronoFrame 个人画廊
# 应用口号（首页/页脚展示）
NUXT_PUBLIC_APP_SLOGAN=自部署、高性能的照片管理系统
# 应用作者名称
NUXT_PUBLIC_APP_AUTHOR=你的名字
# 应用头像URL（导航栏/首页展示）
NUXT_PUBLIC_APP_AVATAR_URL=https://xxx.com/avatar.png
# ===================== 颜色模式（可选） =====================
# 界面颜色模式偏好（可选值：light(亮色)/dark(暗色)/system(跟随系统)，默认：system）
NUXT_PUBLIC_COLOR_MODE_PREFERENCE=system
# ===================== 地图服务配置（可选，但建议配置） =====================
# 地图提供者（可选值：maplibre / mapbox，默认：maplibre）
NUXT_PUBLIC_MAP_PROVIDER=maplibre
# MapLibre 令牌（使用maplibre时必填，需从https://cloud.maptiler.com/获取）
NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=你的MapTiler令牌
# Mapbox 受限令牌（使用mapbox时必填，URL受限，用于地图渲染）
NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=你的Mapbox公网令牌（pk开头）
# Mapbox 无限制令牌（可选，用于反向地理编码，无URL限制）
NUXT_MAPBOX_ACCESS_TOKEN=你的Mapbox私网令牌（sk开头）
# 反向地理编码服务地址（可选，默认：https://nominatim.openstreetmap.org）
NUXT_NOMINATIM_BASE_URL=https://nominatim.openstreetmap.org
# ===================== 存储配置（根据NUXT_STORAGE_PROVIDER适配） =====================
# 1. 本地存储（NUXT_STORAGE_PROVIDER=local 时生效）
NUXT_PROVIDER_LOCAL_PATH=/app/data/storage # 容器内存储路径（宿主机映射需改-v参数）
# 2. S3兼容存储（NUXT_STORAGE_PROVIDER=s3 时生效）
NUXT_PROVIDER_S3_ENDPOINT=http://localhost:9000 # S3服务地址（如MinIO）
NUXT_PROVIDER_S3_BUCKET=chronoframe-dev # S3桶名称
NUXT_PROVIDER_S3_REGION=us-east-1 # S3区域
NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin # S3访问密钥
NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin # S3秘钥
NUXT_PROVIDER_S3_CDN_URL=https://cdn.aaa.com # 可选
# ===================== 开发环境专属配置（可选） =====================
# GitHub OAuth认证（开发环境登录用）
NUXT_OAUTH_GITHUB_CLIENT_ID=你的GitHub开发者客户端ID
NUXT_OAUTH_GITHUB_CLIENT_SECRET=你的GitHub开发者客户端秘钥
# 开启调试信息（开发环境用，生产环境建议关闭）
VITE_SHOW_DEBUG_INFO=true
# 可通过 IP 端口访问
NUXT_ALLOW_INSECURE_COOKIE=true
# 重复文件检测
NUXT_UPLOAD_DUPLICATE_CHECK_ENABLED=true
# 重复文件检测-skip（跳过模式）、warn（警告模式）、block（阻止模式）
NUXT_UPLOAD_DUPLICATE_CHECK_MODE=skip
3. 部署方式
方式一：单容器部署
直接使用 docker run 启动：
docker run -d \
--name chronoframe \
-p 3320:3000 \
-v /www/wwwroot/photo.520301.xyz:/app/data \
--env-file .env \
ghcr.io/hoshinosuzumi/chronoframe:latest
4. 访问服务
部署完成后，通过 http://localhost:3320 访问 ChronoFrame，使用配置的管理员邮箱和密码登录。
5. 常用操作（Docker Compose）
# 查看日志
docker-compose logs -f chronoframe
# 停止服务
docker-compose down
# 更新镜像并重启
docker-compose pull
docker-compose up -d
登录到控制台
- 点击头像跳转到登录页面，可以使用账号密码或 GitHub 登录
上传照片
- 访问仪表板页面
/dashboard - 在
Photos页面中选择图片并点击上传（支持批量上传和拖拽上传） - 系统将自动提取 EXIF 信息、生成缩略图并逆编码照片地理位置
注意事项
-
数据会保存在你所指定的目录，例如上方：
/www/wwwroot/photo.520301.xyz，建议定期备份 -
如果后续修改了
.env文件后，需要重启 ChronoFrame 容器才能使新的配置生效。- 先停止当前运行的容器
docker stop chronoframe-
移除已停止的容器（因为 Docker 容器启动后，配置会固化，必须重建才能加载新配置）
docker rm chronoframe -
用同样的命令重新启动容器（此时会读取更新后的
.env文件）docker run -d \ --name chronoframe \ -p 3320:3000 \ -v /www/wwwroot/photo.520301.xyz:/app/data \ --env-file .env \ ghcr.io/hoshinosuzumi/chronoframe:latest
更新 ChronoFrame 容器的步骤：
-
停止并移除旧容器：
docker stop chronoframe docker rm chronoframe -
拉取最新镜像：
docker pull ghcr.io/hoshinosuzumi/chronoframe:latest -
用新镜像重新启动容器（使用相同的配置）：
docker run -d \ --name chronoframe \ -p 3320:3000 \ -v /www/wwwroot/photo.520301.xyz:/app/data \ --env-file .env \ ghcr.io/hoshinosuzumi/chronoframe:latest