configuration

配置参考

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 生成的内置示例配置（与源码逐字一致）：

# =============================================================================
# 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

相关页面

• 快速开始
• WebSocket 事件推送
• 守护进程自动联网
• SMTP 邮件通知