feat(DebugLogViewer): add LAN access feature for debug log viewer

BAKAOLC · BAKAOLC · commit f08fe7f8cb55 · 2026-06-04T07:38:30.000+08:00
- Introduced a new setting to enable LAN access for the debug log viewer, allowing it to listen on all network interfaces.
- Updated related classes and settings to support the new LAN access functionality, including UI bindings and localization.
- Enhanced logging to provide clearer messages regarding the access mode and available LAN URLs.
diff --git a/Data/Models/RitsuLibSettings.cs b/Data/Models/RitsuLibSettings.cs
@@ -70,8 +70,8 @@ public sealed class RitsuLibSettings
         public bool DebugCompatAncientArchitect { get; set; } = true;
 
         /// <summary>
-        ///     Starts the loopback-only browser debug log viewer for this session.
-        ///     为本会话启动仅监听 loopback 的浏览器调试日志查看器。
+        ///     Starts the browser debug log viewer for this session. It listens on loopback unless LAN access is enabled.
+        ///     为本会话启动浏览器调试日志查看器；除非启用局域网访问，否则仅监听 loopback。
         /// </summary>
         [JsonPropertyName("debug_log_viewer_enabled")]
         public bool DebugLogViewerEnabled { get; set; } = true;
@@ -91,8 +91,15 @@ public sealed class RitsuLibSettings
         public bool DebugLogViewerAutoOpen { get; set; }
 
         /// <summary>
-        ///     Loopback HTTP port for the debug log viewer.
-        ///     调试日志查看器的 loopback HTTP 端口。
+        ///     When true, binds the debug log viewer to all network interfaces so devices on the same LAN can connect.
+        ///     为 true 时，调试日志查看器会监听所有网络接口，使同一局域网设备可以连接。
+        /// </summary>
+        [JsonPropertyName("debug_log_viewer_lan_access_enabled")]
+        public bool DebugLogViewerLanAccessEnabled { get; set; }
+
+        /// <summary>
+        ///     HTTP port for the debug log viewer.
+        ///     调试日志查看器的 HTTP 端口。
         /// </summary>
         [JsonPropertyName("debug_log_viewer_port")]
         public int DebugLogViewerPort { get; set; } = 18742;
@@ -105,8 +112,8 @@ public sealed class RitsuLibSettings
         public int DebugLogViewerPortFallbackCount { get; set; } = 20;
 
         /// <summary>
-        ///     Stable browser access token for the loopback debug log viewer.
-        ///     本机调试日志查看器使用的稳定浏览器访问 token。
+        ///     Stable browser access token for the debug log viewer.
+        ///     调试日志查看器使用的稳定浏览器访问 token。
         /// </summary>
         [JsonPropertyName("debug_log_viewer_access_token")]
         public string DebugLogViewerAccessToken { get; set; } = "";
diff --git a/Data/RitsuLibSettingsStore.cs b/Data/RitsuLibSettingsStore.cs
@@ -224,6 +224,7 @@ internal static RitsuDebugLogViewerOptions GetDebugLogViewerOptions()
                 s.DebugLogViewerEnabled,
                 s.DebugLogViewerMirrorGameLogs,
                 s.DebugLogViewerAutoOpen,
+                s.DebugLogViewerLanAccessEnabled,
                 Math.Clamp(s.DebugLogViewerPort, 1, 65535),
                 Math.Clamp(s.DebugLogViewerPortFallbackCount, 0, 100),
                 s.DebugLogViewerAccessToken,
diff --git a/Diagnostics/Logging/RitsuDebugLogPipeline.cs b/Diagnostics/Logging/RitsuDebugLogPipeline.cs
@@ -47,7 +47,12 @@ public static void Initialize(RitsuDebugLogViewerOptions options)
                     _ring = new(Math.Clamp(options.RingBufferCapacity, 512, 100000));
                     _cts = new();
 
-                    _server = new(options.AccessToken, Snapshot, BuildStatus, ResolveViewerAssetRoot());
+                    _server = new(
+                        options.AccessToken,
+                        options.LanAccessEnabled,
+                        Snapshot,
+                        BuildStatus,
+                        ResolveViewerAssetRoot());
                     _server.Start(options.Port, options.PortFallbackCount);
 
                     _worker = Task.Run(WorkerLoopAsync);
@@ -63,13 +68,12 @@ public static void Initialize(RitsuDebugLogViewerOptions options)
                     _initialized = true;
                     AppDomain.CurrentDomain.ProcessExit += OnProcessExit;
 
-                    RitsuLibFramework.Logger.Info(
-                        $"[DebugLogViewer] Local debug log viewer listening at {_server.Url}");
+                    RitsuLibFramework.Logger.Info(CreateViewerStartMessage(_server));
                 }
                 catch (Exception ex)
                 {
                     CleanupAfterFailedStart();
-                    RitsuLibFramework.Logger.Warn($"[DebugLogViewer] Failed to start local viewer: {ex.Message}");
+                    RitsuLibFramework.Logger.Warn($"[DebugLogViewer] Failed to start viewer: {ex.Message}");
                 }
             }
         }
@@ -104,6 +108,9 @@ public static object BuildStatus()
                 sessionStartedAtUtc = SessionStartedAtUtc,
                 processId = Environment.ProcessId,
                 url = ViewerUrl,
+                accessMode = _server?.AccessMode ?? "loopback",
+                lanAccessEnabled = _server?.LanAccessEnabled ?? false,
+                lanUrls = _server?.LanUrls ?? [],
                 clients = _server?.ClientCount ?? 0,
                 bufferCount = _ring?.Count ?? 0,
                 bufferCapacity = _ring?.Capacity ?? 0,
@@ -135,6 +142,17 @@ public static (bool Success, string Message) TryOpenViewerInBrowser()
                 : (false, $"Error {error}: Could not open browser. URL: {url}");
         }
 
+        private static string CreateViewerStartMessage(RitsuDebugLogViewerServer server)
+        {
+            if (!server.LanAccessEnabled)
+                return $"[DebugLogViewer] Local debug log viewer listening at {server.Url}";
+
+            var lanUrls = server.LanUrls;
+            return lanUrls.Count == 0
+                ? $"[DebugLogViewer] LAN debug log viewer listening at {server.Url}; no LAN IPv4 address was found."
+                : $"[DebugLogViewer] LAN debug log viewer listening at {server.Url}; LAN URLs: {string.Join(", ", lanUrls)}";
+        }
+
         private static async Task WorkerLoopAsync()
         {
             var token = _cts!.Token;
diff --git a/Diagnostics/Logging/RitsuDebugLogViewerOptions.cs b/Diagnostics/Logging/RitsuDebugLogViewerOptions.cs
@@ -4,6 +4,7 @@ internal sealed record RitsuDebugLogViewerOptions(
         bool Enabled,
         bool MirrorGameLogs,
         bool AutoOpen,
+        bool LanAccessEnabled,
         int Port,
         int PortFallbackCount,
         string AccessToken,
diff --git a/Diagnostics/Logging/RitsuDebugLogViewerServer.cs b/Diagnostics/Logging/RitsuDebugLogViewerServer.cs
@@ -25,11 +25,13 @@ internal sealed class RitsuDebugLogViewerServer : IDisposable
 
         public RitsuDebugLogViewerServer(
             string token,
+            bool lanAccessEnabled,
             Func<int, RitsuDebugLogRecord[]> historyProvider,
             Func<object> statusProvider,
             string? assetRoot)
         {
             _token = token;
+            LanAccessEnabled = lanAccessEnabled;
             _historyProvider = historyProvider;
             _statusProvider = statusProvider;
             _assetRoot = string.IsNullOrWhiteSpace(assetRoot) ? null : assetRoot;
@@ -39,7 +41,13 @@ public RitsuDebugLogViewerServer(
 
         public int ClientCount => _clients.Count;
 
-        public string Url => $"http://127.0.0.1:{Port}/?token={Uri.EscapeDataString(_token)}";
+        public bool LanAccessEnabled { get; }
+
+        public string AccessMode => LanAccessEnabled ? "lan" : "loopback";
+
+        public string Url => BuildUrl("127.0.0.1");
+
+        public IReadOnlyList<string> LanUrls => LanAccessEnabled ? GetLanUrls() : [];
 
         public void Dispose()
         {
@@ -59,7 +67,7 @@ public void Start(int requestedPort, int fallbackCount)
                 var port = firstPort + i;
                 try
                 {
-                    _listener = new(IPAddress.Loopback, port);
+                    _listener = new(LanAccessEnabled ? IPAddress.Any : IPAddress.Loopback, port);
                     _listener.Start();
                     break;
                 }
@@ -73,7 +81,7 @@ public void Start(int requestedPort, int fallbackCount)
 
             if (_listener == null)
                 throw new InvalidOperationException(
-                    $"Could not bind local debug viewer port range {firstPort}-{firstPort + maxAttempts - 1}.",
+                    $"Could not bind debug viewer port range {firstPort}-{firstPort + maxAttempts - 1}.",
                     lastException);
 
             Port = ((IPEndPoint)_listener.LocalEndpoint).Port;
@@ -291,6 +299,40 @@ private static int ParseLimit(string query)
             return int.TryParse(GetQueryValue(query, "limit"), out var limit) ? Math.Clamp(limit, 1, 20000) : 5000;
         }
 
+        private string BuildUrl(string host)
+        {
+            return $"http://{host}:{Port}/?token={Uri.EscapeDataString(_token)}";
+        }
+
+        private IReadOnlyList<string> GetLanUrls()
+        {
+            if (Port <= 0)
+                return [];
+
+            try
+            {
+                return Dns.GetHostAddresses(Dns.GetHostName())
+                    .Where(IsUsableLanAddress)
+                    .Select(address => BuildUrl(address.ToString()))
+                    .Distinct(StringComparer.OrdinalIgnoreCase)
+                    .ToArray();
+            }
+            catch (Exception ex) when (ex is SocketException or InvalidOperationException)
+            {
+                RitsuDebugLogPipeline.ReportInternalWarning($"Could not enumerate LAN addresses: {ex.Message}");
+                return [];
+            }
+        }
+
+        private static bool IsUsableLanAddress(IPAddress address)
+        {
+            if (address.AddressFamily != AddressFamily.InterNetwork || IPAddress.IsLoopback(address))
+                return false;
+
+            var bytes = address.GetAddressBytes();
+            return bytes is not [0, 0, 0, 0] and not [169, 254, _, _];
+        }
+
         private static string? GetQueryValue(string query, string key)
         {
             return (from pair in query.Split('&', StringSplitOptions.RemoveEmptyEntries)
diff --git a/Settings/Integration/RitsuLibModSettingsBootstrap.DebugLogViewerPage.cs b/Settings/Integration/RitsuLibModSettingsBootstrap.DebugLogViewerPage.cs
@@ -21,6 +21,12 @@ private static void RegisterDebugLogViewerPage(RitsuLibModSettingsUiBindings ui)
                             ui.DebugLogViewerAutoOpen,
                             T("ritsulib.debugLogViewer.autoOpen.description",
                                 "When enabled, RitsuLib waits 3 seconds after starting the viewer. If no browser page is listening, it opens one."))
+                        .AddToggle(
+                            "debug_log_viewer_lan_access",
+                            T("ritsulib.debugLogViewer.lanAccess.label", "Allow LAN access"),
+                            ui.DebugLogViewerLanAccessEnabled,
+                            T("ritsulib.debugLogViewer.lanAccess.description",
+                                "When enabled, the debug log viewer listens on all network interfaces so other devices on the same LAN can open it with the tokenized URL. Changes apply on next launch."))
                         .AddIntSlider(
                             "debug_log_viewer_port",
                             T("ritsulib.debugLogViewer.port.label", "Viewer port"),
@@ -30,15 +36,15 @@ private static void RegisterDebugLogViewerPage(RitsuLibModSettingsUiBindings ui)
                             1,
                             value => value.ToString(),
                             T("ritsulib.debugLogViewer.port.description",
-                                "Loopback HTTP port. If the port is busy, RitsuLib tries the following ports in order. Changes apply on next launch."))
+                                "HTTP port. If the port is busy, RitsuLib tries the following ports in order. Changes apply on next launch."))
                         .AddButton(
                             "debug_log_viewer_open_now",
                             T("ritsulib.debugLogViewer.openNow.label", "Open viewer"),
                             T("ritsulib.debugLogViewer.openNow.button", "Open log viewer"),
                             OpenDebugLogViewerFromSettings,
                             ModSettingsButtonTone.Accent,
                             T("ritsulib.debugLogViewer.openNow.description",
-                                "Opens the currently running local log viewer in your system browser."))),
+                                "Opens the currently running log viewer in your system browser."))),
                 "debug-log-viewer");
         }
 
diff --git a/Settings/Integration/RitsuLibModSettingsUiBindings.cs b/Settings/Integration/RitsuLibModSettingsUiBindings.cs
@@ -15,6 +15,7 @@ private RitsuLibModSettingsUiBindings()
         public IModSettingsValueBinding<bool> DebugCompatLocTable { get; private init; } = null!;
         public IModSettingsValueBinding<bool> DebugCompatUnlockEpoch { get; private init; } = null!;
         public IModSettingsValueBinding<bool> DebugLogViewerAutoOpen { get; private init; } = null!;
+        public IModSettingsValueBinding<bool> DebugLogViewerLanAccessEnabled { get; private init; } = null!;
         public IModSettingsValueBinding<int> DebugLogViewerPort { get; private init; } = null!;
 
         public IModSettingsValueBinding<bool> DebugCompatAncientArchitect { get; private init; } =
@@ -152,6 +153,13 @@ public static RitsuLibModSettingsUiBindings Create()
                         settings => settings.DebugLogViewerAutoOpen,
                         (settings, value) => settings.DebugLogViewerAutoOpen = value),
                     () => defaults.DebugLogViewerAutoOpen),
+                DebugLogViewerLanAccessEnabled = ModSettingsBindings.WithDefault(
+                    ModSettingsBindings.Global<RitsuLibSettings, bool>(
+                        Const.ModId,
+                        Const.SettingsKey,
+                        settings => settings.DebugLogViewerLanAccessEnabled,
+                        (settings, value) => settings.DebugLogViewerLanAccessEnabled = value),
+                    () => defaults.DebugLogViewerLanAccessEnabled),
                 DebugLogViewerPort = ModSettingsBindings.WithDefault(
                     ModSettingsBindings.Global<RitsuLibSettings, int>(
                         Const.ModId,
@@ -510,6 +518,5 @@ private static string NormalizeToastAnimation(string? value)
                 _ => "fadeslide",
             };
         }
-
     }
 }
diff --git a/Settings/Localization/ModSettingsUi/eng.json b/Settings/Localization/ModSettingsUi/eng.json
@@ -223,11 +223,13 @@
   "ritsulib.debugLogViewer.description": "Configure the browser-based live log viewer. Port changes apply on next game launch.",
   "ritsulib.debugLogViewer.autoOpen.label": "Open browser automatically",
   "ritsulib.debugLogViewer.autoOpen.description": "When enabled, RitsuLib waits 3 seconds after starting the viewer. If no browser page is listening, it opens one.",
+  "ritsulib.debugLogViewer.lanAccess.label": "Allow LAN access",
+  "ritsulib.debugLogViewer.lanAccess.description": "When enabled, the debug log viewer listens on all network interfaces so other devices on the same LAN can open it with the tokenized URL. Changes apply on next launch.",
   "ritsulib.debugLogViewer.port.label": "Viewer port",
-  "ritsulib.debugLogViewer.port.description": "Loopback HTTP port. If the port is busy, RitsuLib tries the following ports in order. Changes apply on next launch.",
+  "ritsulib.debugLogViewer.port.description": "HTTP port. If the port is busy, RitsuLib tries the following ports in order. Changes apply on next launch.",
   "ritsulib.debugLogViewer.openNow.label": "Open viewer",
   "ritsulib.debugLogViewer.openNow.button": "Open log viewer",
-  "ritsulib.debugLogViewer.openNow.description": "Opens the currently running local log viewer in your system browser.",
+  "ritsulib.debugLogViewer.openNow.description": "Opens the currently running log viewer in your system browser.",
   "ritsulib.section.harmonyDump.title": "Harmony patch dump",
   "ritsulib.section.harmonyDump.description": "Export a text report of patched methods (prefix/postfix/transpiler/finalizer) for debugging mod interactions.",
   "ritsulib.section.selfCheck.title": "Self-check mode",
diff --git a/Settings/Localization/ModSettingsUi/zhs.json b/Settings/Localization/ModSettingsUi/zhs.json
@@ -223,11 +223,13 @@
   "ritsulib.debugLogViewer.description": "配置基于浏览器的实时日志查看器。端口修改会在下次启动游戏时生效。",
   "ritsulib.debugLogViewer.autoOpen.label": "自动打开浏览器",
   "ritsulib.debugLogViewer.autoOpen.description": "启用后，RitsuLib 会在查看器启动后等待 3 秒；如果没有浏览器页面正在监听，就自动打开一个页面。",
+  "ritsulib.debugLogViewer.lanAccess.label": "允许局域网访问",
+  "ritsulib.debugLogViewer.lanAccess.description": "启用后，调试日志查看器会监听所有网络接口，同一局域网内的其他设备可通过带 token 的 URL 打开。修改会在下次启动时生效。",
   "ritsulib.debugLogViewer.port.label": "查看器端口",
-  "ritsulib.debugLogViewer.port.description": "本机 HTTP 端口。如果端口被占用，RitsuLib 会按顺序尝试后续端口。修改会在下次启动时生效。",
+  "ritsulib.debugLogViewer.port.description": "HTTP 端口。如果端口被占用，RitsuLib 会按顺序尝试后续端口。修改会在下次启动时生效。",
   "ritsulib.debugLogViewer.openNow.label": "打开查看器",
   "ritsulib.debugLogViewer.openNow.button": "打开日志查看器",
-  "ritsulib.debugLogViewer.openNow.description": "在系统浏览器中打开当前正在运行的本机日志查看器。",
+  "ritsulib.debugLogViewer.openNow.description": "在系统浏览器中打开当前正在运行的日志查看器。",
   "ritsulib.section.harmonyDump.title": "Harmony 补丁导出",
   "ritsulib.section.harmonyDump.description": "导出已补丁方法的文本报告（前缀/后缀/Transpiler/Finalizer），用于排查模组冲突。",
   "ritsulib.section.selfCheck.title": "自检模式",
diff --git a/Viewer/src/logTypes.ts b/Viewer/src/logTypes.ts
@@ -20,6 +20,9 @@ export type Status = {
     sessionStartedAtUtc?: string;
     processId?: number;
     url?: string;
+    accessMode?: "loopback" | "lan";
+    lanAccessEnabled?: boolean;
+    lanUrls?: string[];
     bufferCount: number;
     bufferCapacity: number;
     queueDepth: number;
