# 管理台（Sveltia CMS）使用指南

> 地址：`https://wait4x.online/admin/`（页脚「管理」入口）｜ 用途：照片上传与 sidecar 编辑的图形界面 ｜ 保存即 commit 到 main → webhook 自动构建发布（约 10 秒上线）
>
> 这份是**操作手册**：每个入口能改什么、字段怎么填、改完会发生什么。写文章正文的排版技巧见 [写作指南](./写作指南.md)——两份分工：这里讲"后台怎么用"，那里讲"正文怎么写"。

## 登录

选 **Sign In with Token** → 用 gitea 的 access token（宿主 `~/docker_apps/gitea/init-templates.txt` 里的 api-token，或 gitea 网页新建 scope=read/write:repository）。token 存浏览器 localStorage，下次免登。

## 四类内容集合

| 入口 | 文件位置 | 用来放什么 | 关键约束 |
|---|---|---|---|
| 文章 | `content/posts/<slug>.md` | 书评 / 技术文 / 摄影札记三轨 | `category` 三选一（`reading` / `tech` / `photo`），首页分轨由它派生 |
| 瞬间 | `content/moments/*.md` | 一句话 + 一张图的时间线 | `text` 与 `image` **至少填一项**（后台无法表达条件必填，保存前自查） |
| 照片 | `content/photos/*.json` + 图 | 图库（街拍 / 风景两组） | 标题**必填**（空标题会让构建炸，实测坑）；EXIF 由构建期 loader 自动补全 |
| 站点页面 | `content/site/*.yaml` | 首页、关于页、开源页、主题 | 后台改的是**单例文件**，没有"新建" |

几条通用规则：

- **双语字段成对出现**：中文 / 英文两个输入框。英文留空不是错误——构建期回落中文并在日志里打 WARN（`[blocks] 缺译…`），页面不会破版。
- **留空 = 用默认**：任何字段清空都回到仓库自带的默认文案 / 默认值，构建永远成功。想让某段彻底消失，请看字段自带的"留空则不渲染"提示。
- **文章英文版**：不在后台写。跑 `python3 scripts/translate/translate_posts.py` 生成 `content/posts-en/` 同名文件；手写润色过的译文在 frontmatter 写 `locked: true`，翻译脚本会无条件跳过它。
- **保存即提交**：后台保存等于向仓库提交，push 后约 10 秒自动构建上线。

## 文章置顶（5h 新增）

文章编辑页有一个「置顶」开关。打开后这篇文章排在首页分轨、归档、书架三处列表的最前面，列表里显示一个灰阶「置顶」小徽标。

语义边界（刻意如此，别当 bug 报）：
- **只影响列表顺序**：`pubDate` 不变、URL 不变、RSS 里的时间序列不变，订阅者不会看到时间错乱
- **支持多篇/多本同时置顶**：置顶组内部仍按日期倒序；书架页（/books）里每个置顶的书评都会排在前面并**默认展开**
- 书架页用「↑ + 横线」的回到顶部图标表示置顶（不写文字），与右侧展开箭头形状不同，不会混读
- 关掉开关立即恢复时间序，没有"冷却期"

## 瞬间（5h 起与文章同级）

「瞬间」集合的「文字」字段是 **markdown 编辑器**，与文章同一套表达力：

- markdown：`**加粗**`、`*斜体*`、列表、`> 引用`、`` `行内代码` ``
- 排版类 HTML：`<span class="c-blue font-kai">彩色 + 楷体</span>`（可用类清单见写作指南「文章排版类」一节，与文章完全同一份白名单）
- 彩色**不再限次**（原「≤3 处/页」已取消）；仍守外壳灰阶：导航/页脚/按钮/背景不染色

**每条瞬间自带评论区**：时间线卡片下方有「评论」折叠条，读者点开才加载评论（不点开不为它付任何加载成本）。中文页与英文页共用同一条评论流，语言切换不会丢评论。

**每条的浏览 / 评论数字是只读的**：读者点开评论区不会虚增浏览数（只有整页访问才计一次）。

## 照片说明文字（灯箱右侧）支持排版（5i 新增）

照片的「说明」（caption）现在支持 markdown 与排版类，与文章正文同一套：

```yaml
caption: 落日把海与城一齐烫成金箔，**这一帧等了二十分钟**
```

```html
<span class="c-blue">蓝色</span>、<span class="font-kai">楷体</span> 这些类都能用。
```

灯箱是深底，颜色类会自动取柔和对暗底的那一档，不会刺眼。EXIF 那几行是相机数据，不做排版。

## 照片上传流

1. 图库照片 → New Entry：填标题（**必填**，空标题会让构建炸——实测坑）、选分组（street/landscape）、可写 alt
2. 图片字段 → 资产库上传 jpg（与 sidecar 同目录落位，零重压缩）
3. Save → 自动 commit + 构建 → 画廊出现（EXIF 构建期自动提取，exif 字段留空即可）

## 块编辑：关于页的块式页面构建器

关于页（`content/site/about.yaml`）的正文由 **blocks 列表**构成，后台里是一串可拖拽排序的卡片。每个块都有「显示」开关；关掉只是不渲染，块本身留在数据里。

两条渲染纪律：

- 列表为空（或全关）时，页面回落到 `intro` 字段的 markdown 正文；`intro` 也空则用内置默认文案。三级回落，任何一级为空都不会出白页。
- 未知块型（手工编辑 yaml 写错的 `type`）会被**跳过并打印 `[blocks]` 警告**，不会炸构建；块数上限 24，单块文本上限 4000 字，超限截断并 WARN。

九类块与字段（文本字段一律 `{zh, en}` 双语对象）：

| 块型 | 必填 | 可选 | 用途 |
|---|---|---|---|
| `prose` 正文 | `body` | `title`、`width`（`narrow` 版心 / `full` 通栏） | markdown 长文，最常用 |
| `tracks` 版图 | `title`、`items[].name` | `items[].icon`、`items[].desc` | 几条主线 / 能力面，图标白名单外或留空显示首字占位 |
| `cards` 卡片墙 | `items[].title` | `title`、`columns`（2 或 3，默认 3）、`items[].desc/href/tag` | 并列展示若干条目 |
| `timeline` 时间线 | `items[].time`、`items[].title` | `title`、`items[].desc` | 时间列是自由文本（`2024 — 2026` 也行） |
| `quote` 引文 | `text` | `cite` | 单句金句，配 `font-kai` 更出效果 |
| `figure` 图片 | `image` | `alt`、`caption` | **只能后台上传**（落 `content/site/assets/`，走图片管线），禁止外链 |
| `linklist` 链接清单 | `items[].label`、`items[].href` | `title`、`items[].note` | 相关阅读 / 外部资源 |
| `cta` 行动按钮 | `text`、`href`、`label` | — | 一页建议不超过一个 |
| `divider` 分隔 | — | `style`（`line` 细线 / `space` 纯留白） | 长页分段 |

yaml 形态示例（手工编辑时照此写）：

```yaml
blocks:
  - type: prose
    title: { zh: 关于这个站点, en: About this site }
    body:
      zh: 这里写 markdown 正文，支持列表、粗斜体、链接与排版类。
      en: Markdown body here.
    width: narrow
  - type: quote
    text: { zh: 所谓暮色，就是光慢慢地承认自己要走。, en: Dusk is light admitting it has to go. }
    cite: { zh: 本站, en: this site }
  - type: figure
    image: ./assets/desk.jpg   # 后台会替你写成这个相对路径
    caption: { zh: 工作台一角, en: A corner of the desk }
```

其它可用字段：`layout.showIdCard`（关掉则不渲染名片区，默认开）、`typography`（见下一节）。

**预览限制**：后台只提供字段编辑与列表摘要（摘要显示块型名），块的真实排版以下次构建后的页面为准——想调间距 / 字号，请用「主题设置」而不是在块里硬凑空行。

## 页面排版覆盖（每页一处）

首页 / 关于页 / 开源页各自有一个「页面排版覆盖（可选）」对象：

| 字段 | 取值 | 说明 |
|---|---|---|
| `font` | 字族下拉（10 项） | 本页**正文**默认字体类 |
| `accent` | 颜色下拉（18 项） | 本页强调色类 |
| `scale` | 0.8–1.25 | 字号缩放，1 = 全站默认 |

- 只作用于**该页内容容器**（挂 `.page-typo` + CSS 变量），不写全站 tokens，其它页面零影响。
- **体积成本提醒**：整页换艺术/展示字族（`font-huiwen` 汇文、`font-kuaile` 快乐体）意味着整页正文都要下载对应切片——单页字体成本会明显抬升，见写作指南的体积账。
- 白名单外的类名会被忽略（构建期过滤），写错不报错、也不生效。

## 主题设置（全站 17 个旋钮）

「主题设置」入口写 `content/site/theme.yaml`，17 项全部可选，留空 = 仓库默认值。**配错不会炸站**：越界值回落默认，组内单调性被破坏则整组回落。

| 组 | 字段 | 范围 | 约束语义 |
|---|---|---|---|
| 强调色 | `accent_light` / `accent_dark` | `#rrggbb` | 明暗各一份；构建期对比度闸门断言正文 ≥4.5:1，不达标构建失败 |
| 圆角 | `radius_img` | 4–16 | 图片圆角，建议 ≤14 |
| 标题字号 | `text_h1` / `text_h2` / `text_h3` | h1/h2：22–32，h3：16–32 | **必须严格递减**（h1 > h2 > h3），否则三档一起回落默认 |
| 正文字号 | `prose_size_reading` / `prose_size_tech` | 16–22 | 书评 / 技术文分轨独立 |
| 行高 | `leading_reading` / `leading_tech` | 1.5–2.0 | 同上分轨 |
| 间距梯度 | `space_3` / `space_4` / `space_5` / `space_6` | 8–80 | **必须严格递增**，否则整组回落 |
| 流距 | `flow_p` / `flow_h2_post` | 0–2（em） | 段间距 / 标题下间距 |
| 动效 | `dur` | 150–600（ms） | 过渡时长；`prefers-reduced-motion` 下自动归零 |

不能配的东西（有意为止）：版心宽度、断点、纸墨色、代码配色——它们牵动版面结构与分轨身份，属于设计红线。注入方式是构建期内联 `:root:root{…}`，运行时零 JS、零请求。

## 首页与开源页的其余旋钮

### 首页三字段（5g 新增）

| 字段 | 取值 | 默认 | 作用 |
|---|---|---|---|
| `projectsLimit` | 1–99 | 6 | 首页项目墙条数（越界夹取） |
| `announcement` | `{zh, en}` markdown | 空 | 名片区下方公告；**空 = 不渲染**，走富文本管线（可写排版类 span） |
| `postsTracks` | `{reading, tech, photo}` 布尔 | 全开 | 关掉某轨，该轨文章不在首页列出（归档页仍可见） |

### 开源页（opensource.yaml）

**开篇是原生「GitHub 档案卡」（5h 起）**：头像 / 名字@handle / 定位叙述 / 社交图标 / 统计四格（关注者、公开仓、总星标）/ 语言占比灰阶条（只有第一名用强调色，其余灰阶）。**零第三方图片、零 iframe**。数据失败只隐藏对应数字，不会破版。

想换那段「定位叙述」，改本文件的 `blurb` + `blurb_after`（双语，后台可改）——它们现在同时供给档案卡与项目墙下方的说明。

下面的 `intro_from: "github-readme"` **仍可用但不推荐**：那会把 GitHub 专用 README 原样渲染，带 7 类外链图（shields.io、readme-typing-svg、github-readme-stats、streak-stats、activity-graph、snake、komarev 访客徽章）与 `<div align="center">` 居中——本站按普通块渲染，故居中失效；外链图在慢网或被墙时全空白。这也是当初"部分内容没居中、有些图片没显示"的根因。

| 字段 | 取值 | 说明 |
|---|---|---|
| `pinned` | 仓短名数组 | 置顶顺序即展示顺序 |
| `mode` | `all` / `only` / `exclude` | 可见性模式 |
| `include` / `exclude` | 仓短名数组 | 对应模式的白 / 黑名单 |
| `sort` | `pinned-first` / `stars` / `updated` | 排序 |
| `perSource` | `both` / `github` / `gitea` | 来源过滤 |
| `intro_from` | `"off"` / `"github-readme"` | 开篇文案来源（**带引号写**，YAML 1.1 里裸 `off` 是布尔 false） |

**`mode: only` 的"看不见"排查**：构建日志会给每个没显示出来的 include 项打一行 `[opensource] projects：include 里的「X」…`，并区分两种原因——双源结果里根本没有这个仓（拼写 / 私有仓 / 该源刚失败），或者命中了但被 `perSource` 过滤掉。看到哪一行就知道该改什么。

**README 开篇（`intro_from: "github-readme"`）的回落矩阵**，构建日志逐级点名：

1. 取到 → 内容有变化才刷新缓存 `content/.github-readme.md`（入仓，保证构建确定性）
2. token 缺位 / HTTP 非 2xx / 内容为空 / 超时（10 秒）/ 网络异常 → 改用缓存（日志标注"可能陈旧"）
3. 缓存也不在 → 回落本文件 `blurb` 的叙述文案
4. 缓存回写失败（构建仓只读挂载等）→ 只告警，本次渲染照常

token 位在 `~/docker_apps/blog/github-token.txt`（本机，0600）。

**两条已知限制**：

- **README 里的相对链接不重写**（如 `./img/x.png`、`docs/foo.md`）：它们相对 GitHub 仓根解析，在本站没有对应产物，点了多半 404。保原样比猜一个基址可信，所以不做改写。
- **外部徽章图片加固但不参与构建**：shields.io、readme-typing-svg 这类第三方徽章在构建期**不抓取**，渲染时统一补 `loading="lazy"`（缺 alt 补空），它们慢、被墙或 404 都不影响页面渲染；尺寸已由样式限制在内容宽度内。

## 浏览与评论计数（5h 新增）

文章页、瞬间页、开源页、关于页都用同一枚灰阶徽标：**眼睛图标 = 浏览数，气泡图标 = 条评论**，数据来自自建 Artalk，不依赖任何第三方徽章服务。

几条行为约定（省得当成 bug）：

- **一页只计一次浏览**：「计一次」发生在这页唯一那个 `page` 模式徽标（文章页在标题下方），同一页其余徽标都是只读镜像，显示的是同一个数字——不会出现"页头 17、评论区 16"
- **开评论不算浏览**：瞬间逐条徽标是只读的，读者展开评论区不会给那条动态虚增浏览量
- **接口挂掉显示「–」而不是 0**：宁可留白，也不给读者看一个错误的零
- **换页重计、同页刷新重计**：这是浏览量的定义，不是重复计数的 bug（软导航回同一页也算新一次访问）

## 纪律（与写作指南同源）

- **图片体积**：上传前自行压缩（长边 ≤2400px）——Sveltia 内建优化**刻意关闭**（会抹 EXIF 断构建期提取管线）
- **删除**：删条目会连带删除被其独占引用的 jpg（实测行为，官方文档说的"不连带"是错的）
- EXIF 覆盖字段一般留空；文章 markdown 仍建议本地/gitea web 写（Sveltia 只管照片）
- 保存直连 main 无分支缓冲——webhook 构建是安全网，构建失败 gitea 的 webhook 投递记录可查

## 已知限制

- 启动时探测 /api/forgejo 报 404 属良性回落（日志噪音，无影响）
- 大视频仍走仓外 store + /media/ 绝对路径（见写作指南体积纪律表）