文档

ResourcePackSync 文档

从快速开始到生产加固，覆盖安装、配置、命令、API 与架构的完整指南。

快速开始

ResourcePackSync 由三部分组成：Go 后端（含 Vue 管理控制台）、双端 Minecraft Mod、共享 common 协议层。最快的方式是下载分发包，按单机演示流程跑通。

核心理念

资源包版本不可变。每次上传生成新版本号，事件保存完整版本快照，回退基于历史版本创建新事件。这是整个系统安全可追溯的基石。

环境要求

组件	要求	说明
后端运行时	Go 1.25 编译，无 JVM	单二进制，Win + Linux amd64
旧版 Mod 构建	JDK 21	1.20.1 / 1.21.11
MC 26.2 构建	JDK 25	编译与运行均需 Java 25
数据库	SQLite（内置）	纯 Go 驱动，无 CGO
前端构建	Node 24 + npm	Vue 3 + Vite + TS

分发包说明

执行 ./gradlew.bat releaseArtifacts 后，产物整理进 build/release/：

发布产物结构

build/release/
|-- backend/
|   |-- rpsync-backend.exe        # Windows
|   '-- rpsync-backend            # Linux
|-- minecraft-1.20.1/{forge,fabric,neoforge}/
|-- minecraft-1.21.11/{forge,fabric,neoforge}/
|-- minecraft-26.2/{forge,fabric,neoforge}/
|-- resourcepacksync-mods-mc1.20.1-0.1.4-rc.1.zip
|-- resourcepacksync-mods-mc1.21.11-0.1.4-rc.1.zip
|-- resourcepacksync-mods-mc26.2-0.1.4-rc.1.zip
|-- resourcepacksync-deploy-0.1.4-rc.1.zip   # 完整部署包
'-- SHA256SUMS.txt

JAR 命名规则：rpsync-{loader}-mc{mcVersion}-{modVersion}.jar。完整部署 ZIP 包含后端二进制、config/rpsync.env.example、启动脚本、static/admin/（Vue 构建）、内置 packs/、docs/，以及 mods/minecraft-*/loader/ 目录树与 rpsync-common.example.toml（Forge/NeoForge）。

单机演示

后端与 Minecraft 服务端在同一台机器上，适合本地测试。

单机演示流程

# 1. 启动后端
./start-backend.bat   # 或 .sh

# 2. 启动 Forge/Fabric/NeoForge 服务端
#    将 rpsync-*-mc*.jar 放入 mods/

# 3. 客户端安装同一版本 JAR，进服
#    Mod 配置 baseUrl=http://localhost:8080
#    allowLocalHttpForDevelopment=true

仅限开发

allowLocalHttpForDevelopment = true 仅用于本地演示。生产环境必须关闭并使用 HTTPS。

生产部署

后端部署在独立主机/域名，前置 Nginx/Caddy 提供 HTTPS。客户端与服务端均指向真实 baseUrl。

生产启动

# rpsync.env
RPSYNC_BIND_ADDRESS=0.0.0.0
RPSYNC_PORT=8080
RPSYNC_PUBLIC_BASE_URL=https://packs.example.com
RPSYNC_DOWNLOAD_TOKEN_SECRET=<32位以上强随机密钥>
RPSYNC_ADMIN_PASSWORD=<16位以上强密码>
RPSYNC_ADMIN_COOKIE_SECURE=true
RPSYNC_SERVER_AUTH_ENABLED=true
RPSYNC_SERVER_AUTH_SECRET=<32位以上HMAC密钥>

启动顺序

必须按以下顺序启动，否则 Mod 在服务端启动时无法连接后端：

后端 -- start-backend.bat / .sh
Minecraft 服务端 -- 含 RPSync 服务端 Mod
客户端 -- 安装匹配 JAR 后加入服务器

向玩家分发时，发送对应 MC 版本与加载器的单个 JAR 即可；Fabric 用户另需安装 Fabric API。

配置总览

配置分为两部分：后端通过环境变量（rpsync.env），Mod 通过 TOML（Forge/NeoForge）或 properties（Fabric）。首次运行自动生成 Mod 配置文件。

后端环境变量

变量	默认值	说明
`RPSYNC_BIND_ADDRESS`	127.0.0.1	HTTP 绑定地址。公网暴露设为 0.0.0.0
`RPSYNC_PORT`	8080	HTTP 端口
`RPSYNC_PUBLIC_BASE_URL`	http://127.0.0.1:<port>	客户端可见 URL，写入清单
`RPSYNC_DOWNLOAD_TOKEN_SECRET`	开发占位符	下载令牌 HMAC 密钥，生产需 ≥32 字符
`RPSYNC_ADMIN_DATA_DIR`	./backend-admin-panel-data	SQLite、资源包、图标、暂存目录
`RPSYNC_DATABASE_PATH`	<data>/rpsync-admin.db	数据库路径覆盖
`RPSYNC_STATIC_DIR`	自动检测	Vue 静态文件目录
`RPSYNC_BUILTIN_PACKS_DIR`	自动检测 packs	内置 ZIP 目录
`RPSYNC_ADMIN_USERNAME`	admin	首个 SUPER_ADMIN 用户名（仅初始化时）
`RPSYNC_ADMIN_PASSWORD`	开发占位符	管理员密码，生产需 ≥16 字符
`RPSYNC_ADMIN_PASSWORD_HASH`	空	bcrypt 哈希替代项（{bcrypt}$2a$...）
`RPSYNC_ADMIN_COOKIE_SECURE`	false	HTTPS 下设为 true
`RPSYNC_SERVER_AUTH_ENABLED`	false	校验游戏服 HMAC 请求
`RPSYNC_SERVER_AUTH_SECRET`	空	与 Mod 共享的 HMAC 密钥，≥32 字符
`RPSYNC_ALLOW_PUBLIC_HTTP_CUSTOM_PORT`	false	允许公网 HTTP 非 80/443 端口
`RPSYNC_ADMIN_TOTP_ENABLED`	false	启用 2FA
`RPSYNC_ADMIN_TOTP_SECRET_BASE32`	-	Base32 TOTP 密钥（启用 2FA 时必填）
`RPSYNC_ADMIN_TOTP_ISSUER`	ResourcePackSync	TOTP 发行方标签
`RPSYNC_ADMIN_TOTP_ACCOUNT`	-	TOTP 账户标签

管理控制台 Cookie 名固定为 RPSYNCADMIN，属性 HttpOnly + SameSite=Strict。HTTPS 下需设 RPSYNC_ADMIN_COOKIE_SECURE=true。

Mod 配置

Forge/NeoForge 生成 config/rpsync-common.toml；Fabric 生成 config/rpsync-fabric.properties（等价键 + rpsync.serverAuthSecret 系统属性）。

rpsync-common.toml

[sync]
mode = "dedicated_only"

[backend]
baseUrl = "https://packs.example.com"
serverId = "production-1"
connectTimeoutMillis = 7000
requestTimeoutMillis = 30000
downloadRetries = 4
maxDownloadSizeBytes = 536870912     # 512 MiB
downloadRateLimitKiBPerSec = 0
allowLocalHttpForDevelopment = false
allowInsecureHttpDownloads = false
allowHttpDownloadsOnCustomPort = false
allowedDownloadEndpoints = []
blockedDownloadPorts = [3389, 3390]

命令参考

所有命令均为客户端命令（RegisterClientCommandsEvent / Fabric ClientCommandManager）。无服务端权限节点；服务端到后端认证通过 HMAC。

命令	作用
`/rpsync checkupdate`	立即检查资源包更新
`/rpsync settings`	打开客户端设置（登录时是否自动检查）
`/rpsync guide`	打开游戏内首次使用引导

自动检查与提醒

关闭自动检查不会关闭 upcoming 或预约到点聊天提醒。服务端每 30s 轮询到期事件，到点仅发送聊天提醒，不自动弹出下载 UI。

管理控制台

访问 http://localhost:8080/admin/login。主导航：

控制台导航

概览 / 资源包更新 / 事件历史 / 用户组 / 玩家 / 日志 / 设置

默认数据目录 ./backend-admin-panel-data：

数据目录

backend-admin-panel-data/
|-- rpsync-admin.db      # SQLite 主库
|-- admin-state.json     # 仅旧数据备份
'-- packs/               # 资源包版本存储

管理角色：SUPER_ADMIN（全部权限 + 面板用户管理）vs ADMIN（无面板用户管理）。不能删除自身或最后一个超级管理员；角色变更/删除后下次请求重新校验会话。i18n 存储于 localStorage 的 rpsync-admin-locale。

更新事件

事件状态实时派生：scheduled / active / superseded / rolled_back / cancelled。一个事件中每个资源包只能选一个版本；要同时更新多个包，在同一事件中分别为每个包选一个版本。

更新资源包流程：上传新 ZIP -> 选择不可变版本 + 用户组 -> 创建即时/预约事件 -> 玩家下次登录或 /rpsync checkupdate 触发。切勿用不同内容覆盖旧文件名。

暂存上传

预览阶段返回 stagedUploadId（1 小时 TTL，单次使用）；提交阶段仅发送 ID + 元数据，避免重复传输文件内容。

API 参考

方法	路径	说明
POST	`/api/session/check`	Mod 会话检查，返回 PASS / NEED_UPDATE / DENY
POST	`/api/session/report`	客户端下载结果上报
POST	`/api/server/resourcepack-event-notices/poll`	游戏服轮询到期事件（30s）
GET	`/api/resourcepacks/{versionId}/manifest`	资源包清单
GET	`/api/resourcepacks/{versionId}/download`	资源包下载（需 token）
GET	`/health`	健康检查
GET	`/api/admin/bootstrap`	控制台首屏数据
GET	`/api/admin/resourcepack-console`	资源包控制台聚合数据
GET	`/api/admin/dashboard`	仪表盘数据
POST	`/api/admin/packs/preview`	暂存上传预览，返回 stagedUploadId
POST	`/api/admin/packs`	提交暂存 ID + 元数据完成上传
GET	`/api/admin/resourcepack-events`	事件列表
POST	`/api/admin/resourcepack-events`	创建更新事件
GET	`/api/admin/resourcepack-events/{eventId}/diff`	事件版本差异
POST	`/api/admin/resourcepack-events/{eventId}/rollback`	回退（创建新事件）
POST	`/api/admin/resourcepack-events/{eventId}/cancel`	取消未生效事件
POST	`/api/admin/groups`	创建用户组
DELETE	`/api/admin/groups/{groupId}`	删除用户组
POST	`/api/admin/players`	注册玩家
DELETE	`/api/admin/players/{minecraftUuid}`	删除玩家
GET	`/api/admin/logs`	查询日志
GET	`/api/admin/log-settings`	日志设置
PUT	`/api/admin/log-settings`	更新日志设置

Session Check

SessionCheckRequest.mods 仅用于兼容旧客户端，后端不读取或校验 Java Mod 列表。Session Check 只返回 PASS 或 NEED_UPDATE（外加 DENY）。下载 URL 与 token 绑定到不可变 versionId。

架构设计

Mod 为双端：服务端解析玩家用户组 + 活动事件并调用后端；客户端执行实际下载。网络协议版本为 "2"，数据包 ID 统一 rpsync:* 前缀。

项目结构

Root Gradle (8.8)
|-- backend/admin-panel/         Go + Vue 3
|   |-- cmd/rpsync-backend/      单二进制 HTTP 服务
|   |-- internal/                config/db/auth/packs/events
|   '-- frontend/                Vue 3 + Vite + TS -> static/admin/
|-- minecraft-mod/
|   |-- common/                  共享 DTO/JSON/协议/安全
|   |-- forge/1.20.x, fabric/1.20.x, neoforge/1.20.x
|   '-- modern/                  Gradle 9.5.1 多加载器 (1.21.11 + 26.2)
|-- distribution-resources/      启动脚本/环境示例/Mod 配置模板
'-- docs/

数据库迁移 V001-V005 与旧 Spring 后端一致；V006 新增查询索引与 staged_pack_uploads 表。旧 session_reports / audit_logs 保留只读，新写入进入 app_log_entries。DB 设置：WAL 模式、外键开启、5s 忙等待、小连接池、每小时清理日志与过期暂存上传。

构建指南

本地构建

# 后端 (Go 1.25+)
cd backend/admin-panel
go test ./...
cd ../..

# 旧版 Mod (JDK 21)
./gradlew.bat :forge-1.20.x:test
./gradlew.bat :fabric-1.20.x:build
./gradlew.bat :neoforge-1.20.x:build

# 全量构建 + 发布产物
./gradlew.bat build
./gradlew.bat releaseArtifacts

# Vue 前端
cd backend/admin-panel/frontend
npm run typecheck
npm run build

releaseArtifacts 会调用现代构建包装器，并按 MC 版本与加载器整理 build/release/。Go 构建标志：-trimpath -ldflags "-s -w"，CGO_ENABLED=0。

生产加固

绑定地址仅公网暴露时设 RPSYNC_BIND_ADDRESS=0.0.0.0
双 HMAC 密钥下载令牌 + 服务端认证各一把，均 ≥32 字符，绝不复用
管理员密码≥16 字符，或提供 bcrypt RPSYNC_ADMIN_PASSWORD_HASH
HTTPS + 安全 CookieRPSYNC_ADMIN_COOKIE_SECURE=true，前置 Nginx/Caddy
启用服务端认证RPSYNC_SERVER_AUTH_ENABLED=true 配合 Mod 端密钥
TOTP 2FA公网管理控制台强烈建议启用
反向代理限制限制 /admin 来源 IP 并记录访问日志
端口隔离MC FRP / RDP FRP / RPSync 后端三端口分离，勿把 RDP 端口放进 baseUrl
Mod 客户端生产关闭 allowLocalHttpForDevelopment，显式白名单 HTTP 端点

非回环启动拦截

非回环绑定时，后端启动会自动拦截：占位/过短密钥、缺失服务端 HMAC、明文公网 HTTP（必须设 RPSYNC_ALLOW_PUBLIC_HTTP_CUSTOM_PORT=true 并避开 3389/3390 端口）。

最小上线清单

真实 HTTPS 域名 · 强下载令牌密钥 · 已替换管理员凭据 · 公网启用 TOTP · 客户端+服务端 baseUrl 一致 · allowLocalHttpForDevelopment=false · 受限的 /admin 日志。验证：go test ./...、npm run build（含 vue-tsc）、gradlew Mod 测试。