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" 一节）：

依赖	版本要求	用途
Java	Java SE 17 或更高	运行 Grasscutter 服务端
MongoDB	社区版，推荐 4.0+	服务端持久化存储（账号、角色、背包等数据）
代理守护进程	mitmproxy（mitmdump，推荐）或 Fiddler Classic 等	将游戏客户端的网络流量重定向到本机服务端

关于 Java 的注意事项

• 如果你仅运行服务端（不参与二次开发），安装JRE（Java 运行时环境）即可，不必安装完整 JDK；
• 若需要从源码编译Grasscutter，则必须安装JDK 17，并确保JDK/bin已加入系统PATH（见后文"快速故障排查"）。

MongoDB 的作用

MongoDB 是 Grasscutter 的默认数据存储。从 ConfigContainer.java 的源码可以看到，默认连接串为mongodb://localhost:27017，数据库集合名为grasscutter。也就是说，在未修改配置的前提下，MongoDB 必须监听本机默认端口27017，服务端启动时才能成功完成 DatabaseManager.initialize() 的初始化流程。

快速部署：三步启动服务端

原文档 "Running" 一节给出了标准的部署三步走，这里结合仓库源码做完整还原：

第一步：获取 grasscutter.jar

获取服务端可执行包有三种途径：

1. 从项目的 Releases 页面下载最新版本；
2. 从项目的 CI 构建产物（Actions 构建流水线）中下载；
3. 自行从源码编译，具体方法见下文"从源码构建"一节。

第二步：准备 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）。

重定向流量：三种方式任选其一

原文档要求在以下三种流量重定向方案中只选择一种：

方案 A：mitmdump（推荐）

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

方案 B：Fiddler Classic

启动 Fiddler Classic 后：

1. 在Tools -> Options -> HTTPS中开启Decrypt https traffic（解密 HTTPS 流量）；
2. 在Tools -> Options -> Connections中把默认端口改为除8888以外的任意端口（这是因为游戏客户端对8888端口有特殊处理，直接使用会导致连接失败）；
3. 将仓库 Wiki 提供的 Fiddler 脚本复制粘贴到FiddlerScript标签页，点击Save Script保存。

方案 C：Hosts 文件

直接修改系统 hosts 文件，将相关游戏域名解析到本机（具体域名列表可参考 Wiki 资源页），适用于希望绕开代理、直连本机服务端的场景。

配置客户端代理

完成上述任一方案后，将系统/客户端的网络代理设置为127.0.0.1:8080（或你自定义的代理端口）。

验证流量是否生效：若使用 mitmproxy，代理配置完成后访问http://mitm.it/，如果页面显示 mitmproxy 的证书安装提示，说明流量已正确经过代理。

一键自动化：start.cmd

原文档还提到，可以使用仓库根目录的start.cmd自动完成服务端与代理守护进程的启动，前提是：

1. 配置好JAVA_HOME环境变量；
2. 按需修改start_config.cmd配置文件。

从 start.cmd 与 start_config.cmd 的源码看，这套自动化脚本会依次执行：

• 读取start_config.cmd中的路径配置（JAVA_PATH、MITMDUMP_PATH、MONGODB_PATH、SERVER_JAR_NAME=grasscutter.jar、PROXY_SCRIPT_NAME=proxy等，见 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 与 Linux

Grasscutter 使用Gradle管理依赖与构建流程（构建配置见 build.gradle，其中group为io.grasscutter，并声明了 Java 17 源码/目标兼容性）。

构建前置依赖

• Java SE Development Kits17或更高（注意：构建必须用 JDK，JRE 不够）；
• 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 # 编译打包 jar

Linux 下首次执行前需要为gradlew脚本添加可执行权限（即chmod +x gradlew），然后直接运行./gradlew jar即可。

构建产物

编译完成后，检查项目目录即可找到生成的 jar 文件。若为开发版本，通常命名为grasscutter-<version>-dev.jar（版本号与仓库 build.gradle 中声明的版本一致），将该 jar 按上文"快速部署"流程放置并运行即可。

快速故障排查指南

原文档最后给出了三条实战中最高频的排查经验：

1. 编译失败：请检查你的 JDK 安装是否完整 —— 需要 JDK 17，且 JDK 的bin目录必须已配置到系统PATH环境变量中（构建脚本依赖java/javac命令可用）。

2. 连不上服务器 / 无法登录 / 报错 4206：绝大多数情况下是代理设置不正确导致的。如果使用 Fiddler，务必确认端口已修改为除8888之外的任意值；同时确认 mitmproxy CA 证书已正确安装到系统受信任的根证书存储区。

3. 正确的启动顺序：严格遵守以下顺序逐项启动，缺一不可：

   MongoDB > Grasscutter > 代理守护进程（mitmdump / Fiddler 等） > 游戏客户端

进阶理解：配置文件的源码视角

原文档虽未逐条列出config.json的全部字段，但结合仓库 ConfigContainer.java 可以进一步理解几个与部署强相关的核心配置项，便于按需定制：

配置区域	关键字段	默认值	说明
database	server.connectionUri/game.connectionUri	mongodb://localhost:27017	MongoDB 连接地址
database	server.collection/game.collection	grasscutter	数据库集合名
folderStructure	resources	./resources/	资源目录位置（对应上文 resources 文件夹）
server.http	bindPort/accessAddress	443/127.0.0.1	HTTP（dispatch）服务端口与对外地址
server.game	bindPort/accessAddress	22102/127.0.0.1	游戏 KCP 服务端口与对外地址
server.game	useUniquePacketKey	true	是否为每个玩家生成独立的数据包加密密钥
account	EXPERIMENTAL_RealPassword	false	是否启用真实密码登录（影响 account 命令用法）
account	autoCreate	false	是否允许客户端自动创建账号
server.http.encryption	keystore/keystorePassword	./keystore.p12/123456	HTTPS 加密密钥库（仓库根目录自带 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