调整版本

Reviewed-on: #1

README.md

@@ -2,9 +2,214 @@
 
 一些最基础的功能的模组包，包括录制、光影、基本优化等。主打原版味道。
 
-## 使用
+## 开发
 
 分为服务端和客户端两部分。服务端会在不同时间，安装不同的娱乐性质的模组。客户端则会努力保持不变。
 
 使用 [packwiz](https://packwiz.infra.link) 进行模组包管理。
 
+首先你要安装 packwiz。建议的是用 Golang 技术栈来直接安装：
+
+```bash
+go install github.com/packwiz/packwiz@latest
+```
+
+然后，进入对应的目录开始工作。例如要更改客户端相关：
+
+```bash
+cd client
+```
+
+### 添加模组
+
+```bash
+packwiz add https://modrinth.com/mod/create
+```
+
+### 构建 .mrpack 文件
+
+```bash
+packwiz modrinth export
+```
+
+## 服务端部署
+
+参见 [该文档](https://packwiz.infra.link/tutorials/installing/packwiz-installer/)。
+
+可以直接使用 Docker 来测试运行：
+
+```bash
+docker run --pull=always \
+    -e TYPE=FABRIC \
+    -e "PACKWIZ_URL=https://gitea.service.jazzwhom.top/Passthem/pt-minecraft-modpack/raw/branch/main/server-01-random-block/pack.toml" \
+    -e "EULA=TRUE" \
+    -e "VERSION=1.21.10" \
+    -p 25565:25565 \
+    itzg/minecraft-server
+```
+
+或者，需要从 [https://github.com/packwiz/packwiz-installer/releases](这里) 下载最新最热的 Installer，以安装需要的文件。
+
+## 面板服一键启动方案
+
+仓库根目录提供了 `start.sh`，适合“只能上传文件、编辑文件，然后点一个固定 shell 脚本启动”的面板服环境。
+
+这个脚本现在**直接复用官方 `packwiz-installer-bootstrap` / `packwiz-installer`**，而不是自己手动管理模组列表。
+
+它会自动完成这些事情：
+
+1. 选择一个具体服务端 pack（例如 `server-01-random-block`）
+2. 读取该 pack 的 `pack.toml` 中的 Minecraft / Fabric 版本
+3. 下载并执行 Fabric 官方 installer，生成服务端启动 jar
+4. 下载并执行 `packwiz-installer-bootstrap`
+5. 用 `packwiz-installer --side server` 根据远程 `pack.toml` 自动同步当前服务端需要的模组
+6. 自动写入 `eula.txt`
+7. 最后启动服务端
+
+这意味着以后仓库里新增更多目录，例如：
+
+- `server-01-random-block`
+- `server-02-xxx`
+- `server-03-yyy`
+
+都可以继续复用同一个启动脚本，只需要切换 `PT_SERVER` 即可。
+
+## 方案一：你把整个仓库上传到面板服
+
+上传后，最简单的执行方式就是：
+
+```bash
+PT_SERVER="server-01-random-block" bash start.sh
+```
+
+因为这时 `start.sh` 会直接使用仓库里的本地 `server-01-random-block/pack.toml`。
+
+如果仓库里只有一个 `server-*` 目录，不传 `PT_SERVER` 也可以自动选择；但只要有多个，建议明确传。
+
+### 常用示例
+
+```bash
+PT_SERVER="server-01-random-block" PT_JAVA_ARGS="-Xms1G -Xmx1G" bash start.sh
+```
+
+```bash
+PT_SERVER="server-02-xxx" bash start.sh
+```
+
+### 什么时候需要 `PT_REPO_URL / PT_REPO_REF`
+
+如果你希望 `packwiz-installer` 始终以远程仓库中的 `pack.toml` 为准，而不是当前本地文件，也可以额外传：
+
+```bash
+PT_REPO_URL="https://gitea.service.jazzwhom.top/Passthem/pt-minecraft-modpack" \
+PT_REPO_REF="main" \
+PT_SERVER="server-01-random-block" \
+bash start.sh
+```
+
+## 方案二：面板服里只粘贴一个“远程拉取并运行”的脚本
+
+如果你的面板服不方便手动上传整个仓库，而是允许你在固定 `.sh` 入口里粘贴脚本，那么可以直接粘贴下面这段：
+
+```bash
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+REPO_URL="https://gitea.service.jazzwhom.top/Passthem/pt-minecraft-modpack"
+REPO_REF="main"
+PT_SERVER="server-01-random-block"
+INSTALL_DIR="$(pwd)/pt-minecraft-modpack"
+PT_JAVA_ARGS="-Xms1G -Xmx1G"
+
+if command -v curl >/dev/null 2>&1; then
+  DOWNLOAD() { curl -fL --retry 3 --retry-delay 2 -o "$1" "$2"; }
+elif command -v wget >/dev/null 2>&1; then
+  DOWNLOAD() { wget -O "$1" "$2"; }
+else
+  echo "缺少 curl 或 wget" >&2
+  exit 1
+fi
+
+ARCHIVE_PATH="$INSTALL_DIR.tar.gz"
+TMP_DIR="$INSTALL_DIR.__tmp"
+rm -rf "$TMP_DIR"
+mkdir -p "$TMP_DIR"
+
+DOWNLOAD "$ARCHIVE_PATH" "$REPO_URL/archive/$REPO_REF.tar.gz"
+tar -xzf "$ARCHIVE_PATH" -C "$TMP_DIR"
+
+EXTRACTED_DIR="$(find "$TMP_DIR" -mindepth 1 -maxdepth 1 -type d | head -n 1)"
+[ -n "$EXTRACTED_DIR" ] || { echo "解压失败" >&2; exit 1; }
+
+rm -rf "$INSTALL_DIR"
+mv "$EXTRACTED_DIR" "$INSTALL_DIR"
+rm -rf "$TMP_DIR" "$ARCHIVE_PATH"
+
+cd "$INSTALL_DIR"
+PT_REPO_URL="$REPO_URL" \
+PT_REPO_REF="$REPO_REF" \
+PT_SERVER="$PT_SERVER" \
+PT_JAVA_ARGS="$PT_JAVA_ARGS" \
+bash start.sh
+```
+
+### 这个远程脚本怎么改
+
+你通常只需要改这几个变量：
+
+- `REPO_REF`：默认 `main`，也可以改成某个分支或 tag
+- `PT_SERVER`：你这次要开的服务端目录名
+- `INSTALL_DIR`：解压后的安装目录
+- `PT_JAVA_ARGS`：JVM 参数
+
+例如切换到另一个服务端：
+
+```bash
+PT_SERVER="server-02-xxx"
+```
+
+## 环境要求
+
+- 必须有 `bash`
+- 必须有 `java`
+- 必须有 `curl` 或 `wget`
+- 远程拉取方案还需要 `tar`
+- 建议有常见基础命令：`grep`、`sed`、`awk`、`find`
+- 服务器需要能联网下载：
+  - 你的 Gitea 仓库归档
+  - Fabric installer
+  - `packwiz-installer-bootstrap`
+  - Modrinth 模组文件
+
+## `start.sh` 可选环境变量
+
+- `PT_SERVER`：选择要安装/启动的服务端目录名，例如 `server-01-random-block`
+- `PT_REPO_URL`：仓库地址，例如 `https://gitea.service.jazzwhom.top/Passthem/pt-minecraft-modpack`
+- `PT_REPO_REF`：仓库分支或 tag，例如 `main`
+- `PT_PACK_URL`：如果你想完全手动指定远程 `pack.toml` 地址，也可以直接传这个
+- `PT_INSTALL_ROOT`：实际运行目录，默认是脚本所在目录
+- `PT_JAVA_ARGS`：Java 内存等参数，默认 `-Xms1G -Xmx1G`
+- `PT_AUTO_EULA`：默认 `TRUE`，自动写入 `eula=true`
+- `PT_FORCE_UPDATE=1`：强制重新下载 Fabric installer / bootstrap，并重新执行安装
+- `PT_SERVER_JAR`：手动指定启动的服务端 jar 路径
+- `PT_RUNTIME_DIR`：缓存下载内容与状态文件的目录，默认 `.pt-panel-runtime/`
+- `PT_PACKWIZ_BOOTSTRAP_NO_UPDATE=1`：禁用 bootstrap 自更新
+- `PT_FABRIC_INSTALLER_VERSION`：手动指定 Fabric installer 版本
+- `PT_PACKWIZ_BOOTSTRAP_URL`：手动指定 bootstrap 下载地址
+
+## 验证思路
+
+本脚本已按真实链路验证过以下关键步骤：
+
+```bash
+bash -n start.sh
+PT_DRY_RUN=1 PT_SERVER=server-01-random-block bash start.sh
+```
+
+并且另外在独立测试目录里实际完成了端到端验证：
+
+- `packwiz-installer-bootstrap` 可以直接读取该仓库的 `server-01-random-block/pack.toml`
+- `--side server` 会正确安装服务端所需模组
+- Fabric 官方 installer 能正确安装 `Minecraft 1.21.10 + Loader 0.18.5`
+- 使用 Java 21、`-Xms1G -Xmx1G` 成功启动服务器
+- 服务器日志已出现：`Done (...)! For help, type "help"`

client/config/flashback/flashback.json

@@ -2,15 +2,15 @@
   "configVersion": 2,
   "recordingControls": {
     "controlsLocation": "RIGHT",
-    "automaticallyStart": true,
+    "automaticallyStart": false,
     "automaticallyFinish": true,
     "showRecordingToasts": true,
-    "quicksave": true
+    "quicksave": false
   },
   "recording": {
     "markDimensionChanges": true,
     "recordHotbar": true,
-    "localPlayerUpdatesPerSecond": 120,
+    "localPlayerUpdatesPerSecond": 60,
     "recordVoiceChat": true
   },
   "exporting": {

client/index.toml

@@ -2,7 +2,7 @@ hash-format = "sha256"
 
 [[files]]
 file = "config/flashback/flashback.json"
-hash = "e87d234ed112fe00988e2bb8e8b019dd3d6c7842c5680d468a21507c7343e6f1"
+hash = "2303330c04e7ac1b4070bf3bc181e6db2241c0679c9c6f2b4f887626a2e01398"
 
 [[files]]
 file = "config/minihud.json"

client/pack.toml

@@ -1,12 +1,12 @@
 name = "PT's Basic Modpack"
 author = "passthem"
-version = "1.0.0"
+version = "1.0.1"
 pack-format = "packwiz:1.1.0"
 
 [index]
 file = "index.toml"
 hash-format = "sha256"
-hash = "74c317c3afd3443572a4afcb86847d4ed43758d2c2d08c9c906c34fe8651de38"
+hash = "290e6849aa435a004b728046f75f93474d6cd501760ee7dd87d20ad30a9f9e55"
 
 [versions]
 fabric = "0.18.5"

justfile

@@ -1,5 +1,2 @@
 build-client:
     cd client && packwiz modrinth export
-
-serve:
-    cd server && packwiz serve

start.sh

@@ -0,0 +1,299 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+INSTALL_ROOT="${PT_INSTALL_ROOT:-$SCRIPT_DIR}"
+SERVER_NAME="${PT_SERVER:-${1:-}}"
+RUNTIME_BASE_DIR="${PT_RUNTIME_DIR:-$INSTALL_ROOT/.pt-panel-runtime}"
+DOWNLOAD_DIR="$RUNTIME_BASE_DIR/downloads"
+BOOTSTRAP_JAR="$DOWNLOAD_DIR/packwiz-installer-bootstrap.jar"
+PACKWIZ_META_FILE="packwiz-installer.json"
+
+JAVA_BIN="${JAVA_BIN:-java}"
+JAVA_ARGS="${PT_JAVA_ARGS:--Xms1G -Xmx1G}"
+SERVER_JAR_OVERRIDE="${PT_SERVER_JAR:-}"
+FORCE_UPDATE="${PT_FORCE_UPDATE:-0}"
+DRY_RUN="${PT_DRY_RUN:-0}"
+AUTO_EULA="${PT_AUTO_EULA:-TRUE}"
+PACKWIZ_BOOTSTRAP_NO_UPDATE="${PT_PACKWIZ_BOOTSTRAP_NO_UPDATE:-0}"
+FABRIC_INSTALLER_VERSION="${PT_FABRIC_INSTALLER_VERSION:-}"
+PACKWIZ_BOOTSTRAP_URL="${PT_PACKWIZ_BOOTSTRAP_URL:-https://github.com/packwiz/packwiz-installer-bootstrap/releases/latest/download/packwiz-installer-bootstrap.jar}"
+
+PACK_DIR=""
+PACK_URL=""
+PACK_SLUG=""
+STAMP_FILE=""
+
+log() {
+  printf '[pt-panel] %s\n' "$*"
+}
+
+fail() {
+  printf '[pt-panel] ERROR: %s\n' "$*" >&2
+  exit 1
+}
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1 || fail "缺少命令: $1"
+}
+
+fetch() {
+  local url="$1"
+  local dest="$2"
+
+  if command -v curl >/dev/null 2>&1; then
+    curl -fL --retry 3 --retry-delay 2 -o "$dest" "$url"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -O "$dest" "$url"
+  else
+    fail "缺少 curl 或 wget，无法下载文件"
+  fi
+}
+
+fetch_to_stdout() {
+  local url="$1"
+
+  if command -v curl >/dev/null 2>&1; then
+    curl -fL --retry 3 --retry-delay 2 "$url"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -O - "$url"
+  else
+    fail "缺少 curl 或 wget，无法下载文件"
+  fi
+}
+
+trim_quotes() {
+  local value="$1"
+  value="${value#\"}"
+  value="${value%\"}"
+  printf '%s' "$value"
+}
+
+toml_value() {
+  local key="$1"
+  local file="$2"
+  local line
+
+  line="$(grep -E "^${key}[[:space:]]*=" "$file" | head -n 1 || true)"
+  [ -n "$line" ] || return 1
+  line="${line#*=}"
+  line="${line#${line%%[![:space:]]*}}"
+  trim_quotes "$line"
+}
+
+list_available_servers() {
+  find "$SCRIPT_DIR" -mindepth 1 -maxdepth 1 -type d -name 'server-*' -exec basename {} \; | sort
+}
+
+select_server() {
+  local available count first
+
+  if [ -n "$SERVER_NAME" ]; then
+    PACK_DIR="$SCRIPT_DIR/$SERVER_NAME"
+    [ -f "$PACK_DIR/pack.toml" ] || fail "指定的服务端不存在: $SERVER_NAME"
+    return 0
+  fi
+
+  available="$(list_available_servers || true)"
+  count="$(printf '%s\n' "$available" | sed '/^$/d' | wc -l | awk '{print $1}')"
+
+  if [ "$count" = "1" ]; then
+    first="$(printf '%s\n' "$available" | sed -n '1p')"
+    SERVER_NAME="$first"
+    PACK_DIR="$SCRIPT_DIR/$SERVER_NAME"
+    return 0
+  fi
+
+  if [ "$count" = "0" ]; then
+    fail "仓库中没有找到任何 server-* 服务端目录"
+  fi
+
+  printf '[pt-panel] 可选服务端：\n%s\n' "$(printf '%s\n' "$available" | sed 's/^/  - /')" >&2
+  fail "检测到多个服务端，请通过 PT_SERVER=<目录名> 或第一个参数指定，例如：PT_SERVER=server-01-random-block bash start.sh"
+}
+
+ensure_dirs() {
+  mkdir -p "$INSTALL_ROOT" "$RUNTIME_BASE_DIR" "$DOWNLOAD_DIR"
+}
+
+prepare_server_paths() {
+  PACK_SLUG="$(printf '%s' "$SERVER_NAME" | tr '/' '_')"
+  STAMP_FILE="$RUNTIME_BASE_DIR/fabric-install-${PACK_SLUG}.stamp"
+}
+
+load_pack_versions() {
+  [ -f "$PACK_DIR/pack.toml" ] || fail "找不到 $PACK_DIR/pack.toml，请确认服务端 pack 存在"
+
+  MINECRAFT_VERSION="$(toml_value 'minecraft' "$PACK_DIR/pack.toml")"
+  FABRIC_LOADER_VERSION="$(toml_value 'fabric' "$PACK_DIR/pack.toml")"
+
+  [ -n "$MINECRAFT_VERSION" ] || fail "无法从 $PACK_DIR/pack.toml 读取 minecraft 版本"
+  [ -n "$FABRIC_LOADER_VERSION" ] || fail "无法从 $PACK_DIR/pack.toml 读取 fabric 版本"
+}
+
+compute_pack_url() {
+  if [ -n "${PT_PACK_URL:-}" ]; then
+    PACK_URL="$PT_PACK_URL"
+    return 0
+  fi
+
+  if [ -n "${PT_REPO_URL:-}" ] && [ -n "${PT_REPO_REF:-}" ]; then
+    PACK_URL="${PT_REPO_URL%/}/raw/branch/${PT_REPO_REF}/${SERVER_NAME}/pack.toml"
+    return 0
+  fi
+
+  PACK_URL="$PACK_DIR/pack.toml"
+}
+
+load_latest_fabric_installer_version() {
+  if [ -n "$FABRIC_INSTALLER_VERSION" ]; then
+    printf '%s' "$FABRIC_INSTALLER_VERSION"
+    return 0
+  fi
+
+  local meta version
+  meta="$(fetch_to_stdout 'https://meta.fabricmc.net/v2/versions/installer')"
+  version="$(printf '%s\n' "$meta" | grep '"version"' | head -n 1 | sed 's/.*"version": *"\([^"]*\)".*/\1/')"
+  [ -n "$version" ] || fail "无法获取最新 Fabric installer 版本"
+  printf '%s' "$version"
+}
+
+ensure_packwiz_bootstrap() {
+  if [ -f "$BOOTSTRAP_JAR" ] && [ "$FORCE_UPDATE" != "1" ]; then
+    return 0
+  fi
+
+  log "下载 packwiz-installer-bootstrap"
+  fetch "$PACKWIZ_BOOTSTRAP_URL" "$BOOTSTRAP_JAR"
+}
+
+install_fabric_server() {
+  local installer_version installer_jar wanted_stamp current_stamp
+
+  installer_version="$(load_latest_fabric_installer_version)"
+  installer_jar="$DOWNLOAD_DIR/fabric-installer-${installer_version}.jar"
+  wanted_stamp="server=$SERVER_NAME mc=$MINECRAFT_VERSION loader=$FABRIC_LOADER_VERSION installer=$installer_version"
+  current_stamp="$(cat "$STAMP_FILE" 2>/dev/null || true)"
+
+  if [ "$FORCE_UPDATE" != "1" ] && [ -f "$INSTALL_ROOT/fabric-server-launch.jar" ] && [ "$wanted_stamp" = "$current_stamp" ]; then
+    log "Fabric 服务端已就绪，跳过重复安装"
+    return 0
+  fi
+
+  log "准备安装 Fabric 服务端：$SERVER_NAME (Minecraft $MINECRAFT_VERSION / Loader $FABRIC_LOADER_VERSION)"
+  fetch "https://maven.fabricmc.net/net/fabricmc/fabric-installer/${installer_version}/fabric-installer-${installer_version}.jar" "$installer_jar"
+
+  if [ "$DRY_RUN" = "1" ]; then
+    log "DRY RUN: 跳过执行 Fabric installer"
+    return 0
+  fi
+
+  (
+    cd "$INSTALL_ROOT"
+    "$JAVA_BIN" -jar "$installer_jar" server -mcversion "$MINECRAFT_VERSION" -loader "$FABRIC_LOADER_VERSION" -downloadMinecraft
+  )
+  printf '%s\n' "$wanted_stamp" > "$STAMP_FILE"
+}
+
+run_packwiz_installer() {
+  local args=( -jar "$BOOTSTRAP_JAR" -g --side server --pack-folder "$INSTALL_ROOT" --meta-file "$PACKWIZ_META_FILE" "$PACK_URL" )
+
+  if [ "$PACKWIZ_BOOTSTRAP_NO_UPDATE" = "1" ]; then
+    args=( -jar "$BOOTSTRAP_JAR" --bootstrap-no-update -g --side server --pack-folder "$INSTALL_ROOT" --meta-file "$PACKWIZ_META_FILE" "$PACK_URL" )
+  fi
+
+  if [ "$DRY_RUN" = "1" ]; then
+    log "DRY RUN: 跳过执行 packwiz-installer"
+    log "pack.toml URL: $PACK_URL"
+    return 0
+  fi
+
+  log "使用 packwiz-installer 同步服务端模组"
+  (
+    cd "$INSTALL_ROOT"
+    "$JAVA_BIN" "${args[@]}"
+  )
+}
+
+write_eula() {
+  if [ "$AUTO_EULA" = "TRUE" ] || [ "$AUTO_EULA" = "true" ] || [ "$AUTO_EULA" = "1" ]; then
+    printf 'eula=true\n' > "$INSTALL_ROOT/eula.txt"
+    log "已写入 eula.txt"
+  else
+    log "已跳过自动写入 EULA（PT_AUTO_EULA=$AUTO_EULA）"
+  fi
+}
+
+find_server_jar() {
+  if [ -n "$SERVER_JAR_OVERRIDE" ]; then
+    printf '%s' "$SERVER_JAR_OVERRIDE"
+    return 0
+  fi
+
+  if [ -f "$INSTALL_ROOT/fabric-server-launch.jar" ]; then
+    printf '%s' "$INSTALL_ROOT/fabric-server-launch.jar"
+    return 0
+  fi
+
+  local candidate
+  candidate="$(find "$INSTALL_ROOT" -maxdepth 1 -type f \( -name 'fabric-server-launch.jar' -o -name 'fabric-server-*.jar' -o -name 'server.jar' \) | sort | head -n 1 || true)"
+  [ -n "$candidate" ] || return 1
+  printf '%s' "$candidate"
+}
+
+start_server() {
+  local server_jar
+  server_jar="$(find_server_jar || true)"
+
+  if [ "$DRY_RUN" = "1" ]; then
+    if [ -n "$server_jar" ]; then
+      log "使用服务端文件: $server_jar"
+    else
+      log "DRY RUN: 当前尚未生成服务端 jar；正式运行时会先执行 Fabric installer"
+    fi
+    log "安装目录: $INSTALL_ROOT"
+    log "启动参数: $JAVA_ARGS"
+    log "DRY RUN: 跳过实际启动"
+    return 0
+  fi
+
+  [ -n "$server_jar" ] || fail "找不到可启动的服务端 jar，请检查 Fabric 安装是否成功"
+
+  log "使用服务端: $SERVER_NAME"
+  log "使用服务端文件: $server_jar"
+  log "安装目录: $INSTALL_ROOT"
+  log "启动参数: $JAVA_ARGS"
+
+  cd "$INSTALL_ROOT"
+  exec "$JAVA_BIN" $JAVA_ARGS -jar "$server_jar" nogui
+}
+
+main() {
+  need_cmd "$JAVA_BIN"
+  need_cmd grep
+  need_cmd sed
+  need_cmd awk
+  need_cmd find
+
+  select_server
+  ensure_dirs
+  prepare_server_paths
+  load_pack_versions
+  compute_pack_url
+  ensure_packwiz_bootstrap
+
+  log "脚本目录: $SCRIPT_DIR"
+  log "安装目录: $INSTALL_ROOT"
+  log "选择服务端: $SERVER_NAME"
+  log "Pack 目录: $PACK_DIR"
+  log "Pack URL: $PACK_URL"
+  log "Minecraft 版本: $MINECRAFT_VERSION"
+  log "Fabric Loader 版本: $FABRIC_LOADER_VERSION"
+
+  install_fabric_server
+  run_packwiz_installer
+  write_eula
+  start_server
+}
+
+main "$@"