blog/docs/管理台.md

管理台（Sveltia CMS）使用指南

地址：https://wait4x.online/admin/（页脚「管理」入口）｜ 用途：照片上传与 sidecar 编辑的图形界面 ｜ 保存即 commit 到 main → webhook 自动构建发布（约 10 秒上线）

这份是操作手册：每个入口能改什么、字段怎么填、改完会发生什么。写文章正文的排版技巧见 写作指南——两份分工：这里讲"后台怎么用"，那里讲"正文怎么写"。

登录

选 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 里的时间序列不变，订阅者不会看到时间错乱
• 多篇同时置顶时，置顶组内部仍按日期倒序
• 关掉开关立即恢复时间序，没有"冷却期"

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

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

• markdown：**加粗**、*斜体*、列表、> 引用、`行内代码`
• 排版类 HTML：<span class="c-blue font-kai">彩色 + 楷体</span>（可用类清单见写作指南「文章排版类」一节，与文章完全同一份白名单）
• 仍守外壳灰阶纪律：彩色是强调不是装饰，一页 ≤3 处

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

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

照片上传流

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 形态示例（手工编辑时照此写）：

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/ 绝对路径（见写作指南体积纪律表）