Crafty Controller 介绍与选型指南

目标：搞清 Crafty Controller 是什么、架构长什么样、能干什么、边界在哪，并用可量化维度与 Pterodactyl、MCSManager、LinuxGSM、auto-mcs 做选型对比。本篇为认知篇，全部结论来自官方仓库/官网/文档站联网溯源，查询日期 2026-11-02；动手部署请看本专栏 Docker Compose 部署篇。

一、环境信息

二、软件概述

Crafty Controller 是一个 Python 编写的 Minecraft 服务器控制面板/启动器。官方 README 对定位的表述是：把 Minecraft 服务器以进程方式拉起在后台，给管理员提供一个 Web 界面去操作这些服务器（"The purpose of Crafty Controller is to launch a Minecraft Server in the background and present a web interface for the server administrators to interact with their servers"），兼容 Docker、Linux、Windows。

溯源要点（查询日期 2026-11-02）：

1. 仓库已迁 GitLab。原 GitHub 地址 Arcane-Nexus/Crafty 现已 404（实测抓取 GitHub 页面返回 "Page not found · GitHub"），开发主阵地是 GitLab 的 crafty-controller/crafty-4，README 中 Git Repository 一栏也指向 GitLab。
2. 官网域名有坑。craftycontroller.com 已被停放（parked，非项目方控制）；真实主页是 **https://craftycontrol.com**，文档站是 **https://docs.craftycontrol.com**。官方 README 的 Meta 栏与项目主页一致标注 craftycontrol.com。检索资料时留意别被停放页误导。
3. 版本节奏。GitLab tag 列表最新为 v4.11.0（2026-09-16）；4.x 线的工程重心按官方 README 说法是 DevOps 化、构建自动化与容器安全（提供预构建镜像、容器内非 root 运行）。
4. 维护方。镜像发布走 Arcadia Technology 名义（Docker Hub arcadiatechnology/crafty-4、内置下载源 jars.arcadiatech.org），项目以开源社区 + Discord 为主要协作渠道。

💡 技术拓展：游戏服务器面板业界存在两类架构路线——

路线	代表	特点	取舍
控制面/数据面分离	Pterodactyl（Panel+Daemon）、Pelican	Web 面板与节点守护进程解耦，可多节点调度、真多租户	组件多、部署重、需要 MySQL/Redis
单机一体化	Crafty Controller、auto-mcs	一个进程（或一个容器）同时管 Web 与游戏进程	上手轻、资源省，但天然单节点

Crafty 属后者：它面向"一台机器上管一堆 MC 服"的场景，不做跨节点调度。

三、核心架构

从官方仓库目录结构与 Dockerfile 溯源归纳（GitLab crafty-controller/crafty-4，v4.11.0，查询日期 2026-11-02）：

• 语言与运行时：Python 3.12，容器镜像内以虚拟环境 /crafty/.venv 运行，入口是 python3 main.py（daemon 模式加 -d -i）。
• Web 层：Tornado（HTTPS 默认 8443，出厂自签证书；HTTP 8000 仅做转发用途），前端配 WebSocket 实时推送（服务器状态、日志、任务进度）。
• 数据层：peewee ORM + SQLite（config/db/crafty.sqlite），启动时按 migratehistory 表做 peewee 迁移回放；无外部数据库依赖——这是它与 Pterodactyl（MySQL+Redis）在部署复杂度上的最大差异。
• 调度层：APScheduler 定时任务（默认 30 秒采集主机/服务器指标、备份计划、Cron 任务、日志 watcher、命令队列线程）。
• 制品层（BigBucket）：内置从 jars.arcadiatech.org 拉取的服务器 jar 元数据缓存（config/bigbucket.json），覆盖 Minecraft Java 官方各版本（含 1.21.x 与 26.x 新线，附 Mojang 官方 piston-data.mojang.com 下载 URL 与 sha256），面板内一键下载对应核心。
• 进程管理层：以 SteamCMD 支撑 Bedrock/Hytale 等需要 Valve 工具链的服务器类型（仅 amd64 镜像提供该依赖）；Java 服直接拉起 jar。
• 权限模型（容器）：镜像内部 crafty:root 组权限结构（仿 OpenShift/Kubernetes 实践），bind mount 无需匹配宿主 UID/GID；入口脚本 docker_launcher.sh 开机自动修复卷权限。
• 数据目录：官方 compose 约定 5 个卷——/crafty/backups、/crafty/logs、/crafty/servers、/crafty/app/config、/crafty/import。

四、功能特性

按官方仓库数据模型（app/migrations 迁移目录与 models 定义溯源：servers、users、roles、user_roles、api_keys、backups、schedules、webhooks、host_stats、server_stats、totp_data、passkey_data 等 18 表）与官方文档归纳：

1. 服务器全生命周期：创建/导入已有服、启停/重启、控制台虚拟终端（默认 70 行环形缓冲）、崩溃检测与忽略退出码、优雅关闭超时、自动开机自启与延迟。
2. 多服务器类型：Minecraft Java（vanilla/Paper/Spigot 等经 BigBucket 下载）、Bedrock（SteamCMD）、Hytale（5520-5550/udp 端口段预留）。
3. 用户与 RBAC：多用户、角色权限（roles/user_roles/role_servers）、配额（quota 迁移记录）、服务器级授权；支持 TOTP 两步验证与 Passkey（4.11 线新增 passkey_data/passkey_challenges 表与 disable_password_auth 字段，可完全关闭口令登录）。
4. API：API Key 体系（api_keys 表含 server_permissions/crafty_permissions/full_access），REST 端点走 /api/v2/*，未认证访问返回 403。
5. 自动化：备份（含压缩、备份保留策略、备份计划）、Cron 式计划任务（schedules）、Webhook 出站事件、审计日志（max_audit_entries）。
6. 可观测：主机与分服务器指标时序（CPU/内存/磁盘/玩家数），按时间窗分档采样降采样（sampling_tiers），历史保留天数可配（history_max_age）。
7. 周边集成：Dynmap 端口直通（8123）、服务器图标/登录页定制（og_embed、custom_logos 迁移）、主题与仪表盘列自定义、多语言文件。
8. 端口族：8443 HTTPS / 8000 HTTP / 8123 Dynmap / 19132/udp Bedrock / 25500-25600 Java 服段 / 5520-5550/udp Hytale。

五、快速开始（官方最小示例）

以下为官方 README 给出的最小 Docker Compose 用法（来源：GitLab crafty-controller/crafty-4 仓库 README，查询日期 2026-11-02；逐行实测部署与验证回显见本专栏部署篇，本篇不做本地实测）：

services:
  crafty:
    container_name: crafty_container
    image: registry.gitlab.com/crafty-controller/crafty-4:latest
    restart: always
    environment:
      - TZ=Etc/UTC
    ports:
      - "5520-5550:5520-5550/udp" # Hytale
      - "8000:8000" # HTTP
      - "8443:8443" # HTTPS
      - "8123:8123" # DYNMAP
      - "19132:19132/udp" # BEDROCK
      - "25500-25600:25500-25600" # MC SERV PORT RANGE
    volumes:
      - ./docker/backups:/crafty/backups
      - ./docker/logs:/crafty/logs
      - ./docker/servers:/crafty/servers
      - ./docker/config:/crafty/app/config
      - ./docker/import:/crafty/import

docker-compose up -d && docker-compose logs -f

起栈后访问 https://<主机>:8443，首次启动会打印随机初始管理员口令（config/default-creds.txt），登录改密即可开服。

六、适用场景与限制

适合：

• 单机（或单机容器宿主）上管理多个 Minecraft Java/Bedrock 服，要 Web UI、要玩家协作账号体系；
• 希望"一个容器解决一切"、不想引入 MySQL/Redis 外部依赖；
• 树莓派/NAS 等 arm64 设备（官方镜像双架构）；
• 需要 API/备份/计划任务做轻度自动化的小团队。

限制与风险（均有官方依据）：

1. WSL2 / Docker Desktop 上跑 Minecraft 容器被官方明确警告不可用：README 原文指出上游在 "Docker under WSL/WSL2, Windows 11 / DOCKER DESKTOP" 已 broken，停服/重启时世界区块有 90% 概率不可逆损坏，官方建议 Docker 路线只在 Linux 用，Windows 改用便携安装。
2. 单节点设计：无跨节点调度、无多服务器实例编排（面板本体只跑在一台机器上）。
3. SQLite 并发上限：适合中小规模用户/服务器数；重度多租户不是它的赛道。
4. SteamCMD 依赖仅 amd64：arm64 镜像上 Bedrock 等 SteamCMD 功能自动禁用（launcher 脚本按 uname -m 检测打印警告）。
5. GPL-3.0 传染性：对二次分发闭源集成不友好（自用无碍）。
6. 社区规模：GitLab 256 star，比 Pterodactyl/MCSManager 小一个数量级，生态（教程、第三方集成）相对薄。

七、同类选型对比

量化数据均为 2026-11-02 实查（star 数与版本经 shields.io 徽章接口取数；Crafty 星标为 GitLab 徽章）：

解读与选择建议：

• 要"单机 Docker 一把梭 + Web UI 管 MC 服群"：选 Crafty Controller。它是本组里唯一"零外部依赖单容器"的 Web 面板，SQLite 自带、jar 内置下载源、权限自愈，部署心智负担最小。
• 要做服主售卖/真多租户托管：选 Pterodactyl。9.5k star 生态最大、egg 市场成熟、控制面/数据面分离可横向扩节点；代价是 MySQL/Redis/Daemon 全家桶和明显的运维门槛。
• 中文用户、多游戏混布、不想碰容器：MCSManager 最顺手，v10 线发版极勤（实查距上次发布仅 1 天），但面板+守护进程两件套的运维面比 Crafty 大。
• 纯 CLI、脚本化、极简资源：LinuxGSM（120+ 游戏、MIT）；只是想要"一条命令开一个 MC 服"则 auto-mcs 更轻。

💡 说明：star 数只反映社区关注度，不等于工程质量；本组里 Pterodactyl 的活跃度优势主要体现在第三方 egg 生态与托管场景，而 Crafty 的价值在"单人服主的最小运维面"。

八、参考链接

• 官方仓库（GitLab）：https://gitlab.com/crafty-controller/crafty-4
• 项目主页：https://craftycontrol.com
• 官方文档：https://docs.craftycontrol.com
• Docker Hub 镜像：https://hub.docker.com/r/arcadiatechnology/crafty-4
• Discord 社区：https://discord.gg/9VJPhCE
• awesome-selfhosted 条目（Games - Administrative Utilities & Control Panels 分类）：https://github.com/awesome-selfhosted/awesome-selfhosted
• 对比对象主页：Pterodactyl https://pterodactyl.io/ 、MCSManager https://mcsmanager.com 、LinuxGSM https://linuxgsm.com/ 、auto-mcs https://www.auto-mcs.com

（以上链接与数据查询日期均为 2026-11-02。）