# 配置参考

`config.toml` 是 `astral-server` 的唯一配置文件，同时承载两类内容：本服务（Web 管理端、守护进程、SMTP、第三方服务密钥）配置，以及标准 EasyTier 配置。

## 配置架构

一份 `config.toml` 分为两部分：

- **`[astral_server]` 表** —— 本服务配置，由 `astral-server` 解析并使用；
- **其余所有表**（`instance_name`、`[network_identity]`、`[[peer]]`、`[flags]` 等）—— 标准 EasyTier 配置，解析时原样剥离后交给 EasyTier 内核加载。

面板「保存设置」时只重写 `[astral_server]` 表，EasyTier 部分保持用户手改内容不变。

## `[astral_server]` 配置字段

以下字段全部位于顶层 `[astral_server]` 表：

| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `web_bind` | string | `0.0.0.0` | Web 管理端监听地址（`0.0.0.0` 对全网卡开放，`127.0.0.1` 仅本机） |
| `web_port` | int | `8080` | Web 管理端监听端口 |
| `username` | string | 空 | 鉴权用户名；为空则关闭鉴权（生产环境务必设置） |
| `password` | string | 空 | 鉴权密码（同时用于 Cookie 登录校验与 Basic Auth 兼容） |
| `log_level` | string | `info` | 日志级别：`trace` / `debug` / `info` / `warn` / `error` |
| `nickname` | string | `astral-server` | 房间内展示的昵称（写入 EasyTier hostname，对端可见） |
| `icon` | string | `🎮` | 房间内展示的本机图标（emoji，Web 端显示） |
| `disable_p2p` | bool | `false` | 是否禁用 P2P 打洞（开启后仅走中继） |
| `enable_tun` | bool | `true` | 是否创建 TUN 虚拟网卡（MC 局域网发现等场景依赖虚拟 IP） |
| `static_ipv4` | string | 空 | 启用 TUN 时可选的静态虚拟 IP（CIDR，如 `10.126.0.1/24`）；为空则走 DHCP |
| `auto_join_enabled` | bool | `false` | 守护进程：服务启动后自动加入预设房间 |
| `auto_join_code` | string | 空 | 自动加入使用的邀请：短码 / 完整链接 / `AG1.` 离线串 |
| `auto_create_enabled` | bool | `false` | 守护进程：服务启动后自动创建预设房间（与自动加入二选一） |
| `auto_create_game_id` | string | 空 | 自动创建使用的预设游戏 ID（如 `minecraft`） |
| `auto_create_game_name` | string | 空 | 自动创建使用的预设游戏名称（如 `我的世界`） |
| `ws_key` | string | 空 | WebSocket 第三方服务连接密钥；留空则启动时自动生成随机密钥 |
| `service_control_enabled` | bool | `false` | 是否允许第三方服务发送控制指令（`restart` / `close` / `open` / `join`）；开启后任何持有 `ws_key` 的连接都能执行控制类操作 |

> `service_control_enabled` 为 **1.4.2_4** 新增配置项，也可在面板「设置 → 第三方服务」中切换。

## `[astral_server.smtp]` 配置字段

邮件通知参数（收件人可在面板维护并写回）：

| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `enabled` | bool | `false` | 总开关（关闭则不发信） |
| `host` | string | 空 | SMTP 服务器主机，如 `smtp.qq.com` |
| `port` | int | `465` | SMTP 端口（TLS 一般 465，STARTTLS 一般 587） |
| `username` | string | 空 | 登录用户名（一般与发件邮箱一致） |
| `password` | string | 空 | 登录密码 / SMTP 授权码 |
| `from_name` | string | `Astral Server` | 发件人显示名称 |
| `from_email` | string | 空 | 发件邮箱地址 |
| `encryption` | string | `tls` | 加密方式：`tls`（隐式 TLS / 465）/ `starttls`（587）/ `none`（不加密） |
| `recipients` | string 数组 | `[]` | 收件人邮箱列表（面板可维护） |

## EasyTier 节点配置段

`[astral_server]` 以外的内容是标准 EasyTier 配置，会原样传给内核。示例配置中常见的 EasyTier 段包括：

| 配置项 | 说明 |
|---|---|
| `instance_name` | 实例名，固定为 `astral-server` |
| `hostname` | 主机名（面板昵称写入此字段，对端可见） |
| `dhcp` / `ipv4` | 虚拟 IP 分配方式：`dhcp = true` 时由网络自动分配；`false` 则使用固定 `ipv4` |
| `listeners` | 本机监听地址（`tcp://0.0.0.0:0`、`udp://0.0.0.0:0`，端口 0 表示随机） |
| `[network_identity]` | 组网身份：同网络节点的 `network_name` / `network_secret` 必须一致 |
| `[[peer]]` | 公共服务器（中继 / 打洞），客户端与服务器共享这些 peer |
| `[flags]` | EasyTier 内核开关（压缩算法、默认协议、KCP/QUIC 入站与中继开关等） |

## 示例配置

运行 `astral-server init` 生成的内置示例配置（与源码逐字一致）：

```toml
# =============================================================================
# Astral Game 服务器（CLI + Web 管理端）配置
# 除 [astral_server] 之外的所有内容都是标准 EasyTier 配置，会原样传给内核。
# =============================================================================

[astral_server]
# Web 管理端监听地址与端口（端口在此处本地配置文件中修改即可）
web_bind = "0.0.0.0"
web_port = 8080
# Basic Auth（留空则不启用鉴权，请务必在生产环境设置）
username = "admin"
password = "change-me-please"
# 日志级别：trace / debug / info / warn / error
log_level = "info"
# 房间内展示的昵称（写入 EasyTier hostname，对端客户端可见）
nickname = "astral-server"
# 房间内展示的本机图标（emoji，Web 端显示）
icon = "🎮"
# 是否禁用 P2P 打洞（仅走中继，谨慎开启）
disable_p2p = false
# 是否创建 TUN 虚拟网卡（参与 MC 局域网发现等需要虚拟 IP 的场景）
enable_tun = true
# 启用 TUN 时的静态虚拟 IP（CIDR 格式，如 "10.126.0.1/24"）；留空则走 DHCP
static_ipv4 = ""
# 守护进程：系统启动（服务启动）后自动加入下面预设的房间
auto_join_enabled = false
# 自动加入的邀请：短码 / 完整邀请链接 / AG1. 离线串
auto_join_code = ""

# 守护进程（二选一）：系统启动后自动创建下面预设的游戏房间。
# 若设置了 auto_join_enabled = true 则优先执行"自动加入"，此项忽略。
auto_create_enabled = false
# 自动创建使用的预设游戏 ID（如我的世界 minecraft，与面板创建房间所选 ID 一致）
auto_create_game_id = ""
# 自动创建使用的预设游戏名称（面板展示用，与游戏 ID 对应）
auto_create_game_name = ""

# -----------------------------------------------------------------------------
# SMTP 邮件通知：服务器重启或房间码变动时，自动把房间内容与房间码发给收件人。
# 收件人列表也可以在 Web 面板「设置 → 邮件通知」里维护。
# -----------------------------------------------------------------------------
[astral_server.smtp]
enabled = false                  # 总开关
host = "smtp.qq.com"             # SMTP 服务器（QQ: smtp.qq.com / 163: smtp.163.com / Gmail: smtp.gmail.com）
port = 465                       # 隐式 TLS 用 465；STARTTLS 用 587
username = "your_mail@qq.com"    # 登录账号（一般为发件邮箱）
password = "授权码"               # 注意是 SMTP 授权码，不是邮箱登录密码
from_name = "Astral Server"      # 发件人显示名称
from_email = "your_mail@qq.com"  # 发件邮箱
encryption = "tls"               # 加密方式：tls / starttls / none
recipients = ["a@example.com"]   # 收件人列表（可在面板编辑）

# -----------------------------------------------------------------------------
# WebSocket 第三方服务连接密钥
# 第三方软件（如 AstrBOT 插件）通过 /api/ws/service?key=...&name=...&type=... 连接，
# 连接成功后会出现在面板「设置 → 第三方服务」列表中。留空则启动时自动生成随机密钥。
# -----------------------------------------------------------------------------
# ws_key = ""

# -----------------------------------------------------------------------------
# 第三方服务控制开关（默认关闭）
# 开启后，持有上面 ws_key 的第三方服务除接收房间事件外，还可以发送指令：
#   get_room_info 查询房间类型/成员延迟/运行时长；restart 重启；close 关闭；
#   open 开启（带 game_id/game_name 建房，不带则重放上次配置）；join 加入房间。
# 该开关也可以在面板「设置 → 第三方服务」中切换。
# -----------------------------------------------------------------------------
service_control_enabled = false

# -----------------------------------------------------------------------------
# 以下是 EasyTier 节点配置
# -----------------------------------------------------------------------------
instance_name = "astral-server"
hostname = "astral-server"

# dhcp = true 时由网络自动分配虚拟 IP；false 则使用下方固定 ipv4
dhcp = true
# ipv4 = "10.10.10.1"

# 本机监听地址（0.0.0.0 对外开放；换成 127.0.0.1 仅本机；端口 0 表示随机）
listeners = [
    "tcp://0.0.0.0:0",
    "udp://0.0.0.0:0",
]

# 组网身份：同网络的节点 network_name / network_secret 必须一致
[network_identity]
network_name = "astral-net"
network_secret = "please-change-this-secret"

# 可选的公共服务器（中继 / 打洞）。客户端与服务器共享这些 peer。
# [[peer]]
# uri = "tcp://public.easytier.cn:11010"

# EasyTier 内核开关（与原版客户端对齐）
[flags]
data_compress_algo = 2
default_protocol = "tcp"
dev_name = "astral0"
disable_kcp_input = true
disable_relay_kcp = true
enable_relay_foreign_network_kcp = false
disable_quic_input = true
disable_relay_quic = true
enable_relay_foreign_network_quic = false
# 若使用固定 IP 且关闭 DHCP，请把 dhcp 设为 false 并填写 ipv4
```

## 相关页面

- [快速开始](quick-start.md)
- [WebSocket 事件推送](websocket-events.md)
- [守护进程自动联网](daemon-auto-connect.md)
- [SMTP 邮件通知](smtp-notifications.md)