ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

Grasscutter 服务端部署与源码构建实战指南:从环境准备到客户端接入

Grasscutter 服务端部署与源码构建实战指南:从环境准备到客户端接入 Grasscutter 服务端部署与源码构建实战指南从环境准备到客户端接入【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter导读本文以仓库根目录的 docs/README_fil-PH.md菲律宾语版快速部署指南为骨架系统讲解 Grasscutter —— 一个针对某动漫游戏的服务器软件重实现server software reimplementation—— 的完整部署链路环境依赖、服务端启动、代理流量重定向、客户端接入、从源码编译以及常见故障排查。读完本文你将掌握java -jar grasscutter.jar之外的一整套可复现的部署与构建方法并能结合仓库内 Grasscutter.java、proxy.py、start.cmd 等源码理解每一步背后的实现原理。项目概况与当前功能清单Grasscutter 的目标是使用 Java 重新实现某动漫游戏的服务器端逻辑允许玩家自行搭建并运行私服环境。根据 docs/README_fil-PH.md 的 Ang mga kasalukuyang features 一节当前已实现的功能包括登录Logging in账号创建、登录鉴权与游戏会话建立战斗Combat角色战斗相关的服务端逻辑好友列表Friends list好友系统与社交交互传送Teleportation地图点与场景间传送抽卡系统Gacha system祈愿/抽卡服务端逻辑联机Co-op部分可用文档明确标注 partially works即联机功能尚未完全稳定控制台生成怪物Spawning monsters via console通过服务端控制台命令在场景中刷怪背包功能Inventory features获取物品/角色、强化物品/角色等背包相关操作。从源码结构看上述能力分别由仓库中的src/main/java/emu/grasscutter/game/下各子系统承载例如inventory/背包与物品、gacha/抽卡、friends/好友、world/世界与场景传送等模块可作为进一步阅读源码的入口。环境准备三件套依赖在启动服务端之前需要准备以下运行环境对应原文档 Ang mga kailangan 一节依赖版本要求用途JavaJava SE 17 或更高运行 Grasscutter 服务端MongoDB社区版推荐 4.0服务端持久化存储账号、角色、背包等数据代理守护进程mitmproxymitmdump推荐或 Fiddler Classic 等将游戏客户端的网络流量重定向到本机服务端关于 Java 的注意事项如果你仅运行服务端不参与二次开发安装JREJava 运行时环境即可不必安装完整 JDK若需要从源码编译Grasscutter则必须安装JDK 17并确保JDK/bin已加入系统PATH见后文快速故障排查。MongoDB 的作用MongoDB 是 Grasscutter 的默认数据存储。从 ConfigContainer.java 的源码可以看到默认连接串为mongodb://localhost:27017数据库集合名为grasscutter。也就是说在未修改配置的前提下MongoDB 必须监听本机默认端口27017服务端启动时才能成功完成 DatabaseManager.initialize() 的初始化流程。快速部署三步启动服务端原文档 Running 一节给出了标准的部署三步走这里结合仓库源码做完整还原第一步获取 grasscutter.jar获取服务端可执行包有三种途径从项目的 Releases 页面下载最新版本从项目的 CI 构建产物Actions 构建流水线中下载自行从源码编译具体方法见下文从源码构建一节。第二步准备 resources 资源目录在grasscutter.jar所在目录下创建resources文件夹并将以下目录放入其中BinOutput、ExcelBinOutput、Readables、Scripts、Subtitle、TextMap这些目录存放游戏的服务端资源数据二进制配置、Excel 数据表、脚本等是服务端解析游戏数据的依据。在仓库中资源路径的默认配置同样体现在 ConfigContainer.java 的Structure类里resources字段默认指向./resources/其中scripts字段默认值为resources:Scripts/。第三步启动服务端java -jar grasscutter.jar启动前务必确认 MongoDB 服务已经处于运行状态。服务端启动后会依次完成配置加载、语言包加载、数据库初始化、命令映射构建以及 HTTP/Game/Dispatch 服务器的创建对应 Grasscutter.java 的main方法主流程。升级旧版本时的特殊说明原文档特别强调如果你是从旧版本升级而来请先删除config.json让服务端重新生成配置文件。这一提醒在源码中有明确依据Grasscutter.java 中定义了配置文件路径./config.json而 ConfigContainer.java 实现了配置版本迁移机制当前版本为 13当检测到旧版本配置时会自动更新字段并重新保存。手动删除config.json可以确保获得一份与当前版本完全匹配的干净配置避免旧字段残留导致兼容性问题。连接客户端账号创建与流量重定向服务端启动后还需要完成两件事才能让游戏客户端连入在服务端创建账号以及将客户端流量重定向到本机服务端。创建账号服务端控制台命令在原文档中创建账号使用的是account create|delete username [UID]形式的控制台命令。结合仓库中的 AccountCommand.java该命令的实际用法与行为如下默认模式未开启EXPERIMENTAL_RealPassword时account create username [UID] account delete username执行account create后服务端会通过 DatabaseHelper.createAccountWithUid 创建账号并自动赋予*全部权限见源码第 87 行同时打印该账号保留的 UID。实验性密码模式在配置中启用ACCOUNT.EXPERIMENTAL_RealPassword后account create username password [UID] account resetpass username password密码会通过 BCrypt 算法cost 因子 12哈希后存储见 AccountCommand.java。resetpass在重置密码的同时会强制踢出该账号的在线会话。此外还有account list子命令用于列出当前数据库中全部账号及其 UID。该开关对应 ConfigContainer.java 中的Account.EXPERIMENTAL_RealPassword字段默认false。重定向流量三种方式任选其一原文档要求在以下三种流量重定向方案中只选择一种方案 Amitmdump推荐mitmdump -s proxy.py -k其中proxy.py即仓库 scripts/proxy.py 中的 mitmproxy 附加脚本-k表示不校验上游 TLS 证书。该脚本维护了一份游戏相关域名列表LIST_DOMAINS涵盖*.mihoyo.com、*.yuanshen.com、*.hoyoverse.com等见 proxy.py当检测到请求 host 命中列表时会将其重写指向本地服务端。重写目标由同目录的 scripts/proxy_config.py 控制USE_SSL True REMOTE_HOST localhost REMOTE_PORT 443这三个值还可通过环境变量MITM_REMOTE_HOST、MITM_REMOTE_PORT、MITM_USE_SSL动态覆盖见 proxy_config.py便于将远程服务端部署在其他主机时灵活调整。使用 mitmdump 方案还需要信任 mitmproxy 的 CA 证书图形化安装证书位于%USERPROFILE%\.mitmproxy目录下找到mitmproxy-ca-cert.cer文件双击安装即可命令行安装需要管理员权限certutil -addstore root %USERPROFILE%\.mitmproxy\mitmproxy-ca-cert.cer方案 BFiddler Classic启动 Fiddler Classic 后在Tools - Options - HTTPS中开启Decrypt https traffic解密 HTTPS 流量在Tools - Options - Connections中把默认端口改为除8888以外的任意端口这是因为游戏客户端对8888端口有特殊处理直接使用会导致连接失败将仓库 Wiki 提供的 Fiddler 脚本复制粘贴到FiddlerScript标签页点击Save Script保存。方案 CHosts 文件直接修改系统 hosts 文件将相关游戏域名解析到本机具体域名列表可参考 Wiki 资源页适用于希望绕开代理、直连本机服务端的场景。配置客户端代理完成上述任一方案后将系统/客户端的网络代理设置为127.0.0.1:8080或你自定义的代理端口。验证流量是否生效若使用 mitmproxy代理配置完成后访问http://mitm.it/如果页面显示 mitmproxy 的证书安装提示说明流量已正确经过代理。一键自动化start.cmd原文档还提到可以使用仓库根目录的start.cmd自动完成服务端与代理守护进程的启动前提是配置好JAVA_HOME环境变量按需修改start_config.cmd配置文件。从 start.cmd 与 start_config.cmd 的源码看这套自动化脚本会依次执行读取start_config.cmd中的路径配置JAVA_PATH、MITMDUMP_PATH、MONGODB_PATH、SERVER_JAR_NAMEgrasscutter.jar、PROXY_SCRIPT_NAMEproxy等见 start_config.cmd校验 Java、mitmdump、MongoDB 可执行文件是否存在缺失时自动降级为仅服务端模式以管理员权限启动 mitmdump参数为mitmdump.exe -s proxy.py -k --allow-hosts .*\.yuanshen\.com|.*\.mihoyo\.com|.*\.hoyoverse\.com见 start.cmd等待并自动将 mitmproxy CA 证书加入系统信任根同时设置系统代理为127.0.0.1:8080见 start.cmd启动mongod.exe数据目录为resources\Database最终执行java -jar grasscutter.jar启动服务端退出时自动还原代理设置、移除 CA 证书并关闭相关守护进程。从源码构建Windows 与 LinuxGrasscutter 使用Gradle管理依赖与构建流程构建配置见 build.gradle其中group为io.grasscutter并声明了 Java 17 源码/目标兼容性。构建前置依赖Java SE Development Kits17或更高注意构建必须用 JDKJRE 不够Git用于克隆仓库。Windows 构建git clone https://github.com/Grasscutters/Grasscutter.git cd Grasscutter .\gradlew.bat # 初始化构建环境 .\gradlew jar # 编译打包 jar首次执行gradlew.bat会完成 Gradle Wrapper 与依赖的初始化之后gradlew jar产出可执行 jar 包。Linux 构建git clone https://github.com/Grasscutters/Grasscutter.git cd Grasscutter chmod x gradlew ./gradlew jar # 编译打包 jarLinux 下首次执行前需要为gradlew脚本添加可执行权限即chmod x gradlew然后直接运行./gradlew jar即可。构建产物编译完成后检查项目目录即可找到生成的 jar 文件。若为开发版本通常命名为grasscutter-version-dev.jar版本号与仓库 build.gradle 中声明的版本一致将该 jar 按上文快速部署流程放置并运行即可。快速故障排查指南原文档最后给出了三条实战中最高频的排查经验编译失败请检查你的 JDK 安装是否完整 —— 需要 JDK 17且 JDK 的bin目录必须已配置到系统PATH环境变量中构建脚本依赖java/javac命令可用。连不上服务器 / 无法登录 / 报错 4206绝大多数情况下是代理设置不正确导致的。如果使用 Fiddler务必确认端口已修改为除8888之外的任意值同时确认 mitmproxy CA 证书已正确安装到系统受信任的根证书存储区。正确的启动顺序严格遵守以下顺序逐项启动缺一不可MongoDB Grasscutter 代理守护进程mitmdump / Fiddler 等 游戏客户端进阶理解配置文件的源码视角原文档虽未逐条列出config.json的全部字段但结合仓库 ConfigContainer.java 可以进一步理解几个与部署强相关的核心配置项便于按需定制配置区域关键字段默认值说明databaseserver.connectionUri/game.connectionUrimongodb://localhost:27017MongoDB 连接地址databaseserver.collection/game.collectiongrasscutter数据库集合名folderStructureresources./resources/资源目录位置对应上文 resources 文件夹server.httpbindPort/accessAddress443/127.0.0.1HTTPdispatch服务端口与对外地址server.gamebindPort/accessAddress22102/127.0.0.1游戏 KCP 服务端口与对外地址server.gameuseUniquePacketKeytrue是否为每个玩家生成独立的数据包加密密钥accountEXPERIMENTAL_RealPasswordfalse是否启用真实密码登录影响 account 命令用法accountautoCreatefalse是否允许客户端自动创建账号server.http.encryptionkeystore/keystorePassword./keystore.p12/123456HTTPS 加密密钥库仓库根目录自带 keystore.p12其中server.http的bindPort默认443与 proxy_config.py 中REMOTE_PORT 443遥相呼应代理脚本把游戏域名的请求重写到localhost:443正好落在 HTTP 服务监听的端口上从而完成流量闭环。总结围绕 docs/README_fil-PH.md 的部署主线本文完整覆盖了 Grasscutter 从环境准备、jar 获取、resources 目录搭建、服务端启动到客户端账号创建与三种流量重定向方案再到源码级构建与故障排查的全过程并用 Grasscutter.java、proxy.py、start.cmd、ConfigContainer.java 等仓库源码印证了每一步的底层实现。需要特别牢记的三点启动顺序必须是MongoDB → Grasscutter → 代理 → 游戏连接失败优先检查代理端口与 CA 证书升级版本时先删除config.json再启动。【免费下载链接】GrasscutterA server software reimplementation for a certain anime game.项目地址: https://gitcode.com/GitHub_Trending/gr/Grasscutter创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表