feat: 交付官方 Docker 运行时，外观改背景图并下线自定义 CSS/JS

站点/后台分轨背景与用户列表排序一并落地；生产 CORS 改走 SITE_URL，健康检查带版本号。

Co-authored-by: Cursor <cursoragent@cursor.com>

frontend/app/admin/appearance/AppearanceAdmin.tsx

@@ -12,7 +12,11 @@ import {
   RotateCcw,
   Pipette,
   Sparkles,
-  FileCode2,
+  ImageIcon,
+  Monitor,
+  LayoutDashboard,
+  Trash2,
+  Upload,
 } from "lucide-react";
 import {
   AdminPageHeader,
@@ -20,8 +24,13 @@ import {
   AdminSettingRow,
   AdminStepper,
   AdminSwitch,
+  AdminSegmented,
 } from "@/components/admin";
-import { apiUpdateSiteSettings, type PublicSettings, type UpdateSiteSettingsBody } from "@/lib/api";
+import {
+  apiUpdateSiteSettings,
+  apiUploadSiteBackground,
+  type PublicSettings,
+} from "@/lib/api";
 import { toast } from "@/lib/toast";
 import {
   ACCENT_PRESETS,
@@ -32,26 +41,23 @@ import {
   normalizeHex,
 } from "@/lib/theme";
 import {
-  MAX_CUSTOM_CSS_CHARS,
-  MAX_CUSTOM_JS_CHARS,
-  SAMPLE_CUSTOM_CSS,
-  SAMPLE_CUSTOM_JS,
-  applyCustomCSS,
-  clipCustomSnippet,
-} from "@/lib/customCode";
+  BG_MODE_OPTIONS,
+  applySiteBackground,
+  bgConfigFromSettings,
+  normalizeBgMode,
+  previewBoxStyle,
+  type BgMode,
+  type BgSurface,
+  type SiteBgConfig,
+} from "@/lib/bg";
 
-// 后台「外观设置」：主题色、自定义 CSS/JS、代码块折叠与界面动画。
-// 主题色 / 自定义 CSS 修改时立即对整页实时预览（仅本地），保存后才写库并对所有用户生效。
-// 自定义 JS 不在编辑时执行，保存后整页加载生效。
+// 后台「外观设置」：主题色、代码块折叠与界面动画。
+// 主题色修改时立即对整页实时预览（仅本地），保存后才写库并对所有用户生效。
 export default function AppearanceAdmin({ initial }: { initial: PublicSettings }) {
   const router = useRouter();
   const initialAccent = initial.accent || "";
   const [savedHex, setSavedHex] = useState(initialAccent);
   const [draft, setDraft] = useState(initialAccent || DEFAULT_ACCENT);
-  const [savedCustomCSS, setSavedCustomCSS] = useState(initial.custom_css || "");
-  const [customCSS, setCustomCSS] = useState(initial.custom_css || SAMPLE_CUSTOM_CSS);
-  const [savedCustomJS, setSavedCustomJS] = useState(initial.custom_js || "");
-  const [customJS, setCustomJS] = useState(initial.custom_js || SAMPLE_CUSTOM_JS);
   const [codeAutoFold, setCodeAutoFold] = useState(initial.code_block_auto_fold !== false);
   const [foldLines, setFoldLines] = useState(
     Number.isFinite(initial.code_block_fold_lines) ? initial.code_block_fold_lines : 5
@@ -66,10 +72,12 @@ export default function AppearanceAdmin({ initial }: { initial: PublicSettings }
   const [animChrome, setAnimChrome] = useState(initial.anim_chrome !== false);
   const [togglingMotion, setTogglingMotion] = useState(false);
   const [saving, setSaving] = useState(false);
+  const [bg, setBg] = useState<SiteBgConfig>(() => bgConfigFromSettings(initial));
+  const [bgBusy, setBgBusy] = useState<BgSurface | null>(null);
+  const siteFileRef = useRef<HTMLInputElement>(null);
+  const adminFileRef = useRef<HTMLInputElement>(null);
   const savedRef = useRef(savedHex);
   savedRef.current = savedHex;
-  const savedCSSRef = useRef(savedCustomCSS);
-  savedCSSRef.current = savedCustomCSS;
 
   const normalized = useMemo(() => normalizeHex(draft), [draft]);
   const pair = useMemo(
@@ -78,12 +86,7 @@ export default function AppearanceAdmin({ initial }: { initial: PublicSettings }
   );
   const preset = useMemo(() => (normalized ? findPreset(normalized) : null), [normalized]);
   const submitHex = normalized && normalized !== DEFAULT_ACCENT ? normalized : "";
-  const accentDirty = (savedHex || DEFAULT_ACCENT) !== (normalized || "");
-  const cssIsGuide = !savedCustomCSS && customCSS === SAMPLE_CUSTOM_CSS;
-  const jsIsGuide = !savedCustomJS && customJS === SAMPLE_CUSTOM_JS;
-  const cssDirty = customCSS !== savedCustomCSS && !cssIsGuide;
-  const jsDirty = customJS !== savedCustomJS && !jsIsGuide;
-  const dirty = accentDirty || cssDirty || jsDirty;
+  const dirty = (savedHex || DEFAULT_ACCENT) !== (normalized || "");
   const invalid = draft.trim() !== "" && !normalized;
 
   useEffect(() => {
@@ -93,35 +96,19 @@ export default function AppearanceAdmin({ initial }: { initial: PublicSettings }
     };
   }, [normalized]);
 
-  useEffect(() => {
-    applyCustomCSS(customCSS, true);
-    return () => {
-      applyCustomCSS(savedCSSRef.current, false);
-    };
-  }, [customCSS]);
-
   const handleSave = async () => {
     if (!normalized || saving) return;
-    const body: UpdateSiteSettingsBody = {};
-    if (accentDirty) body.accent = submitHex;
-    if (cssDirty) body.custom_css = customCSS;
-    if (jsDirty) body.custom_js = customJS;
-    if (Object.keys(body).length === 0) return;
     setSaving(true);
     try {
-      const res = await apiUpdateSiteSettings(body);
+      const res = await apiUpdateSiteSettings({ accent: submitHex });
       const next = (res.accent || "").toLowerCase();
       setSavedHex(next);
-      setSavedCustomCSS(res.custom_css || "");
-      setSavedCustomJS(res.custom_js || "");
       applyAccentTheme(next || null);
-      applyCustomCSS(res.custom_css || "", false);
       router.refresh();
-      toast(jsDirty ? "外观已保存；自定义 JS 将在整页刷新后执行" : "外观已保存并对全站生效");
+      toast(next ? "主题色已保存并对全站生效" : "已恢复默认主题色");
     } catch (e) {
       toast(e instanceof Error ? e.message : "保存失败", "error");
       applyAccentTheme(savedRef.current || null);
-      applyCustomCSS(savedCSSRef.current, false);
     } finally {
       setSaving(false);
     }
@@ -129,10 +116,7 @@ export default function AppearanceAdmin({ initial }: { initial: PublicSettings }
 
   const discard = () => {
     setDraft(savedHex || DEFAULT_ACCENT);
-    setCustomCSS(savedCustomCSS || SAMPLE_CUSTOM_CSS);
-    setCustomJS(savedCustomJS || SAMPLE_CUSTOM_JS);
     applyAccentTheme(savedHex || null);
-    applyCustomCSS(savedCustomCSS, true);
   };
 
   const toggleCodeFold = async () => {
@@ -202,12 +186,180 @@ export default function AppearanceAdmin({ initial }: { initial: PublicSettings }
     }
   };
 
+  const commitBg = (next: SiteBgConfig) => {
+    setBg(next);
+    applySiteBackground(next);
+  };
+
+  const saveBgPatch = async (patch: Partial<SiteBgConfig>, toastOk: string) => {
+    const res = await apiUpdateSiteSettings(patch);
+    commitBg(bgConfigFromSettings(res));
+    toast(toastOk, "ok");
+  };
+
+  const onPickBg = async (surface: BgSurface, file: File | undefined) => {
+    if (!file || bgBusy) return;
+    if (!/^image\/(jpeg|png|webp)$/i.test(file.type) && !/\.(jpe?g|png|webp)$/i.test(file.name)) {
+      toast("仅支持 JPEG / PNG / WebP", "error");
+      return;
+    }
+    if (file.size > 8 * 1024 * 1024) {
+      toast("背景图不能超过 8MB", "error");
+      return;
+    }
+    setBgBusy(surface);
+    try {
+      const pendingMode = surface === "site" ? bg.bg_site_mode : bg.bg_admin_mode;
+      let res = await apiUploadSiteBackground(surface, file);
+      let next = bgConfigFromSettings(res);
+      const savedMode = surface === "site" ? next.bg_site_mode : next.bg_admin_mode;
+      if (pendingMode !== savedMode) {
+        const modeKey = surface === "site" ? "bg_site_mode" : "bg_admin_mode";
+        res = await apiUpdateSiteSettings({ [modeKey]: pendingMode });
+        next = bgConfigFromSettings(res);
+      }
+      commitBg(next);
+      toast(surface === "site" ? "前台背景已更新" : "后台背景已更新", "ok");
+    } catch (e) {
+      toast(e instanceof Error ? e.message : "上传失败", "error");
+    } finally {
+      setBgBusy(null);
+    }
+  };
+
+  const onChangeBgMode = async (surface: BgSurface, mode: BgMode) => {
+    if (bgBusy) return;
+    const key = surface === "site" ? "bg_site_mode" : "bg_admin_mode";
+    const url = surface === "site" ? bg.bg_site_url : bg.bg_admin_url;
+    if (!url) {
+      commitBg({ ...bg, [key]: mode });
+      return;
+    }
+    setBgBusy(surface);
+    try {
+      await saveBgPatch(
+        { [key]: mode },
+        surface === "site" ? "前台铺放模式已保存" : "后台铺放模式已保存"
+      );
+    } catch (e) {
+      toast(e instanceof Error ? e.message : "保存失败", "error");
+    } finally {
+      setBgBusy(null);
+    }
+  };
+
+  const onClearBg = async (surface: BgSurface) => {
+    if (bgBusy) return;
+    const key = surface === "site" ? "bg_site_url" : "bg_admin_url";
+    setBgBusy(surface);
+    try {
+      await saveBgPatch(
+        { [key]: "" },
+        surface === "site" ? "已恢复前台默认画布" : "已恢复后台默认画布"
+      );
+    } catch (e) {
+      toast(e instanceof Error ? e.message : "保存失败", "error");
+    } finally {
+      setBgBusy(null);
+    }
+  };
+
+  const renderBgRail = (
+    surface: BgSurface,
+    title: string,
+    desc: string,
+    Icon: typeof Monitor,
+    fileRef: typeof siteFileRef
+  ) => {
+    const url = surface === "site" ? bg.bg_site_url : bg.bg_admin_url;
+    const mode = surface === "site" ? bg.bg_site_mode : bg.bg_admin_mode;
+    const busy = bgBusy === surface;
+    return (
+      <div className="flex flex-col gap-3 min-w-0">
+        <div className="flex items-start justify-between gap-2">
+          <div className="min-w-0">
+            <h3 className="text-[14px] font-medium flex items-center gap-1.5" style={{ color: "var(--ink)" }}>
+              <Icon size={15} /> {title}
+            </h3>
+            <p className="meta text-[12.5px] mt-0.5 leading-relaxed">{desc}</p>
+          </div>
+        </div>
+        <div
+          className="relative h-36 rounded-[var(--r-sm)] border overflow-hidden"
+          style={{
+            borderColor: "var(--line)",
+            ...previewBoxStyle(url, mode),
+          }}
+        >
+          {!url && (
+            <span
+              className="absolute inset-0 flex items-center justify-center text-[12.5px]"
+              style={{ color: "var(--ink-3)" }}
+            >
+              默认纹饰画布
+            </span>
+          )}
+        </div>
+        <input
+          ref={fileRef}
+          type="file"
+          accept="image/jpeg,image/png,image/webp,.jpg,.jpeg,.png,.webp"
+          className="hidden"
+          onChange={(e) => {
+            const f = e.target.files?.[0];
+            e.target.value = "";
+            void onPickBg(surface, f);
+          }}
+        />
+        <div className="flex flex-wrap items-center gap-2">
+          <button
+            type="button"
+            className="btn btn-line btn-sm"
+            disabled={busy}
+            onClick={() => fileRef.current?.click()}
+          >
+            {busy ? <Loader2 size={14} className="animate-spin" /> : <Upload size={14} />}
+            {url ? "更换图片" : "上传图片"}
+          </button>
+          {url ? (
+            <button
+              type="button"
+              className="btn btn-line btn-sm"
+              disabled={busy}
+              onClick={() => void onClearBg(surface)}
+            >
+              <Trash2 size={14} /> 恢复默认
+            </button>
+          ) : null}
+        </div>
+        <div>
+          <p className="field-label mb-2">铺放模式</p>
+          <AdminSegmented
+            size="sm"
+            role="group"
+            ariaLabel={`${title}铺放模式`}
+            value={mode}
+            onChange={(key) => void onChangeBgMode(surface, normalizeBgMode(key))}
+            options={BG_MODE_OPTIONS.map((o) => ({
+              key: o.key,
+              label: o.label,
+              disabled: busy,
+            }))}
+          />
+          <p className="meta text-[12px] mt-1.5">
+            {BG_MODE_OPTIONS.find((o) => o.key === mode)?.hint}
+          </p>
+        </div>
+      </div>
+    );
+  };
+
   return (
     <div>
       <AdminPageHeader
         icon={Palette}
         title="外观设置"
-        description="配置站点主题色、自定义 CSS/JS、代码块折叠与界面动画"
+        description="配置站点主题色、背景图、代码块折叠与界面动画"
       />
 
       <div className="grid grid-cols-1 xl:grid-cols-3 gap-4 mb-6">
@@ -370,7 +522,8 @@ export default function AppearanceAdmin({ initial }: { initial: PublicSettings }
                 </span>
               </div>
               <div className="max-w-xs">
-                <div className="panel p-3">
+                <section className="j13-module">
+                  <p className="j13-module-title mb-2.5">板块目录</p>
                   <div className="j13-bcard" aria-current="page">
                     <span
                       className="j13-bcard-ico"
@@ -378,9 +531,9 @@ export default function AppearanceAdmin({ initial }: { initial: PublicSettings }
                     >
                       <Palette size={16} />
                     </span>
-                    <span className="j13-bcard-name text-[13px] flex-1">选中的板块卡片</span>
+                    <span className="j13-bcard-name flex-1">选中的板块</span>
                   </div>
-                </div>
+                </section>
               </div>
             </div>
           </AdminSection>
@@ -516,81 +669,29 @@ export default function AppearanceAdmin({ initial }: { initial: PublicSettings }
       </div>
 
       <AdminSection
+        className="mb-6"
         title={
           <span className="inline-flex items-center gap-1.5">
-            <FileCode2 size={15} /> 自定义代码
+            <ImageIcon size={15} /> 站点背景图
           </span>
         }
-        description="注入全站 HTML。空配置时先显示注释示例（不会自动写入）；保存后才对访客生效。勿包含 </style> 或 </script>。"
-        className="mb-6"
+        description="前台与后台可分别上传 JPEG / PNG / WebP（≤8MB）。未配置时使用默认纹饰画布。"
       >
-        <div className="grid grid-cols-1 xl:grid-cols-2 gap-4">
-          <div>
-            <div className="flex items-center justify-between gap-2 mb-1">
-              <label className="field-label !mb-0" htmlFor="custom-css">
-                自定义 CSS
-              </label>
-              {customCSS !== SAMPLE_CUSTOM_CSS && (
-                <button
-                  type="button"
-                  className="btn btn-line btn-sm !h-7 !px-2.5 !text-[12px]"
-                  onClick={() => setCustomCSS(SAMPLE_CUSTOM_CSS)}
-                >
-                  填入示例
-                </button>
-              )}
-            </div>
-            <p className="meta text-[12.5px] mb-2 leading-relaxed">
-              覆盖令牌或组件类。本页即时预览；去掉注释后的规则才会改变外观。上限{" "}
-              {MAX_CUSTOM_CSS_CHARS.toLocaleString()} 字。
-            </p>
-            <textarea
-              id="custom-css"
-              className="j13-compose-field w-full font-mono text-[12.5px] leading-relaxed"
-              style={{ minHeight: 280 }}
-              spellCheck={false}
-              value={customCSS}
-              onChange={(e) => setCustomCSS(clipCustomSnippet(e.target.value, MAX_CUSTOM_CSS_CHARS))}
-              aria-label="自定义 CSS"
-            />
-            <p className="meta text-[11.5px] mt-1.5 tabular-nums">
-              {customCSS.length.toLocaleString()} / {MAX_CUSTOM_CSS_CHARS.toLocaleString()}
-              {cssIsGuide ? " · 示例未保存" : ""}
-            </p>
-          </div>
-          <div>
-            <div className="flex items-center justify-between gap-2 mb-1">
-              <label className="field-label !mb-0" htmlFor="custom-js">
-                自定义 JS
-              </label>
-              {customJS !== SAMPLE_CUSTOM_JS && (
-                <button
-                  type="button"
-                  className="btn btn-line btn-sm !h-7 !px-2.5 !text-[12px]"
-                  onClick={() => setCustomJS(SAMPLE_CUSTOM_JS)}
-                >
-                  填入示例
-                </button>
-              )}
-            </div>
-            <p className="meta text-[12.5px] mb-2 leading-relaxed">
-              仅站长/超管可写。不在编辑时运行，保存后需整页刷新。上限{" "}
-              {MAX_CUSTOM_JS_CHARS.toLocaleString()} 字。
-            </p>
-            <textarea
-              id="custom-js"
-              className="j13-compose-field w-full font-mono text-[12.5px] leading-relaxed"
-              style={{ minHeight: 280 }}
-              spellCheck={false}
-              value={customJS}
-              onChange={(e) => setCustomJS(clipCustomSnippet(e.target.value, MAX_CUSTOM_JS_CHARS))}
-              aria-label="自定义 JS"
-            />
-            <p className="meta text-[11.5px] mt-1.5 tabular-nums">
-              {customJS.length.toLocaleString()} / {MAX_CUSTOM_JS_CHARS.toLocaleString()}
-              {jsIsGuide ? " · 示例未保存" : ""}
-            </p>
-          </div>
+        <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+          {renderBgRail(
+            "site",
+            "前台",
+            "访客看到的论坛页面，含首页、帖子与个人主页。",
+            Monitor,
+            siteFileRef
+          )}
+          {renderBgRail(
+            "admin",
+            "后台",
+            "管理面板专用。与前台互不影响，可配更克制的图案。",
+            LayoutDashboard,
+            adminFileRef
+          )}
         </div>
       </AdminSection>