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: add tabbed and step components for provider guides

Timothy Yin27f622f3b98c
diff --git a/docs/.vitepress/theme/components/DocStep.vue b/docs/.vitepress/theme/components/DocStep.vue
new file mode 100644
index 00000000..5a6bab57
--- /dev/null
+++ b/docs/.vitepress/theme/components/DocStep.vue
@@ -0,0 +1,56 @@
+<script setup lang="ts">
+defineProps<{ number: string; label: string }>()
+</script>
+
+<template>
+ <section
+ class="doc-step"
+ :aria-label="label"
+ >
+ <span
+ class="step-number"
+ aria-hidden="true"
+ >{{ number }}</span
+ >
+ <div class="step-body"><slot /></div>
+ </section>
+</template>
+
+<style scoped>
+.doc-step {
+ position: relative;
+ padding: 0 0 12px 44px;
+ margin: 24px 0;
+ border-left: 1px solid var(--vp-c-divider);
+}
+.step-number {
+ position: absolute;
+ left: -16px;
+ top: 0;
+ display: grid;
+ place-items: center;
+ width: 32px;
+ height: 32px;
+ border: 1px solid var(--vp-c-brand-1);
+ border-radius: 50%;
+ color: var(--vp-c-brand-1);
+ background: var(--vp-c-bg);
+ font-size: 14px;
+ font-weight: 600;
+}
+.step-body {
+ min-width: 0;
+ display: flow-root;
+}
+.step-body :deep(h2:first-child) {
+ margin-top: 0;
+ padding-top: 0;
+ border-top: 0;
+}
+@media (max-width: 640px) {
+ .doc-step {
+ margin-left: 16px;
+ padding-left: 28px;
+ }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/DocTabs.vue b/docs/.vitepress/theme/components/DocTabs.vue
new file mode 100644
index 00000000..4fefe333
--- /dev/null
+++ b/docs/.vitepress/theme/components/DocTabs.vue
@@ -0,0 +1,128 @@
+<script setup lang="ts">
+import { nextTick, onBeforeUnmount, onMounted, ref, useId } from 'vue'
+
+const props = defineProps<{
+ tabs: { id: string; label: string }[]
+ label: string
+}>()
+const instanceId = useId()
+const active = ref(props.tabs[0]?.id)
+const root = ref<HTMLElement>()
+
+async function navigate(event: KeyboardEvent, index: number) {
+ let next = index
+ if (event.key === 'ArrowRight') next = (index + 1) % props.tabs.length
+ else if (event.key === 'ArrowLeft')
+ next = (index - 1 + props.tabs.length) % props.tabs.length
+ else if (event.key === 'Home') next = 0
+ else if (event.key === 'End') next = props.tabs.length - 1
+ else return
+ event.preventDefault()
+ active.value = props.tabs[next].id
+ await nextTick()
+ root.value?.querySelectorAll<HTMLButtonElement>('[role="tab"]')[next]?.focus()
+}
+
+function revealHash() {
+ let hash: string
+ try {
+ hash = decodeURIComponent(window.location.hash.slice(1))
+ } catch {
+ return
+ }
+ if (!hash) return
+ const target = document.getElementById(hash)
+ const panel = target?.closest<HTMLElement>('[data-doc-tab]')
+ if (panel && root.value?.contains(panel)) {
+ active.value = panel.dataset.docTab
+ nextTick(() => target?.scrollIntoView())
+ }
+}
+onMounted(() => {
+ revealHash()
+ window.addEventListener('hashchange', revealHash)
+})
+onBeforeUnmount(() => window.removeEventListener('hashchange', revealHash))
+</script>
+
+<template>
+ <div
+ ref="root"
+ class="doc-tabs"
+ >
+ <div
+ class="doc-tab-list"
+ role="tablist"
+ :aria-label="label"
+ >
+ <button
+ v-for="(tab, index) in tabs"
+ :id="`${instanceId}-tab-${tab.id}`"
+ :key="tab.id"
+ type="button"
+ role="tab"
+ :aria-selected="active === tab.id"
+ :aria-controls="`${instanceId}-panel-${tab.id}`"
+ :tabindex="active === tab.id ? 0 : -1"
+ @click="active = tab.id"
+ @keydown="navigate($event, index)"
+ >
+ {{ tab.label }}
+ </button>
+ </div>
+ <div
+ v-for="tab in tabs"
+ v-show="active === tab.id"
+ :id="`${instanceId}-panel-${tab.id}`"
+ :key="tab.id"
+ :data-doc-tab="tab.id"
+ role="tabpanel"
+ :aria-labelledby="`${instanceId}-tab-${tab.id}`"
+ tabindex="0"
+ class="doc-tab-panel"
+ >
+ <slot :name="tab.id" />
+ </div>
+ </div>
+</template>
+
+<style scoped>
+.doc-tabs {
+ margin: 20px 0 28px;
+}
+.doc-tab-list {
+ display: flex;
+ gap: 4px;
+ overflow-x: auto;
+ padding: 4px;
+ border: 1px solid var(--vp-c-divider);
+ border-radius: 10px;
+ background: var(--vp-c-bg-soft);
+}
+.doc-tab-list button {
+ flex: 0 0 auto;
+ padding: 7px 14px;
+ border-radius: 6px;
+ color: var(--vp-c-text-2);
+ font-size: 14px;
+ font-weight: 500;
+ line-height: 24px;
+ cursor: pointer;
+}
+.doc-tab-list button:hover {
+ color: var(--vp-c-brand-1);
+}
+.doc-tab-list button[aria-selected='true'] {
+ color: var(--vp-c-brand-1);
+ background: var(--vp-c-bg);
+ box-shadow: 0 1px 4px rgb(0 0 0 / 8%);
+}
+.doc-tab-list button:focus-visible,
+.doc-tab-panel:focus-visible {
+ outline: 2px solid var(--vp-c-brand-1);
+ outline-offset: 2px;
+}
+.doc-tab-panel {
+ padding-top: 4px;
+}
+</style>
diff --git a/docs/.vitepress/theme/components/StorageChoices.vue b/docs/.vitepress/theme/components/StorageChoices.vue
new file mode 100644
index 00000000..02323afc
--- /dev/null
+++ b/docs/.vitepress/theme/components/StorageChoices.vue
@@ -0,0 +1,140 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useData } from 'vitepress'
+const { lang } = useData()
+const chinese = computed(() => lang.value.startsWith('zh'))
+const choices = computed(() =>
+ chinese.value
+ ? [
+ {
+ title: '本地文件系统',
+ tag: '直接开始',
+ href: '#本地文件系统',
+ text: '把照片保存在自己的服务器或 NAS。',
+ need: '准备可写的挂载目录',
+ note: '自行管理磁盘容量和备份',
+ },
+ {
+ title: 'S3 兼容存储',
+ tag: '对象存储',
+ href: '#s3-兼容存储',
+ text: '接入云存储或已有的 MinIO 服务。',
+ need: '准备存储桶、Endpoint 和密钥',
+ note: '配置 CORS 和图片读取地址',
+ },
+ {
+ title: 'OpenList',
+ tag: '网盘与 NAS',
+ href: '#openlist',
+ text: '使用已经挂载到 OpenList 的存储。',
+ need: '准备服务地址、根路径和令牌',
+ note: '检查权限、限速和下载地址有效期',
+ },
+ ]
+ : [
+ {
+ title: 'Local filesystem',
+ tag: 'Start here',
+ href: '#local-filesystem',
+ text: 'Keep photos on your own server or NAS.',
+ need: 'A writable, mounted directory',
+ note: 'Manage disk capacity and backups',
+ },
+ {
+ title: 'S3-compatible',
+ tag: 'Object storage',
+ href: '#s3-compatible-storage',
+ text: 'Connect cloud storage or an existing MinIO service.',
+ need: 'Bucket, endpoint and credentials',
+ note: 'Configure CORS and image read URLs',
+ },
+ {
+ title: 'OpenList',
+ tag: 'Drives and NAS',
+ href: '#openlist',
+ text: 'Use storage already mounted in OpenList.',
+ need: 'Service URL, root path and token',
+ note: 'Check permissions, limits and URL expiry',
+ },
+ ],
+)
+</script>
+
+<template>
+ <div class="storage-choices">
+ <a
+ v-for="choice in choices"
+ :key="choice.href"
+ :href="choice.href"
+ class="storage-choice"
+ >
+ <span class="choice-tag">{{ choice.tag }}</span>
+ <strong>{{ choice.title }} <span aria-hidden="true">↗</span></strong>
+ <span class="choice-text">{{ choice.text }}</span>
+ <span class="choice-notes"
+ ><span>{{ choice.need }}</span
+ ><span>{{ choice.note }}</span></span
+ >
+ </a>
+ </div>
+</template>
+
+<style scoped>
+.storage-choices {
+ display: grid;
+ grid-template-columns: repeat(3, minmax(0, 1fr));
+ gap: 12px;
+ margin: 20px 0;
+}
+.storage-choice {
+ display: flex;
+ flex-direction: column;
+ gap: 10px;
+ padding: 16px;
+ border: 1px solid var(--vp-c-divider);
+ border-radius: 10px;
+ text-decoration: none;
+ color: var(--vp-c-text-1);
+}
+.storage-choice:hover {
+ border-color: var(--vp-c-brand-1);
+ background: var(--vp-c-bg-soft);
+}
+.storage-choice:focus-visible {
+ outline: 2px solid var(--vp-c-brand-1);
+ outline-offset: 3px;
+}
+.choice-tag {
+ color: var(--vp-c-brand-1);
+ font-size: 12px;
+ font-weight: 500;
+}
+.storage-choice strong {
+ font-size: 16px;
+}
+.storage-choice strong span {
+ float: right;
+ color: var(--vp-c-text-3);
+}
+.choice-text {
+ color: var(--vp-c-text-2);
+ font-size: 14px;
+ line-height: 1.6;
+}
+.choice-notes {
+ display: flex;
+ flex-direction: column;
+ gap: 5px;
+ margin-top: auto;
+ padding-top: 10px;
+ border-top: 1px solid var(--vp-c-divider);
+ color: var(--vp-c-text-2);
+ font-size: 12px;
+ line-height: 1.6;
+}
+@media (max-width: 700px) {
+ .storage-choices {
+ grid-template-columns: 1fr;
+ }
+}
+</style>
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 9d5d27b2..76f521d9 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -2,12 +2,18 @@ import type { App } from 'vue'
import DefaultTheme from 'vitepress/theme'
import AdsenseToc from './components/AdsenseToc.vue'
import Layout from './Layout.vue'
+import DocTabs from './components/DocTabs.vue'
+import StorageChoices from './components/StorageChoices.vue'
+import DocStep from './components/DocStep.vue'
import DemoSites from './components/DemoSites.vue'
export default {
...DefaultTheme,
enhanceApp({ app }: { app: App }) {
app.component('AdsenseToc', AdsenseToc)
+ app.component('DocTabs', DocTabs)
+ app.component('StorageChoices', StorageChoices)
+ app.component('DocStep', DocStep)
app.component('DemoSites', DemoSites)
},
Layout,
diff --git a/docs/configuration/map-providers.md b/docs/configuration/map-providers.md
index 39d3224b..1cafa8cf 100644
--- a/docs/configuration/map-providers.md
+++ b/docs/configuration/map-providers.md
@@ -13,6 +13,10 @@ Open **Site settings → Maps and locations**. Map display and place-name lookup
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.
:::
+<DocTabs label="Map service" :tabs="[{ id: 'maplibre', label: 'MapLibre + MapTiler' }, { id: 'mapbox', label: 'Mapbox' }]">
+
+<template #maplibre>
+
## MapLibre + MapTiler
1. Sign in to [MapTiler Cloud](https://cloud.maptiler.com/).
@@ -41,6 +45,10 @@ https://api.maptiler.com/maps/streets-v2/style.json?key=YOUR_MAPTILER_KEY
:::
+</template>
+
+<template #mapbox>
+
## Mapbox
1. Sign in to [Mapbox](https://console.mapbox.com/).
@@ -61,6 +69,10 @@ mapbox://styles/YOUR_USERNAME/YOUR_STYLE_ID
The token must be able to read the style. Do not use the Studio editor URL.
+</template>
+
+</DocTabs>
+
## Place-name lookup
Location settings further down the same page include:
diff --git a/docs/configuration/storage-providers.md b/docs/configuration/storage-providers.md
index 87302a5a..529c612e 100644
--- a/docs/configuration/storage-providers.md
+++ b/docs/configuration/storage-providers.md
@@ -8,11 +8,7 @@ Switching the default affects future uploads; existing files are not moved. Keep
## 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 |
+<StorageChoices />
::: tip
Files copied or uploaded directly to any storage backend will not automatically appear in the gallery. Use the ChronoFrame dashboard to upload new media so it can be indexed and processed. Support for scanning and importing media already in storage is planned for a future release.
@@ -48,18 +44,69 @@ This is a **container path**, not a host path. To use another disk, add a mount
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 |
+<DocTabs label="S3 provider" :tabs="[{ id: 'aws', label: 'AWS S3' }, { id: 'r2', label: 'Cloudflare R2' }, { id: 'oss', label: 'Alibaba Cloud OSS' }, { id: 'cos', label: 'Tencent COS' }, { id: 'minio', label: 'MinIO' }]">
+
+<template #aws>
+
+| Field | Value |
+| -------- | ------------------------------------ |
+| Endpoint | `https://s3.us-east-1.amazonaws.com` |
+| Region | `us-east-1` |
+
+Use IAM access keys scoped to the bucket
+
+</template>
+
+<template #r2>
+
+| Field | Value |
+| -------- | ----------------------------------------------- |
+| Endpoint | `https://<ACCOUNT_ID>.r2.cloudflarestorage.com` |
+| Region | `auto` |
+
+An R2 API token provides S3 credentials; configure a separate domain for image reads
::: 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.
:::
+</template>
+
+<template #oss>
+
+| Field | Value |
+| -------- | --------------------------------------------------- |
+| Endpoint | `https://oss-cn-hangzhou.aliyuncs.com` |
+| Region | Follow the service's S3 compatibility configuration |
+
+Use RAM AccessKeys and the bucket's regional endpoint
+
+</template>
+
+<template #cos>
+
+| Field | Value |
+| -------- | ------------------------------------- |
+| Endpoint | `https://cos.ap-beijing.myqcloud.com` |
+| Region | `ap-beijing` |
+
+Use API credentials and the full bucket name including `-APPID`
+
+</template>
+
+<template #minio>
+
+| Field | Value |
+| -------- | --------------------------- |
+| Endpoint | `https://minio.example.com` |
+| Region | Service-configured region |
+
+Use the S3 API address, not the management console; enable Force Path Style for path-based access
+
+</template>
+
+</DocTabs>
+
::: 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/).
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 33e61b97..3978a373 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -4,6 +4,10 @@ ChronoFrame stores photo metadata and settings in SQLite. You only need Docker a
## Start the container
+<DocTabs label="Deployment method" :tabs="[{ id: 'compose', label: 'Docker Compose' }, { id: 'run', label: 'Docker Run' }]">
+
+<template #compose>
+
Create `docker-compose.yml`:
```yaml
@@ -18,14 +22,16 @@ services:
- ./data:/app/data
```
-For Docker Hub, replace the image with `hoshinosuzumi/chronoframe:latest`.
-
```bash
docker compose up -d
docker compose logs -f chronoframe
```
-Or use Docker directly:
+</template>
+
+<template #run>
+
+Start the container directly:
```bash
docker run -d --name chronoframe --restart unless-stopped \
@@ -33,6 +39,12 @@ docker run -d --name chronoframe --restart unless-stopped \
ghcr.io/hoshinosuzumi/chronoframe:latest
```
+</template>
+
+</DocTabs>
+
+For Docker Hub, replace the image with `hoshinosuzumi/chronoframe:latest`.
+
Open `http://localhost:3000`. A fresh installation opens the setup wizard; you do not need to create an `.env` file first.
## Complete the setup wizard
diff --git a/docs/guide/updates.md b/docs/guide/updates.md
index 713f40ad..4ccd0a92 100644
--- a/docs/guide/updates.md
+++ b/docs/guide/updates.md
@@ -2,6 +2,8 @@
Read the [changelog](/changelog) before choosing a target version and review its migration notes. The dashboard overview shows your running version.
+<DocStep number="1" label="Back up">
+
## Back up
::: warning Stop and back up first
@@ -20,6 +22,10 @@ cp -a data "backups/data-$(date +%Y%m%d-%H%M%S)"
cp docker-compose.yml backups/docker-compose.yml
```
+</DocStep>
+
+<DocStep number="2" label="Update and rollback">
+
## Replace the image
Change the image tag in Compose to the version you want, for example `v1.0.0`, then run:
@@ -44,13 +50,19 @@ For a `docker run` deployment, stop and remove the old container, then recreate
- If setup appears after upgrading, use the existing administrator email and confirm the original storage path. Check the data mount and startup logs before proceeding; do not create an empty replacement data directory.
- Preserve the session secret, database and storage paths. Deployment options such as proxy trust still belong in the runtime environment.
-## Check the result
-
-Sign in, open several existing photos, upload a photo and check albums, maps and the task queue. 1.0.0 adds access restrictions for photos in hidden albums; check your public gallery after upgrading.
-
## 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.
:::
+
+</DocStep>
+
+<DocStep number="3" label="Check">
+
+## Check the result
+
+Sign in, open several existing photos, upload a photo and check albums, maps and the task queue. 1.0.0 adds access restrictions for photos in hidden albums; check your public gallery after upgrading.
+
+</DocStep>
diff --git a/docs/zh/configuration/map-providers.md b/docs/zh/configuration/map-providers.md
index a22b2433..b2ed6ae1 100644
--- a/docs/zh/configuration/map-providers.md
+++ b/docs/zh/configuration/map-providers.md
@@ -13,6 +13,10 @@
MapLibre 是渲染器,MapTiler 是提供地图数据的服务,两者不是同一个产品。默认 MapLibre 样式随站点明暗主题切换;自定义样式会覆盖内置样式。服务的免费额度、商用要求和计费以各自官网为准。
:::
+<DocTabs label="地图服务" :tabs="[{ id: 'maplibre', label: 'MapLibre + MapTiler' }, { id: 'mapbox', label: 'Mapbox' }]">
+
+<template #maplibre>
+
## MapLibre + MapTiler
1. 注册或登录 [MapTiler Cloud](https://cloud.maptiler.com/)。
@@ -41,6 +45,10 @@ https://api.maptiler.com/maps/streets-v2/style.json?key=YOUR_MAPTILER_KEY
:::
+</template>
+
+<template #mapbox>
+
## Mapbox
1. 注册或登录 [Mapbox](https://console.mapbox.com/)。
@@ -61,6 +69,10 @@ mapbox://styles/YOUR_USERNAME/YOUR_STYLE_ID
该样式必须对当前令牌可读,不能填 Studio 编辑页的地址。
+</template>
+
+</DocTabs>
+
## 地点识别
同一页面下方的位置设置包括:
diff --git a/docs/zh/configuration/storage-providers.md b/docs/zh/configuration/storage-providers.md
index e72984ea..58aeab34 100644
--- a/docs/zh/configuration/storage-providers.md
+++ b/docs/zh/configuration/storage-providers.md
@@ -8,11 +8,7 @@
## 选择哪种存储
-| 提供器 | 适合的情况 | 需要准备 | 需要留意 |
-| ------------ | -------------------------------------------- | -------------------------------- | ----------------------------------------------- |
-| 本地文件系统 | 想先开始使用,或把照片放在自己的服务器 / NAS | 已挂载、可写的目录 | 磁盘容量和备份由自己管理 |
-| S3 兼容存储 | 使用云对象存储,或已有 MinIO 等服务 | 存储桶、Endpoint、区域、访问密钥 | 浏览器直传需要 CORS,图片访问需要可用的读取地址 |
-| OpenList | 已经用 OpenList 管理网盘或 NAS | 服务地址、根路径、令牌 | 上传权限、后端限速和下载地址有效期 |
+<StorageChoices />
::: tip
直接复制或上传到存储中的文件不会自动出现在画廊中。请通过 ChronoFrame 仪表盘上传新媒体,以便应用完成索引和处理。后续版本计划支持扫描并导入存储中已有的媒体文件。
@@ -48,18 +44,69 @@
以下地址是示例,请换成自己账号和区域的信息。
-| 服务 | 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 |
+<DocTabs label="S3 服务商" :tabs="[{ id: 'aws', label: 'AWS S3' }, { id: 'r2', label: 'Cloudflare R2' }, { id: 'oss', label: '阿里云 OSS' }, { id: 'cos', label: '腾讯云 COS' }, { id: 'minio', label: 'MinIO' }]">
+
+<template #aws>
+
+| 字段 | 填写值 |
+| -------- | ------------------------------------ |
+| Endpoint | `https://s3.us-east-1.amazonaws.com` |
+| Region | `us-east-1` |
+
+创建桶后使用 IAM 身份的访问密钥,并限制到目标桶
+
+</template>
+
+<template #r2>
+
+| 字段 | 填写值 |
+| -------- | ----------------------------------------------- |
+| Endpoint | `https://<ACCOUNT_ID>.r2.cloudflarestorage.com` |
+| Region | `auto` |
+
+创建 R2 API Token 后获得 Access Key ID 和 Secret Access Key;图片读取另配自定义域名
::: info R2 的上传和读取地址不同
R2 的 S3 Endpoint 用于签名上传,不能当成公开图片域名。将可访问对象的域名填写为 CDN URL;正式站点可使用自定义域名。
:::
+</template>
+
+<template #oss>
+
+| 字段 | 填写值 |
+| -------- | -------------------------------------- |
+| Endpoint | `https://oss-cn-hangzhou.aliyuncs.com` |
+| Region | 按服务的 S3 兼容配置填写 |
+
+从 RAM 身份获取 AccessKey,Endpoint 使用桶所在地域的地址
+
+</template>
+
+<template #cos>
+
+| 字段 | 填写值 |
+| -------- | ------------------------------------- |
+| Endpoint | `https://cos.ap-beijing.myqcloud.com` |
+| Region | `ap-beijing` |
+
+使用 API 密钥,Bucket 包含 `-APPID` 后缀
+
+</template>
+
+<template #minio>
+
+| 字段 | 填写值 |
+| -------- | --------------------------- |
+| Endpoint | `https://minio.example.com` |
+| Region | 服务配置的区域 |
+
+使用 S3 API 端口对应的地址,而不是管理控制台;按路径访问时开启 Force Path Style
+
+</template>
+
+</DocTabs>
+
::: details 服务商参考文档
- Cloudflare R2:[凭据获取](https://developers.cloudflare.com/r2/api/tokens/)、[公开访问](https://developers.cloudflare.com/r2/buckets/public-buckets/)。
diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md
index 966106d7..6d67222b 100644
--- a/docs/zh/guide/getting-started.md
+++ b/docs/zh/guide/getting-started.md
@@ -4,6 +4,10 @@ ChronoFrame 使用 SQLite 保存照片信息和设置,无需单独部署数据
## 启动容器
+<DocTabs label="部署方式" :tabs="[{ id: 'compose', label: 'Docker Compose' }, { id: 'run', label: 'Docker Run' }]">
+
+<template #compose>
+
创建 `docker-compose.yml`:
```yaml
@@ -18,14 +22,16 @@ services:
- ./data:/app/data
```
-也可以将镜像名换成 `hoshinosuzumi/chronoframe:latest`,从 Docker Hub 拉取。
-
```bash
docker compose up -d
docker compose logs -f chronoframe
```
-习惯直接使用 Docker 的话:
+</template>
+
+<template #run>
+
+直接启动容器:
```bash
docker run -d --name chronoframe --restart unless-stopped \
@@ -33,6 +39,12 @@ docker run -d --name chronoframe --restart unless-stopped \
ghcr.io/hoshinosuzumi/chronoframe:latest
```
+</template>
+
+</DocTabs>
+
+也可以将镜像名换成 `hoshinosuzumi/chronoframe:latest`,从 Docker Hub 拉取。
+
打开 `http://localhost:3000`,首次访问会进入设置向导。新部署不需要先填写 `.env`。
## 完成设置向导
diff --git a/docs/zh/guide/updates.md b/docs/zh/guide/updates.md
index c770da45..dd9079bc 100644
--- a/docs/zh/guide/updates.md
+++ b/docs/zh/guide/updates.md
@@ -2,6 +2,8 @@
升级前先查看[更新日志](/zh/changelog),确定目标版本及其迁移说明。可以在后台概览的运行信息中查看当前版本。
+<DocStep number="1" label="备份">
+
## 备份
::: warning 先停止服务并备份
@@ -20,6 +22,10 @@ cp -a data "backups/data-$(date +%Y%m%d-%H%M%S)"
cp docker-compose.yml backups/docker-compose.yml
```
+</DocStep>
+
+<DocStep number="2" label="更新与回退">
+
## 更新镜像
在 Compose 文件中将镜像标签改为目标版本,例如 `v1.0.0`,然后执行:
@@ -44,13 +50,19 @@ docker compose logs -f chronoframe
- 如果升级后进入向导,使用已有管理员邮箱,确认原存储路径,不要新建空数据目录。先核对挂载和启动日志,再继续操作。
- 会话密钥、数据库、存储路径等部署数据必须保留。代理信任等部署选项仍由运行环境提供,不属于可删除的旧站点设置。
-## 升级后检查
-
-确认能登录后台,打开几张已有照片,尝试上传一张照片,并检查相册、地图和任务队列。1.0.0 新增了隐藏相册照片的访问限制,升级后也应检查公开画廊。
-
## 回退
::: danger 回退时同时恢复数据库
数据库迁移可能改变结构。需要回退时,停止新容器,恢复升级前的完整数据备份,再使用原版本标签启动。不要只降级镜像并继续使用已经迁移的数据库。
:::
+
+</DocStep>
+
+<DocStep number="3" label="检查">
+
+## 升级后检查
+
+确认能登录后台,打开几张已有照片,尝试上传一张照片,并检查相册、地图和任务队列。1.0.0 新增了隐藏相册照片的访问限制,升级后也应检查公开画廊。
+
+</DocStep>