下载与首次配置

接下来让我们一起配置吧：首先下载管理端。管理端有两个版本——桌面版解压后直接运行就行；终端版第一次运行时，会有一个首次引导。

一、先认识两个组成部分#

开始部署之前，先记住整个系统由两个部分构成：管理端和玩家端。管理端可以运行在运行 Minecraft 的服务器上，也可以运行在其他服务器或者你自己的电脑上；玩家端运行在玩家电脑上，由玩家端本体和 Agent（启动引导器）组成。让我们先认识这两个部分。

服主使用

管理端

负责管理内容、发布版本、制作玩家实例，并启动玩家下载服务。管理端有桌面版和终端版两个版本：终端版启动后可以打开网页管理界面，和桌面版的界面一模一样，也可以直接用交互式命令行。不管用哪种，读写的都是同一份数据，后面会一一介绍。

玩家使用

玩家端

随整合包发给玩家的桌面程序，由玩家端本体和 Agent（启动引导器）组成。本体负责在游戏启动前检查和更新文件；Agent 挂在启动器里，负责拉起玩家端、等待启动许可，并参与玩家端自更新与失败回退。

一次启动的协作过程：

服主发布在管理端维护标准目录、检查改动并发布新版本。

服主完成启动器接入按 PCL 或 HMCL 的实际规则配置 Agent，并确认版本隔离生效。

玩家启动游戏启动器加载 Agent，Agent 再拉起玩家端。

返回启动许可玩家端完成检查后放行，Minecraft 正常加载。

管理端的不同版本#

管理端分为两个版本，按管理端放在什么系统上来选：

版本	放在哪	怎么管理
桌面版	Windows 电脑或 Windows Server（推荐）；也可以装在自己的 Windows 电脑上，远程管理服务器上的终端版	免安装，解压后双击 `DreamingFishAdminDesktop.exe`（也有安装版），打开就是管理界面
终端版	Linux 服务器或 VPS；Windows 上想省点资源、不想开桌面程序，也可以用它	平时用网页管理界面：在终端里启动它，再用浏览器打开 `http://127.0.0.1:18080/`（远程服务器先建 SSH 隧道），界面和桌面版一模一样。网页也不方便用的时候，运行 `dfs-admin` 进入交互式命令行，按中文菜单操作

Windows 上推荐直接用桌面版；Linux 上用终端版，终端版也提供了网页操作界面；网页也不方便的话，我们也提供了交互式命令行操作。

二、准备发行包与三个位置#

管理端和玩家端发行包都自带运行环境，不需要额外安装 Java。建议先准备以下三个固定位置：

Windows 目录示例

D:\管理端       管理端程序与自动生成的数据
D:\被管理的文件      服主希望更新器管理的内容
D:\待发布的完整游戏版本      准备发给玩家的完整 Minecraft 实例

D:\管理端 应长期保留，升级管理端时继续使用其中的 data 和设置文件。用桌面版的话，管理数据默认放在当前用户的应用数据目录里（%LOCALAPPDATA%\cn.dreamingfish.admin.desktop\management），想放到 D:\管理端 这种好找的地方，在连接页改一下“管理数据目录”就行。
D:\被管理的文件 不要求是完整游戏目录。只管理模组时可以只有 mods；只管理配置时也可以只有需要的 config。
D:\待发布的完整游戏版本 是最终交给玩家的完整实例，它由启动器、游戏文件和 DreamingFish 组件共同组成。

三、下载并运行管理端#

到 GitHub Releases 下载管理端。两个版本选一个就行：

版本	能装在哪	第一次运行
桌面版 `dfs-admin-desktop-windows-x64`	Windows 电脑、Windows Server（推荐）	直接运行，在窗口里选连接，没有终端引导
终端版 `dfs-admin-linux-x64` / `dfs-admin-windows-x64`	Linux 服务器或 VPS；Windows 也能用	终端先走一遍首次引导，之后用网页管理界面或交互式命令行管理

方式一：桌面版，直接运行#

桌面版免安装：下载便携版 dfs-admin-desktop-windows-x64-0.2.1.zip，解压到一个固定的目录（比如 D:\梦鱼管理端桌面版），双击里面的 DreamingFishAdminDesktop.exe 就能用。它自带 Java 和管理核心，不需要另外装任何东西，也不需要先在终端里跑首次引导。习惯装软件的，也可以下载安装版 dfs-admin-desktop-windows-x64-0.2.1-setup.exe，装好后从开始菜单打开，用起来完全一样。

选“本机管理”

打开后先看到连接页。选上方的“本机管理”，填个好认的连接名称。

确认管理数据目录

第一次用可以保留默认目录；以前用过终端版，就点旁边的文件夹按钮，选中原来放 management-settings.json 的那个目录，项目和发布记录都会接着用。

打开工作区

点“打开工作区”，第一次进入要先创建管理账户。接下来直接看下一页「创建第一个项目」就行。

梦鱼更新管理0.2.1

工作区编辑连接

DREAMINGFISH WORKSPACE

本机管理

修改连接信息，或打开这个工作区。

本机管理管理地址SSH 连接

在这台电脑上整理整合包、检查改动和发布版本。

连接名称本机管理管理数据目录D:\梦鱼管理端已有管理端目录中的项目和发布记录可以继续使用。打开工作区

桌面版连接页：选“本机管理”，点“打开工作区”

玩家下载服务的端口

桌面版的玩家下载服务默认监听 0.0.0.0:8080，和终端版首次引导里的默认值一样。要换端口，进工作区后到“设置”→“服务设置”里改。管理端放在 Windows Server 上的话，记得在系统防火墙和云服务商的安全组里放行这个端口，玩家才连得上。

在 Windows Server 上用桌面版

桌面版要用系统的 WebView2。Windows Server 上不一定装了它：用便携版之前先确认装了 Microsoft Edge WebView2 Runtime，或者直接用安装版，缺的话安装程序会自动联网安装。
桌面版关掉窗口会收进系统托盘，下载服务继续运行；远程桌面点“断开连接”没关系，程序会继续跑，但“注销”会把它一起关掉。
没有桌面的 Windows Server Core 用不了桌面版，请用下面的终端版。

方式二：终端版与首次引导#

管理端放在 Linux 服务器或 VPS 上的，下载 dfs-admin-linux-x64；Windows 上想用终端版的，下载 dfs-admin-windows-x64：

解压到固定目录

Windows 将管理端压缩包解压到 D:\管理端；Linux 将管理端压缩包解压到长期使用的目录，例如 /opt/dfs-admin。两边都一样：不要每次升级都新建一套空目录。

运行管理端

Windows 双击 DreamingFishAdmin.exe 或从 PowerShell 启动；Linux 解压后在发行包根目录运行 ./dfs-admin，建议用 tmux 挂起（如 tmux new -s dfs ./dfs-admin），断开 SSH 后管理端仍会继续运行。

第一次运行时，终端会先带你走一遍首次引导，继续往下看第四节。

四、第一次运行：跟着终端引导走#

这一节只针对方式二的终端版；用桌面版的朋友不会看到这个引导，可以直接翻到下一页「创建第一个项目」。

第一次启动终端版会进入“首次使用引导”。默认值已经适合大多数情况，不确定就直接按回车。下面就是你第一次运行时会看到的终端界面（Linux 路径以 /opt/dfs-admin 为例，Windows 对应 D:\管理端）：

下面会对三步进行讲解。

第 1 步 · 数据保存位置

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

首次使用引导
================
欢迎使用 DreamingFish Updater！
请跟随引导完成设置。如果不确定怎么填，直接按回车使用默认值即可。

[1/3] 管理端数据保存位置
管理端会把项目设置、发布记录和签名密钥自动保存在下面这个文件夹：
  /opt/dfs-admin/data
这个 data 文件夹位于管理端根目录中，非常重要，请勿删除！

升级管理端的方法：
  1. 把旧管理端根目录中的 data 文件夹、management-settings.json
     和 management-web-auth.json（如果已经注册 Web 账户）
     移动或复制到新版管理端根目录。
  2. 启动新版管理端，程序会自动读取原有数据。

data 里面会放什么？为什么重要

项目设置、发布记录、签名密钥、操作记录和全部内容对象都存在 data 里，相当于管理端的“全部家当”。升级或迁移管理端时，把旧版本的 data 连同 management-settings.json 等设置文件一起搬到新版本根目录，项目和发布历史就会原样恢复；备份时也请优先备份 data，不要只复制一个空目录。

第 2 步 · 玩家下载服务

[2/3] 配置玩家下载服务
玩家更新器会通过这项服务下载模组和配置文件。
请设置服务监听地址和端口。

监听地址决定哪些电脑可以连接：
  0.0.0.0   = 允许其他电脑连接，部署在服务器或 VPS 时使用（推荐）。
  127.0.0.1 = 只有当前电脑能连接，仅在内部测试时使用。
这里填写的不是公网 IP。玩家访问的公网地址会在创建项目时填写。
下载服务监听地址（一般直接按回车） [0.0.0.0]：

监听端口通常使用默认值 8080。只有端口冲突或服务商有要求时才修改。
如果使用端口映射，这里填写服务器内部端口。
下载服务端口（一般直接按回车） [8080]：

这里填的不是公网地址

这一步配置的是服务器上的监听地址和端口：0.0.0.0 表示允许其他电脑连接，8080 是默认内网端口。玩家真正访问的公网地址（例如 http://你的公网IP:端口）要等创建项目时才填写；如果 8080 被其他程序占用，就换一个空闲端口。

第 3 步 · Web 管理页面

[3/3] Web 管理页面
这个页面只给管理员使用，不要提供给玩家。
  默认端口是 18080，通常直接按回车。
  默认只监听 127.0.0.1；需要公网访问时，先通过本机或 SSH 隧道注册账户，
  再在服务设置或 Web 页面显式改为 0.0.0.0，并务必配置 HTTPS 反向代理。
Web 管理端口（一般直接按回车） [18080]：

Web 管理页面只给管理员用

它默认只监听 127.0.0.1，只有管理端本机能打开。远程服务器上想用浏览器管理时，先通过 SSH 隧道访问，不要把 18080 直接暴露到公网。如果你自己的电脑是 Windows，也可以用桌面版的“SSH 连接”管理服务器：服务器上先启动 Web 管理界面，桌面版会借用你电脑上的 SSH 配置自己建好转发，做法见「远程管理与 AI agent」。网页也不方便用的话也没关系，创建项目、检查发布和下载服务这些主要操作，交互式命令行都能完成。

第 4 步 · 设置完成，创建第一个项目

首次设置已完成
================
  管理端数据：/opt/dfs-admin/data
  下载服务：0.0.0.0:8080
  Web 管理页面：http://127.0.0.1:18080/
  设置文件：/opt/dfs-admin/management-settings.json

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

✓

很好，你已经完成了首次设置！

推荐按 Y 进入网页配置模式：管理端会自动启动 Web 管理界面，你在浏览器里填写项目信息，每个字段都带用途和示例。
无图形界面的 Linux 需要 SSH 隧道：服务器上打不开浏览器，先在你自己的电脑上建立 SSH 隧道再访问管理页面，不要把 18080 直接暴露到公网。
如果你无法使用 Web：也可以按 N 进入命令行模式，使用便捷的终端交互创建项目。
下一页继续：创建项目和终端主菜单的内容在下一页“创建第一个项目”继续，点页面底部的“下一页”即可。