fix: clarify WebUI bind settings and toast visibility

Author: Activer007

apps/dsa-web/src/components/settings/SettingsAlert.tsx

@@ -1,10 +1,12 @@
 import type React from 'react';
 import { Button, InlineAlert } from '../common';
+import { cn } from '../../utils/cn';
 
 interface SettingsAlertProps {
   title: string;
   message: string;
   variant?: 'error' | 'success' | 'warning';
+  presentation?: 'inline' | 'toast';
   actionLabel?: string;
   onAction?: () => void;
   className?: string;
@@ -16,20 +18,35 @@ const variantMap: Record<NonNullable<SettingsAlertProps['variant']>, 'danger' |
   warning: 'warning',
 };
 
+const toastHighlightStyle = [
+  'relative overflow-hidden bg-card/95 text-foreground shadow-soft-card-strong backdrop-blur-sm',
+  'before:pointer-events-none before:absolute before:inset-x-0 before:top-0 before:h-1.5',
+  'before:bg-gradient-to-r before:from-cyan/80 before:via-primary/70 before:to-purple/70',
+].join(' ');
+
+const toastVariantStyles: Record<NonNullable<SettingsAlertProps['variant']>, string> = {
+  error: toastHighlightStyle,
+  success: toastHighlightStyle,
+  warning: toastHighlightStyle,
+};
+
 export const SettingsAlert: React.FC<SettingsAlertProps> = ({
   title,
   message,
   variant = 'error',
+  presentation = 'inline',
   actionLabel,
   onAction,
   className = '',
 }) => {
+  const presentationClassName = presentation === 'toast' ? toastVariantStyles[variant] : '';
+
   return (
     <InlineAlert
       title={title}
       message={message}
       variant={variantMap[variant]}
-      className={className}
+      className={cn(presentationClassName, className)}
       action={actionLabel && onAction ? (
         <Button
           type="button"

apps/dsa-web/src/locales/settingsHelp.ts

@@ -86,13 +86,15 @@ const settingsHelpZhCN: SettingsHelpMap = {
     summary: '控制 WebUI 服务绑定在哪个网络地址上。',
     usage: '本机访问通常使用 127.0.0.1；云服务器、Docker 或需要外部访问时通常使用 0.0.0.0。',
     valueNotes: [
-      '.env 里的 WEBUI_HOST 优先级高于命令行 --host 参数。',
+      '.env 里的 WEBUI_HOST 在进程启动读取时优先级高于命令行 --host 参数。',
+      '在设置页保存后，只会写入 .env 并重载运行时配置对象，不会让当前 WebUI/API 进程重新绑定监听地址。',
       'Docker Compose 中通常会在容器内使用 0.0.0.0，宿主机访问还取决于端口映射。',
     ],
     impact: [
-      '影响浏览器能否从本机、局域网或公网访问 WebUI。',
+      '影响重启后浏览器能否从本机、局域网或公网访问 WebUI。',
     ],
     notes: [
+      '修改 WEBUI_HOST 后需要重启当前进程、Docker 容器或服务管理器才会生效。',
       '直连公网时建议同时启用 ADMIN_AUTH_ENABLED。',
       '如果部署在反向代理后面，登录限流与真实 IP 识别还需要评估 TRUST_X_FORWARDED_FOR。',
     ],
@@ -162,11 +164,13 @@ const settingsHelpEnUS: SettingsHelpMap = {
     summary: 'Controls the network address the WebUI service binds to.',
     usage: 'Use 127.0.0.1 for local-only access. Use 0.0.0.0 for cloud, Docker, or external access.',
     valueNotes: [
-      'WEBUI_HOST in .env has higher priority than the --host command-line argument.',
+      'WEBUI_HOST in .env has higher priority than the --host command-line argument when the process starts.',
+      'Saving it from the settings page writes .env and reloads runtime config objects, but the running WebUI/API process will not rebind its host.',
       'Docker Compose commonly binds 0.0.0.0 inside the container; host access also depends on port mapping.',
     ],
-    impact: ['Affects whether the WebUI can be reached locally, on the LAN, or from the public internet.'],
+    impact: ['Affects whether the WebUI can be reached locally, on the LAN, or from the public internet after restart.'],
     notes: [
+      'Restart the process, Docker container, or service manager after changing WEBUI_HOST.',
       'Enable ADMIN_AUTH_ENABLED when exposing the service publicly.',
       'Behind a reverse proxy, also evaluate TRUST_X_FORWARDED_FOR for login rate limiting and real IP detection.',
     ],

apps/dsa-web/src/pages/SettingsPage.tsx

@@ -686,7 +686,14 @@ const SettingsPage: React.FC = () => {
       {toast ? (
         <div className="fixed bottom-5 right-5 z-50 w-[320px] max-w-[calc(100vw-24px)]">
           {toast.type === 'success'
-            ? <SettingsAlert title="操作成功" message={toast.message} variant="success" />
+            ? (
+                <SettingsAlert
+                  title="操作成功"
+                  message={toast.message}
+                  variant="success"
+                  presentation="toast"
+                />
+              )
             : <ApiErrorAlert error={toast.error} />}
         </div>
       ) : null}

src/core/config_registry.py

@@ -1494,7 +1494,7 @@
                 "href": "https://github.com/ZhuLinsen/daily_stock_analysis/blob/main/docs/full-guide.md#webui-与-api-服务",
             },
         ],
-        "warning_codes": ["public_bind_requires_auth"],
+        "warning_codes": ["public_bind_requires_auth", "restart_required"],
     },
     "WEBUI_PORT": {
         "title": "Web UI Port",

src/services/system_config_service.py

@@ -1227,6 +1227,19 @@ def _build_explainability_warnings(
                 )
             )
 
+        startup_only_bind_keys = submitted_keys & {
+            "WEBUI_HOST",
+            "WEBUI_PORT",
+        }
+        if startup_only_bind_keys:
+            warnings.append(
+                (
+                    f"{', '.join(sorted(startup_only_bind_keys))} 已写入 .env。"
+                    "这些属于启动期监听配置：当前已运行的 WebUI/API 进程不会因为本次保存重新绑定监听地址或端口；"
+                    "请重启当前进程、Docker 容器或服务管理器后生效。"
+                )
+            )
+
         return warnings
 
     @staticmethod

tests/test_system_config_service.py

@@ -1528,6 +1528,27 @@ def test_update_appends_mode_specific_startup_warnings(self) -> None:
         self.assertIn("以 schedule 模式重新启动后生效", schedule_warning)
         self.assertNotIn("它属于启动期单次运行配置", schedule_warning)
 
+    def test_update_appends_webui_bind_restart_warning(self) -> None:
+        response = self.service.update(
+            config_version=self.manager.get_config_version(),
+            items=[
+                {"key": "WEBUI_HOST", "value": "0.0.0.0"},
+                {"key": "WEBUI_PORT", "value": "18000"},
+            ],
+            reload_now=True,
+        )
+
+        self.assertTrue(response["success"])
+        bind_warning = next(
+            warning
+            for warning in response["warnings"]
+            if "WEBUI_HOST" in warning and "WEBUI_PORT" in warning
+        )
+
+        self.assertIn("启动期监听配置", bind_warning)
+        self.assertIn("不会因为本次保存重新绑定监听地址或端口", bind_warning)
+        self.assertIn("重启当前进程、Docker 容器或服务管理器后生效", bind_warning)
+
     def test_update_warns_when_runtime_model_references_are_cleared(self) -> None:
         self._rewrite_env(
             "STOCK_LIST=600519,000001",