# 项目概述

Astral Game P2P Server（`astral-server`）是基于 EasyTier 开发的服务器版 Astral 联机工具，适配 Debian/Ubuntu 无头服务器。内置 Web 管理界面，可通过浏览器管理服务器、创建/加入房间。当前版本 **1.5.1_1**。

## 核心特性

- **联机**：创建房间 / 加入房间（支持短码、`AG1.` 离线串、完整链接）
- **成员**：房间内成员列表自动过滤中继节点，仅显示真实用户；本机标记「本机」
- **编辑资料**：自定义昵称、emoji 图标、上传头像图片；昵称与头像通过 peer-RPC `user.getInfo` 广播给房间内客户端（与 Astral Game 客户端互通）
- **网络设置**：可开关「禁用 P2P 打洞」（仅走中继转发）、TUN 虚拟网卡与静态虚拟 IP
- **守护进程**：开机自动加入或自动创建预设房间（二选一），服务器重启免人工
- **WebSocket 推送**：房间内容、房间码、运行状态变动时自动广播给已连接的第三方服务（1.4.2_4 起还支持第三方服务发送控制指令）
- **邮件通知**：SMTP 配置后，房间码变动自动发送同风格 HTML 邮件，支持测试邮件、一键发送当前房间详情、模板可自由编辑
- **配色方案**：设置页内置昼间 5 种 + 夜间 5 种（共 10 种）配色，本地记忆
- **服务器**：添加/编辑/删除中继服务器，一键测速查看延迟
- **设置**：查看运行状态、编辑配置、管理进网凭据、查看实时日志、在线检查更新
- **响应式面板**（1.5.1_1 起）：适配手机 / 平板 / 电脑三种视口，窄屏自动折叠侧边栏
- **操作记录**（1.5.1_1 起）：登录、登出与全部修改操作按 IP 记录，保留 14 天并实时滚动

## 适用场景

- Debian / Ubuntu 无头服务器（无需图形界面）；
- 需要长时间稳定在线、重启后自动恢复房间的游戏联机服务器；
- 面向第三方插件（如 AstrBOT）开放房间状态推送与控制能力。

## 整体架构

单进程内嵌四层：

```
┌────────────────────────────────────────────────┐
│ Web 管理端（单页前端，编译时内嵌 index.html）     │
├────────────────────────────────────────────────┤
│ Axum HTTP 层：REST API + WebSocket 事件推送     │
│ 鉴权：Cookie 会话（面板）/ Basic Auth / ws_key   │
├────────────────────────────────────────────────┤
│ 业务层：房间管理、服务器列表、凭据、SMTP、更新     │
│ 事件中心：一处发布，同时驱动 WS 广播与通知邮件     │
├────────────────────────────────────────────────┤
│ EasyTier 内核：组网节点、TUN、P2P 打洞、中继      │
└────────────────────────────────────────────────┘
```

## 源码模块划分

| 模块 | 职责 |
|---|---|
| `main.rs` | 入口：解析 `run` / `init` / `export-web` 子命令，组装共享状态，启动 HTTP 服务 |
| `config.rs` | `config.toml` 的加载、解析、写回与示例配置生成 |
| `http.rs` | Axum 路由装配与鉴权中间件（Cookie 会话优先，Basic Auth 兼容） |
| `api.rs` | REST API 处理器（登录、房间、服务器、凭据、SMTP、更新等） |
| `ws.rs` | WebSocket：面板事件推送 + 第三方服务密钥接入 + 控制指令协议 |
| `notify.rs` | 事件中心：一处发布，同时驱动 WebSocket 广播与通知邮件 |
| `invite.rs` | `AG1.` 离线邀请串 / 短码 / 分享链接的生成与解析 |
| `mailer.rs` | SMTP 发信（房间变动通知、测试邮件，模板可外置编辑） |
| `node.rs` | EasyTier 实例生命周期：启动/停止/重启、事件日志、状态快照、凭据 |
| `peer_rpc.rs` | EasyTier 应用层 peer-RPC 入站处理（向客户端广播昵称/头像） |
| `status.rs` | EasyTier 运行信息 → 前端节点列表 DTO 的转换 |
| `store.rs` | 本地文件持久化（`servers.json` 服务器列表、`avatar.bin` 头像） |
| `audit.rs` | 操作记录：登录 / 登出 / 修改操作按 IP 留痕，落盘 `audit_log.json`（保留 14 天），并实时广播 `audit` 事件 |
| `update.rs` | 在线更新：检查 GitHub Releases、下载替换二进制、systemctl 重启 |
| `web.rs` | 通过 `include_str!` 内嵌的单文件 Web 管理端 |

## 部署目录

```
/opt/astral-server/       # 部署后统一目录
├── astral-server         # 可执行文件
├── config.toml           # 配置文件（Web 端口、账号密码等）
├── servers.json          # 服务器列表数据（自动生成）
├── audit_log.json        # 操作记录（保留最近 14 天，自动生成）
└── Email/                # 邮件模板（首次运行自动生成，可自由编辑）
    ├── room_notification.html   # HTML 模板
    └── room_notification.txt    # 纯文本模板
```

所有运行期数据（`config.toml`、`servers.json`、`avatar.bin`、`Email/` 模板）统一放在可执行文件同目录，单目录即可维护整套服务。

## 相关页面

- [快速开始](quick-start.md)
- [配置参考](configuration.md)
- [WebSocket 事件推送](websocket-events.md)
- [REST API 参考](rest-api.md)