Skip to content
BranchesTags

Repository files navigation

Hypercraft

跨平台进程管理与监控系统，面向 Minecraft 服务端及其他需长期运行的进程。

功能概览

模块说明
进程管理启动 / 停止 / 重启 / 强杀；支持自动重启与优雅关闭指令
终端WebSocket + PTY attach，可交互输入输出
日志历史截取、实时跟随（SSE）、自动截断
调度Cron 定时 start / stop / restart
认证JWT 会话；DevToken 超管入口；Token 刷新与撤销
权限超级管理员 / 系统管理员 / 普通用户；服务级 ACL
Agent API长期 API Key 与 /agent/* 运维面
安全策略可执行命令白名单、工作目录前缀限制
Web 控制台服务分组、标签、拖拽排序、API Key 与接口测试

快速部署

配置统一使用仓库根目录 .env（模板：.env.example）。

预编译安装（推荐）

自 Releases / main 拉取二进制与 Web standalone，无需本机安装 Rust / Node。

# Linux / macOS
chmod +x install.sh && ./install.sh
# Windows PowerShell
.\install.ps1
模式命令前置条件
预编译（默认）./install.sh · .\install.ps1可访问 GitHub
Docker Compose--docker · -DockerDocker
源码构建--build · -BuildRust 1.75+、Node 20+、pnpm
仅生成配置--env-only · -EnvOnly—
日志 / 停止--logs · --down—

安装完成后访问 http://localhost:3000，使用脚本输出的 HC_DEV_TOKEN 以超级管理员身份登录。

运行时目录

路径用途
dist/预编译 API / CLI 与 Web standalone
data/持久化数据、安装缓存、运行日志
services/被托管进程的推荐工作目录
.env运行时配置（勿提交版本库）

源码开发

./install.sh --env-only # 或 .\install.ps1 -EnvOnly# Windows 可选用 .\dev.ps1 同时拉起前后端cd backend && cargo run -p hypercraft-api
cd web && pnpm install && pnpm dev

API 与 CLI 自当前工作目录向上查找 .env。

CLI

export HC_API_BASE=http://127.0.0.1:8080
# 或 export HC_DEV_TOKEN=...
hypercraft-cli list
hypercraft-cli get <id>
hypercraft-cli start|stop|restart <id>
hypercraft-cli attach <id>
hypercraft-cli logs <id> --follow
hypercraft-cli shell
hypercraft-cli schedule get|set|enable|disable|remove <id>
hypercraft-cli user list
hypercraft-cli user create -u <name> -p <password>
hypercraft-cli user grant|revoke <user-id><service-id>

Agent API

长期凭证格式：hc_ak_<id>_<secret>。
API Key 可访问全部服务，能力由 scopes 控制。API Key 不具备用户管理与超管能力。

Scopes

scope能力
read列表 / 详情 / 状态
controlstart / stop / restart / shutdown / kill
manage创建 / 更新 / 删除服务定义与分组
logs日志 tail / follow
attachWebSocket PTY

管理端点（超级管理员 JWT）

方法路径说明
GET/api-keys列表
POST/api-keys创建
GET/api-keys/:id摘要
GET/api-keys/:id/secret查看完整密钥（加密存储）
PATCH/api-keys/:id更新 scopes / 名称
POST/api-keys/:id/rotate重置密钥
DELETE/api-keys/:id撤销

系统管理员 JWT 不能调用上表；Web 控制台 /api-keys、/api-test 亦仅超级管理员可用。

Agent 分组与服务入组

方法路径scope
GET/agent/groupsread
POST/agent/groupsmanage
POST/agent/groups/reordermanage
PATCH/agent/groups/:idmanage
DELETE/agent/groups/:idmanage
PATCH/services/:id/groupmanage

分配服务到分组（group 为分组 id；null 表示移出分组）：

curl -X PATCH -H "Authorization: Bearer $HC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"group":"default"}' \
"$HC_API/services/<service-id>/group"

Web 控制台：/api-keys（密钥管理）、/api-test（接口联调，仅超管）。

调用示例

export HC_API=http://127.0.0.1:8080
export HC_API_KEY=hc_ak_...
curl -H "Authorization: Bearer $HC_API_KEY""$HC_API/agent/me"
curl -H "Authorization: Bearer $HC_API_KEY""$HC_API/agent/help"
curl -H "Authorization: Bearer $HC_API_KEY""$HC_API/agent/services"
curl -H "Authorization: Bearer $HC_API_KEY""$HC_API/agent/groups"
curl -X POST -H "Authorization: Bearer $HC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id":"default","name":"Default"}' \
"$HC_API/agent/groups"
curl -X PATCH -H "Authorization: Bearer $HC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"group":"default"}' \
"$HC_API/services/<service-id>/group"
curl -X POST -H "Authorization: Bearer $HC_API_KEY" \
"$HC_API/agent/services/<id>/restart"
curl -H "Authorization: Bearer $HC_API_KEY" \
"$HC_API/agent/services/<id>/logs?tail=100"
curl -N -H "Authorization: Bearer $HC_API_KEY" \
"$HC_API/agent/services/<id>/logs?follow=true"# WebSocket: ws://127.0.0.1:8080/agent/services/<id>/attach?token=$HC_API_KEY

同一 Key 亦可调用 /services/*；日志纯文本：/services/:id/logs?format=text。

环境变量

变量说明默认
HC_DATA_DIR数据目录./data
HC_BINDAPI 监听地址0.0.0.0:8080
HC_API_BASECLI 默认 API 地址http://127.0.0.1:8080
HC_DEV_TOKEN超级管理员口令（≥32 字符）未设置则每次启动随机生成
HC_JWT_SECRETJWT 签名密钥未设置则每次启动随机生成
HC_JWT_ISSUERJWT isshypercraft-api
HC_JWT_AUDIENCEJWT audhypercraft-clients
HC_ACCESS_TOKEN_TTLAccess Token 有效期（秒）21600
HC_REFRESH_TOKEN_TTLRefresh Token 有效期（秒）604800
HC_ALLOWED_COMMANDS可执行命令白名单（逗号分隔）见 .env.example
HC_ALLOWED_CWD_PREFIXES工作目录白名单（本机分号分隔）空则按实现放宽
HC_CORS_ORIGINS前端 Origin 列表（禁止 *）本地 3000
HC_WEB_GATEWAY_BASE_DOMAINWeb 网关基础域（无协议）—
NEXT_PUBLIC_API_URL浏览器侧 API 基址http://localhost:8080
HC_API_PORT / HC_WEB_PORTCompose 宿主机端口映射8080 / 3000
RUST_LOG日志级别info

服务清单示例

{
"id": "minecraft-server",
"name": "Minecraft Server",
"command": "java",
"args": ["-Xmx4G", "-jar", "server.jar", "nogui"],
"cwd": "/opt/minecraft",
"env": {
"JAVA_HOME": "/usr/lib/jvm/java-17"
},
"auto_start": false,
"auto_restart": true,
"shutdown_command": "stop",
"tags": ["game", "production"],
"schedule": {
"enabled": true,
"cron": "0 0 8 * * *",
"action": "start"
}
}

systemd（Linux）

将 Release 中的 API 二进制与 Web standalone 分别部署，例如：

  • API：/opt/hypercraft/backend/hypercraft-api
  • Web：/opt/hypercraft/web（含 node、server.js）
  • 配置：/opt/hypercraft/.env
# /etc/systemd/system/hypercraft-api.service[Unit]Description=Hypercraft API
After=network-online.target
Wants=network-online.target
[Service]Type=simple
User=hypercraft
Group=hypercraft
WorkingDirectory=/opt/hypercraft/backend
EnvironmentFile=/opt/hypercraft/.env
ExecStart=/opt/hypercraft/backend/hypercraft-api
Restart=always
RestartSec=5
[Install]WantedBy=multi-user.target
# /etc/systemd/system/hypercraft-web.service[Unit]Description=Hypercraft Web
After=network-online.target hypercraft-api.service
Wants=network-online.target
[Service]Type=simple
User=hypercraft
Group=hypercraft
WorkingDirectory=/opt/hypercraft/web
Environment=PORT=3000
Environment=HOSTNAME=0.0.0.0
ExecStart=/opt/hypercraft/web/node /opt/hypercraft/web/server.js
Restart=always
RestartSec=5
[Install]WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now hypercraft-api hypercraft-web
systemctl status hypercraft-api hypercraft-web
journalctl -u hypercraft-api -f

修改 .env 或替换二进制后需 systemctl restart 对应单元。健康检查：curl -fsS http://127.0.0.1:8080/health。

反向代理与跨域

浏览器会话使用带凭据 Cookie，HC_CORS_ORIGINS 必须为面板实际 Origin（协议 + 主机 + 非默认端口），不得使用 *。

# .env
HC_CORS_ORIGINS=https://panel.example.com
NEXT_PUBLIC_API_URL=https://api.example.com
# 可选：服务页子域网关# HC_WEB_GATEWAY_BASE_DOMAIN=hyper.example.com
server{listen443ssl;server_name api.example.com;location / {proxy_passhttp://127.0.0.1:8080;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_http_version 1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection "upgrade";}}server{listen443ssl;server_name panel.example.com;location / {proxy_passhttp://127.0.0.1:3000;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;}}

Web Gateway 子域需配置通配 DNS、TLS 及至 API 的反代。

仓库结构

hypercraft/
├── backend/ # Rust workspace
│ ├── hypercraft-core/ # 进程与用户核心库
│ ├── hypercraft-api/ # HTTP / WebSocket API
│ └── hypercraft-cli/ # 命令行客户端
├── web/ # Next.js 控制台
├── docker/ # 容器构建与入口
├── install.sh / install.ps1 # 安装与启停
├── docker-compose.yml
└── .env.example

许可证

MIT

About

跨平台的进程管理与监控平台，适用于 Minecraft 服务端等长期运行的进程。

Topics

minecraftminecraft-server-managementrustserver-management

Resources

Readme
Activity

Stars

8 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Contributors

Languages