Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

docs: improve readability with callouts and concise guidance

Timothy Yin2d64ebbe7fea
diff --git a/docs/changelog.md b/docs/changelog.md
index 35104868..302b8ea8 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -45,13 +45,15 @@ Changes grouped by stable version. 1.0.0 includes all changes since v0.14.1, wit
- Rebuild the Docker runtime with TLS certificates, Perl and ExifTool dependencies; the runtime has no shell or package manager.
- Archive environment-based instructions under Legacy and use the wizard for new installations.
-### Upgrade notes
+::: warning Upgrade notes
- Keep old environment variables for the initial migration and verify settings and storage paths in the dashboard.
- Album passwords cannot block direct access through public S3, OpenList or CDN URLs; manage external storage access too.
- Photos in hidden albums are excluded from anonymous access, which can affect their display in public albums.
- Back up all data before upgrading and restore the pre-migration database when rolling back.
+:::
+
## v0.14.1
2025-10-28 · [Release notes](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.14.1) · [Code changes](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.0...v0.14.1)
diff --git a/docs/configuration/map-providers.md b/docs/configuration/map-providers.md
index d78a48f5..39d3224b 100644
--- a/docs/configuration/map-providers.md
+++ b/docs/configuration/map-providers.md
@@ -9,7 +9,9 @@ Open **Site settings → Maps and locations**. Map display and place-name lookup
| MapLibre | Open-source MapLibre GL JS | MapTiler | MapTiler API key for the built-in style |
| Mapbox | Mapbox GL JS | Mapbox | Mapbox public access token |
+::: info Renderer and map data service
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
@@ -19,7 +21,9 @@ MapLibre is the renderer; MapTiler supplies map data. The built-in MapLibre styl
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.
+::: warning Restrict where the key can be used
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
@@ -29,7 +33,13 @@ Copy a MapLibre-compatible **Style JSON URL** from the MapTiler map page and ent
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.
+::: tip Use the Style JSON URL
+
+- Enter a style URL, not a preview page or embedded HTML.
+- Use your own key in the URL and check it when rotating keys.
+- Self-hosted tiles, fonts and sprites must be accessible to visitors' browsers with appropriate CORS headers.
+
+:::
## Mapbox
@@ -63,6 +73,8 @@ MapLibre can display maps while Mapbox or Nominatim identifies places. Troublesh
## Configure later and troubleshoot
+::: tip Configure maps later
You can skip the token during setup and add it here later. Uploads and photo management still work. MapLibre views indicate that setup is missing only when neither a token nor a custom style is configured; the built-in MapTiler style requires a key.
+:::
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.md
index 1eaf62c5..87302a5a 100644
--- a/docs/configuration/storage-providers.md
+++ b/docs/configuration/storage-providers.md
@@ -1,6 +1,10 @@
# Storage Schemes
-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.
+Add, edit or select a default scheme in **Site settings → Storage settings**. Enter connection details directly in the form.
+
+::: warning Switching does not move files
+Switching the default affects future uploads; existing files are not moved. Keep the original scheme and a backup when planning a migration.
+:::
## Choose storage
@@ -18,7 +22,9 @@ Files copied or uploaded directly to any storage backend will not automatically
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`.
+::: tip Use a container path
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
@@ -50,7 +56,17 @@ Replace account and region placeholders with your own values.
| 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).
+::: info R2 upload and read URLs differ
+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.
+:::
+
+::: details Provider reference documentation
+
+- Cloudflare R2: [credentials](https://developers.cloudflare.com/r2/api/tokens/) and [public access](https://developers.cloudflare.com/r2/buckets/public-buckets/).
+- Alibaba Cloud OSS: [regions and endpoints](https://www.alibabacloud.com/help/en/oss/user-guide/regions-and-endpoints).
+- Tencent COS: [API compatibility notes](https://cloud.tencent.com/document/faq/436/50743).
+
+:::
### Bucket CORS
@@ -75,13 +91,17 @@ In AWS S3, open the bucket's **Permissions → Cross-origin resource sharing (CO
- 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.
+::: info CORS is not access control
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.
+::: warning Use local storage for protected albums
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
@@ -90,7 +110,9 @@ Remote media links currently cannot guarantee that every request passes through
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.
+::: details Advanced OpenList endpoints
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
diff --git a/docs/development/api.md b/docs/development/api.md
index ad14867a..8a9b5338 100644
--- a/docs/development/api.md
+++ b/docs/development/api.md
@@ -2,7 +2,9 @@
The API uses the same session authentication as the web app. Authenticated requests carry the cookie obtained at sign-in; dashboard settings and management operations also check administrator privileges.
+::: info API scope
Common routes are listed below. For full parameters, responses and access rules, consult the routes and Zod validation in `server/api/`. These routes are not a versioned external API contract.
+:::
| Method | Path | Purpose |
| ------ | ------------------------------------------- | ---------------------------------------------------------------------- |
@@ -30,4 +32,8 @@ With an administrator session, send a PUT request to `/api/system/settings/batch
}
```
-For new settings or form changes, read [Adding a setting](/development/how-to-add-setting). Photo access follows album visibility and password rules; do not use the authenticated dashboard photo list as a public API.
+For new settings or form changes, read [Adding a setting](/development/how-to-add-setting).
+
+::: warning Dashboard endpoints are not public photo feeds
+Photo access follows album visibility and password rules. Do not expose the authenticated dashboard photo list as a public API.
+:::
diff --git a/docs/development/contributing.md b/docs/development/contributing.md
index 0ae89101..4a4085c9 100644
--- a/docs/development/contributing.md
+++ b/docs/development/contributing.md
@@ -12,7 +12,9 @@ pnpm install --frozen-lockfile
pnpm dev
```
+::: tip Local setup
Open `http://localhost:3000` and use the wizard to create an administrator and choose local storage. `./data/storage` works for development. Database migrations run at startup; you do not need to generate migrations or fill out a minimal environment configuration just to run the app.
+:::
## Commands
@@ -28,7 +30,9 @@ pnpm docs:build
`pnpm dev` runs the WebGL package development build alongside Nuxt. Once the dependency package is built, use `pnpm dev:only` to start Nuxt alone. Code checks use Oxlint; formatting uses Oxfmt.
+::: warning Review migrations and committed files
After changing the database schema, run `pnpm db:generate` and review the generated SQL. `pnpm db:migrate` applies migrations manually. Keep local databases, photos and credentials out of Git.
+:::
## Where code lives
diff --git a/docs/development/debug-tools.md b/docs/development/debug-tools.md
index 979ce4d7..e5b15248 100644
--- a/docs/development/debug-tools.md
+++ b/docs/development/debug-tools.md
@@ -1,14 +1,16 @@
# Development debug tools
+::: info Development only
The floating debug entry appears globally under `pnpm dev`. Production builds
remove the panel import and disable debug reads, writes, and registrations.
`?debug=1` opens the panel; the previous `?queueDebug=1` link also enables the
queue preview in development. Neither parameter activates production debugging.
+:::
-Drag the entry to dock it against the nearest edge; near a corner it docks to
-both edges. Drag a window header to move it, and its edges/corners to resize it.
-The header buttons maximize/restore and close the window. Double-clicking the
-header also maximizes/restores. Escape closes the window.
+- Drag the entry to dock it against the nearest edge or corner.
+- Drag a window header to move it; drag its edges or corners to resize it.
+- Use the header buttons to maximize, restore or close the window. Double-clicking the header also toggles maximization.
+- Press Escape to close the window.
## Register page controls
@@ -50,8 +52,10 @@ Supported controls: `switch`, `select` (with `options`), `number`, `text`,
Use `useDebugValue` for reactive reads/writes, or `useDebugStore().get/set`
for imperative access. Configuration persists in local storage. Route controls
are scoped to their page lifecycle and filtered by exact route path.
-In production reads return the supplied defaults and writes are ignored.
-Wrap expensive mock generation in `if (import.meta.dev)` for build removal.
+
+::: warning Guard expensive fixtures
+In production, reads return defaults and writes are ignored. Wrap expensive mock generation in `if (import.meta.dev)` so it can be removed from the build.
+:::
## Reuse the floating window
diff --git a/docs/development/how-to-add-setting.md b/docs/development/how-to-add-setting.md
index 71e1387c..457089ad 100644
--- a/docs/development/how-to-add-setting.md
+++ b/docs/development/how-to-add-setting.md
@@ -16,7 +16,9 @@ Add a definition under the appropriate namespace:
},
```
+::: warning Keep credentials out of public settings
Use `isPublic` only for values visitors may read. Use `isSecret` for credentials and `isReadonly` for values that normal setting updates must not change. An `enum` limits available string values.
+:::
## Describe the form field
@@ -40,4 +42,7 @@ Add `settings.app.foo.label`, `settings.app.foo.description` and any help text t
Existing forms use `useSettingsForm('app')` and render their descriptors through `SettingField`. For another namespace, use its corresponding UI configuration and form namespace. Server code reads and writes values through `settingsManager`.
+::: tip Verify persistence and visibility
Check that the field renders, saves and survives a restart. If it is private or secret, also check that it is absent from public settings responses. Database-backed settings do not normally require a new environment variable.
+
+:::
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index a1a27d89..788f882d 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -1,5 +1,7 @@
# Archived configuration
+::: info Legacy configuration is archived
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/guide/configuration)
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 7443264b..1ce3f25a 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -45,13 +45,17 @@ Open `http://localhost:3000`. A fresh installation opens the setup wizard; you d
## Enter the dashboard
+::: tip First-visit tours
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**.
+:::
![Dashboard overview showing the photo library, queue and settings navigation alongside photo statistics and task status](/images/dashboard-overview.jpg)
### 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.
+1. Open **Photos** and select or drag in your files.
+2. Check **Queue management** while EXIF, thumbnails and location lookup finish.
+3. Open the gallery to check the result; inspect and retry failed tasks.
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.
@@ -59,13 +63,17 @@ Local storage is ready to use. The service guides explain S3 credentials and COR
Keep the `./data:/app/data` mount. The default database is `/app/data/app.sqlite3`; a session secret is generated automatically and saved to `/app/data/.session-password`. With the local path above, originals and derived files also live under this directory.
+::: warning Preserve data when updating
Keep the data directory when replacing a container. Files stored in S3 or OpenList need their own backup; a database backup alone cannot restore missing originals.
+:::
## Use a domain and HTTPS
You can place Caddy, Nginx or Traefik in front of the container. Match the proxy upload limit to your dashboard setting and allow streaming responses for live logs.
+::: warning Trust only your own proxy
Enable `NUXT_TRUST_PROXY=true` only if port 3000 is reachable exclusively through a trusted proxy that replaces client-supplied `X-Forwarded-For` headers. This deployment option still uses an environment variable, for example in Compose:
+:::
```yaml
environment:
diff --git a/docs/guide/updates.md b/docs/guide/updates.md
index c5d4458a..713f40ad 100644
--- a/docs/guide/updates.md
+++ b/docs/guide/updates.md
@@ -4,7 +4,14 @@ Read the [changelog](/changelog) before choosing a target version and review its
## Back up
-Stop the container before copying the complete data directory and Compose file. If your older deployment uses `.env`, save it too. Back up local storage separately if it is outside `data`, and back up S3 or OpenList files in their storage service.
+::: warning Stop and back up first
+Stop the container, then back up:
+
+- The complete data directory and Compose file.
+- `.env`, if your older deployment still uses it.
+- Local photos outside `data`, plus files in S3 or OpenList.
+
+:::
```bash
docker compose stop chronoframe
@@ -23,7 +30,9 @@ docker compose up -d chronoframe
docker compose logs -f chronoframe
```
+::: info Migrations run at startup
Database migrations run automatically at startup. Manual migration commands are normally unnecessary. The current runtime image has no shell or package manager, so older instructions using `docker exec ... sh` or `npx drizzle-kit migrate` inside the container do not apply.
+:::
For a `docker run` deployment, stop and remove the old container, then recreate it with the new tag and the same data mount. Preserve your ports, networks and any deployment environment variables you still need.
@@ -41,4 +50,7 @@ Sign in, open several existing photos, upload a photo and check albums, maps and
## Roll back
+::: danger Restore the database when rolling back
Migrations may change the database schema. To roll back, stop the new container, restore the complete backup from before the upgrade and start the original image tag. Downgrading only the image while retaining a migrated database is not a reliable rollback.
+
+:::
diff --git a/docs/guide/usage.md b/docs/guide/usage.md
index 5cf8b9fd..5f7c22cc 100644
--- a/docs/guide/usage.md
+++ b/docs/guide/usage.md
@@ -7,14 +7,19 @@ Sign in and open `/dashboard`. Select files or drag them onto the Photos page to
- Sort and filter the photo table and choose which columns to show. ChronoFrame remembers column visibility and supports sorting by upload date.
- Select photos to delete, download, reindex or add them to albums in batches. You can also use Shift + click range selection.
- Edit photo metadata such as title, description and rating.
-- For Apple Live Photos, use matching image and MOV filenames, such as `IMG_1234.heic` and `IMG_1234.mov`. Either file can be uploaded first; pairing can be retried in the dashboard.
- Motion Photos with embedded video are also supported. The WebGL viewer provides zoom, pan and tiled rendering for large images.
+::: tip Pairing Live Photos
+For Apple Live Photos, use matching image and MOV filenames, such as `IMG_1234.heic` and `IMG_1234.mov`. Either file can be uploaded first; pairing can be retried in the dashboard.
+:::
+
## Albums and visibility
Albums group photos by subject. ChronoFrame supports ordering for both albums and the photos within them.
+::: warning Hidden albums also affect shared photos
Hidden albums restrict public visibility. ChronoFrame also restricts anonymous access to their photos, even when a photo belongs to a public album as well. Check the public gallery after changing visibility.
+:::
ChronoFrame supports album passwords with a minimum of six characters. Visitors must unlock the album to browse it in ChronoFrame, and photo shares retain the album access scope.
@@ -38,18 +43,33 @@ Site details, maps, location services, storage and upload limits can be edited i
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.
+::: tip After changing settings
-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.
+- **Place-name language**: reindex existing locations to update saved names.
+- **Storage scheme**: confirm existing photos still open. Switching does not move originals; local paths must remain inside a mounted directory.
-The upload privacy option applies to future uploads; it does not automatically clean previously uploaded files. For existing photos, use the individual or batch location-removal action and confirm completion in the task queue. Check descriptions and tags for information you do not want to publish as well.
+:::
+
+::: warning Privacy settings do not clean older files
+Location removal on upload applies to future uploads. For existing photos, run the individual or batch removal action and confirm completion in the queue. Check descriptions and tags before publishing too.
+:::
## GitHub login
Sign in with the email and password created during setup, then enable GitHub OAuth in system settings and enter the Client ID and Client Secret. Set the OAuth application's callback URL to `https://your-domain/api/auth/github`.
+::: info GitHub login does not grant admin access
The email returned by GitHub must match an existing administrator. Enabling OAuth does not grant administrator access to every GitHub user; unauthorized accounts are rejected.
+:::
## Troubleshoot uploads
-Use the task queue for processing errors and the log page for live and historical logs. For rejected uploads, check both the application and proxy size limits. For storage failures, check directory permissions or remote credentials. Include your version, storage type and relevant logs when reporting a problem, removing tokens and secrets first.
+| Symptom | Where to check |
+| ------------------ | ------------------------------------------- |
+| Upload rejected | Application and proxy size limits |
+| Storage failure | Directory permissions or remote credentials |
+| Processing failure | Task errors, retry results and the log page |
+
+::: tip Reporting a problem
+Include your version, storage type and relevant logs. Remove tokens, credentials and private information first.
+:::
diff --git a/docs/zh/changelog.md b/docs/zh/changelog.md
index 8824e571..5cde9eee 100644
--- a/docs/zh/changelog.md
+++ b/docs/zh/changelog.md
@@ -45,13 +45,15 @@
- 重做 Docker 运行镜像,补齐 TLS 证书、Perl 和 ExifTool 运行依赖。运行镜像不再提供 shell 和包管理器。
- 旧环境变量配置文档归档到 Legacy;新部署以设置向导为入口。
-### 升级注意
+::: warning 升级注意
- 首次升级保留旧环境变量,迁移后在后台核对设置和存储路径。
- 相册密码不能阻止通过公开的 S3、OpenList 或 CDN 地址访问原图,需要同时管理外部存储权限。
- 隐藏相册中的照片会从匿名访问中排除,可能影响它们在公开相册中的展示。
- 更新前备份完整数据;回退时同时恢复迁移前的数据库。
+:::
+
## v0.14.1
2025-10-28 · [发布记录](https://github.com/HoshinoSuzumi/chronoframe/releases/tag/v0.14.1) · [代码变更](https://github.com/HoshinoSuzumi/chronoframe/compare/v0.14.0...v0.14.1)
diff --git a/docs/zh/configuration/map-providers.md b/docs/zh/configuration/map-providers.md
index 6b2c1b08..a22b2433 100644
--- a/docs/zh/configuration/map-providers.md
+++ b/docs/zh/configuration/map-providers.md
@@ -9,7 +9,9 @@
| MapLibre | 开源 MapLibre GL JS | MapTiler | 使用内置样式时需要 MapTiler API Key |
| Mapbox | Mapbox GL JS | Mapbox | Mapbox 公共访问令牌 |
+::: info 渲染器与地图数据服务
MapLibre 是渲染器,MapTiler 是提供地图数据的服务,两者不是同一个产品。默认 MapLibre 样式随站点明暗主题切换;自定义样式会覆盖内置样式。服务的免费额度、商用要求和计费以各自官网为准。
+:::
## MapLibre + MapTiler
@@ -19,7 +21,9 @@ MapLibre 是渲染器,MapTiler 是提供地图数据的服务,两者不是
4. 在 MapTiler 的 Key 设置中配置 **Allowed HTTP origins**,填写画廊的来源地址,例如 `https://gallery.example.com`;本地调试另加 `http://localhost:3000`。
5. 保存设置并打开地球仪或带 GPS 的照片详情,检查地图是否正常加载。
+::: warning 限制 Key 的使用来源
Key 会被浏览器用于请求地图,所以不要把它当作只存在服务器上的秘密。来源限制的说明见 [MapTiler API Key 指南](https://docs.maptiler.com/guides/credentials/api-key/)。
+:::
### 自定义样式
@@ -29,7 +33,13 @@ Key 会被浏览器用于请求地图,所以不要把它当作只存在服务
https://api.maptiler.com/maps/streets-v2/style.json?key=YOUR_MAPTILER_KEY
```
-这是样式地址,不能填预览页面或嵌入 HTML。若地址中包含 Key,请使用自己创建的 Key;更换令牌时也要检查样式地址。自托管样式需保证瓦片、字体和图标地址可由访客浏览器访问,并允许跨域请求。
+::: tip 填写 Style JSON 地址
+
+- 填写样式地址,不要填预览页或嵌入 HTML。
+- 地址中的 Key 使用自己的;更换令牌时也检查样式地址。
+- 自托管样式的瓦片、字体和图标必须可由访客浏览器访问,并允许跨域请求。
+
+:::
## Mapbox
@@ -63,6 +73,8 @@ mapbox://styles/YOUR_USERNAME/YOUR_STYLE_ID
## 暂不配置及排查
+::: tip 地图可以稍后设置
设置向导允许先跳过令牌,之后在本页补齐。仍可上传和管理照片。MapLibre 仅在令牌和自定义样式均未配置时提示尚未设置;使用内置 MapTiler 样式需要 API Key。
+:::
地图空白或请求出现 401 / 403 时,核对选择的提供器、令牌、当前域名限制,以及样式、瓦片和字体的访问权限。站点从 localhost 换成正式域名后,要同步修改服务商的来源限制。
diff --git a/docs/zh/configuration/storage-providers.md b/docs/zh/configuration/storage-providers.md
index 49425656..e72984ea 100644
--- a/docs/zh/configuration/storage-providers.md
+++ b/docs/zh/configuration/storage-providers.md
@@ -1,6 +1,10 @@
# 存储方案
-在 **站点设置 → 存储设置** 中添加、编辑或设为默认方案,连接信息直接填写到表单。更换默认方案只影响后续上传,已有文件不会自动迁移;迁移前请保留原方案和备份。
+在 **站点设置 → 存储设置** 中添加、编辑或设为默认方案,连接信息直接填写到表单。
+
+::: warning 切换方案不会迁移文件
+更换默认方案只影响后续上传,已有文件不会自动迁移;迁移前请保留原方案和备份。
+:::
## 选择哪种存储
@@ -18,7 +22,9 @@
添加方案时选择“本地存储”,基础路径填写容器内的 `/app/data/storage`,与快速开始中的 `./data:/app/data` 挂载配合使用。访问地址通常保留 `/storage`。
+::: tip 填写容器内路径
这里填的是**容器内路径**,不是宿主机路径。想使用另一块磁盘,可先增加 `./photos:/app/photos` 挂载,再把基础路径填写为 `/app/photos`。确认运行应用的用户有读写权限,并单独备份该目录。
+:::
## S3 兼容存储
@@ -50,7 +56,17 @@
| 腾讯云 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)。
+::: info R2 的上传和读取地址不同
+R2 的 S3 Endpoint 用于签名上传,不能当成公开图片域名。将可访问对象的域名填写为 CDN URL;正式站点可使用自定义域名。
+:::
+
+::: details 服务商参考文档
+
+- Cloudflare 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
@@ -75,13 +91,17 @@ R2 的 S3 Endpoint 用于签名上传,不能当成公开图片域名。将可
- OSS / COS 等控制台若使用逐项表单,按同样的来源、方法、请求头和暴露头填写。
- 使用 CDN 时也要检查图片响应中的跨域头。修改规则后,旧缓存可能需要刷新。
+::: info CORS 不等于访问权限
详细字段见 [AWS CORS 文档](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html)和 [R2 CORS 文档](https://developers.cloudflare.com/r2/buckets/cors/)。CORS 解决浏览器跨域请求,不会授予密钥权限,也不能代替文件访问控制。
+:::
### 图片读取与密码相册
验证上传成功后,还要从访客视角打开图片,确认读取地址、对象路径和 HTTPS 都正确。不要为了排查 CORS 就开放整个桶。
+::: warning 密码相册请使用本地存储
当前远端存储的媒体直链不能保证经过 ChronoFrame 的相册授权。需要保护密码相册中的文件时,使用本地存储;公开 S3、OpenList 或 CDN 的直链和缓存不会因修改相册密码而撤销。
+:::
## OpenList
@@ -90,7 +110,9 @@ R2 的 S3 Endpoint 用于签名上传,不能当成公开图片域名。将可
3. 在 ChronoFrame 添加 OpenList 方案:服务地址填写 `https://openlist.example.com`,根路径填写 `/115pan/chronoframe` 等 OpenList 中的实际路径,再填入令牌。
4. 先上传一张照片并检查能否打开原图。目录权限、服务网络和下载地址有效期都可能影响结果。
+::: details OpenList 高级接口设置
标准服务通常保留高级接口默认值:上传 `/api/fs/put`、删除 `/api/fs/remove`、元数据 `/api/fs/get`,路径字段为 `path`。只有反向代理或服务接口有改动时才调整。可另填 CDN URL,但要确认它与真实对象路径一致。服务相关说明见 [OpenList 文档](https://doc.oplist.org/)。
+:::
## 常见问题
diff --git a/docs/zh/development/api.md b/docs/zh/development/api.md
index fd0f2d33..e1fa43f6 100644
--- a/docs/zh/development/api.md
+++ b/docs/zh/development/api.md
@@ -2,7 +2,9 @@
API 与网页使用同一套会话认证。需要登录的请求携带登录后获得的 Cookie;后台设置和管理操作还会检查管理员权限。
+::: info 接口范围
下面列出常用入口,完整参数、响应和访问规则以 `server/api/` 的路由及其 Zod 校验为准。这不是一份固定版本的外部 API 合约。
+:::
| 方法 | 路径 | 用途 |
| ---- | ------------------------------------------- | ---------------------------------------- |
@@ -30,4 +32,8 @@ API 与网页使用同一套会话认证。需要登录的请求携带登录后
}
```
-新增设置或修改设置表单,请阅读[设置开发指南](/zh/development/how-to-add-setting)。照片读取需要遵守相册可见性和密码访问规则,不要将后台照片列表当作公开接口使用。
+新增设置或修改设置表单,请阅读[设置开发指南](/zh/development/how-to-add-setting)。
+
+::: warning 后台接口不是公开照片接口
+照片读取需要遵守相册可见性和密码访问规则,不要将后台照片列表当作公开接口使用。
+:::
diff --git a/docs/zh/development/contributing.md b/docs/zh/development/contributing.md
index cf4ec1cc..30da892d 100644
--- a/docs/zh/development/contributing.md
+++ b/docs/zh/development/contributing.md
@@ -12,7 +12,9 @@ pnpm install --frozen-lockfile
pnpm dev
```
+::: tip 本地初始化
打开 `http://localhost:3000`,按设置向导创建管理员并选择本地存储。开发时可以使用 `./data/storage`。数据库在启动时自动迁移,无需为启动项目生成新的迁移文件,也无需填写最小环境变量配置。
+:::
## 常用命令
@@ -28,7 +30,9 @@ pnpm docs:build
`pnpm dev` 同时启动 WebGL 包的开发构建和 Nuxt。已有依赖构建时,可使用 `pnpm dev:only` 单独启动 Nuxt。代码检查使用 Oxlint,格式化使用 Oxfmt。
+::: warning 检查迁移和提交内容
修改数据库 schema 后使用 `pnpm db:generate` 生成迁移,并检查生成的 SQL;`pnpm db:migrate` 可手动应用迁移。提交前不要把本地数据库、照片或访问密钥放进 Git。
+:::
## 代码位置
diff --git a/docs/zh/development/how-to-add-setting.md b/docs/zh/development/how-to-add-setting.md
index 0c33518a..0d28051a 100644
--- a/docs/zh/development/how-to-add-setting.md
+++ b/docs/zh/development/how-to-add-setting.md
@@ -31,7 +31,13 @@
- `isSecret`: 是否为机密字段(如密码)
- `enum`: 枚举值数组
-> 💡 **注意**:不需要在 DEFAULT_SETTINGS 中添加 `label` 和 `description`。SettingField 组件会自动生成翻译键 `settings.${namespace}.${key}.label` 和 `settings.${namespace}.${key}.description`
+::: tip 翻译键自动生成
+不需要在 `DEFAULT_SETTINGS` 中添加 `label` 和 `description`。`SettingField` 会自动生成翻译键 `settings.${namespace}.${key}.label` 和 `settings.${namespace}.${key}.description`。
+:::
+
+::: warning 不要公开凭据
+`isPublic` 仅用于访客可以读取的值;访问密钥等凭据应标为 `isSecret`,并检查公开设置响应中没有这些内容。
+:::
## 步骤 2:添加 UI 配置
diff --git a/docs/zh/guide/configuration.md b/docs/zh/guide/configuration.md
index 38d0fdc9..2b15f0ed 100644
--- a/docs/zh/guide/configuration.md
+++ b/docs/zh/guide/configuration.md
@@ -1,5 +1,7 @@
# 旧配置文档
+::: info 旧配置文档已归档
此页已归档。新部署请使用[设置向导](/zh/guide/getting-started),已有实例的设置可在后台修改。
+:::
[查看历史文档](/zh/legacy/guide/configuration)
diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md
index 4fc8bdce..92362583 100644
--- a/docs/zh/guide/getting-started.md
+++ b/docs/zh/guide/getting-started.md
@@ -45,13 +45,17 @@ docker run -d --name chronoframe --restart unless-stopped \
## 进入仪表盘
+::: tip 首次进入会有指引
完成向导后进入 `/dashboard`。第一次访问仪表盘、照片库和各设置页时,会有分步指引,带你找到上传入口、队列和常用设置。可以随时跳过;需要重新查看时,在 **站点设置 → 系统设置** 中重置指引。
+:::
![仪表盘概览:左侧为照片库、队列和站点设置,右侧为照片统计和任务状态](/images/dashboard-overview.jpg)
### 上传第一张照片
-打开 **照片库**,选择文件或拖入照片开始上传。上传结束后,应用还会在后台提取 EXIF、生成缩略图和识别地点;到 **队列管理** 查看是否完成,再打开画廊检查效果。遇到失败任务,可以查看错误原因并重试。
+1. 打开 **照片库**,选择文件或拖入照片开始上传。
+2. 到 **队列管理** 等待 EXIF 提取、缩略图和地点识别完成。
+3. 打开画廊检查效果;失败任务可以查看原因并重试。
本地存储可以直接开始使用。S3 的访问密钥和 CORS、OpenList 的服务地址与令牌,以及地图服务的 Key,都在对应的服务指南中说明,无需换成环境变量。
@@ -59,13 +63,17 @@ docker run -d --name chronoframe --restart unless-stopped \
`./data:/app/data` 是部署中必须保留的挂载。默认数据库为 `/app/data/app.sqlite3`,会话密钥自动生成并保存在 `/app/data/.session-password`。使用上述本地路径时,原图和衍生文件也在这个目录下。
+::: warning 更新时保留数据
不要删除数据目录来更新应用。S3 和 OpenList 的文件存放在外部服务中,需要另外备份;只备份数据库无法恢复丢失的原图。
+:::
## 使用域名和 HTTPS
可以在容器前使用 Caddy、Nginx 或 Traefik。反向代理的上传大小上限应与后台设置匹配,并保留流式响应,供实时日志使用。
+::: warning 仅信任受控代理
只有在 3000 端口只能被可信代理访问、且代理会覆盖用户传入的 `X-Forwarded-For` 时,才启用 `NUXT_TRUST_PROXY=true`。这项部署设置仍使用环境变量,例如在 Compose 中加入:
+:::
```yaml
environment:
diff --git a/docs/zh/guide/updates.md b/docs/zh/guide/updates.md
index 53bee8f5..c770da45 100644
--- a/docs/zh/guide/updates.md
+++ b/docs/zh/guide/updates.md
@@ -4,7 +4,14 @@
## 备份
-停止容器后备份整个数据目录和 Compose 文件。如果旧部署仍使用 `.env`,也要保存它;本地存储不在 `data` 中时,需要额外备份对应目录。S3 和 OpenList 的文件应在外部服务中单独备份。
+::: warning 先停止服务并备份
+停止容器后,备份以下内容:
+
+- 整个数据目录和 Compose 文件。
+- 旧部署仍在使用的 `.env`。
+- `data` 目录之外的本地照片,以及 S3 / OpenList 中的外部文件。
+
+:::
```bash
docker compose stop chronoframe
@@ -23,7 +30,9 @@ docker compose up -d chronoframe
docker compose logs -f chronoframe
```
+::: info 启动时自动迁移
容器启动时会自动执行数据库迁移,正常情况下无需手动运行迁移命令。当前运行镜像不包含 shell 和包管理器,旧文档中的 `docker exec ... sh` 或容器内 `npx drizzle-kit migrate` 不适用。
+:::
直接使用 `docker run` 的部署,先停止并移除旧容器,再用新标签和相同的数据挂载重建。保留原有的端口、网络和仍有用途的部署环境变量。
@@ -41,4 +50,7 @@ docker compose logs -f chronoframe
## 回退
+::: danger 回退时同时恢复数据库
数据库迁移可能改变结构。需要回退时,停止新容器,恢复升级前的完整数据备份,再使用原版本标签启动。不要只降级镜像并继续使用已经迁移的数据库。
+
+:::
diff --git a/docs/zh/guide/usage.md b/docs/zh/guide/usage.md
index 13a7e4bf..5c28fc91 100644
--- a/docs/zh/guide/usage.md
+++ b/docs/zh/guide/usage.md
@@ -7,14 +7,19 @@
- 照片表格支持排序、筛选和自选显示列,并记住列的显示状态,也支持按上传日期排序。
- 选中照片后可以批量删除、下载、重新索引或加入相册。支持 Shift + 单击连续选择。
- 编辑照片可以修改标题、描述、评分等元数据。
-- Apple Live Photo 的照片和 MOV 文件使用同一文件名,例如 `IMG_1234.heic` 和 `IMG_1234.mov`。上传顺序不限,配对失败时可在后台重新处理。
- 也支持带有嵌入视频的 Motion Photo。大图由 WebGL 查看器显示,支持平移、缩放和分块渲染。
+::: tip 实况照片配对
+Apple Live Photo 的照片和 MOV 文件使用同一文件名,例如 `IMG_1234.heic` 和 `IMG_1234.mov`。上传顺序不限,配对失败时可在后台重新处理。
+:::
+
## 相册和可见性
相册可将同一主题的照片集中展示,支持相册排序和相册内照片排序。
+::: warning 隐藏相册也会影响公开相册中的照片
隐藏相册用于限制公开展示,同时限制匿名访客访问其中的照片,即使该照片还属于公开相册;请在调整可见性后检查公开画廊的结果。
+:::
也可以为相册设置密码,密码至少 6 个字符。访客需要解锁才能在 ChronoFrame 中查看相册内容,分享其中照片时也会保留相册访问范围。
@@ -38,18 +43,33 @@
存储选型、凭据与 CORS 见[存储方案](/zh/configuration/storage-providers);地图令牌与样式设置见[地图和位置](/zh/configuration/map-providers)。
-地图负责显示,位置服务负责将 GPS 坐标转换成地名,两者分别设置。更改地名语言后,已有照片需要重新索引位置才能更新保存的地名。
+::: tip 修改设置后检查
-更换存储方案前,请确认已有照片仍能访问。选择新方案不等于将原图自动搬到新存储中。本地存储路径必须位于已挂载的目录内,容器才能在重建后继续访问文件。
+- **地名语言**:已有地点名称不会自动更新,需要重新索引位置。
+- **存储方案**:确认已有照片仍能打开;切换方案不会迁移原图,本地路径应位于挂载目录内。
-隐私设置影响之后的上传,不会自动清理过去上传的文件。已有照片可以在照片管理中单独或批量执行移除位置信息,并在任务队列中确认完成。公开前也应检查照片描述和标签是否含有不希望分享的信息。
+:::
+
+::: warning 隐私设置不追溯旧文件
+上传时移除位置信息只影响后续上传。已有照片需单独或批量执行移除操作,并在任务队列中确认完成。公开前也检查描述和标签。
+:::
## GitHub 登录
先使用向导创建的邮箱和密码登录,再在系统设置中开启 GitHub OAuth,填写 Client ID 和 Client Secret。OAuth 应用的回调地址填写 `https://你的域名/api/auth/github`。
+::: info GitHub 登录不会自动授予管理员权限
GitHub 返回的邮箱需要匹配已有管理员的邮箱。启用 OAuth 不会让任意 GitHub 用户成为管理员;未获授权的账号会被拒绝登录。
+:::
## 排查上传问题
-任务队列显示处理进度和失败原因,日志页可以查看实时日志和历史记录。遇到上传被拒绝时,先核对应用和反向代理的文件大小限制;遇到存储失败时,检查目录写入权限或远端凭据。反馈问题时附上版本号、使用的存储类型和相关日志,并去掉令牌、密钥等私人信息。
+| 现象 | 检查位置 |
+| ---------- | ------------------------------------ |
+| 上传被拒绝 | 应用和反向代理的文件大小限制 |
+| 存储失败 | 本地目录权限或远端凭据 |
+| 处理失败 | 任务队列的错误原因、重试结果及日志页 |
+
+::: tip 反馈问题时
+附上版本号、存储类型和相关日志,去掉令牌、密钥等私人信息。
+:::