升级指南

本页记录 PicFast 各版本之间的 breaking change 与迁移方法。每一节独立，只看对应你当前版本的那一节即可。

从 0.15.x 升级到 0.16

v0.16 把主题系统收敛成单一内置主题。6 套预设、token 调色板、JSON 主题包导入导出、用户级 theme_override 全部移除。

会失去什么

admin 站点设置：独立的「外观风格」页面没了；并入新的「站点信息」页，只保留 custom_css 一项。「主题包」导入导出 UI 移除。
用户设置：个人设置里的「外观」tab 没了。用户唯一与主题相关的控件是 header 里的亮/暗/系统切换（作为基础可用性保留，不算"个性化"）。
已存数据：旧值仍然躺在 site_settings.theme_config JSONB 里，以及设过的用户的 users.settings.theme_override 里，但应用不再读任何一项。

会保留什么

所有现有的 site_settings.theme_config.custom_css 完整保留，现在直接驱动站点的 <style> 标签。
现有的 per-user image_processing、default_strategy、default_album、default_permission 不受影响。
数据库 schema 不变。升级时不需要数据迁移——旧值变成死数据，不会报错。

步骤 1：部署新镜像

按标准 PicFast 升级流程即可。启动时会自动跑 migration 029，清理每个用户的 users.settings.theme_override 字段。旧的 site_settings.theme_config 保留不动（应用现在只读 mode 和 custom_css）。

docker compose pull
docker compose up -d

步骤 2：还原你之前用的预设

如果你之前选了 6 套被砍掉的预设之一（default / moe / cyber / pixel / terminal / fresh），或改过 token 面板 / public 字段，视觉上会回到 default 主题。把下面对应的 custom_css 贴到 admin → 站点信息 → 自定义 CSS 即可还原。

default

不需要任何 custom_css。

moe（粉系柔光）

:root {
  --primary: oklch(0.70 0.16 350);
  --accent: oklch(0.92 0.05 350);
  --background: oklch(0.99 0.01 350);
  --ring: oklch(0.70 0.16 350);
}
.pf-site-logo { border-radius: 1.25rem; }

cyber（赛博霓虹）

:root {
  --background: oklch(0.13 0.02 280);
  --foreground: oklch(0.95 0.02 280);
  --card: oklch(0.18 0.03 280);
  --primary: oklch(0.78 0.20 200);
  --accent: oklch(0.72 0.25 320);
  --border: oklch(0.28 0.04 280);
  --ring: oklch(0.78 0.20 200);
}

pixel（像素乐园）

:root {
  --radius: 0.125rem;
  --border: oklch(0.85 0 0);
}

terminal（黑绿终端）

:root {
  --background: oklch(0.05 0 0);
  --foreground: oklch(0.85 0.18 145);
  --card: oklch(0.08 0 0);
  --primary: oklch(0.75 0.22 145);
  --border: oklch(0.20 0.05 145);
  --ring: oklch(0.75 0.22 145);
}

fresh（清新海盐）

:root {
  --primary: oklch(0.72 0.10 195);
  --accent: oklch(0.94 0.04 195);
  --background: oklch(0.99 0.005 195);
  --ring: oklch(0.72 0.10 195);
}
.pf-site-logo { border-radius: 0.875rem; }

步骤 3：还原 token 覆盖

如果之前在 token 面板里改过 primary / accent / radius，把对应值复制到 custom_css 里的 :root 块：

:root {
  --primary: oklch(0.65 0.20 30);
  --radius: 0.875rem;
}

步骤 4：还原 public 字段

之前设过 `background_image`

body::before {
  content: '';
  position: fixed;
  inset: 0;
  z-index: -1;
  background-image: url('https://your-host/bg.jpg');
  background-size: cover;
  background-position: center;
}
.pf-public-glow { display: none; }

之前设过 `logo_shape`

/* circle */   .pf-site-logo { border-radius: 9999px; }
/* square */   .pf-site-logo { border-radius: 0; }
/* rounded */  .pf-site-logo { border-radius: 0.75rem; }

步骤 5：通知用户 mode 的变化

亮/暗/系统切换现在存到浏览器的 localStorage，不再写 server。换设备不会同步——每个用户每个设备需要各选一次。

回滚

如果升级后样式不理想：

回滚到 v0.15 镜像。数据库不动——旧 JSONB 字段还在。
在 v0.15 的 admin → 站点信息 → 外观风格里把 theme_config 完整复制一份作为参考。
再升级到 v0.16，按上面步骤用 custom_css 重做。

FAQ

我从来没设过任何主题，会受影响吗？

不会。你的 site_settings.theme_config 是 {} 或 {"custom_css": "..."}，升级对你来说无感。

我的某个用户在个人设置里选过预设，会怎样？

该用户的视觉回到 default 主题。他的 theme_override 字段被 migration 029 清掉。请他在 header 里选 dark（如果你的站点整体偏 cyber 或 terminal 风格，会比较接近）。

升级前能导出我的配置吗？

可以。在 v0.15 打开 admin → 站点信息 → 外观风格 → 主题包 → 复制 JSON，本地保存。升到 v0.16 之后导入按钮没了，需要按上面步骤手工把 preset / tokens / public 翻译成 custom_css。

能恢复预设选择器吗？

预设 UI 不会回来。用上面 6 段 custom_css 配方能完整还原任意一套预设的视觉效果——底层变的本来就只有 token，配方是等价的。

我的 custom_css 撞到 20000 字符上限了怎么办？

20000 字符是硬限制（之前没显式，现在强制了）。建议：

把重复的值抽成 CSS 变量，其他地方用变量名引用。
去掉 vendor 前缀——Tailwind 已经处理了兼容性。
把稳定共享的规则搬到 fork 的 index.css 里，发布你自己的镜像。