well404.WebPanel 1.2.2

well404.WebPanel

Unturned / OpenMod 通用 Web 管理面板 —— 一个 schema 驱动的单页面板,让各功能插件挂载自己的可视化管理模块。

well404.WebPanel 是 well404 OpenMod 插件家族 的基础设施插件。它内置一个轻量 HTTP 服务(基于 BCL HttpListener,无外部依赖)与单页应用,并对外暴露 IWebPanelRegistry; well404.Economy、 well404.Shop 等插件在加载时把自己的管理 模块注册进来,面板即可通用地渲染出表单、设置组、集合 CRUD 与搜索框,而无需了解各插件实现。

功能

• 🌐 内置 HTTP 服务 + 单页管理界面,零外部依赖
• 🧩 IWebPanelRegistry:其他插件按统一 schema 注册管理模块(Settings / Collection / Search / Form / Table)
• 🔐 路径式 token 鉴权(/<token>/,管理面强制有 token;留空则自动生成并写回配置)
• 🌐 内置反代/隧道(可选):一键经 cloudflared / ngrok 把面板安全暴露到公网,隐藏真实 IP、自动 HTTPS;系统没装 cloudflared 时自动下载便携版(不污染系统)
• 🛠️ 安装即用:装了哪个家族插件,面板里就出现对应模块
• 🎮 面向玩家的网页界面(/p):玩家游戏内 /menu 即可在浏览器里看服务器介绍页、逛商店买卖、查钱包转账、用实用工具(传送/组队/礼包/睡觉);各插件经 IPlayerMenuRegistry 注册「玩家菜单」
• 🌍 管理面板 + 玩家面板均中英双语可切换(默认英文);网页文案经 IWebTranslationRegistry 提供翻译,新增语言只需加一张映射表

安装

openmod install well404.WebPanel

重启服务器或执行 openmod reload 后,启动日志会打印管理面地址 http://<地址>:<端口>/<token>/。

配置 (config.yaml)

web:
  bindAddress: "127.0.0.1"   # 监听地址:127.0.0.1(仅本机)| 0.0.0.0(全部)| 指定 IP
  port: 27020                 # 监听端口
  token: ""                  # 管理面密钥;留空=首次启动随机生成 12 位并写回本文件
  tunnel:                    # 可选:内置反代,把面板安全暴露到公网
    enabled: false
    type: "cloudflare"       # cloudflare(找不到 cloudflared 会自动下载便携版) | custom(自定义,适配 ngrok 等)
    command: "cloudflared"
    autoDownload: true       # cloudflare 专用:找不到 cloudflared 时下载便携版到插件数据目录(不装进系统),缓存复用
    downloadMirrors: []      # 下载源列表;空=内置默认(GitHub→jsDelivr 镜像→代理)。先探测连通性,只下能连通的;遵循系统/HTTPS_PROXY 代理
    downloadAttempts: 2      # 每个下载源的重试次数
  publicBaseUrl: ""          # 玩家 /menu 链接的公网地址;空=自动推导(开 tunnel 时用隧道地址)
  playerSessionMinutes: 5    # 玩家链接有效期下限;实际不少于 15 分钟
  devPlayer:                 # 开发预览:不进游戏也能以指定账号查看玩家面(默认关)
    enabled: false
    steamId: ""              # 要模拟的玩家 Steam ID
    displayName: "Dev Player"

开发者预览:devPlayer.enabled: true 后访问 /<token>/dev-player,即以 steamId 账号 直接进入其玩家面板(/p),无需进游戏发 /menu——便于在浏览器里调试玩家菜单。藏在管理面密钥 路径之后且默认关闭;属玩家身份模拟,生产环境请保持关闭。需玩家在线的动作(买卖/传送)仍提示「需要在线」。

安全说明

• 路径式 token:管理面始终在 http://host:port/<token>/ 下,token 即鉴权;路径不对一律 404(不泄露面板是否存在)。
• token 强制存在:留空则自动生成 12 位大小写字母+数字并写回 config.yaml(重启不变);不在 WebUI 中可改,只能改配置文件。
• 内置反代(web.tunnel):开启后经 cloudflared / ngrok 把面板反代到公网,不暴露真实 IP、不开入站端口、自动 HTTPS;隧道把整个端口反代出去,管理面就靠路径 token 保护,务必保密。
• 玩家面(/p)用各玩家一次性短时令牌:有效期至少 15 分钟,之后只要在线就有效,下线即失效;与管理员 token 互相独立。

命令

HTTP 接口

管理面全部在 /<token>/ 前缀下(下表省略前缀);玩家面在 /p、/api/p/*。

给插件开发者

• 管理模块:可选注入 IWebPanelRegistry(来自共享库 UnturnedMods.Shared),用 WebPanelModule 描述若干 WebPanelAction 并注册;面板自动渲染。
• 玩家菜单:可选注入 IPlayerMenuRegistry,实现 IPlayerMenu(RenderAsync 出卡片、 InvokeAsync 执行按钮)并注册;玩家在 /p 面板里以自己的身份操作。

两者注入皆为可选——未安装本面板时注册被跳过,你的插件照常工作。

well404 OpenMod 插件家族

完整文档、配置示例与本地调试说明见 GitHub 仓库 的 docs/。

许可

CC BY-NC-SA 4.0 © well404