原创 开源 工具 娱乐 网页端玩家商店 Release 1

MagicWebShop · 魔法集市 — 我的世界跨服交易插件​

我的世界版"淘宝"：自带网页商城的跨服物品交易插件。 玩家在游戏内上架物品，网页实时展示商品与真实材质图标，其他服务器的玩家也能浏览、购买、换购。 支持货币交易（Vault）与以物换物两种玩法，跨服互通、离线发货、邮箱领取、安全登录，一应俱全。

点击展开...

功能特性​

交易玩法​

• 货币交易：一口价上架，单价可设，支持"全部买下"与"按件购买"；通过 Vault 结算，可配置手续费比例。
• 以物换物：指定想要的物品与数量，买家在线用对应物品交换。
• 跨服互通：多个服务器商品自动聚合到同一个网页商城，支持链路聚合（内网直连优先、公网/frp 备用，断线自动切换）。
• 邮箱系统：买到的物品进邮箱（分页 45 格/页，最多 5 页），随时 /webshop mailbox 领取；离线也不丢货。
• 收货方式自选：玩家可 /webshop delivery 切换"直接进背包 / 进邮箱"，背包装不下自动转邮箱。
• 玩家店铺：点击商品上的卖家名直达其店铺页——显示头像、在售商品、历史成交统计（上架/成交/换物/收入）。
• 收藏卖家：网页一键收藏，快速关注常买的卖家。
• 系统商店：管理员 /webshop sellallmaterials 一键上架全部原版物品（卖家"系统"，不占用玩家上架名额）。

网页商城​

• 零部署网页：插件内置 HTTP 服务器，无需额外网站程序；可选复用游戏端口（share-server-port: true，省去单独开端口/隧道）。
• 真实材质图标：优先使用服务器材质包（支持头颅皮肤 / CustomModelData / item_model），回退到原版镜像下载缓存，离线环境自动用内置贴图+生成的像素图标兜底，永远不会裂图。
• 双浏览模式：翻页（默认 7 行/页，行数可配）/ 加载更多，玩家网页一键切换、浏览器记忆选择。
• 双主题 UI：科幻风 / 可爱风，一键切换，响应式布局手机电脑都好用。
• 玩家头像：优先在线解析皮肤（Mojang/mc-heads/crafatar），离线服自动生成像素风玩家头，也可放自定义头像文件。

安全与运维​

• 双重登录：一次性登录码（8 位字母数字，5 分钟有效，输错 3 次作废）+ 游戏内固定密码（/webshop setpass，SHA-256 加盐存储，防爆破锁定）。
• 防爆破：登录按 IP 限流（5 次失败/分钟锁定）、会话 24 小时过期、请求体大小限制、图片接口参数白名单、缓存上限。
• 自动更新：可选开启，定时检测 GitHub 最新 Release，发现新版本自动下载替换 jar，重启即生效（支持镜像加速）。
• 随机广播：上架/成交/换物各有随机文案模板，全服聊天播报，概率可在配置独立开关（0 = 关闭）。
• 离线兼容：无外网也能跑：头像兜底、内置贴图、离线发货全部可用。

环境要求​

安装与更新​

1. 下载最新 MagicWebShop.jar（Release 资产，命名 MagicWebShop-<版本>.jar，构建号形如 v1.0.0-Build-N）。
2. 放入每台要参与交易的服务器 plugins/ 目录。
3. 重启服务器（或 /reload，但涉及端口/自动更新的改动建议重启）。
4. 首次启动自动生成 plugins/MagicWebShop/config.yml，按下方说明配置。

更新：替换 jar 后重启。若开启了 auto-update: true，插件会自行检测 GitHub 最新版本并下载替换（默认关闭）。 服务器无法直连 GitHub 时，可在 update-mirror 填反代前缀（如 https://ghproxy.net/）。

点击展开...

指令大全​

玩家指令（别名：/mws、/ws、/shop）​

管理员指令（需要 webshop.admin）​

指令演示​

# 玩家上架手中钻石，一口价 100，单价 20（允许按件购买）
/ws sell 100 20
[魔法集市] 已上架 1 个 钻石，一口价 $100.00，单价 $20.00。

# 背包里有 16 个铁矿，一次性全部上架
/ws sellall 160
[魔法集市] 已上架全部 16 个 铁锭，一口价 $160.00，单价 $10.00。

# 上架木棍，想换 8 个石头（把石头放到快捷栏第 3 格）
/ws barter 3
[魔法集市] 已上架 32 个 木棍，用于交换 8 个 石头。

# 获取网页登录码（点击蓝色链接可直接打开并自动登录）
/ws web
[魔法集市] 点击自动登录并打开商城: http://your-ip:25565/?u=Steve&c=Ab3Xk9Qm
（若需手动登录）网址: http://your-ip:25565  登录码: Ab3Xk9Qm
登录码 5 分钟内有效，仅可使用一次（输错 3 次作废）。

# 切换收货方式为直接进背包
/ws delivery backpack
[魔法集市] 已切换收货方式为: 直接放入背包（背包满自动进邮箱）

# 下架（按 Tab 自动补全自己上架的编号）
/ws cancel 3f2a1b90
[魔法集市] 已下架，物品已放入邮箱（使用 /webshop mailbox 领取）。

# 管理员：以系统卖家上架所有原版物品每种 64 个
/ws sellallmaterials 64
[魔法集市] 已以「系统」卖家身份上架 290+ 种原版物品，每种 64 个（单价 1 元）。

权限​

配置文件（config.yml）​

基础​

server-name: "Server-1"    # 本服唯一名字，显示在商品上；全网互不相同
network-secret: "change-me-to-a-long-random-secret"   # 全网所有服务器必须一致，务必改掉！

网页（web）​

web:
  port: 25565                    # 网页 + 跨服 API 端口（跨服需固定且对其它服可达）
  public-url: "auto"             # auto=自动探测公网IP；也可填域名或完整网址
  bind: "0.0.0.0"                # 监听地址
  share-server-port: true        # true=复用游戏端口提供网页（省端口），失败自动回退独立端口
  shop-rows-per-page: 7          # 翻页模式每页行数
  shop-default-view: "pages"     # 默认浏览模式：pages 翻页 / loadmore 加载更多

跨服（peers）​

peers:
  - name: "Server-2"             # 必须等于对方的 server-name
    addresses:                   # 链路聚合，按顺序尝试，第一条能连通的使用
      - "play.otherserver.cn:25565"  # 建议用域名
      - "192.168.1.20:8085"          # 内网直连（快）
      - "cn-hk.sakurafrp.com:23456"  # frp 备用
peer-refresh-seconds: 15         # 每 15 秒刷新一次对端商品缓存

双向互配：跨服交易要求双方服务器都互相在 peers 里填了对方，且 network-secret 一致，才允许互通；不支持单向交易（防止一方漏配造成商品被单边看到/买走）。漏配时日志会提示 403 与原因。

点击展开...

收货方式​

delivery:
  default-mode: "mailbox"        # 玩家默认收货：backpack 背包 / mailbox 邮箱

经济​

economy:
  enabled: true                  # 需要 Vault；false 则只能以物换物
  currency-symbol: "$"           # 货币符号
  sell-fee-percent: 0            # 卖家手续费百分比 0-100
  flat-follows-stock: true       # 一口价是否随剩余数量浮动

贴图​

texture:
  version: "1.20.4"              # 与服务器版本一致，决定下载的镜像贴图
  cdn-base: "https://assets.mcasset.cloud/{version}/assets/minecraft/textures"
  cdn-template: ""               # 高级：直链图床模板（{material} 占位），留空用默认下载+缓存
  resource-pack-dir: ""          # 服务器材质包目录（解压后含 assets 的那层）；留空自动探测

限制 / 邮箱 / 广播​

limits:
  max-listings-per-player: 27    # 每名玩家最大同时上架数
  max-price: 0                   # 最高一口价，0=不限
  allow-self-purchase: false     # 是否允许买自己上架的商品（默认禁止防刷）
mailbox:
  max-pages: 5                   # 邮箱最多显示页数（每页 45 格）
broadcast:
  listing-chance: 100            # 上架广播概率 0-100
  sale-chance: 100               # 成交广播概率
  barter-chance: 100             # 换物成功广播概率

自动更新​

auto-update: false               # 默认关闭
update-repo: "https://github.com/Yomicer/MagicWebShop"
update-mirror: ""                # 墙内加速：填 GitHub 反代前缀，如 https://ghproxy.net/

跨服配置步骤（两台服务器 A / B 示例）​

1. 两台都安装本插件并重启。
2. 两边 network-secret 填同一个随机长字符串。
3. A 的 peers 填 B 的 name + 地址；B 的 peers 也要填 A（双向）。
4. 确保双方 web.port（或共享端口）在防火墙/安全组放行、互相可达。
5. 重启后各自执行 /ws address 确认网址，A 的网页应能看到 B 的商品（反之亦然）。

玩家使用流程​

1. 手持物品，/ws sell 100 或 /ws barter 3 上架。
2. /ws web 拿到网址与登录码，点击链接自动登录网页商城。
3. 浏览全网商品（翻页/加载更多），点击卖家名可看 TA 的店铺与成交记录。
4. 「立即购买 / 用物品交换」完成交易。
5. 金钱即时到账；物品按你的收货方式进背包或邮箱（背包满自动转邮箱）。

常见问题​

• 检查端口是否放行；share-server-port: true 时直接用 http://IP:游戏端口 访问。
• /ws address 可查看插件认定的网址。

• 确认双方 peers 双向互配、name 与 server-name 完全一致、network-secret 相同；服务器日志会提示 403 及原因。

• 需要 Vault + 经济插件，且经济插件支持离线玩家存款（EssentialsX 等均可）。

• 服务器访问 GitHub 受限时，在 update-mirror 填可用的反代前缀，或手动下载替换 jar。

安全建议​

• 务必修改默认的 network-secret 为一串随机长字符；未改则知晓地址者可调用跨服接口。
• 网页登录已内置：IP 限流、登录码熵值/试错上限、密码加盐哈希、会话 24 小时过期、请求体大小限制、参数白名单、缓存上限。
• 暴露公网时建议在网页端口前挂 Nginx/Caddy 反代 + HTTPS（密码与登录码在网络中加密传输）。
• 仅内网互通时，可将 web.bind 改为内网网卡地址。

构建​

# 本地开发构建（版本 = 1.0.0）
mvn clean package
# CI 自动构建（注入构建标识，版本 = 1.0.0-Build-<运行号>，发布 Release）
mvn clean package -Dbuild.suffix=-Build-42