theme: 启动日志暴露未登记的主题

新增主题后忘了写进 [theme] available，表现只是"设置页里找不到"，
日志里没有任何痕迹。现在启动时会打：
- info  主题注册表已加载 enabled=...
- warn  [theme] available 未登记以下主题 themes=shiroko available=...

discover() 用 fs.Glob 扫内嵌 css/themes/*.css，按 slug 规则过滤掉 _scaffold.css。
示例配置补上 shiroko，文档补「部署后看不到主题」的两步排查。

.workbuddy/memory/2026-10-19.md

@@ -539,3 +539,16 @@ P1 剩余两项（首屏跟随系统深色、首页 Waline 懒加载）用户明
 上次的 `Failed to authenticate user` 是临时态 —— 用户本机 Git for Windows 认证过之后 store 凭据恢复，
 本轮 `git push origin main` 直接成功（`38cd41a..0c39aff`），`git rev-list --left-right --count origin/main...HEAD` = 0 0。
 远端 8 个 shiroko 素材文件齐全。教训：**不要用一次 push 失败就断言无凭据**，先看一眼提交是否已存在、再试一次。
+
+### 部署后「设置页找不到 shiroko」
+
+线上实测：`/static/css/themes/shiroko.css?v=20261019m` 200 / 5038B 且与本地逐字节一致，
+说明二进制确实带了新主题；但 `/user/profile` 渲染出来的主题单选只有 `""`、`default`、`sakura`
+→ **根因是 `[theme] available` 白名单没登记 shiroko**（列表在 `theme.load()` 里按配置构建，启动时读一次）。
+- `internal/theme/theme.go` 新增 `reportRegistry()` / `discover()`：启动打 info「主题注册表已加载 enabled=...」，
+  并把「css 在、但没登记」的主题以 warning 打出建议的 available 值。
+  没有这段时，这个故障在日志里完全没有痕迹，只能靠猜。
+  `discover()` 用 `fs.Glob(static.FS, "css/themes/*.css")`，用 slugRe 过滤掉 `_scaffold.css`（下划线开头）。
+- `conf/app.sample.ini`：`available = default,sakura,shiroko` + 补充「没登记就不显示」的注释。
+- `docs/theme-shiroko.md` 补「部署后看不到主题」两段排查（先 curl css 看 200/404，再看 available）。
+- 排查口径：**先分「文件没发布」与「没登记」两类**，别一上来怀疑缓存；`StaticVersion` 只影响缓存，不影响列表。

.workbuddy/memory/MEMORY.md

@@ -169,6 +169,10 @@
   必须在任何 i18n 取词之前调用，否则先渲染出的提示会按访客语言。箱主未配语言时才回退访客/站点默认。
 - 主题 = 一个 css 文件只覆盖令牌；新增主题不用改 Go/模板，放 `static/css/themes/<slug>.css` +
   `[theme] available` 登记即可（`static/fs.go` 已嵌整个目录）。底稿 `_scaffold.css`。
+- ⚠️ **`[theme] available` 是硬白名单，启动时读一次**：css 随二进制发布了但没登记，设置页就是看不到，
+  现象和「部署没生效」一模一样。排查先分两类 —— `curl /static/css/themes/<slug>.css` 返回 200 说明文件在
+  （那就是没登记），404 才是旧二进制；`StaticVersion` 只管缓存、不影响列表。
+  启动日志会打 `主题注册表已加载 enabled=...` 与 `[theme] available 未登记以下主题`（2026-10-19 加）。
 - 带图片素材的主题把图放 `static/images/themes/<slug>/`（`static/fs.go` 的 embed 已含 `images/themes`，
   子目录自动覆盖；**新增别的顶层目录才要改清单**）。整页图用 16:9 + 竖版两张，靠 `@media` 切换 ——
   `--tb-page-image` 是 `cover`，贴着图片边缘放的插画会被按视口裁掉。

conf/app.sample.ini

@@ -194,3 +194,5 @@ daily_message_limit_max = 999
 ;           需要图片素材的，放 static/images/themes/<slug>/（static/fs.go 已嵌 images/themes 目录）。
 default = default
 available = default,sakura,shiroko
+; ⚠️ 没登记在 available 里的主题，即使 css 已随二进制发布也不会出现在设置页；
+;    启动日志会打出「[theme] available 未登记以下主题」提醒。,shiroko

docs/theme-shiroko.md

@@ -93,3 +93,35 @@ available = default,sakura,shiroko
 3. 换配色：改 `shiroko.css` 的令牌即可，插画是位图，换色需重新生成。
 4. 新增素材不需要改 `static/fs.go`（已嵌整个 `images/themes` 目录）；但改了 CSS 必须把
    `conf.StaticVersion` +1，否则老访客吃缓存看不到变化。
+
+## 部署后设置页看不到这个主题？
+
+先分两步确认，不要一上来就怀疑缓存：
+
+1. **文件是否随二进制发布了** —— 直接取一次静态资源：
+
+   ```bash
+   curl -o /dev/null -w "%{http_code}\n" \
+     https://<你的域名>/static/css/themes/shiroko.css?v=<StaticVersion>
+   ```
+
+   返回 200 说明 css 已经嵌进去了；返回 404 说明部署的是旧二进制。
+
+2. **是否登记进 `[theme] available`** —— 主题列表是启动时按白名单构建的，
+   css 在但没登记，设置页就看不到它。检查 `conf/app.ini`：
+
+   ```ini
+   [theme]
+   default = default
+   available = default,sakura,shiroko
+   ```
+
+   改完**重启**进程（`[theme]` 只在启动时读）。
+
+启动日志会直接告诉你缺哪一行：
+
+```
+level=info  msg="主题注册表已加载" enabled="default,sakura"
+level=warning msg="[theme] available 未登记以下主题，它们不会出现在设置页"
+      available="default,sakura,shiroko" themes=shiroko
+```

internal/theme/theme.go

@@ -6,6 +6,7 @@
 package theme
 
 import (
+	"io/fs"
 	"regexp"
 	"strings"
 	"sync"
@@ -83,9 +84,55 @@ func build(defaultSlug, available string) ([]Theme, string, map[string]Theme) {
 		logrus.WithField("theme", def).Warn("站点默认主题不可用，回退基础外观")
 		def = ""
 	}
+
+	reportRegistry(list, bySlug)
 	return list, def, bySlug
 }
 
+// reportRegistry 把注册表状态写进启动日志。
+// 没有这段时，主题文件已随二进制发布、却忘了在 [theme] available 登记，
+// 表现只是"设置页里找不到这个主题"，从日志里完全看不出原因。
+func reportRegistry(list []Theme, bySlug map[string]Theme) {
+	enabled := make([]string, 0, len(list))
+	for _, t := range list {
+		enabled = append(enabled, t.Slug)
+	}
+	logrus.WithField("enabled", strings.Join(enabled, ",")).Info("主题注册表已加载")
+
+	var pending []string
+	for _, slug := range discover() {
+		if slug == DefaultSlug {
+			continue
+		}
+		if _, ok := bySlug[slug]; ok {
+			continue
+		}
+		pending = append(pending, slug)
+	}
+	if len(pending) > 0 {
+		logrus.WithFields(logrus.Fields{
+			"themes":    strings.Join(pending, ","),
+			"available": strings.Join(append(enabled, pending...), ","),
+		}).Warn("[theme] available 未登记以下主题，它们不会出现在设置页")
+	}
+}
+
+// discover 列出内嵌的主题 css（不符合 slug 规则的模板文件如 _scaffold.css 会被跳过）。
+func discover() []string {
+	matches, err := fs.Glob(static.FS, themeCSSDir+"*.css")
+	if err != nil {
+		return nil
+	}
+	slugs := make([]string, 0, len(matches))
+	for _, m := range matches {
+		slug := strings.TrimSuffix(strings.TrimPrefix(m, themeCSSDir), ".css")
+		if slugRe.MatchString(slug) {
+			slugs = append(slugs, slug)
+		}
+	}
+	return slugs
+}
+
 func normalize(slug string) string {
 	slug = strings.ToLower(strings.TrimSpace(slug))
 	if !slugRe.MatchString(slug) {