Minecraft PaperMC 服务器部署指南 / 05 - 权限系统

05 - 权限系统

5.1 权限系统概述

Minecraft 的权限系统控制玩家可以执行哪些命令、使用哪些功能。原版游戏仅通过 OP（管理员）来区分权限，粒度极粗。插件引入了更精细的权限节点（Permission Node）体系。

5.1.1 权限节点格式

权限节点采用层级命名，使用 . 分隔：

plugin.feature.sub-feature

# 示例：
essentials.tp                # 允许 /tp 命令
essentials.tp.others         # 允许传送到其他玩家
essentials.gamemode          # 允许切换游戏模式
worldedit.navigation.thru    # 允许穿过方块
luckperms.group.admin        # 允许管理 admin 组

5.1.2 权限值类型

5.2 LuckPerms 介绍

LuckPerms 是当前最流行、功能最完善的权限管理插件，已成为 Minecraft 服务器的标配。

5.2.1 为什么选择 LuckPerms

5.2.2 安装 LuckPerms

# 从官方下载
# https://luckperms.net/download

# 方式一：直接下载
wget -O /opt/minecraft/paper/plugins/LuckPerms-Bukkit-5.4.jar \
  "https://download.luckperms.net/1529/LuckPerms-Bukkit-5.4.130.jar"

# 方式二：使用 paper plugin.yml 自动下载（Paper 特性）
# 在 plugins/ 目录下创建 paper-plugin.yml

# plugins/paper-plugin.yml（Paper 自动下载插件）
name: LuckPerms
main: me.lucko.luckperms.bukkit.LPBootstrap
version: "5.4"
api-version: "1.20"
dependencies:
  - name: Bukkit
    required: true

注意：Paper 1.20.5+ 支持 paper-plugin.yml 自动下载特性，但 LuckPerms 官方 JAR 仍是推荐方式。

5.3 LuckPerms 基础操作

5.3.1 命令格式

/lp user <用户名> permission set <权限节点> <true/false>
/lp group <组名> permission set <权限节点> <true/false>

5.3.2 用户操作

# 给玩家设置权限
/lp user Steve permission set essentials.tp true

# 移除玩家权限
/lp user Steve permission unset essentials.tp

# 查看玩家所有权限
/lp user Steve permission info

# 设置玩家前缀
/lp user Steve meta setprefix "&a[管理员]"

# 设置玩家后缀
/lp user Steve meta setsuffix "&7"

# 将玩家加入组
/lp user Steve parent add admin

# 将玩家从组中移除
/lp user Steve parent remove default

# 查看玩家信息
/lp user Steve info

5.3.3 组操作

# 创建组
/lp creategroup moderator

# 给组添加权限
/lp group moderator permission set essentials.kick true
/lp group moderator permission set essentials.ban true
/lp group moderator permission set essentials.mute true

# 设置组的优先级（数字越大优先级越高）
/lp group moderator setweight 50

# 设置组前缀
/lp group moderator meta setprefix "&b[版主] &r"

# 设置组继承（admin 继承 moderator 的所有权限）
/lp group admin parent add moderator

# 列出所有组
/lp listgroups

# 删除组
/lp deletegroup oldgroup

5.4 权限组设计

5.4.1 典型权限组层级

default (默认，0)
  └── member (成员，10)
        └── vip (VIP，20)
              └── elite (精英，30)
                    └── moderator (版主，50)
                          └── admin (管理员，80)
                                └── owner (服主，100)

5.4.2 权限组配置示例

default 组（默认组，所有玩家自动继承）：

# 创建默认组
/lp creategroup default
/lp group default setweight 0

# 基础权限
/lp group default permission set essentials.spawn true
/lp group default permission set essentials.sethome true
/lp group default permission set essentials.home true
/lp group default permission set essentials.delhome true
/lp group default permission set essentials.tpahere false
/lp group default permission set essentials.warps.* false
/lp group default permission set essentials.msg true
/lp group default permission set essentials.r true
/lp group default permission set essentials.mail true
/lp group default permission set essentials.balance true
/lp group default permission set essentials.pay true

# 聊天
/lp group default permission set essentials.chat.color false
/lp group default permission set essentials.chat.url true

# 传送
/lp group default permission set essentials.tpa true
/lp group default permission set essentials.tpaccept true
/lp group default permission set essentials.tpdeny true

# 前缀
/lp group default meta setprefix "&7[玩家] &r"

member 组（正式成员）：

/lp creategroup member
/lp group member setweight 10
/lp group member parent add default

# 更多权限
/lp group member permission set essentials.warps.* true
/lp group member permission set essentials.sethome.multiple true
/lp group member permission set essentials.home.multiple true
/lp group member permission set essentials.back true
/lp group member permission set essentials.back.ondeath true
/lp group member permission set essentials.near true

# 前缀
/lp group member meta setprefix "&a[成员] &r"

vip 组：

/lp creategroup vip
/lp group vip setweight 20
/lp group vip parent add member

# VIP 权限
/lp group vip permission set essentials.fly true
/lp group vip permission set essentials.speed true
/lp group vip permission set essentials.feed true
/lp group vip permission set essentials.heal true
/lp group vip permission set essentials.eco true
/lp group vip permission set essentials.nick true
/lp group vip permission set essentials.chat.color true
/lp group vip permission set essentials.sethome.multiple.vip true
/lp group vip meta setprefix "&6[VIP] &r"

moderator 组：

/lp creategroup moderator
/lp group moderator setweight 50
/lp group moderator parent add vip

# 管理权限
/lp group moderator permission set essentials.kick true
/lp group moderator permission set essentials.ban true
/lp group moderator permission set essentials.tempban true
/lp group moderator permission set essentials.mute true
/lp group moderator permission set essentials.jails.* true
/lp group moderator permission set essentials.gamemode true
/lp group moderator permission set essentials.teleport true
/lp group moderator permission set essentials.vanish true
/lp group moderator permission set coreprotect.inspect true
/lp group moderator permission set coreprotect.lookup true
/lp group moderator meta setprefix "&b[版主] &r"

admin 组：

/lp creategroup admin
/lp group admin setweight 80
/lp group admin parent add moderator

# 管理员权限
/lp group admin permission set essentials.* true
/lp group admin permission set worldedit.* true
/lp group admin permission set worldguard.* true
/lp group admin permission set coreprotect.* true
/lp group admin permission set luckperms.* true
/lp group admin permission set minecraft.command.op false  # 禁止直接 OP
/lp group admin meta setprefix "&c[管理员] &r"

5.4.3 默认玩家组设置

# 设置默认组（新玩家自动加入）
/lp setdefaultgroup default

# 查看当前默认组
/lp info

5.5 LuckPerms Web 编辑器

Web 编辑器是 LuckPerms 最强大的功能之一：

# 生成 Web 编辑器链接
/lp editor

# 输出类似：
# https://luckperms.net/editor/xxxxxx-xxxx-xxxx-xxxx
# 有效期：10 分钟

# 在浏览器中打开链接，进行可视化编辑
# 编辑完成后点击 "Save" 保存
# 复制生成的命令到控制台执行

Web 编辑器功能

5.6 权限上下文（Context）

LuckPerms 支持按条件分配权限：

5.6.1 世界特定权限

# 仅在创造世界允许飞行
/lp user Steve permission set essentials.fly true world=creative

# 仅在主世界允许传送
/lp user Steve permission set essentials.tp true world=world
/lp user Steve permission set essentials.tp false world=world_nether

5.6.2 服务器特定权限（BungeeCord/Velocity）

# 仅在生存服允许 /home
/lp user Steve permission set essentials.home true server=survival

# 仅在创造服允许 WorldEdit
/lp user Steve permission set worldedit.* true server=creative

5.6.3 时间段权限

# 夜间模式（22:00 - 06:00）允许使用烟花
/lp group member permission set essentials.firework true time=22:00-06:00

5.6.4 组合上下文

# 在创造世界的夜间允许使用烟花
/lp group member permission set essentials.firework true world=creative time=22:00-06:00

5.7 前缀、后缀与聊天格式

5.7.1 配置前缀

# 设置组前缀（用于 Tab 列表和聊天）
/lp group admin meta setprefix "&c[管理员] "
/lp group moderator meta setprefix "&b[版主] "
/lp group vip meta setprefix "&6[VIP] "
/lp group member meta setprefix "&a[成员] "
/lp group default meta setprefix "&7[玩家] "

# 设置用户特定前缀
/lp user Steve meta setprefix "&4[服主] "

5.7.2 与聊天插件集成

# 如果使用 EssentialsXChat
# config.yml 中配置格式：
chat:
  format: '{DISPLAYNAME}&7: {MESSAGE}'
  # {DISPLAYNAME} 会自动包含 LuckPerms 的前缀

# 如果使用 DeluxeChat
# 配置 LuckPerms 前缀变量：
# {luckperms_prefix} - 来自 LuckPerms
# {luckperms_suffix} - 来自 LuckPerms
# {luckperms_meta_<key>} - 自定义元数据

5.8 迁移与导入

5.8.1 从 PermissionsEx 迁移

# 1. 安装 LuckPerms
# 2. 运行导入命令
/lp migration permsFromPex

# 或使用离线工具
java -jar luckperms-bukkit.jar import pex

5.8.2 从 GroupManager 迁移

/lp migration groupsFromGroupManager

5.8.3 导出与导入

# 导出当前权限配置
/lp export output.json

# 导入权限配置
/lp import input.json

5.9 数据存储

5.9.1 存储类型对比

5.9.2 MySQL 配置

# plugins/LuckPerms/config.yml
storage-method: mysql
data:
  address: "localhost:3306"
  database: "luckperms"
  username: "minecraft"
  password: "your_password"
  table-prefix: "luckperms_"
  pool-settings:
    maximum-pool-size: 10
    minimum-idle: 10
    maximum-lifetime: 1800000
    keepalive-time: 300000
    connection-timeout: 5000

-- 创建数据库和用户
CREATE DATABASE luckperms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'minecraft'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON luckperms.* TO 'minecraft'@'localhost';
FLUSH PRIVILEGES;

5.10 权限审计与维护

5.10.1 检查玩家权限

# 查看玩家所有有效权限（包括继承）
/lp user Steve permission check essentials.tp

# 查看玩家所属组
/lp user Steve parent info

# 详细权限列表
/lp user Steve permission verbose true
# 执行后所有权限检查会输出到日志
# 用完后关闭
/lp user Steve permission verbose false

5.10.2 批量操作

# 给所有在线玩家添加权限
/lp bulkupdate users set permission essentials.fly true

# 删除所有玩家的某个权限
/lp bulkupdate users delete permission old.permission

5.10.3 日志与审计

# 查看操作日志
/lp log

# 查看特定用户的操作历史
/lp log user Steve

# 查看最近的操作
/lp log recent

5.11 常见问题

Q1：设置权限后不生效？

# 1. 检查权限节点是否拼写正确
/lp user Steve permission info

# 2. 检查是否有更高优先级的 false 权限
/lp user Steve permission check essentials.tp

# 3. 检查插件是否需要 OP 才能使用
# 某些插件需要 OP 而非权限节点

# 4. 尝试 /lp sync 同步数据
/lp sync

Q2：玩家加入时不自动加入默认组？

# 确认默认组设置正确
/lp info
# 应显示 "Default group: default"

# 手动修复
/lp setdefaultgroup default

Q3：如何让 OP 不自动拥有所有权限？

# 在 LuckPerms config.yml 中
include-global-permissions: false
include-global-world-permissions: false
# 注意：OP 默认拥有所有权限，这是 Minecraft 的设计
# 建议不使用 OP，仅通过权限组管理

5.12 本章小结

扩展阅读

• LuckPerms 官方文档
• LuckPerms 权限节点列表
• LuckPerms Wiki - 权限上下文
• EssentialsX 权限列表