Phira-mp+

Phira-mp+ 是基于 phira-mp 开发的Phira多人游戏服务端，使用Rust开发，支持WASM插件系统，旨在提供稳定，高性能，高拓展性的Phira多人游戏服务端。使用AI开发。被HSNPhira使用。

简介

Phira-mp+（PMP） 是 phira-mp 的增强版多人游戏服务端。在 Phira+ 架构中，PMP 负责游戏协议、房间运行时、WASM 插件与游戏数据持久化。HTTP/SSE/WebSocket 端口用于兼容、诊断和内部集成。

核心特性

有界连接接入 — TCP accept 与认证解耦，认证并发和在线会话由信号量预留，慢认证连接不会串行阻塞全局 accept
WASM 插件边界 — 基于 wasmtime 组件模型（WIT ABI v2），逐插件 capability、fuel、线性内存/实例/表限制、有界事件队列与超时 quarantine 已接线
可靠生命周期 — 插件事件和持久化使用有界队列；Flush/Shutdown 带确认；数据库重试耗尽后写入本地 dead-letter；后台任务由 Supervisor 统一跟踪并在关闭时取消和等待
严格命令入口 — Session 与 Room 管理命令只经 mailbox 执行；mailbox 缺失、关闭、拥塞或结果不确定时显式失败，不再切换到直接处理路径
一致房间控制面 — host/lock/cycle/hidden/endpoint/容量等控制字段共享同一快照和 generation。ActorState 已是快照权威来源，全部 17 个命令走 actor_state
慢消费者隔离 — 会话发送采用有界队列和非阻塞路径；网络读取与业务处理通过有界命令队列解耦
内部接口 — 房间信息 HTTP、SSE、WebSocket 和插件动态路由
插件 TCP 连接 API — 供 WASM 插件通过句柄建立和管理 TCP 连接（connect/listen/send/close），纯明文，无 TLS
jemalloc 分配器 — Linux 下使用 jemalloc 替代 musl malloc，降低长期运行中的 RSS 膨胀风险

文档

分类	文档
功能总览	PMP 相对 Phira-mp 新增功能（含兼容矩阵）
部署与运维	部署/配置/运维 · 配置 JSON Schema
对外 API	HTTP/SSE/WS · 插件 API · 能力表 · OpenUDS
CLI 手册	CLI 命令参考（含基准测试）
插件开发	插件开发指南（含 WIT ABI、示例）
开发	架构 · 测试指南 · CLI 错误码 (EN)

许可

PMP 服务端采用 AGPL-3.0 开源。插件 SDK（phira-plugin-sdk）采用 Apache-2.0 许可。第三方依赖的许可声明见 NOTICE。

技术栈

技术	用途
Rust	主开发语言（2021 Edition）
Tokio	异步运行时
ratatui + crossterm	TUI 终端界面
Clap	CLI 参数解析
Axum	HTTP/SSE 服务器
wasmtime	WASM 运行时（可选）
fluent	本地化 (i18n)
reqwest	HTTP 客户端
tracing	日志与诊断
serde_yaml	YAML 配置解析

快速开始

下载发行版（推荐）

从 Releases 或 CI 构建产物下载：

phira-mp-plus-server-linux-glibc（Linux glibc，通用）
phira-mp-plus-server-linux（Linux musl，更便携）
phira-mp-plus-server-linux-arm64-glibc（Linux ARM64）
phira-mp-plus-server-windows-x86_64（Windows x86_64）

平台说明：Windows 版本不编译、不支持 OpenUDS（Unix Domain Socket 是 Unix 特性，模块已 #[cfg(unix)] 排除）；其余功能与 Linux 版一致。

环境配置：

# 1. 安装 PostgreSQL（Ubuntu/Debian）
sudo apt update && sudo apt install -y postgresql
sudo systemctl start postgresql

# 2. 配置数据库（database_url 必填，不能留空）
sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'your_password';"
sudo -u postgres createdb phira_mp_plus

# 3. 下载 phira-mp-plus-server-linux-glibc 并赋予执行权限
chmod +x phira-mp-plus-server-linux-glibc

# 4. 启动（默认配置 + PM_DATABASE_URL 指定数据库即可）
PM_DATABASE_URL="postgres://postgres:your_password@localhost:5432/phira_mp_plus" ./phira-mp-plus-server-linux-glibc
# （如需自定义其它配置，可用 --config 指定 server_config.yml）

database_url 必填（留空会启动失败）：PMP 需要 PostgreSQL 连接。数据库需先创建（createdb），PMP 启动后自动 sqlx 迁移建表。以非 postgres 用户运行时，localhost 走密码认证，需先设置 postgres 密码（ALTER USER）。

Docker 部署（推荐）

需要 Docker 和 Docker Compose：

# 克隆仓库
git clone https://github.com/HyperSynapseNetwork/Phira-mp-plus.git
cd Phira-mp-plus

# Docker Compose 会自动配置 database_url，默认配置即可
# 一键启动（PostgreSQL + PMP）
docker compose up -d

# 查看日志
docker compose logs -f phira-mp-plus

# 停止
docker compose down

Docker Compose 会自动创建 PostgreSQL 容器并初始化数据库。配置文件通过 server_config.yml 挂载，数据持久化在 Docker volumes 中。

手动部署（从源码编译）

1. 安装依赖

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update stable

# 安装 PostgreSQL（Ubuntu/Debian）
sudo apt update && sudo apt install -y postgresql
sudo systemctl start postgresql

# 对于二进制部署，安装 musl 目标并构建（可选）
rustup target add x86_64-unknown-linux-musl
sudo apt install -y musl-tools

2. 构建

git clone https://github.com/HyperSynapseNetwork/Phira-mp-plus.git
cd Phira-mp-plus
cargo build --release --target x86_64-unknown-linux-musl

3. 配置

创建 server_config.yml：

port: 12346
http_port: 12347
monitors:
  - 12345
  - 67890
phira_api_endpoint: "https://phira.5wyxi.com"
plugins_dir: plugins
connection_rate_limit: 60
connection_rate_window: 10
round_data_retention_days: 7
server_name: "My Phira Server"
chat_enabled: true
cli_enabled: true

4. 启动

# database_url 留空时自动连接本地 PostgreSQL（Unix socket peer auth，无需密码）
# 数据库不存在时自动创建
./target/x86_64-unknown-linux-musl/release/phira-mp-plus-server

# 指定自定义配置启动
./target/x86_64-unknown-linux-musl/release/phira-mp-plus-server --config my_config.yml

# 指定数据库连接串（覆盖配置文件）
PM_DATABASE_URL="postgres://user:pass@host:5432/phira_mp_plus" ./phira-mp-plus-server

PostgreSQL 设置：首次启动会自动创建 phira_mp_plus 数据库和所有表。如果自动建库失败，可以手动创建：
sudo -u postgres psql -c "CREATE DATABASE phira_mp_plus;"

配置加载规则：默认读取 server_config.yml，也可通过 --config <FILE> 指定；配置文件缺失时使用内置默认值，配置文件存在但格式、字段名或取值无效时拒绝启动。只有用户显式提供的命令行参数才覆盖 YAML，避免 CLI 默认值意外覆盖配置文件。完整说明见 docs/deployment.md。

命令行参数

phira-mp-plus-server [OPTIONS]

  -p, --port <PORT>          覆盖 TCP 监听端口（内置默认 12346）
  -d, --plugins-dir <DIR>    覆盖插件目录（内置默认 "plugins"）
  -e, --ext-file <FILE>      覆盖扩展数据文件（内置默认 "data/extensions.json"）
  -l, --log-file <NAME>      日志文件基础名称 [默认: "phira-mp-plus"]
  -m, --monitor <IDS>...     覆盖允许旁观的用户 ID
      --http-port <PORT>     覆盖 HTTP/SSE 端口（内置默认 12347）
      --proxy-port <PORT>    覆盖可信 X-Forwarded-For 兼容监听端口（内置默认 0）
      --no-cli               禁用交互式管理控制台
  -c, --config <FILE>        YAML 配置文件路径 [默认: "server_config.yml"]
  -h, --help                 显示帮助
  -V, --version              显示版本

空载模式仅改变非关键后台活动的调度偏好，不会暂停权威持久化或可靠插件事件。更多配置项见 [docs/deployment.md](docs/deployment.md)。

项目结构

Phira-mp-plus/
│
├── Cargo.toml                       # 工作区根 (workspace)
├── Cargo.lock
├── LICENSE                          # AGPL-3.0
├── README.md
├── server_config.yml                # YAML 配置文件
├── wit/                             # WIT 接口定义
│   └── phira-plugin.wit             #   Plugin ABI v2 WIT (15 interfaces)
│
├── scripts/
│   └── docgen.sh                    #   WIT → Markdown 文档生成脚本
│
├── data/                            # 运行时数据目录
│   ├── extensions.json              #   插件扩展数据
│   └── plugins/                     #   插件私有数据
├── log/                             # 运行日志（每小时轮转）
│
├── docs/                            # 文档
│   ├── features.md                  #   功能总览（相对 Phira-mp 新增 + 兼容矩阵）
│   ├── deployment.md                #   部署/配置/运维
│   ├── api.md                       #   对外 API（HTTP/SSE/WS + 插件 API + 能力表 + OpenUDS）
│   ├── cli.md                       #   CLI 命令参考
│   ├── plugin-dev.md                #   插件开发指南
│   ├── operations/
│   │   └── config-schema.json       #   配置 JSON Schema
│   └── development/                 #   开发文档
│
├── phira-mp-plus-server/            # 服务端核心 (crate)
│   ├── Cargo.toml
│   ├── locales/                     #   Fluent i18n (en/zh-CN/zh-TW)
│   └── src/
│       ├── main.rs                  #   进程入口 & 生命周期
│       ├── lib.rs                   #   模块导出
│       ├── bin/
│       │   └── pmp-admin.rs         #   独立管理工具 (backup/restore)
│       ├── server/                  #   Server 模块 (9 子模块)
│       │   ├── mod.rs               #    模块声明 + re-export
│       │   ├── state.rs             #    PlusServerState/PlusServer 结构
│       │   ├── init.rs              #    PlusServer::new 初始化
│       │   ├── accept.rs            #    TCP 监听 accept 循环
│       │   ├── config.rs            #    PlusConfig / LiveConfig / RuntimeConfig
│       │   ├── events.rs            #    事件订阅/发布
│       │   ├── query.rs             #    ServerStateQuery dispatch
│       │   ├── snapshot.rs          #    RoomSnapshot / build_snapshot
│       │   ├── rooms.rs             #    房间管理方法
│       │   ├── disconnect.rs        #    disconnect_banned_user
│       ├── benchmark/               #   Benchmark 模块
│       │   ├── mod.rs               #    模块入口
│       │   ├── command.rs           #    BenchmarkCommand/BenchmarkRunArgs
│       │   ├── config.rs            #    BenchmarkConfig
│       │   ├── runner.rs            #    顶级调度
│       │   ├── environment.rs       #    环境检测
│       │   ├── mock_phira.rs        #    本地 Mock Phira
│       │   ├── profile.rs           #    CPU/heap profiling
│       │   ├── metrics.rs           #    指标采集
│       │   ├── report.rs            #    报告生成 (text/json/markdown)
│       │   ├── presets.rs           #    预设参数 (quick/standard/stress/soak)
│       │   ├── modes/               #    运行模式
│       │   │   └── real.rs          #      真实 TCP 模式
│       │   └── scenarios/           #    负载场景 (11 个)
│       │       ├── common.rs        #      共享工具
│       │       ├── room_lifecycle.rs
│       │       ├── gameplay.rs
│       │       ├── connection.rs
│       │       ├── steady_state.rs
│       │       ├── hot_room.rs
│       │       ├── slow_consumer.rs
│       │       ├── reconnect.rs
│       │       ├── plugin_load.rs
│       │       ├── database_write.rs
│       │       ├── mixed.rs
│       │       └── long_run.rs
│       ├── cli.rs                   #   CLI 生命周期、输入循环
│       ├── cli/dispatch.rs          #   顶层命令路由
│       ├── cli/commands/            #   命令模块
│       │   ├── admin.rs             #   admin-id / ban / extension
│       │   ├── benchmark.rs         #   benchmark (list/run/suite/compare)
│       │   ├── broadcast.rs         #   消息广播
│       │   ├── plugin.rs            #   WASM 插件管理
│       │   ├── room.rs              #   房间管理
│       │   └── runtime/             #   runtime 诊断子命令
│       ├── cli_tui.rs               #   TUI 终端 (ratatui + crossterm)
│       ├── command_registry.rs      #   命令注册表
│       ├── session.rs               #   会话生命周期
│       ├── session_auth.rs          #   会话认证
│       ├── session_dispatch.rs      #   命令分发
│       ├── session_permissions.rs   #   会话权限
│       ├── session_room.rs          #   房间协议
│       ├── session_telemetry.rs     #   遥测处理 (Touch/Judge → HighFrequencyWriter)
│       ├── session_actor.rs         #   Session Actor mailbox
│       ├── supervisor_actor.rs      #   后台任务注册、退出检测与有序关闭
│       ├── room.rs                  #   房间广播接口 (Actor 已独占 members/monitors/live 状态)
│       ├── backup.rs                #   备份与恢复 (仅 pmp-admin binary)
│       ├── crypto.rs                #   HMAC 签名 (sha2)
│       ├── plugin_tcp.rs            #   插件原始 TCP Actor
│       ├── play_history.rs          #   游玩历史
│       ├── room_actor/              #   Room Actor 命令网关
│       │   ├── mod.rs               #    RoomCommandGateway
│       │   ├── actor.rs             #    RoomActorState / RoomSnapshot
│       │   ├── mailbox.rs           #    per-room mailbox
│       │   ├── command.rs           #    RoomActorCommand 枚举
│       │   ├── handler.rs           #    命令执行
│       │   ├── context.rs           #    命令上下文
│       │   ├── result.rs            #    命令结果
│       │   ├── audit.rs             #    审计日志
│       │   └── ops/                 #    操作
│       │       ├── mod.rs
│       │       ├── control.rs       #      SetLock/SetCycle/SetHidden
│       │       ├── membership.rs    #      AddUser/RemoveUser
│       │       ├── session.rs       #      Chat/Create/Join/Leave
│       │       ├── settings.rs      #      SetHost/SetChart/SetEndpoint
│       │       └── telemetry.rs     #      AddTouches/AddJudges/SetDisplayName
│       ├── idle.rs                  #   空载模式
│       ├── persistence/             #   持久化管道
│       │   ├── mod.rs               #   模块入口
│       │   ├── pipeline.rs          #   写入管道分发
│       │   ├── wal.rs               #   Write-Ahead Log (A 类事件)
│       │   ├── high_frequency.rs    #   高频写入 (Touch/Judge, 绕过 WAL, PostgreSQL COPY)
│       │   ├── worker.rs            #   PersistenceWorker 主循环
│       │   ├── stats.rs             #   写入统计 (含 per-type 细分)
│       │   ├── message.rs           #   PersistenceEvent 枚举
│       │   ├── telemetry.rs         #   批量 INSERT
│       │   ├── rounds.rs            #   Round 持久化
│       │   ├── admin.rs             #   管理员数据
│       │   ├── benchmark.rs         #   Benchmark 报告持久化
│       │   ├── diagnostics.rs       #   队列健康诊断
│       │   ├── events.rs            #   事件持久化
│       │   ├── queries.rs           #   查询方法
│       │   ├── schema.rs            #   Schema 常量
│       │   └── users.rs             #   用户数据持久化
│       ├── proxy_protocol.rs        #   可信代理支持
│       ├── round_store.rs           #   轮次数据存储
│       ├── internal_hooks.rs        #   内部静态注册
│       ├── plugin.rs                #   插件管理器
│       ├── plugin_abi/              #   Plugin ABI 边界
│       │   ├── mod.rs               #    导出 / wit_abi bindgen
│       │   └── plan.rs              #    ABI 版本常量（稳定）
│       ├── plugin_http/             #   HTTP 动态路由
│       │   ├── router.rs            #    DynamicRouter
│       │   ├── sse.rs               #    SseHub / EventStream
│       │   └── websocket.rs         #    WebSocket handler
│       ├── wasm_host.rs             #   WASM 运行时
│       ├── wasm_host_helpers.rs     #   capability/config helpers
│       ├── wit_host.rs              #   WIT host trait 实现
│       ├── extensions.rs            #   扩展 KV 存储
│       ├── ban.rs                   #   封禁系统
│       ├── phira_client.rs          #   Phira HTTP RetryClient
│       ├── rate_limiter.rs          #   速率限制
│       ├── event_bus.rs             #   EventBus (MpEvent 广播)
│       ├── runtime_diagnostics.rs   #   Runtime 诊断常量
│       ├── benchmark/               #   基准测试模块（配置/场景/运行器/报告）
│       ├── db.rs                    #   PostgreSQL 持久化 (DbManager)
│       ├── error.rs                 #   错误类型
│       ├── l10n.rs                  #   Fluent i18n
│       ├── logging.rs               #   tracing 配置
│       └── terminal.rs              #   终端检测
│   └── tests/                       # 集成 & 合约测试
│       ├── admin_command_contracts.rs
│       ├── command_surface_contracts.rs
│       ├── docs_contracts.rs
│       ├── persistence_contracts.rs
│       ├── phira_http_contracts.rs
│       ├── room_state_machine_tests.rs
│       ├── wit_abi_contracts.rs      #   15 接口 conformance (Phase 5)
│       ├── wasm_lifecycle_tests.rs
│       ├── wasm_api_tests.rs
│       ├── sse_tests.rs
│       ├── test-plugin.component.wasm
│       └── test-plugin/
│           ├── Cargo.toml, Makefile
│           └── src/lib.rs
│
├── phira-mp-plus-server-api/        # 共享类型 crate
│   └── src/lib.rs                   #   PluginEvent / HttpHandle / ServerStateQuery
│
├── phira-plugin-sdk/                # WASM 插件 SDK
│   ├── Cargo.toml
│   └── src/lib.rs                   #   wit_bindgen! 宏
│
├── phira-mp/                        # 上游 phira-mp 协议层
│   ├── phira-mp-common/             #   网络协议
│   │   └── src/                     #   ClientCommand / ServerCommand / Stream 帧协议
│   └── phira-mp-macros/             #   #[derive(BinaryData)] 过程宏

终端兼容性

启动时会检测 stdin/stdout、TERM、STY 与 TMUX。GNU Screen、Linux console、ansi/cons25 等环境使用保守 TUI：禁用备用屏幕、鼠标捕获和 Bracketed Paste，并修正 Ctrl+H Backspace；如果 TUI 初始化失败，会自动降级到逐行兼容控制台。tmux、xterm、WezTerm、iTerm、Kitty 等普通终端继续使用完整 TUI。项目遵循 NO_COLOR，逐行输出会再次过滤残留控制序列；非交互环境同样使用逐行控制台。

| http_port | u16 | 12347 | PMP HTTP/SSE/WebSocket 端口 |

许可证

Phira-mp+ 整体采用 GNU Affero General Public License v3.0 — 详见 LICENSE。

协议层（phira-mp-common、phira-mp-macros）基于 phira-mp 衍生； phira-plugin-sdk（WASM 插件 SDK）亦按 Apache License, Version 2.0 授权 — 详见 LICENSE-APACHE。

完整的版权归属和第三方依赖许可证声明见 NOTICE。

致谢

感谢 TeamFlos 开发和维护 Phira、phira-mp 项目，以及 tphira-mp 与 jphira-mp 提供的实现思路，还有所有支持本项目的用户。详见 NOTICE。

Navigation Menu

Uh oh!

Repository files navigation

Phira-mp+

简介

核心特性

文档

许可

技术栈

快速开始

下载发行版（推荐）

Docker 部署（推荐）

手动部署（从源码编译）

命令行参数

项目结构

终端兼容性

许可证

致谢

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 1,230 Commits
.github/workflows		.github/workflows
data		data
deploy/systemd		deploy/systemd
docs		docs
phira-mp-plus-server-api		phira-mp-plus-server-api
phira-mp-plus-server		phira-mp-plus-server
phira-mp		phira-mp
phira-plugin-sdk		phira-plugin-sdk
scripts		scripts
wit		wit
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
LICENSE-APACHE		LICENSE-APACHE
NOTICE		NOTICE
README.md		README.md
THIRDPARTY_LICENSES		THIRDPARTY_LICENSES
about.hbs		about.hbs
about.toml		about.toml
docker-compose.yml		docker-compose.yml
notice.hbs		notice.hbs
rust-toolchain.toml		rust-toolchain.toml
server_config.yml		server_config.yml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Phira-mp+

简介

核心特性

文档

许可

技术栈

快速开始

下载发行版（推荐）

Docker 部署（推荐）

手动部署（从源码编译）

命令行参数

项目结构

终端兼容性

许可证

致谢

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages