创建第一个项目

上一页完成了首次设置，让我们继续配置吧！下面我们先走一遍 Web 配置模式——这是推荐的方式。终端版的网页管理界面和桌面版一模一样，用桌面版的朋友跟着这一部分走就行；网页也不方便用的朋友，可以直接跳到文末的交互式命令行版本。

Web 配置模式#

这是推荐的方式。按 Y 后管理端会自动启动 Web 管理界面。下面就是按 Y 后终端显示的内容：

Web 管理界面已启动，监听：127.0.0.1:18080

如果管理端运行在当前电脑：
  请直接在浏览器打开：http://127.0.0.1:18080/

如果管理端运行在远程服务器且保持安全的 127.0.0.1 监听：
  1. 在您自己的电脑上打开终端，运行以下 SSH 隧道命令：
     ssh -N -L 18080:127.0.0.1:18080 用户名@您的服务器地址
  2. 保持 SSH 窗口运行，再在自己电脑的浏览器打开：
     http://127.0.0.1:18080/
同机 Caddy/Nginx 可代理 127.0.0.1 到公网 443，这是推荐部署方式。

按 Ctrl+C 停止服务并返回主菜单。

网页默认打开的是新版界面，和桌面版一模一样。习惯原来左侧菜单布局的朋友，可以点右上角的“旧版界面”切回去，浏览器会记住你的选择。下面的教程都按新版界面来讲；两套界面读写的是同一份项目，用哪个都行。

打开浏览器后的第一步：创建管理员账户#

首次打开 Web 管理界面时，会先看到下面的页面（桌面版第一次进入工作区也是这一步）：

用户名 3–32 位，只能使用字母、数字、点、下划线或连字符；密码至少 10 位，建议用 14 位以上、而且不和其他网站重复的密码。

第 2 步 · 创建项目#

登录后，工作区里还是空的。点中间的“＋ 创建项目”（左上角“项目”旁边的 + 也行），让我们来创建第一个项目吧！弹出的表单里只有四项：项目名称、项目 ID、整合包目录和玩家更新地址，全部填好就能创建。

这里有三个容易出错的地方，先提醒你：

• 项目 ID：会写进更新地址和玩家端绑定里，创建后不要随意改。
• 整合包目录：这是你要管理的文件目录（也就是上一页说的 D:\被管理的文件），不要和管理端 data 混在一起。点旁边的文件夹按钮，可以直接浏览管理端所在电脑或服务器上的目录。
• 玩家更新地址：必须是玩家电脑能访问的公网地址（例如公网端口映射到内部 8080），不能填 127.0.0.1 或内网地址。

项目名称会显示在管理端里，也会先拿来当玩家端首页的大标题。玩家端的副标题、左上角品牌名、Minecraft 服务器地址、配色、公告这些个性化内容，创建时都不用管，之后在左边的“玩家端设计”里慢慢调就好——这些文字和配色保存以后，玩家下次启动就会自动拿到，不用重新发布整合包。

第 3 步 · 放入文件#

项目建好后，左边活动栏的第一个图标就是“文件”。你可以直接将想添加的模组放进服务器标准目录，再点工具栏右边的“…”→“刷新文件列表”；当然如果你是远程连接，或者想通过软件内直接上传，点右上角的“导入文件”，或者直接把文件拖进窗口。

这里看到的文件不会立刻影响玩家，只有检查并发布新版本后才会生效。

文件页的用法和资源管理器差不多：左边的项目栏是文件夹树，有待发布内容的文件夹后面会带一个小圆点；双击文件夹进去，工具栏左边的后退、前进和向上箭头可以来回跳，按 Backspace 也能返回上一级。窗口比较窄的时候，项目栏可以用命令栏最左边的按钮收起来。

导入清单：先检查，再确认#

通过软件导入的文件不会直接写进标准目录，而是先进导入清单。选好文件后，清单会列出每个文件准备保存到哪里、多大；点“上传并检查”，管理端会把文件先放进私有暂存区，识别模组 ID 和版本，再告诉你它和现有文件是什么关系——是新增，还是同一个模组的新版本。确认没问题，再点“确认导入”。

• 同一个模组换版本：比如把 dreamingfish-core-2.1.jar 换成 2.2，清单会认出旧文件，默认选“替换旧模组”。旧文件会被归档，原来设好的维护方式也会沿用。
• 导入整个文件夹：点“导入文件”旁边的小箭头，选“导入文件夹”。比如在 mods 里导入你电脑上的 mods 文件夹，通常要的是它里面的内容，别变成 mods/mods/；拿不准的时候，以清单里显示的保存路径为准。
• 文件在服务器上：小箭头里还有“从服务器导入”，可以浏览管理端所在服务器上的文件，同样先检查再导入。

某一项上传失败了可以单独重试，导入清单收起来也不影响后台继续处理。导完之后想反悔，打开“操作记录”撤销这次导入就行，后面「日常维护」里会讲。

三种维护方式#

文件放进来以后，默认都是普通同步。管理端一共有三种维护方式：

设置方法很简单：在文件列表里选中文件（按住 Ctrl 或 Shift 可以多选），底部会浮出一条操作栏，直接点“普通同步”“强制同步”或“首次提供”就行。选中的是文件夹时，管理端会先告诉你这次会影响多少文件，再让你确认。

强制同步分为强制整个文件夹和强制单个文件两种：前者比如把 mods 文件夹设为强制同步，文件夹里的所有文件都要和服务器一致，玩家自己放进去的模组会被移进备份，以后新加进这个文件夹的文件也自动跟着这个规则；后者只锁定一个文件，比如 config/server-required.toml，不会清理同目录的其他文件。

不过，大部分情况下其实都不需要设置强制同步：普通同步已经适合绝大多数整合包项目，等真正遇到需要锁定的内容（比如核心模组、反作弊）时，再按需开启也不迟。光影、小地图这类“有的玩家电脑带不动”的内容，还可以在项目栏的“可选内容”里分成一组，让玩家自己决定装不装，这个放到「日常维护」里讲。

第 4 步 · 检查并发布#

文件和维护方式都设好之后，点左边活动栏的第二个图标“改动与版本”。进来时管理端会自动检查一遍，左边列出这次的新增、更新、移除和维护设置的变化，以及新增和更新文件一共多大；右边的“准备新版本”卡片用来填写版本号和更新说明。

重点检查移除的文件：每个被移除的文件后面都有一个下拉框，可以选“移除玩家副本”或者“留给玩家”。不过，第一次发布应该都是「新增」，基本不会遇到移除；以后删文件时，这一步就很重要了。

确认无误后填写本次显示版本（如 1.0.0，以后会按上一个版本自动建议下一个）和更新记录，点击“发布 1.0.0”。最低玩家端版本会根据这次用到的功能自动算好，就写在按钮下面。发布是不可变的：内容有误就修正文件再发新版本，不要修改旧版本。

第 5 步 · 制作玩家端（发布玩家端程序）#

刚刚我们已经发布了整合包文件。接下来，你需要第一次发布玩家端程序，再生成部署包：部署包会把玩家端程序、项目绑定、公网地址，以及最重要的网络传输公钥一起带给玩家（私钥会留在管理端，由服主自己保管）。

玩家端程序和整合包版本是两条独立的发布线：以后只更新模组或配置时，重新发布整合包就好，不用再动玩家端程序；反过来，要发布玩家端程序时，也不用动整合包。

点左边活动栏的“发放”，再点项目栏里的“玩家端程序”，跟着这几步走就行：

1. 点“选择 ZIP”，选中从 GitHub Releases 下载的玩家端发行包，比如 dreamingfish-player-windows-x64-0.2.1.zip，不用解压。
2. 点“检查发行包”，管理端会自己读出程序版本和平台，显示“已识别 0.2.1 · windows-x64”。平台要和玩家实际用的一致，Windows 玩家就是 windows-x64。
3. 核对没问题，点“确认发布”，剩下的交给管理端：自动定位程序目录、生成清单并签名。

如果发行包已经解压在服务器上了，可以展开下方的“从已有程序目录发布”，选发行包解压后的根目录（别选 app、runtime 这些子目录）。这里还能填最低 Bootstrap Agent 版本，目前是 0.1.2——Agent 一般不会更新，只有重新发了更高版本时才需要提高。

发布完玩家端程序，就可以生成部署包了。点项目栏里的“发放整合包”，选好整合包版本和玩家平台，点“生成并下载部署 ZIP”，部署包就下载到你自己的电脑上了，远程管理服务器也一样。玩家第一次启动时会先验证签名基线，然后从你的公网地址拉取清单和整合包文件。

整合包版本怎么选？手上已经有一份完整整合包的，选它实际包含的那个历史版本；只有一份全新的基础 Forge 实例，就选当前最新发布。

部署包是轻量接入模板，不包含 Minecraft、Forge、mods 或 config。也就是说，你需要把部署包放进最后要发给玩家的游戏目录中。玩家首次在线启动时会根据已发布清单补齐缺失的托管文件；服主只需维护一份可正常启动的基础 Forge 实例。

如果你能直接访问玩家实例（就是minecraft的整个版本文件夹）所在的目录（比如管理端和游戏实例在同一台电脑），展开下方的“写入管理端目录 / 准备现有实例”，还有两种高级方式：把部署包写到管理端所在电脑的某个目录里，或者直接选中现有的 Minecraft 实例目录，把更新器、Bootstrap Agent、项目绑定和签名基线直接写进去，不用再合并部署包；远程管理端做 Windows 整合包时，还是推荐用上面的下载 ZIP。

部署包解压出来，应该是这样的：

接下来，把解压出来的所有内容拖进你的 Minecraft 版本目录就行——以这个目录举例:.minecraft\versions\Dreamingfish-Building。注意拖的是里面的内容，不是外面那一层目录本身；.dreamingfish-bootstrap 是隐藏文件夹，别漏掉。

拖完之后，你的版本目录应该是这样的——红色的都是部署包带来的文件，必须完整出现在玩家端里：

红色部分是部署包带来的，一个都不能少；mods、config 等托管内容会在玩家首次在线启动时被检查并补齐——已经配置好的内容不会被重复安装。

让启动器加载 Bootstrap Agent#

推荐把参数随整合包一起分发。把 Agent 参数写进实例的版本 JSON，玩家换启动器时不必再逐个填写这条参数。服主先完成下面的配置和启动测试，再把整合包交给玩家。

打开该版本 JSON，在已有的 arguments.jvm 数组中新增下面这一项：

"-javaagent:.dreamingfish-bootstrap/bootstrap-agent.jar"

例如，原来的数组是：

"arguments": {
  "jvm": [
    "-Djava.library.path=${natives_directory}"
  ]
}

新增后变成：

"arguments": {
  "jvm": [
    "-javaagent:.dreamingfish-bootstrap/bootstrap-agent.jar",
    "-Djava.library.path=${natives_directory}"
  ]
}

上面只演示插入位置，不要用示例覆盖整个版本 JSON。你自己的原有参数和其他字段必须全部保留，只新增一项并注意英文逗号；如果已经有旧的 DreamingFish Agent 参数，替换旧项，保持只有一份。保存后完全退出并重新打开启动器。

三款启动器已实测。2026-10-26，在 Windows、Minecraft 1.21.1 / NeoForge 21.1.248 的同一实例中，美西螈 1.10.1、PCL 2.13.1.1、HMCL 3.15.2 均用这条版本 JSON 参数调用了玩家端 0.3.2，连接远程管理服务并取得启动许可；HMCL 还验证到了整合包主菜单。测试时没有另外添加启动器专用 Agent 参数。其他启动器、目录布局及导出格式仍须分别测试。

不要再把 -javaagent:${game_directory}/... 当作跨启动器的通用写法：本次美西螈会把这个变量原样传给 Java，导致找不到 Agent。也不要把服主电脑的绝对路径发给玩家，或设置 Windows 全局 JAVA_TOOL_OPTIONS。

只使用 PCL 时的备选方式：如果不修改版本 JSON，可以在 PCL 的这个版本的 JVM 参数框中填写：

-javaagent:"{verpath}.dreamingfish-bootstrap/bootstrap-agent.jar"

{verpath} 是 PCL 的占位符。这种方式与前面的版本 JSON 方式二选一，同一个实例不要重复加载 Agent；首次部署包里的 minecraft-jvm-argument.txt 目前也是这条 PCL 专用写法。

分发时，你可以直接把整个版本目录发给玩家，也可以用启动器导出整合包再分享。导出整合包时要注意：整合包文件夹里要包含玩家端文件——就是刚拖进去的 .dreamingfish-bootstrap（隐藏文件夹，别漏）和 DreamingFishUpdater，缺了它们，玩家拿到手也不会有更新器。

第 6 步 · 启动下载服务#

最后，点左下角那个服务器图标（底部状态栏右边的“下载服务已停止”也能点），在弹窗里点“▶ 启动下载服务”，状态变成运行中就好了。玩家更新器就是从这个服务下载清单和文件。

验证方式：先在管理服务器上访问 http://127.0.0.1:8080/healthz，应返回 {"status":"ok"}；再从另一台电脑访问项目的公网地址，确认端口映射正确。服务运行期间管理端进程要保持运行（Linux 用 tmux 挂起的话，断开 SSH 也不会停；桌面版关掉窗口会收进系统托盘，下载服务继续跑）。想在服务器上先确认一下更新地址通不通，也可以去“设置”→“项目设置”，点玩家更新地址旁边的“检测”。

到这里，整个流程就走完了——恭喜你！你的第一个整合包项目已经可以正式发布：玩家拿到客户端后，更新器会自己检查版本、补齐文件、验证签名，然后正常启动游戏。把客户端发给玩家，等着大家上线吧！

日常的更新维护可以看「日常维护」；想在自己的 Windows 电脑上用桌面版管理服务器，可以看「远程管理与 AI agent」；网页也不方便用的话，下面就是交互式命令行的菜单入口。

命令行配置模式#

对于不方便使用 Web 界面的服主，我们还提供了便捷的终端配置：终端与 Web 使用同一套数据，项目、签名和发布都是同一套服务，输入菜单编号即可操作，按 0 退出。网页上的导入清单、实时预览这些可视化操作，终端里换成了直接整理服务器上的文件；维护方式等高级设置则用参数式命令完成，下面会讲到。

第 1 步 · 进入命令行模式#

首次启动时，管理端会询问是否进入 Web 管理界面。输入 N 就会留在终端并进入主菜单。命令行模式不需要创建 Web 管理账户；它直接在管理服务器本机操作，但项目数据、签名密钥和发布结果与 Web 模式完全相同。

在管理端目录运行 dfs-admin，看到欢迎横幅和主菜单：

DreamingFish 整合包更新管理端
================================

主菜单
[1] 查看项目状态
[2] 创建项目
[3] 修改项目设置
[4] 扫描并发布整合包
[5] 查看发布历史
[6] 发布玩家端程序
[7] 制作玩家实例
[8] 修改服务设置
[9] 启动 HTTP 文件服务
[10] 启动 Web 管理界面
[11] 生成玩家端首次部署包
[12] 修改玩家端个性化设置
[13] 导出外部托管目录（HTTP / OSS / CDN）
[0] 退出
请选择：

第 2 步 · 创建项目#

在主菜单选择 [2] 创建项目。和 Web 表单一样，真正必填的是四项：项目 ID、项目显示名称、要管理的文件目录和玩家端更新器访问地址；后面的玩家端个性化内容都可以直接按回车使用默认值，以后从主菜单 [12] 或网页的“玩家端设计”再调整。

这里有三个容易出错的地方，和 Web 模式完全相同：

• 项目 ID：用于目录、接口和玩家端绑定，创建后不要随意更改。
• 要管理的文件目录：只放希望交给更新器管理的内容，例如 mods、config；不要复制完整 .minecraft，也不要与管理端 data 混在一起。
• 玩家端更新器访问地址：必须是玩家电脑真正能访问的公网地址，公网端口需要已经映射或转发到管理端下载服务；不能填写 0.0.0.0、127.0.0.1、localhost 或内网地址。

如果还没有项目，首次引导也会询问是否用 Web 创建；输入 N 后会直接进入同一个命令行创建流程：

还没有整合包项目。推荐在 Web 管理界面中完成首次创建，每个必填项都带有用途和示例。
  按 Y 进入 Web 管理界面创建，按 N 使用命令行创建。
是否现在启动 Web 管理界面并创建第一个项目？ [Y/n]：n

创建整合包项目
================================
[1/3] 创建必备设置
以下四项用于创建项目、定位管理目录并让玩家端连接更新服务。

【必填】项目 ID：用于目录、接口和玩家端绑定；创建后不应随意更改。
  格式：小写字母或数字开头，可包含点、下划线和连字符，例如 build-server。
项目 ID（必填）：dreamhaven
【必填】项目显示名称：显示在管理端项目列表中，例如服务器名称或整合包名称。
  创建时也会作为玩家端主标题的默认值。
项目显示名称（必填）：梦屿 · 生存整合包
【必填】要管理的文件目录：只放准备交给更新器管理的内容，例如 mods、config。
  不需要复制完整 .minecraft；该目录必须与管理端 data 目录分开。
要管理的文件目录（必填）：D:\被管理的文件
【必填】玩家端更新器访问地址：写入玩家部署包，必须能从玩家电脑访问。
  示例：http://example.com:39988；不要填写 0.0.0.0、127.0.0.1 或 localhost。
  请确认公网端口已经映射或转发到管理端下载服务端口。
玩家端更新器访问地址（必填）：http://您的公网IP:39988

[2/3] 文件维护方式
所有文件默认“普通同步”：跟随发布更新，玩家可以停用模组或自行管理文件。
需要强制同步、首次提供、可选包或问题处理时，
创建后在 Web 管理界面的“管理内容”页面，或用 project policy 命令设置。

[3/3] 玩家端个性化
以下内容只影响玩家端显示，直接按回车可使用默认值。
创建后修改标题、配色、公告和页面，不用重新发布整合包，玩家下次启动会自动获取。
创建后可从主菜单 [12]“修改玩家端个性化设置”继续调整，Web 页面还提供实时预览。
首页欢迎文字（显示在大标题上方） [欢迎回家]：
玩家端主标题（显示在首页左侧的大号标题区域） [梦屿 · 生存整合包]：
玩家端副标题（显示在主标题下方） [Minecraft 整合包更新]：
左上角中文品牌名（显示在玩家端窗口左上角） [梦鱼更新器]：
左上角英文品牌名（紧跟在中文品牌名右侧） [DreamingFish]：
Minecraft 服务器地址（显示在服务器信息区域，可留空）：play.example.com:25565
项目已创建：梦屿 · 生存整合包 (dreamhaven)
项目签名私钥已保存在管理数据目录，请通过加密备份保护它。
建议下一步在 Web 管理界面添加整合包文件、扫描差异并创建首次发布。
是否现在启动 Web 管理界面继续配置？ [Y/n]：n

第 3 步 · 放入要管理的文件#

终端没有浏览器上传按钮，因此请直接把 mods、config 等内容放进刚才填写的“要管理的文件目录”。这个目录就是 Web 页面里看到的那份文件，两种模式读取的是同一批真实文件。

把文件放进去不会立刻影响玩家。只有完成下一步扫描并发布新版本后，玩家端才会收到变化。

项目名称、文件目录和更新地址在主菜单 [3] 修改项目设置 里改，直接按回车会保留当前值：

直接按回车保留当前值。
玩家访问公共 HTTP 地址必须是玩家电脑可访问的公网域名或 IP，不是服务器监听地址。
三种维护方式、可选包和问题处理请在 Web“管理内容”页面或用 project policy 命令设置。
项目显示名称（必填） [梦屿 · 生存整合包]：
整合包文件目录（必填） [D:\被管理的文件]：
玩家访问公共 HTTP 地址（必填） [http://您的公网IP:39988]：
项目设置已更新：dreamhaven

三种维护方式#

终端和 Web 使用完全相同的维护规则（三种方式的区别见上面网页部分）。所有文件默认都是普通同步；需要单独设置的时候，用 project policy preset 命令，最后一个参数写维护方式：SYNC 是普通同步，REQUIRED 是强制同步，INITIAL 是首次提供，DEFAULT 表示取消单独设置、跟随上级文件夹。比如锁定一个核心模组、让 options.txt 只首次提供：

dfs-admin project policy preset dreamhaven mods/dreamingfish-core-2.1.jar REQUIRED
dfs-admin project policy preset dreamhaven options.txt INITIAL
dfs-admin project policy show dreamhaven

维护方式（未列出的文件为普通同步）：
  强制同步     mods/dreamingfish-core-2.1.jar
  首次提供     options.txt
完整强制同步的目录：（未开启）
可选内容：（无）
撤回问题版本：（无）
修正玩家文件：（无）
修改会在下一次确认发布后对玩家生效。

想强制整个文件夹，就在后面加 --directory，比如 dfs-admin project policy preset dreamhaven mods REQUIRED --directory。这样 mods 就会出现在“完整强制同步的目录”里：文件夹里的文件都要和服务器一致，玩家额外放进去的文件会被移进备份，以后新增到这个文件夹的文件也自动属于这个规则。强制单个文件只锁定指定文件，不会清理同目录的其他文件。（Windows 把 dfs-admin 换成 DreamingFishAdmin.exe，下同。）

第 4 步 · 扫描并发布#

文件准备好后，在主菜单选择 [4] 扫描并发布整合包。终端会显示与 Web 相同的变更预览：托管文件数、总大小、变更数量、预计下载量、同步范围以及每个新增、修改或删除的文件。

重点检查移除后的处理。普通文件被移除时，终端会逐个问你：[1] 移除玩家副本，还是 [2] 停止维护，留给玩家；强制同步文件夹里的文件只能随发布从玩家端移除。第一次发布通常全部是“新增”，基本不会出现这一步。

预览确认无误后，填写本次显示版本（例如 1.0.0）、最低玩家端程序版本和更新记录。发布内容是不可变的：如果发现错误，请修正整合包文件目录后再发布一个新版本，不要修改旧版本。

发布预览 9f2c1a3e-b4d2-4e7a-8c1f-1a2b3c4d5e6f
托管文件：31，总大小：18.4 MiB
变更数量：31，预计下载：18.4 MiB
本次内容范围：config、kubejs、mods、options.txt、resourcepacks、servers.dat、shaderpacks
完整强制同步的目录：未开启
强制同步的文件：mods/dreamingfish-core-2.1.jar
变更明细：
  新增     config/continuity.json  (34 B)
  新增     mods/dreamingfish-core-2.1.jar  (1.18 MiB)
  新增     mods/sodium-fabric-0.5.11+mc1.20.1.jar  (960.3 KiB)
  ……
本次显示版本（例如 1.0.1）：1.0.0
最低玩家端程序版本 [0.2.0]：
更新记录（可留空；输入 @文件路径读取 UTF-8 文本）：首次发布：接入模组与基础配置。

实际将保存的更新记录：
首次发布：接入模组与基础配置。

项目还没有发布 0.2.0 或更新版本的玩家端，旧玩家端会拒绝这个版本。仍然继续？ [y/N]：y
确认以上版本和更新记录无误并发布？ [y/N]：y
发布完成：1.0.0 / r000001-20261014-161030-ab12cd34

中间那句“项目还没有发布 0.2.0 或更新版本的玩家端”只在第一次发布时出现，下一步就会发布 0.2.1 玩家端，输入 y 继续就好。

第 5 步 · 制作玩家端（发布玩家端程序）#

整合包文件发布完成后，第一次还需要发布玩家端程序。这个过程会把玩家端程序签好名，之后再和项目绑定、公网地址和网络传输公钥一起打进部署包；签名私钥始终留在管理端数据目录，不会进入玩家部署包。

玩家端程序和整合包版本是两条独立的发布线：以后只更新模组或配置时，重新发布整合包即可，不需要再次发布玩家端程序；只有更新器程序本身升级时，才需要重新执行 [6]。

在主菜单选择 [6] 发布玩家端程序，依次完成下面四项：

1. 选择和玩家电脑一致的平台，Windows 通常保持 windows-x64。
2. 填写玩家端发行包解压后的根目录。管理端会自动定位版本目录和 DreamingFishUpdater.exe，不要填写 ZIP 文件、app、runtime 或具体版本子目录。
3. 填写最低启动引导器版本，当前通常保持 0.1.2；只有重新分发了更高版本 Bootstrap Agent 时才提高。
4. 核对后输入 Y，管理端会自动读取程序版本、定位 app-image、生成清单并签名。

玩家端程序发布成功后，再选择 [11] 生成玩家端首次部署包。首次部署包不包含 Minecraft、Forge、mods 或 config，它是需要合并进版本隔离实例的轻量接入文件：

[6] 发布玩家端程序
此处发布的是玩家端更新器程序，不是 mods/config 整合包内容。
平台 [windows-x64]：
玩家端发行包解压根目录：D:\待发布的完整游戏版本\dreamingfish-player-windows-x64
最低启动引导器版本 [0.1.2]：
自动读取版本并发布这个玩家端程序？ [y/N]：y
玩家端程序已发布：0.2.1 / windows-x64

[11] 生成玩家端首次部署包
此功能不需要完整 Minecraft 实例，输出内容用于合并到本地实例根目录。
首次部署包输出父目录：D:\管理端\deploy
平台 [windows-x64]：
请选择这个下载包所对应的不可变发布版本（新版本在前）：
  [1] 1.0.0 r000001-20261014-161030-ab12cd34 *
输入编号或发布 ID，回车使用 * 版本：
按整合包基线 1.0.0 生成首次部署包？ [y/N]：y
首次部署包已生成：D:\管理端\deploy\dreamhaven-player-deployment-1.0.0-0.2.1

部署包会包含更新器程序、Bootstrap Agent、项目绑定和所选整合包发布的签名基线。玩家第一次在线启动时，会先验证基线，再从项目公网地址拉取最新清单并补齐缺失的托管文件。

高级方式 · 直接制作玩家实例#

如果你能直接访问玩家实例所在的目录（比如管理端和游戏实例在同一台电脑），也可以选 [7] 制作玩家实例，直接把更新器、Bootstrap Agent、项目绑定和签名基线写进 Minecraft 实例目录，不用再合并部署包；远程管理端做 Windows 整合包时，还是推荐用上面的部署包：

[7] 制作玩家实例
实例中必须已经解压玩家端发行包，并包含 .dreamingfish-bootstrap/bootstrap-agent.jar。
Minecraft 版本隔离实例目录：D:\mc\.minecraft\versions\Dreamingfish-Building
平台 [windows-x64]：
实例内玩家端目录 [DreamingFishUpdater]：
请选择这个下载包所对应的不可变发布版本（新版本在前）：
  [1] 1.0.0 r000001-20261014-161030-ab12cd34 *
输入编号或发布 ID，回车使用 * 版本：
确认写入项目绑定并核对首个玩家端程序？ [y/N]：y
Prepared signed player program 0.2.1, bundled release 1.0.0 (r000001-20261014-161030-ab12cd34), and wrote project binding to D:\mc\.minecraft\versions\Dreamingfish-Building\.dreamingfish-bootstrap\project-binding.json

部署包导出来，应该是这样的：

接下来，把输出目录里的所有内容拖进你的 Minecraft 版本目录就行——以这个目录举例：D:\Desktop\mc\.minecraft\versions\Dreamingfish-Building。注意拖的是里面的内容，不是输出目录本身；.dreamingfish-bootstrap 是隐藏文件夹，别漏掉。

拖完之后，你的版本目录应该是这样的——红色的都是部署包带来的文件，必须完整出现在玩家端里：

红色部分是部署包带来的，一个都不能少；mods、config 等托管内容会在玩家首次在线启动时被检查并补齐——已经配置好的内容不会被重复安装。

让启动器加载 Bootstrap Agent。接下来使用与 Web 配置模式相同的实例 JSON 接入方式。

推荐把参数随整合包一起分发。把 Agent 参数写进实例的版本 JSON，玩家换启动器时不必再逐个填写这条参数。服主先完成下面的配置和启动测试，再把整合包交给玩家。

打开该版本 JSON，在已有的 arguments.jvm 数组中新增下面这一项：

"-javaagent:.dreamingfish-bootstrap/bootstrap-agent.jar"

例如，原来的数组是：

"arguments": {
  "jvm": [
    "-Djava.library.path=${natives_directory}"
  ]
}

新增后变成：

"arguments": {
  "jvm": [
    "-javaagent:.dreamingfish-bootstrap/bootstrap-agent.jar",
    "-Djava.library.path=${natives_directory}"
  ]
}

上面只演示插入位置，不要用示例覆盖整个版本 JSON。你自己的原有参数和其他字段必须全部保留，只新增一项并注意英文逗号；如果已经有旧的 DreamingFish Agent 参数，替换旧项，保持只有一份。保存后完全退出并重新打开启动器。

三款启动器已实测。2026-10-26，在 Windows、Minecraft 1.21.1 / NeoForge 21.1.248 的同一实例中，美西螈 1.10.1、PCL 2.13.1.1、HMCL 3.15.2 均用这条版本 JSON 参数调用了玩家端 0.3.2，连接远程管理服务并取得启动许可；HMCL 还验证到了整合包主菜单。测试时没有另外添加启动器专用 Agent 参数。其他启动器、目录布局及导出格式仍须分别测试。

不要再把 -javaagent:${game_directory}/... 当作跨启动器的通用写法：本次美西螈会把这个变量原样传给 Java，导致找不到 Agent。也不要把服主电脑的绝对路径发给玩家，或设置 Windows 全局 JAVA_TOOL_OPTIONS。

只使用 PCL 时的备选方式：如果不修改版本 JSON，可以在 PCL 的这个版本的 JVM 参数框中填写：

-javaagent:"{verpath}.dreamingfish-bootstrap/bootstrap-agent.jar"

{verpath} 是 PCL 的占位符。这种方式与前面的版本 JSON 方式二选一，同一个实例不要重复加载 Agent；首次部署包里的 minecraft-jvm-argument.txt 目前也是这条 PCL 专用写法。

分发时，你可以直接把整个版本目录发给玩家，也可以用启动器导出整合包再分享。导出整合包时要注意：整合包文件夹里要包含玩家端文件——就是刚拖进去的 .dreamingfish-bootstrap（隐藏文件夹，别漏）和 DreamingFishUpdater，缺了它们，玩家拿到手也不会有更新器。

第 6 步 · 启动下载服务#

最后在主菜单选择 [9] 启动 HTTP 文件服务。这与网页里的“启动下载服务”是同一项服务：玩家更新器会通过项目的公网地址从这里下载清单和文件。服务运行期间按 Ctrl+C 停止并返回主菜单：

启动只读 HTTP 文件服务 http://0.0.0.0:8080/？ [Y/n]：y
HTTP 文件服务已启动：http://0.0.0.0:8080/
健康检查：http://0.0.0.0:8080/healthz
按 Ctrl+C 停止服务并返回主菜单。

验证方式也和 Web 模式相同：先在管理服务器上访问 http://127.0.0.1:8080/healthz，应返回 {"status":"ok"}；再从另一台电脑访问项目中填写的公网地址，确认公网端口已经正确映射到下载服务端口。服务运行期间管理端进程必须保持运行，Linux 可以放在 tmux 会话中，断开 SSH 后服务仍会继续。

如果管理了多个项目，操作前会先列出项目让你选择，直接回车使用带 * 的默认项目：

请选择项目：
  [1] 梦屿 · 生存整合包 (dreamhaven) *
  [2] 建筑服 (build-server)
输入编号或项目 ID，回车使用 * 项目：

到这里，命令行模式已经完成了与 Web 模式相同的六个步骤：创建项目、准备文件、设置维护方式、扫描发布、制作玩家端和启动下载服务。两种操作方式共用同一套项目与发布数据，可以随时切换。日常维护——修改项目设置 [3]、查看发布历史 [5]、发布玩家端程序 [6]、制作玩家实例 [7]、修改服务设置 [8]、修改玩家端个性化 [12]、导出外部托管目录 [13]——都在主菜单里；备份与恢复等终端专属功能，见「日常维护」；不进菜单、直接用命令操作（也方便交给脚本或 AI agent），见「远程管理与 AI agent」。