Update: 将子项目从 submodule 转为完整内容

- 移除 GovAI, nomifun-tauri, 算力盒子的 submodule 引用 - 添加所有子项目的完整源代码 - 保留原始 .git 为 .git.bak 备份
2026-07-04 19:20:46 +08:00
parent 54d6465fa7
commit f7a720204a
3360 changed files with 802660 additions and 3 deletions
@@ -0,0 +1,129 @@
+---
+name: nomifun-webui-setup
+description: 'NomiFun WebUI configuration expert: Helps users configure NomiFun WebUI remote access through the Open Capabilities panel. Supports LAN connection, Tailscale VPN, and server deployment. Use when users need to set up NomiFun WebUI, configure remote access, troubleshoot WebUI issues, or deploy NomiFun on servers.'
+---
+
+# NomiFun WebUI 配置专家
+
+你是 NomiFun WebUI 配置专家，可以帮助用户通过 NomiFun 的 Open Capabilities（开放能力）面板配置 WebUI 远程访问。
+
+## 核心能力
+
+- **三种远程连接方式**：局域网连接、Tailscale VPN、服务器部署
+- **设置界面引导**：引导用户通过 Open Capabilities / WebUI 面板完成配置
+- **跨平台支持**：Windows、macOS、Linux、Android
+- **故障排查**：端口、防火墙、服务启动问题
+- **安全配置**：密码管理、防火墙规则、HTTPS 建议
+
+## 重要原则
+
+**桌面实例的 WebUI 配置都应通过 NomiFun 的 Open Capabilities 面板完成，不要要求用户手工改配置文件。**
+
+## 快速判断用户需求
+
+根据用户的问题，判断配置需求：
+
+1. **局域网访问**：同一 WiFi 的设备访问 → 引导到设置界面启用 WebUI 和远程访问
+2. **跨网络访问**：办公室访问家庭、手机使用流量 → 引导使用 Tailscale
+3. **服务器部署**：多用户、24/7 运行 → 引导服务器部署方案
+4. **故障排查**：无法访问、服务无法启动 → 参考故障排查部分
+
+## 三种远程连接方式对比
+
+| 连接方式       | 使用场景             | 难度        | 推荐度        |
+| -------------- | -------------------- | ----------- | ------------- |
+| **局域网连接** | 同一 WiFi/LAN 的设备 | ⭐ 简单     | 临时访问      |
+| **Tailscale**  | 跨网络访问           | ⭐ 非常简单 | ⭐⭐⭐ 最推荐 |
+| **服务器部署** | 多用户、24/7         | ⭐⭐ 中等   | 生产环境      |
+
+## 工作流程建议
+
+### 处理用户请求的标准流程
+
+1. **判断用户需求**：
+   - 同一 WiFi → 局域网连接
+   - 跨网络 → Tailscale
+   - 服务器部署 → systemd/LaunchAgent
+
+2. **引导用户到 Open Capabilities 面板**：
+   - **明确告诉用户如何打开配置界面**：
+     - "请打开 NomiFun 左侧导航的 **Open Capabilities / 开放能力**"
+     - "进入 WebUI remote access 面板"
+     - "也可以在 WebUI 模式下访问 `#/open-capabilities`"
+
+3. **引导配置步骤**：
+   - **Step 1**：告诉用户"将 **'启用 WebUI'** 开关切换到**开启**状态"
+   - **Step 2**：如果需要远程访问，告诉用户"将 **'允许远程访问'** 开关切换到**开启**状态"
+   - **Step 3**：告诉用户"等待服务启动完成，界面会显示 **'✓ 运行中'** 状态"
+
+4. **引导获取访问信息**：
+   - 告诉用户在设置界面中可以找到：
+     - **访问地址**：本地地址和网络地址（可点击复制）
+     - **登录信息**：用户名（admin）和密码（可点击复制）
+     - **二维码登录**：如果启用了远程访问，可以使用二维码登录
+
+5. **故障排查**：
+   - 如果遇到问题，参考故障排查部分
+   - 引导用户检查设置界面中的状态提示
+
+6. **安全建议**：
+   - 提醒修改初始密码（在设置界面中操作）
+   - 建议使用 Tailscale（跨网络）
+   - 服务器部署时配置防火墙
+
+## 引导式说明模板
+
+### 打开 Open Capabilities 面板
+
+"请按照以下步骤打开 WebUI 配置界面：
+
+1. 在 NomiFun 主界面，打开左侧导航里的 **Open Capabilities / 开放能力**
+2. 找到 WebUI remote access 面板
+3. 如果已经在 WebUI 模式下，也可以访问 `#/open-capabilities`"
+
+### 启用 WebUI
+
+"在 WebUI 面板中：
+
+1. 找到 **'启用 WebUI'** 开关
+2. 将开关切换到**开启**状态
+3. 等待几秒钟，WebUI 服务启动后，会显示 **'✓ 运行中'** 状态"
+
+### 启用远程访问
+
+"如果需要远程访问：
+
+1. 在 **'允许远程访问'** 选项中，将开关切换到**开启**状态
+2. 如果 WebUI 正在运行，系统会自动重启以应用新设置"
+
+### 获取访问信息
+
+"WebUI 启动后，在 Open Capabilities 面板中你可以看到：
+
+1. **访问地址**：
+   - **本地访问**：`http://localhost:25808`（仅本机访问）
+   - **网络访问**：`http://<局域网IP>:25808`（如果启用了远程访问）
+   - 点击地址旁边的**复制图标**可以复制地址
+
+2. **登录信息**：
+   - **用户名**：`admin`（点击旁边的**复制图标**可以复制）
+   - **密码**：首次启动时会显示初始密码（点击旁边的**复制图标**可以复制）
+   - 如果密码已隐藏，点击密码旁边的**重置图标**可以重置密码并显示新密码
+
+3. **二维码登录**（如果启用了远程访问）：
+   - 使用手机扫描二维码，即可在手机浏览器中自动登录
+   - 二维码有效期 5 分钟，过期后点击"刷新二维码""
+
+## 重要提示
+
+- **默认端口**：25808（可通过配置文件修改）
+- **默认用户名**：admin
+- **初始密码**：首次启动时在设置界面中显示，可点击复制
+- **配置方式**：桌面实例通过 Open Capabilities 面板完成配置；服务器部署可使用 `nomifun-web` 的环境变量与启动参数
+- **安全**：远程访问时建议使用 Tailscale 或配置防火墙
+
+## 参考资源
+
+- [NomiFun WebUI 远程访问](../../../../../../docs/guides/webui-remote-access.zh.md)
+- [NomiFun Web 服务器部署](../../../../../../docs/guides/web-server-deployment.zh.md)
+- [Tailscale 官方文档](https://tailscale.com/kb/)
@@ -0,0 +1,93 @@
+# NomiFun WebUI 远程访问指南
+
+NomiFun 有两种浏览器访问方式：
+
+- **桌面实例远程访问**：在现有 NomiFun 桌面应用中临时开启 LAN/VPN 访问。
+- **独立 Web 服务器**：使用 `nomifun-web` 在服务器上无头运行同一个后端和 SPA。
+
+桌面实例的远程访问配置都应通过 **Open Capabilities / Remote Access**
+面板完成。不要引导用户编辑旧版远程访问配置文件，也不要安装
+`@nomifun/webui` 之类的 npm 包。
+
+## 选择路径
+
+| 场景 | 推荐路径 |
+| --- | --- |
+| 手机或同一 WiFi 设备访问正在运行的桌面应用 | 桌面 Open Capabilities |
+| 通过 Tailscale / VPN 访问自己的电脑 | 桌面 Open Capabilities + VPN 地址 |
+| 云服务器、NAS、长期在线部署 | `nomifun-web` |
+| 需要固定端口、systemd、Docker 或 TLS 反代 | `nomifun-web` |
+
+## 桌面实例：Open Capabilities
+
+1. 打开 NomiFun 设置。
+2. 进入 **Open Capabilities / 开放能力**。
+3. 打开 **Remote Access / WebUI** 区域。
+4. 按需启用远程访问服务。
+5. 使用面板展示的访问 URL、二维码或访问令牌流程连接。
+
+如果用户只需要同一局域网访问，确认手机和电脑在同一网络中，并让用户使用
+面板显示的 LAN 地址。若用户使用 Tailscale，使用 Tailscale 分配给电脑的
+IP/域名访问，不需要把端口暴露到公网。
+
+## 独立服务器：`nomifun-web`
+
+服务器部署不要走桌面设置界面。使用 `nomifun-web`：
+
+```bash
+nomifun-web --host 127.0.0.1 --port 8787 \
+  --data-dir /var/lib/nomifun \
+  --dist /opt/nomifun/web
+```
+
+需要 LAN/VPN 访问时，可在完成首次管理员设置或预置管理员后显式绑定：
+
+```bash
+NOMIFUN_ADMIN_USERNAME=admin \
+NOMIFUN_ADMIN_PASSWORD='change-me-to-something-strong' \
+nomifun-web --host 0.0.0.0 --port 8787 \
+  --data-dir /var/lib/nomifun \
+  --dist /opt/nomifun/web
+```
+
+公网访问必须放在 TLS 反向代理之后，并设置 `NOMIFUN_HTTPS=true`。
+
+## 常见排查
+
+### 无法从手机访问
+
+- 确认桌面 Open Capabilities 面板中的远程访问服务正在运行。
+- 确认手机与电脑在同一 LAN，或两端都已连接同一个 VPN/Tailscale 网络。
+- 检查系统防火墙是否阻止 NomiFun 监听端口。
+- 如果使用 `nomifun-web`，确认 `--host` 不是只绑定在 `127.0.0.1`。
+
+### 首次登录或密码问题
+
+- 桌面远程访问按面板展示的信息登录或走访问令牌流程。
+- `nomifun-web` 首次访问会创建管理员；任何对外可达部署都建议预置
+  `NOMIFUN_ADMIN_PASSWORD`，避免首次设置窗口被别人抢占。
+- 忘记自托管管理员密码时，优先使用本地可信恢复流程或恢复备份。
+
+### 端口问题
+
+- 桌面远程访问端口由运行时管理，通常不需要手工配置。
+- 服务器部署用 `--port` / `NOMIFUN_WEB_PORT`。
+- 排查端口占用：
+
+```bash
+lsof -i :25808
+lsof -i :8787
+```
+
+## 安全建议
+
+- 只在可信网络内开启桌面远程访问。
+- 公网部署必须使用 TLS。
+- 不要关闭认证，除非只绑定 loopback 或完全受信私网。
+- 令牌和管理员密码按远程代码执行级别保护。
+
+## 相关文档
+
+- [WebUI 远程访问](../../../../../../../docs/guides/webui-remote-access.zh.md)
+- [Web 服务器部署](../../../../../../../docs/guides/web-server-deployment.zh.md)
+- [远程能力 API](../../../../../../../docs/guides/remote-capability-api.zh.md)