Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
TypeScript albumsexif-extractiongeocodinglive-photomotion-photophoto-galleryphoto-sharingwebgl-viewer
docs: restore storage and map setup guides
Timothy Yin4c78cf8376e5
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex c7bd3d0b..4173a440 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -53,6 +53,13 @@ export default defineConfig({{ text: 'Demo Sites', link: '/demo-sites' },],},+ {+ text: 'Services',+ items: [+ { text: 'Storage schemes', link: '/configuration/storage-providers' },+ { text: 'Maps and locations', link: '/configuration/map-providers' },+ ],+ },{text: 'Development',items: [diff --git a/docs/configuration/location-providers.md b/docs/configuration/location-providers.mdindex b8299c22..c339f21b 100644--- a/docs/configuration/location-providers.md+++ b/docs/configuration/location-providers.md@@ -1,5 +1,3 @@-# Archived configuration+# Location Services-This page has moved to the archive. Use the [setup wizard](/guide/getting-started) for new installations and the dashboard for existing sites.--[Read the archived page](/legacy/configuration/location-providers)+Location services and maps are managed on the same dashboard page. Read [Maps and locations](/configuration/map-providers#place-name-lookup) for place-name language, Mapbox reverse geocoding and Nominatim settings.diff --git a/docs/configuration/map-providers.md b/docs/configuration/map-providers.mdindex 5d9d2bbb..fa13be5f 100644--- a/docs/configuration/map-providers.md+++ b/docs/configuration/map-providers.md@@ -1,5 +1,68 @@-# Archived configuration+# Maps and Locations-This page has moved to the archive. Use the [setup wizard](/guide/getting-started) for new installations and the dashboard for existing sites.+Open **Site settings → Maps and locations**. Map display and place-name lookup are configured separately: map tokens load the map, while location services turn photo GPS coordinates into city and country names. Enabling maps cannot add a shooting location to a photo without GPS.-[Read the archived page](/legacy/configuration/map-providers)+## Choose a map service++| Option | Renderer | Default map data | Required credential |+| -------- | -------------------------- | ---------------- | -------------------------- |+| MapLibre | Open-source MapLibre GL JS | MapTiler | MapTiler API key |+| Mapbox | Mapbox GL JS | Mapbox | Mapbox public access token |++MapLibre is the renderer; MapTiler supplies map data. The built-in MapLibre style follows the site's light/dark theme. A custom style overrides it. Check each provider's current terms, allowances and pricing.++## MapLibre + MapTiler++1. Sign in to [MapTiler Cloud](https://cloud.maptiler.com/).+2. Create or copy a key for your gallery on the [API keys page](https://cloud.maptiler.com/account/keys/).+3. Choose **MapLibre** in ChronoFrame and paste the key into its token field. Leave the style empty to start with the built-in map.+4. Set **Allowed HTTP origins** for the key to your gallery origin, such as `https://gallery.example.com`. Add `http://localhost:3000` for local testing.+5. Save and open the globe or a GPS-tagged photo to check the map.++The browser uses this key, so it is not a server-only secret. See the [MapTiler API key guide](https://docs.maptiler.com/guides/credentials/api-key/) for origin restrictions.++### Custom styles++Copy a MapLibre-compatible **Style JSON URL** from the MapTiler map page and enter it in the MapLibre style field, for example:++```text+https://api.maptiler.com/maps/streets-v2/style.json?key=YOUR_MAPTILER_KEY+```++Use the style URL, not a preview page or embedded HTML. Use your own key in the URL and check it when rotating keys. For self-hosted styles, visitors' browsers must be able to fetch tiles, fonts and sprites with appropriate CORS headers.++## Mapbox++1. Sign in to [Mapbox](https://console.mapbox.com/).+2. Create a public token on the [Access tokens page](https://console.mapbox.com/account/access-tokens/). It normally starts with `pk.`; retain read access needed for map styles, tiles and fonts.+3. Choose **Mapbox** in ChronoFrame and enter the public token. Do not enter a secret `sk.` token.+4. Add **URL restrictions** for the gallery and any local testing address. Create a dedicated token: the default public token cannot have URL restrictions.+5. Leave the style empty to use Mapbox Standard. Save and open a map to check the result.++See [Mapbox token management](https://docs.mapbox.com/accounts/guides/tokens/) for creation and restrictions.++### Custom styles++Choose or create a style in Mapbox Studio, copy its **Style URL** from the sharing panel and enter it in the Mapbox style field:++```text+mapbox://styles/YOUR_USERNAME/YOUR_STYLE_ID+```++The token must be able to read the style. Do not use the Studio editor URL.++## Place-name lookup++Location settings further down the same page include:++- **Place-name language**: controls names saved by future lookups; reindex existing photo locations to update them.+- **Mapbox reverse-geocoding token**: used for server requests, independently of the browser map token. URL restrictions can reject server requests, so do not simply reuse an origin-restricted map token.+- **Nominatim URL**: use it for a self-hosted service or proxy; otherwise keep the default.++MapLibre can display maps while Mapbox or Nominatim identifies places. Troubleshoot map display and place-name lookup separately.++## Configure later and troubleshoot++You can skip the token during setup and add it here later. Uploads and photo management still work; map views indicate that setup is missing.++For blank maps or 401 / 403 responses, check the provider, token, current URL restrictions and access to styles, tiles and fonts. Update origin restrictions when moving from localhost to a public domain.diff --git a/docs/configuration/storage-providers.md b/docs/configuration/storage-providers.mdindex 820e05d0..c59966f6 100644--- a/docs/configuration/storage-providers.md+++ b/docs/configuration/storage-providers.md@@ -1,5 +1,99 @@-# Archived configuration+# Storage Schemes-This page has moved to the archive. Use the [setup wizard](/guide/getting-started) for new installations and the dashboard for existing sites.+Add, edit or select a default scheme in **Site settings → Storage settings**. Enter connection details directly in the form. Switching the default affects future uploads; existing files are not moved. Keep the original scheme and a backup when planning a migration.-[Read the archived page](/legacy/configuration/storage-providers)+## Choose storage++| Provider | Best fit | What you need | Considerations |+| --------------------- | ----------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------- |+| Local filesystem | Getting started, your own server or NAS | A mounted, writable directory | Manage disk capacity and backups yourself |+| S3-compatible storage | Cloud object storage or an existing MinIO service | Bucket, endpoint, region and access keys | Direct browser uploads need CORS; images need a working read URL |+| OpenList | Existing cloud drives or NAS managed through OpenList | Service URL, root path and token | Check write permissions, backend limits and download URL expiry |++## Local filesystem++Choose local storage and enter `/app/data/storage` as the base path, matching the `./data:/app/data` mount in Getting Started. The base URL can normally remain `/storage`.++This is a **container path**, not a host path. To use another disk, add a mount such as `./photos:/app/photos`, then enter `/app/photos` as the base path. Ensure the application user has read/write access and back up that directory separately.++## S3-compatible storage++### Prepare and enter credentials++1. Create a bucket in the provider's console and note its name and region.+2. Create application-specific credentials allowing object reads, writes, deletes and bucket listing. Large-file multipart uploads also need the corresponding multipart permissions.+3. Add an S3 scheme in the dashboard using the fields below. Keep credentials out of public image URLs and map token fields.++| Field | Value |+| --------------------------------- | ----------------------------------------------------------------------------------------- |+| Endpoint | S3 API URL including `https://`; not a console URL or CDN domain |+| Bucket | Bucket name, including the APPID suffix for Tencent COS |+| Region | Bucket region; use `auto` for R2 and the provider's configured region otherwise |+| Access Key ID / Secret Access Key | The credential pair issued by the provider |+| Prefix | Optional object prefix such as `photos/` |+| CDN URL | Optional image-serving base URL; appending the object key must produce a working read URL |+| Force Path Style | Enable when the service expects `Endpoint/Bucket/Key`, such as path-based MinIO |++### Common services++Replace account and region placeholders with your own values.++| Service | Example endpoint | Region | Credentials and notes |+| ----------------- | ----------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- |+| AWS S3 | `https://s3.us-east-1.amazonaws.com` | `us-east-1` | Use IAM access keys scoped to the bucket |+| Cloudflare R2 | `https://<ACCOUNT_ID>.r2.cloudflarestorage.com` | `auto` | An R2 API token provides S3 credentials; configure a separate domain for image reads |+| Alibaba Cloud OSS | `https://oss-cn-hangzhou.aliyuncs.com` | Follow the service's S3 compatibility configuration | Use RAM AccessKeys and the bucket's regional endpoint |+| Tencent COS | `https://cos.ap-beijing.myqcloud.com` | `ap-beijing` | Use API credentials and the full bucket name including `-APPID` |+| MinIO | `https://minio.example.com` | Service-configured region | Use the S3 API address, not the management console; enable Force Path Style for path-based access |++R2's S3 endpoint is for signed uploads, not a public image domain. Put an object-serving domain in CDN URL; use a custom domain for a production gallery. See [R2 credentials](https://developers.cloudflare.com/r2/api/tokens/) and [public access](https://developers.cloudflare.com/r2/buckets/public-buckets/). For OSS, consult [regions and endpoints](https://www.alibabacloud.com/help/en/oss/user-guide/regions-and-endpoints); for COS, see its [official API notes](https://cloud.tencent.com/document/faq/436/50743).++### Bucket CORS++Browsers upload directly to S3. Presigned URLs still need CORS for the gallery's origin. Multipart uploads also need JavaScript access to `ETag` to complete the upload.++In AWS S3, open the bucket's **Permissions → Cross-origin resource sharing (CORS)**. In R2, use **Settings → CORS Policy**. Start with this JSON in either console:++```json+[+ {+ "AllowedOrigins": ["https://[YOUR_DOMAIN]"],+ "AllowedMethods": ["GET", "PUT", "HEAD"],+ "AllowedHeaders": ["*"],+ "ExposeHeaders": ["ETag", "Content-Length", "Content-Type"],+ "MaxAgeSeconds": 0+ }+]+```++- Replace the origin with your **gallery URL**, including its scheme and non-default port, without a path. Do not use the bucket or CDN URL here.+- Add `http://localhost:3000` for local testing; keep only required origins in production.+- For providers with form-based CORS settings, enter the same origins, methods, allowed headers and exposed headers.+- Check CDN response headers too. Existing cached responses may need refreshing after a policy change.++See [AWS CORS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html) and [R2 CORS documentation](https://developers.cloudflare.com/r2/buckets/cors/). CORS does not grant credential permissions or replace file access control.++### Image reads and protected albums++After uploading, open an image as a visitor to check the read URL, object path and HTTPS. Do not make the whole bucket public merely to troubleshoot CORS.++Remote media links currently cannot guarantee that every request passes through ChronoFrame album authorization. Use local storage for files that need password-album protection. Public S3, OpenList or CDN links and caches are not revoked when an album password changes.++## OpenList++1. Mount the destination in OpenList and confirm that files can be uploaded, read and deleted in the chosen directory.+2. Obtain an API access token from the OpenList management interface; do not use a cloud-drive driver's own token.+3. Add an OpenList scheme in ChronoFrame. Enter a service URL such as `https://openlist.example.com`, an actual OpenList root path such as `/115pan/chronoframe`, and the token.+4. Upload a photo and open its original. Directory permissions, network access and download URL expiry can affect the result.++Keep the standard advanced endpoints unless your service or proxy changes them: upload `/api/fs/put`, delete `/api/fs/remove`, metadata `/api/fs/get`, path field `path`. If using a CDN URL, check that it matches real object paths. See the [OpenList documentation](https://doc.oplist.org/) for service setup.++## Troubleshooting++| Symptom | Check first |+| ---------------------------------- | --------------------------------------------------------------------------- |+| Local permission error | Mounted base path and directory write permissions |+| Missing bucket or signature error | Matching bucket, region, endpoint and credentials |+| Browser CORS error | Gallery origin, PUT method and allowed request headers |+| Small files work, large files fail | Multipart permissions, exposed `ETag` and proxy limits |+| Upload works, image does not open | CDN URL, read access and object path; check CORS and permissions separately |diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.mdindex d0901b53..7443264b 100644--- a/docs/guide/getting-started.md+++ b/docs/guide/getting-started.md@@ -37,13 +37,23 @@ Open `http://localhost:3000`. A fresh installation opens the setup wizard; you d## Complete the setup wizard-1. **Administrator**: choose your email, username and password. Use these credentials to sign in later. Avoid the default password from older tutorials.+1. **Administrator**: choose your email, username and password. Use these credentials to sign in later.2. **Site**: enter the gallery title, description, author and avatar.3. **Storage**: choose local storage, S3 or OpenList. For local storage, use `/app/data/storage` so photos are saved in the mounted data directory.4. **Map**: choose MapLibre or Mapbox and enter the service token and style. You can leave the token empty and add it in the dashboard later. Map views need a working map service.5. Review your choices and finish setup to enter the dashboard.-For S3, prepare an endpoint, bucket, region, access key ID and secret access key, plus an optional CDN URL. For OpenList, prepare the service URL, root path and access token. Enter these in the wizard or dashboard, rather than environment variables.+## Enter the dashboard++After setup, open `/dashboard`. On your first visit to the dashboard, photo library and settings pages, a step-by-step tour points out uploads, queues and common settings. You can skip it and reset the tours later in **Site settings → System settings**.++++### Upload your first photo++Open **Photos**, select files or drag them into the upload area. Background tasks continue extracting EXIF, creating thumbnails and identifying places after transfer finishes. Check completion in **Queue management**, then open the gallery. Failed tasks show an error and can be retried.++Local storage is ready to use. The service guides explain S3 credentials and CORS, OpenList URLs and tokens, and map API keys. Enter these in the dashboard, without converting them into environment variables.## Keep your datadiff --git a/docs/guide/usage.md b/docs/guide/usage.mdindex d82f40cf..5cf8b9fd 100644--- a/docs/guide/usage.md+++ b/docs/guide/usage.md@@ -36,6 +36,8 @@ Site details, maps, location services, storage and upload limits can be edited i| Privacy | Automatically remove location data from new uploads || Analytics | Custom tracking scripts inserted into the page head or body |+For provider selection, credentials and CORS, see [Storage schemes](/configuration/storage-providers). For tokens and styles, see [Maps and locations](/configuration/map-providers).+Map settings control display; location settings convert GPS coordinates into place names. After changing the place-name language, reindex existing locations to update names already saved in the database.Before switching storage schemes, make sure existing photos remain accessible. Selecting a scheme does not automatically move originals to the new storage. Local paths must be inside a mounted directory to survive container replacement.diff --git a/docs/images/dashboard-overview.jpg b/docs/images/dashboard-overview.jpgnew file mode 100644index 00000000..1e32716aBinary files /dev/null and b/docs/images/dashboard-overview.jpg differdiff --git a/docs/images/dashboard-settings.jpg b/docs/images/dashboard-settings.jpgnew file mode 100644index 00000000..b8fe1709Binary files /dev/null and b/docs/images/dashboard-settings.jpg differdiff --git a/docs/zh/config.ts b/docs/zh/config.tsindex a2be08f8..79481642 100644--- a/docs/zh/config.ts+++ b/docs/zh/config.ts@@ -24,6 +24,13 @@ export default defineConfig({{ text: '演示站点', link: '/zh/demo-sites' },],},+ {+ text: '服务接入',+ items: [+ { text: '存储方案', link: '/zh/configuration/storage-providers' },+ { text: '地图和位置', link: '/zh/configuration/map-providers' },+ ],+ },{text: '开发',items: [diff --git a/docs/zh/configuration/location-providers.md b/docs/zh/configuration/location-providers.mdindex 4026bef0..468bef5b 100644--- a/docs/zh/configuration/location-providers.md+++ b/docs/zh/configuration/location-providers.md@@ -1,5 +1,3 @@-# 旧配置文档+# 位置服务-此页已归档。新部署请使用[设置向导](/zh/guide/getting-started),已有实例的设置可在后台修改。--[查看历史文档](/zh/legacy/configuration/location-providers)+位置服务与地图配置在同一个后台页面管理。请查看[地图和位置](/zh/configuration/map-providers#地点识别),了解地名语言、Mapbox 反向地理编码和 Nominatim 的设置。diff --git a/docs/zh/configuration/map-providers.md b/docs/zh/configuration/map-providers.mdindex 9ae1f4a2..cd8636fe 100644--- a/docs/zh/configuration/map-providers.md+++ b/docs/zh/configuration/map-providers.md@@ -1,5 +1,68 @@-# 旧配置文档+# 地图和位置-此页已归档。新部署请使用[设置向导](/zh/guide/getting-started),已有实例的设置可在后台修改。+打开 **站点设置 → 地图和位置**。这里分别设置地图显示和地点识别:地图令牌用于加载地图,位置服务将照片的 GPS 转换成城市、国家等地名。没有 GPS 的照片不会因为开启地图而自动获得拍摄地点。-[查看历史文档](/zh/legacy/configuration/map-providers)+## 选择地图服务++| 选项 | 地图由谁渲染 | 默认地图数据 | 需要准备 |+| -------- | ------------------- | ------------ | ------------------- |+| MapLibre | 开源 MapLibre GL JS | MapTiler | MapTiler API Key |+| Mapbox | Mapbox GL JS | Mapbox | Mapbox 公共访问令牌 |++MapLibre 是渲染器,MapTiler 是提供地图数据的服务,两者不是同一个产品。默认 MapLibre 样式随站点明暗主题切换;自定义样式会覆盖内置样式。服务的免费额度、商用要求和计费以各自官网为准。++## MapLibre + MapTiler++1. 注册或登录 [MapTiler Cloud](https://cloud.maptiler.com/)。+2. 在 [API keys](https://cloud.maptiler.com/account/keys/) 页面创建或复制一个供画廊使用的 Key。+3. 在 ChronoFrame 中选择 **MapLibre**,将 Key 填入 MapLibre 令牌字段;第一次使用可留空样式,使用内置地图。+4. 在 MapTiler 的 Key 设置中配置 **Allowed HTTP origins**,填写画廊的来源地址,例如 `https://gallery.example.com`;本地调试另加 `http://localhost:3000`。+5. 保存设置并打开地球仪或带 GPS 的照片详情,检查地图是否正常加载。++Key 会被浏览器用于请求地图,所以不要把它当作只存在服务器上的秘密。来源限制的说明见 [MapTiler API Key 指南](https://docs.maptiler.com/guides/credentials/api-key/)。++### 自定义样式++从 MapTiler 地图页面复制与 MapLibre 兼容的 **Style JSON URL**,填入 MapLibre 样式字段。例如:++```text+https://api.maptiler.com/maps/streets-v2/style.json?key=YOUR_MAPTILER_KEY+```++这是样式地址,不能填预览页面或嵌入 HTML。若地址中包含 Key,请使用自己创建的 Key;更换令牌时也要检查样式地址。自托管样式需保证瓦片、字体和图标地址可由访客浏览器访问,并允许跨域请求。++## Mapbox++1. 注册或登录 [Mapbox](https://console.mapbox.com/)。+2. 在 [Access tokens](https://console.mapbox.com/account/access-tokens/) 创建供网页地图使用的公共令牌,通常以 `pk.` 开头,保留地图样式、瓦片和字体所需的读取权限。+3. 在 ChronoFrame 中选择 **Mapbox**,将公共令牌填入 Mapbox 令牌字段。不要填需要保密的 `sk.` 令牌。+4. 为这个专用令牌添加画廊地址的 **URL restrictions**;需要本地调试时也允许本地地址。默认公共令牌不能添加 URL 限制,因此推荐创建专用令牌。+5. 样式可先留空,应用使用 Mapbox Standard。保存后打开地图确认效果。++获取和限制令牌的方法见 [Mapbox 令牌管理](https://docs.mapbox.com/accounts/guides/tokens/)。++### 自定义样式++在 Mapbox Studio 创建或选择样式,从分享面板复制 **Style URL**,填入 Mapbox 样式字段,例如:++```text+mapbox://styles/YOUR_USERNAME/YOUR_STYLE_ID+```++该样式必须对当前令牌可读,不能填 Studio 编辑页的地址。++## 地点识别++同一页面下方的位置设置包括:++- **地名语言**:控制后续识别保存的地点名称;修改后可重新索引已有照片的位置。+- **Mapbox 反向地理编码令牌**:供服务器查询地点,独立于上面的网页地图令牌。URL 限制可能使服务器请求被拒绝,不要直接复用带网页来源限制的地图令牌。+- **Nominatim 地址**:需要自建服务或代理时填写;普通使用可保留默认值。++可使用 MapLibre 显示地图,同时使用 Mapbox 或 Nominatim 识别地点。地图显示与地点识别失败时,应分别检查各自的配置。++## 暂不配置及排查++设置向导允许先跳过令牌,之后在本页补齐。没有令牌时仍可上传和管理照片,相关地图会提示尚未设置。++地图空白或请求出现 401 / 403 时,核对选择的提供器、令牌、当前域名限制,以及样式、瓦片和字体的访问权限。站点从 localhost 换成正式域名后,要同步修改服务商的来源限制。diff --git a/docs/zh/configuration/storage-providers.md b/docs/zh/configuration/storage-providers.mdindex 606e225c..ded71566 100644--- a/docs/zh/configuration/storage-providers.md+++ b/docs/zh/configuration/storage-providers.md@@ -1,5 +1,99 @@-# 旧配置文档+# 存储方案-此页已归档。新部署请使用[设置向导](/zh/guide/getting-started),已有实例的设置可在后台修改。+在 **站点设置 → 存储设置** 中添加、编辑或设为默认方案,连接信息直接填写到表单。更换默认方案只影响后续上传,已有文件不会自动迁移;迁移前请保留原方案和备份。-[查看历史文档](/zh/legacy/configuration/storage-providers)+## 选择哪种存储++| 提供器 | 适合的情况 | 需要准备 | 需要留意 |+| ------------ | -------------------------------------------- | -------------------------------- | ----------------------------------------------- |+| 本地文件系统 | 想先开始使用,或把照片放在自己的服务器 / NAS | 已挂载、可写的目录 | 磁盘容量和备份由自己管理 |+| S3 兼容存储 | 使用云对象存储,或已有 MinIO 等服务 | 存储桶、Endpoint、区域、访问密钥 | 浏览器直传需要 CORS,图片访问需要可用的读取地址 |+| OpenList | 已经用 OpenList 管理网盘或 NAS | 服务地址、根路径、令牌 | 上传权限、后端限速和下载地址有效期 |++## 本地文件系统++添加方案时选择“本地存储”,基础路径填写容器内的 `/app/data/storage`,与快速开始中的 `./data:/app/data` 挂载配合使用。访问地址通常保留 `/storage`。++这里填的是**容器内路径**,不是宿主机路径。想使用另一块磁盘,可先增加 `./photos:/app/photos` 挂载,再把基础路径填写为 `/app/photos`。确认运行应用的用户有读写权限,并单独备份该目录。++## S3 兼容存储++### 获取信息并填写表单++1. 在服务商控制台创建存储桶,记下名称和所在区域。+2. 创建应用专用的访问密钥,授权它读取、上传、删除对象和列举这个桶;大文件分片上传还需要对应的 multipart 权限。+3. 在后台添加 S3 方案,按下面的字段填写。密钥只填在后台,不要放进公开的图片地址或地图令牌中。++| 字段 | 怎么填 |+| --------------------------------- | ------------------------------------------------------------------------- |+| Endpoint | 服务商的 S3 API 地址,包含 `https://`,不要填控制台地址或 CDN 域名 |+| Bucket | 存储桶名称;腾讯云 COS 要带上完整的 APPID 后缀 |+| Region | 桶所在区域;R2 使用 `auto`,其他服务按控制台填写 |+| Access Key ID / Secret Access Key | 服务商生成的一对访问凭据 |+| Prefix | 可选的对象前缀,例如 `photos/`,用于与同桶的其他文件区分 |+| CDN URL | 可选的图片读取根地址,不是上传 Endpoint;需保证后面拼接对象键后能读取文件 |+| Force Path Style | 服务需要 `Endpoint/Bucket/Key` 形式时开启,例如按路径访问的 MinIO |++### 常用服务++以下地址是示例,请换成自己账号和区域的信息。++| 服务 | Endpoint 示例 | Region | 凭据与特别说明 |+| ------------- | ----------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------- |+| AWS S3 | `https://s3.us-east-1.amazonaws.com` | `us-east-1` | 创建桶后使用 IAM 身份的访问密钥,并限制到目标桶 |+| Cloudflare R2 | `https://<ACCOUNT_ID>.r2.cloudflarestorage.com` | `auto` | 创建 R2 API Token 后获得 Access Key ID 和 Secret Access Key;图片读取另配自定义域名 |+| 阿里云 OSS | `https://oss-cn-hangzhou.aliyuncs.com` | 按服务的 S3 兼容配置填写 | 从 RAM 身份获取 AccessKey,Endpoint 使用桶所在地域的地址 |+| 腾讯云 COS | `https://cos.ap-beijing.myqcloud.com` | `ap-beijing` | 使用 API 密钥,Bucket 包含 `-APPID` 后缀 |+| MinIO | `https://minio.example.com` | 服务配置的区域 | 使用 S3 API 端口对应的地址,而不是管理控制台;按路径访问时开启 Force Path Style |++R2 的 S3 Endpoint 用于签名上传,不能当成公开图片域名。将可访问对象的域名填写为 CDN URL;正式站点可使用自定义域名。参见 [R2 凭据获取](https://developers.cloudflare.com/r2/api/tokens/)和[公开访问说明](https://developers.cloudflare.com/r2/buckets/public-buckets/)。OSS 地址可查阅[地域和 Endpoint](https://www.alibabacloud.com/help/en/oss/user-guide/regions-and-endpoints);COS 的兼容行为请参阅[官方 API 说明](https://cloud.tencent.com/document/faq/436/50743)。++### 存储桶的 CORS++浏览器会直接向 S3 上传文件,即使使用预签名 URL,存储桶也需要允许来自画廊域名的跨域请求。大文件分片上传需要 JavaScript 读取 `ETag`;缺少这个响应头可能导致文件上传后无法完成合并。++在 AWS S3 控制台打开存储桶的 **Permissions → Cross-origin resource sharing (CORS)**;R2 在桶的 **Settings → CORS Policy** 中配置。下面的 JSON 可作为这两种控制台的起点:++```json+[+ {+ "AllowedOrigins": ["https://[YOUR_DOMAIN]"],+ "AllowedMethods": ["GET", "PUT", "HEAD"],+ "AllowedHeaders": ["*"],+ "ExposeHeaders": ["ETag", "Content-Length", "Content-Type"],+ "MaxAgeSeconds": 0+ }+]+```++- 将 `https://[YOUR_DOMAIN]` 换成**画廊的来源地址**,包含协议和非默认端口,不带路径。它不是存储桶或 CDN 地址。+- 本地调试时另加 `http://localhost:3000`;正式站点只保留需要的来源。+- OSS / COS 等控制台若使用逐项表单,按同样的来源、方法、请求头和暴露头填写。+- 使用 CDN 时也要检查图片响应中的跨域头。修改规则后,旧缓存可能需要刷新。++详细字段见 [AWS CORS 文档](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html)和 [R2 CORS 文档](https://developers.cloudflare.com/r2/buckets/cors/)。CORS 解决浏览器跨域请求,不会授予密钥权限,也不能代替文件访问控制。++### 图片读取与密码相册++验证上传成功后,还要从访客视角打开图片,确认读取地址、对象路径和 HTTPS 都正确。不要为了排查 CORS 就开放整个桶。++当前远端存储的媒体直链不能保证经过 ChronoFrame 的相册授权。需要保护密码相册中的文件时,使用本地存储;公开 S3、OpenList 或 CDN 的直链和缓存不会因修改相册密码而撤销。++## OpenList++1. 先在 OpenList 中挂载目标存储,确认能够在选定目录中上传、读取和删除文件。+2. 从 OpenList 管理后台获取用于 API 访问的令牌;不要误用网盘驱动自身的 token。+3. 在 ChronoFrame 添加 OpenList 方案:服务地址填写 `https://openlist.example.com`,根路径填写 `/115pan/chronoframe` 等 OpenList 中的实际路径,再填入令牌。+4. 先上传一张照片并检查能否打开原图。目录权限、服务网络和下载地址有效期都可能影响结果。++标准服务通常保留高级接口默认值:上传 `/api/fs/put`、删除 `/api/fs/remove`、元数据 `/api/fs/get`,路径字段为 `path`。只有反向代理或服务接口有改动时才调整。可另填 CDN URL,但要确认它与真实对象路径一致。服务相关说明见 [OpenList 文档](https://doc.oplist.org/)。++## 常见问题++| 现象 | 优先检查 |+| ------------------------- | -------------------------------------------------------- |+| 本地上传提示权限错误 | 基础路径是否已挂载,目录是否可写 |+| S3 提示桶不存在或签名错误 | Bucket、Region、Endpoint 是否属于同一个桶,密钥是否正确 |+| 浏览器提示 CORS 错误 | 画廊来源是否允许、PUT 是否允许、请求头是否允许 |+| 小文件成功,大文件失败 | multipart 权限、`ETag` 暴露和网络代理的请求限制 |+| 上传成功但图片打不开 | CDN URL、公开读取方式和对象路径;CORS 与读取权限分别检查 |diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.mdindex 4eed0ea1..4fc8bdce 100644--- a/docs/zh/guide/getting-started.md+++ b/docs/zh/guide/getting-started.md@@ -37,13 +37,23 @@ docker run -d --name chronoframe --restart unless-stopped \## 完成设置向导-1. **管理员**:填写邮箱、用户名和密码,之后使用这组凭据登录。不要沿用旧教程中的默认密码。+1. **管理员**:填写邮箱、用户名和密码,之后使用这组凭据登录。2. **站点信息**:填写画廊名称、介绍、作者和头像。3. **存储**:选择本地存储、S3 或 OpenList。本地存储的路径填写 `/app/data/storage`,这样照片会随数据卷保存。4. **地图**:选择 MapLibre 或 Mapbox,并填写相应服务的令牌和样式。也可以暂不填写令牌,稍后在后台补充。没有可用的地图服务时,相关地图不会正常展示。5. 确认并完成向导,进入后台。-S3 需要准备 Endpoint、Bucket、Region、Access Key ID 和 Secret Access Key,可另设 CDN 地址。OpenList 需要服务地址、根目录和访问令牌。连接信息直接填写到向导或后台,无需换成环境变量。+## 进入仪表盘++完成向导后进入 `/dashboard`。第一次访问仪表盘、照片库和各设置页时,会有分步指引,带你找到上传入口、队列和常用设置。可以随时跳过;需要重新查看时,在 **站点设置 → 系统设置** 中重置指引。++++### 上传第一张照片++打开 **照片库**,选择文件或拖入照片开始上传。上传结束后,应用还会在后台提取 EXIF、生成缩略图和识别地点;到 **队列管理** 查看是否完成,再打开画廊检查效果。遇到失败任务,可以查看错误原因并重试。++本地存储可以直接开始使用。S3 的访问密钥和 CORS、OpenList 的服务地址与令牌,以及地图服务的 Key,都在对应的服务指南中说明,无需换成环境变量。## 保存数据diff --git a/docs/zh/guide/usage.md b/docs/zh/guide/usage.mdindex 9470a864..13a7e4bf 100644--- a/docs/zh/guide/usage.md+++ b/docs/zh/guide/usage.md@@ -36,6 +36,8 @@| 隐私 | 上传时自动移除位置信息 || 分析 | 注入到页面 head 或 body 的自定义统计脚本 |+存储选型、凭据与 CORS 见[存储方案](/zh/configuration/storage-providers);地图令牌与样式设置见[地图和位置](/zh/configuration/map-providers)。+地图负责显示,位置服务负责将 GPS 坐标转换成地名,两者分别设置。更改地名语言后,已有照片需要重新索引位置才能更新保存的地名。更换存储方案前,请确认已有照片仍能访问。选择新方案不等于将原图自动搬到新存储中。本地存储路径必须位于已挂载的目录内,容器才能在重建后继续访问文件。