> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/zh/docs/sample-projects/godot/godotsteam-server.md).

# Edgegap 上的 GodotSteam 服务器

Edgegap 上的 GodotSteam 专用服务器：无头 Linux 导出、Steam 登录和身份验证票据、Docker、部署与 Steam 客户端。

[GodotSteam Server](https://codeberg.org/godotsteam/godotsteam-server) 是 GodotSteam 的专用服务器版本。它封装了 Steam 的游戏服务器 API（`SteamGameServer`），供 Godot 使用，因此无头服务器可以登录 Steam、获取自己的 Steam ID，并检查每位加入的玩家是否是真正的 Steam 用户且拥有你的游戏。

本指南将介绍如何从零开始，使用 Godot 4 项目构建一个在 Edgegap 上运行的 GodotSteam Server 专用服务器，并让 Steam 客户端连接并通过 Steam 身份验证票据检查。玩家通过 Godot 内置的 ENet（UDP）连接；Steam 用于身份、所有权和反作弊检查。

本指南中的完整项目托管在 GitHub 上： [edgegap/server-sample-godotsteam-dedicated-server](https://github.com/edgegap/server-sample-godotsteam-dedicated-server)。克隆该项目，运行 `./tools/fetch-godotsteam.sh` 下载 GodotSteam 插件，然后按照其 README 中的说明，通过几条命令运行服务器。

{% hint style="success" %}
**测试日期：2026-11-09** 测试环境为 Godot 4.7.2、GodotSteam Server 4.12.1（GDExtension）、GodotSteam 4.24（GDExtension）和 Steamworks SDK 1.65：服务器在 Edgegap 上以匿名方式登录 Steam，Windows 客户端通过 ENet 连接，其身份验证票据经 Steam 验证，并且客户端离开后部署会自动停止。
{% endhint %}

## ✔️ 准备工作

开始之前，请确保 [创建 Edgegap 免费账户](https://app.edgegap.com/auth/register) （无需信用卡）。

**在开发机器上完成几项基本配置：**

* [Godot 4.4 或更高版本](https://godotengine.org/download) 以及 **Linux** 导出模板（编辑器 / 管理导出模板）。GodotSteam Server 的 GDExtension 要求 Godot 4.4 或更高版本。
* [Docker Desktop（或 Docker CLI）](https://www.docker.com/products/docker-desktop/).
* 安装并登录 Steam 客户端，以便测试游戏客户端。
* 一个 Steam App ID。本指南使用 `480` （Spacewar），这是 Valve 的测试应用，所有 Steam 账户均可使用。正式发布前，请将其替换为你自己的 App ID。

{% hint style="info" %}
如果你刚接触 Godot 专用服务器，请先阅读 [Godot - 入门指南](https://docs.edgegap.com/zh/godot.md) ，了解使用 Edgegap 插件进行导出、Docker 和部署的步骤，然后再回来添加 Steam。
{% endhint %}

## 🧩 1. 安装 GodotSteam

GodotSteam 有两个版本，客户端/服务器游戏需要同时使用这两者：

| 插件                    | 单例            | 用途    | 下载                                                                                                                                                                                                   |
| --------------------- | ------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GodotSteam Server** | `SteamServer` | 专用服务器 | [Codeberg 发行版](https://codeberg.org/godotsteam/godotsteam-server/releases) (`godotsteam-server-<version>-gdextension-plugin-4.4.zip`），或在 Godot Asset Library 中搜索“GodotSteam Server GDExtension 4.4+” |
| **GodotSteam**        | `Steam`       | 游戏客户端 | [Codeberg 发行版](https://codeberg.org/godotsteam/godotsteam/releases) (`godotsteam-<version>-gdextension-plugin-4.4.zip`），或在 Godot Asset Library 或 Asset Store 中搜索“GodotSteam GDExtension 4.4+”        |

☑️ 将两个压缩包解压到项目中，使其包含 `addons/godotsteam_server/` 和 `addons/godotsteam/`。Steamworks API 库（`libsteam_api.so`, `steam_api64.dll`等）已包含在每个插件中。

{% hint style="info" %}
**GDExtension 还是模块？** 本指南使用 GDExtension 版本：它们可与标准 Godot 编辑器和标准导出模板配合使用。模块版本（`godotsteam-server` 模板和编辑器）是自定义 Godot 构建版本；如果使用它们，请改用 GodotSteam Server 模板导出服务器，并跳过插件文件夹。切勿在同一个项目中混用 GDExtension 和模块版本。
{% endhint %}

{% hint style="warning" %}
如果在同一个项目中添加了两个插件，编辑器会打印诸如以下错误： `Attempt to register extension class 'SteamProjectSettings', which appears to be already registered`。两个插件都声明了该设置类。在我们的测试中，这不会影响服务器或客户端；而且本指南中的每次导出只会打包两个插件中的一个，因此导出的构建不会出现此问题。
{% endhint %}

✅ 现在可以继续下一步了。

## 🔧 2. 添加服务器和客户端脚本

下面的脚本是一个自动加载脚本：在服务器导出中，它作为专用服务器运行；在其他情况下则作为客户端运行。它使用 `Engine.get_singleton()` 因此，即使导出中只包含两个插件之一，它也仍能通过解析。

**服务器的功能：**

1. `serverInitEx()` 使用游戏端口、查询端口、身份验证模式和版本字符串启动 Steam 游戏服务器 API。
2. 设置服务器的产品、描述、mod 目录、名称和玩家人数。Steam 只接受在 **登录之前** 设置这些信息。
3. `logOnAnonymous()` 使用临时 Steam ID 登录 Steam；或者使用 `logOn(token)` 和游戏服务器登录令牌登录，前提是设置了 `STEAM_GSLT` （参见 [#steam-account-and-game-server-login-token](#steam-account-and-game-server-login-token "mention")).
4. 在端口 `7777`上打开 ENet 服务器。当有对等端连接时，向其发送服务器的 Steam ID，并等待最多 15 秒以获取 Steam 身份验证票据。
5. `beginAuthSession()` 将票据交给 Steam； `validate_auth_ticket_response` 信号会指示该玩家是否获准加入。验证失败或始终未发送票据的玩家会被断开连接。
6. 当所有玩家都离开（或 2 分钟内无人加入）时，服务器会退出 Steam 登录并删除自己的 Edgegap 部署，这样空服务器就不会继续产生费用。

**客户端的功能：** 使用你的 App ID 初始化 Steam，通过 ENet 连接，向 Steam 请求一个绑定到服务器 Steam ID 的身份验证会话票据，等待 Steam 确认该票据，然后将其发送给服务器。

{% hint style="warning" %}
只有调用 `run_callbacks()`后，Steam 信号才会触发。脚本会在 `SteamServer.run_callbacks()` （以及 `Steam.run_callbacks()` ，客户端上）中，于每帧的 `_process`阶段调用回调。GodotSteam 的“嵌入回调”项目设置会改为在渲染帧中挂接回调，而无头服务器不会进行渲染。
{% endhint %}

☑️ 将脚本保存为 `res://net/session.gd`.

{% code title="net/session.gd" lineNumbers="true" expandable="true" %}

```gdscript
extends Node
## 连接两端共用一个自动加载脚本。
## 服务器（导出为 dedicated_server，或使用 `-- --server` 启动）：通过 GodotSteam Server 登录 Steam，并在 GAME_PORT 上使用 ENet
## 且每位玩家都必须通过 Steam 身份验证票据检查。
## 客户端（GodotSteam）：使用 ENet 连接，然后向服务器发送 Steam 身份验证票据。
## 使用 Engine.get_singleton()，这样脚本在仅包含两个附加组件之一的导出版本中也能通过解析。

const STEAM_APP_ID := 480            # Spacewar，Valve 的测试应用。请使用你自己的 App ID。
const SERVER_VERSION := "1.0.0.0"    # x.x.x.x；Steam 只会列出最新版本的服务器。
const GAME_PORT := 7777              # ENet，UDP。Edgegap 端口 "gameport"。
const QUERY_PORT := 27015            # Steam 查询，UDP。Edgegap 端口 "queryport"。
const MAX_PLAYERS := 8
const AUTH_TIMEOUT_SEC := 15.0       # 在时限内未发送有效票据的对等端将被踢出。
const NO_PLAYER_TIMEOUT_SEC := 120.0 # 如果无人加入，则停止部署。

# SteamServer.ServerMode，以及我们要检查的 BeginAuthSession / AuthSession 结果。
const SERVER_MODE_AUTHENTICATION := 2
const BEGIN_AUTH_RESULT_OK := 0
const AUTH_SESSION_RESPONSE_OK := 0

var steam_server: Object  # SteamServer 单例，仅服务器使用
var steam: Object         # Steam 单例，仅客户端使用
var server_steam_id := 0
var players := {}         # peer_id -> steam_id，已通过身份验证的玩家
var pending := {}         # peer_id -> {"steam_id": int, "deadline": float}
var had_players := false
var stopping := false


func _ready() -> void:
	if is_server_launch():
		_start_server()
	else:
		_start_client()


func _process(_delta: float) -> void:
	# 只有调用此方法时，Steam 回调（信号）才会触发。
	if steam_server:
		steam_server.run_callbacks()
	if steam:
		steam.run_callbacks()
	if multiplayer.is_server() and steam_server:
		_check_timeouts()


static func is_server_launch() -> bool:
	return OS.has_feature("dedicated_server") or "--server" in OS.get_cmdline_user_args()


# ---------------------------------------------------------------- 服务器

func _start_server() -> void:
	steam_server = Engine.get_singleton("SteamServer")
	if steam_server == null:
		_fail("GodotSteam Server 附加组件未加载")
		return

	# Edgegap 会将内部端口映射到随机外部端口。Steam 通告的游戏端口就是我们
	# 在此处传入的端口，因此应使用玩家实际连接的外部端口。
	var advertised_port := int(_env("ARBITRIUM_PORT_GAMEPORT_EXTERNAL", str(GAME_PORT)))
	var init: Dictionary = steam_server.serverInitEx("0.0.0.0", advertised_port, QUERY_PORT,
			SERVER_MODE_AUTHENTICATION, SERVER_VERSION)
	if init.get("status", -1) != 0:
		_fail("serverInitEx failed: %s" % init)
		return
	print("STEAM init ok game_port=%d query_port=%d" % [advertised_port, QUERY_PORT])

	steam_server.server_connected.connect(_on_steam_connected)
	steam_server.server_connect_failure.connect(_on_steam_connect_failure)
	steam_server.server_disconnected.connect(_on_steam_disconnected)
	steam_server.validate_auth_ticket_response.connect(_on_validate_auth_ticket_response)

	# 这些必须在登录前设置。
	steam_server.setModDir("spacewar")        # 你的游戏在 Steam 上的文件夹名称。
	steam_server.setProduct(str(STEAM_APP_ID))
	steam_server.setGameDescription("GodotSteam Server on Edgegap")
	steam_server.setDedicatedServer(true)
	steam_server.setMaxPlayerCount(MAX_PLAYERS)
	steam_server.setServerName("Edgegap %s" % _env("ARBITRIUM_REQUEST_ID", "local"))
	steam_server.setMapName("arena")

	var gslt := _env("STEAM_GSLT", "")
	if gslt.is_empty():
		steam_server.logOnAnonymous()
	else:
		steam_server.logOn(gslt)  # 持久 Steam ID，需要游戏服务器登录令牌。
	steam_server.setAdvertiseServerActive(true)

	var peer := ENetMultiplayerPeer.new()
	var err := peer.create_server(GAME_PORT, MAX_PLAYERS)
	if err != OK:
		_fail("ENet create_server failed: %s" % error_string(err))
		return
	multiplayer.multiplayer_peer = peer
	multiplayer.peer_connected.connect(_on_peer_connected)
	multiplayer.peer_disconnected.connect(_on_peer_disconnected)
	print("SERVER listening udp=%d request_id=%s" % [GAME_PORT, _env("ARBITRIUM_REQUEST_ID", "-")])
	get_tree().create_timer(NO_PLAYER_TIMEOUT_SEC).timeout.connect(func():
		if not had_players:
			_stop_server("nobody joined"))


func _on_steam_connected() -> void:
	server_steam_id = steam_server.getSteamID()
	var ip: Dictionary = steam_server.getPublicIP()
	print("STEAM logged on steam_id=%d public_ip=%s secure=%s" % [server_steam_id,
			_ip_to_string(ip.get("ipv4", 0)), steam_server.isServerSecure()])


func _on_steam_connect_failure(result: int, retrying: bool) -> void:
	print("STEAM connect failure result=%d retrying=%s" % [result, retrying])


func _on_steam_disconnected(result: int) -> void:
	print("STEAM disconnected result=%d" % result)


func _on_peer_connected(peer_id: int) -> void:
	pending[peer_id] = {"steam_id": 0, "deadline": Time.get_ticks_msec() / 1000.0 + AUTH_TIMEOUT_SEC}
	print("PEER connected peer=%d, waiting for Steam ticket" % peer_id)
	# 告知客户端我们的身份：客户端会将其票据绑定到此服务器的 Steam ID。
	server_hello.rpc_id(peer_id, server_steam_id)


func _on_peer_disconnected(peer_id: int) -> void:
	pending.erase(peer_id)
	if players.has(peer_id):
		steam_server.endAuthSession(players[peer_id])
		players.erase(peer_id)
	print("PEER left peer=%d players=%d" % [peer_id, players.size()])
	if had_players and players.is_empty() and pending.is_empty():
		_stop_server("everyone left")


@rpc("any_peer", "reliable")
func submit_ticket(ticket: PackedByteArray, steam_id: int) -> void:
	if not multiplayer.is_server():
		return
	var peer_id := multiplayer.get_remote_sender_id()
	if not pending.has(peer_id):
		return
	var result: int = steam_server.beginAuthSession(ticket, ticket.size(), steam_id)
	print("AUTH begin peer=%d steam_id=%d result=%d" % [peer_id, steam_id, result])
	if result != BEGIN_AUTH_RESULT_OK:
		_kick(peer_id, "ticket rejected (%d)" % result)
		return
	pending[peer_id]["steam_id"] = steam_id
	# Steam 稍后会通过 validate_auth_ticket_response 返回验证结果。


func _on_validate_auth_ticket_response(steam_id: int, response: int, owner_id: int) -> void:
	for peer_id in pending.keys():
		if pending[peer_id]["steam_id"] != steam_id:
			continue
		pending.erase(peer_id)
		if response != AUTH_SESSION_RESPONSE_OK:
			steam_server.endAuthSession(steam_id)
			_kick(peer_id, "Steam auth failed (%d)" % response)
			return
		players[peer_id] = steam_id
		had_players = true
		print("AUTH ok peer=%d steam_id=%d owner=%d players=%d" % [peer_id, steam_id, owner_id, players.size()])
		welcome.rpc_id(peer_id, players.size())
		return
	# 对已在游戏中的玩家收到响应，意味着 Steam 结束了其会话（封禁、在其他地方登录）。
	for peer_id in players.keys():
		if players[peer_id] == steam_id and response != AUTH_SESSION_RESPONSE_OK:
			_kick(peer_id, "Steam session ended (%d)" % response)


func _check_timeouts() -> void:
	var now := Time.get_ticks_msec() / 1000.0
	for peer_id in pending.keys():
		if now > pending[peer_id]["deadline"]:
			_kick(peer_id, "no Steam ticket")


func _kick(peer_id: int, reason: String) -> void:
	print("KICK peer=%d reason=%s" % [peer_id, reason])
	pending.erase(peer_id)
	multiplayer.multiplayer_peer.disconnect_peer(peer_id)


func _stop_server(reason: String) -> void:
	if stopping:
		return
	stopping = true
	print("SERVER stopping reason=%s" % reason)
	steam_server.setAdvertiseServerActive(false)
	steam_server.logOff()
	steam_server.serverShutdown()
	var url := _env("ARBITRIUM_DELETE_URL", "")
	if url.is_empty():
		get_tree().quit()
		return
	# Edgegap：删除我们自己的部署，以停止计费。
	var http := HTTPRequest.new()
	add_child(http)
	http.request_completed.connect(func(result, code, _h, _b):
		print("SERVER self_stop result=%d http=%d" % [result, code])
		get_tree().quit())
	http.request(url, ["authorization: " + _env("ARBITRIUM_DELETE_TOKEN", "")], HTTPClient.METHOD_DELETE)


# ---------------------------------------------------------------- 客户端

func _start_client() -> void:
	steam = Engine.get_singleton("Steam")
	if steam == null:
		_fail("GodotSteam 插件未加载")
		return
	var init: Dictionary = steam.steamInitEx(STEAM_APP_ID)
	if init.get("status", -1) != 0:
		_fail("Steam 初始化失败，Steam 是否正在运行且已登录？%s" % init)
		return
	print("CLIENT steam_id=%d name=%s" % [steam.getSteamID(), steam.getPersonaName()])

	var address := _arg("connect", "127.0.0.1:%d" % GAME_PORT)
	var host := address.get_slice(":", 0)
	var port := int(address.get_slice(":", 1))
	var peer := ENetMultiplayerPeer.new()
	var err := peer.create_client(host, port)
	if err != OK:
		_fail("ENet create_client 失败：%s" % error_string(err))
		return
	multiplayer.multiplayer_peer = peer
	multiplayer.connection_failed.connect(func(): _fail("无法连接到 %s" % address))
	multiplayer.server_disconnected.connect(func(): _status("已与服务器断开连接"))
	_status("正在连接到 %s..." % address)


@rpc("authority", "reliable")
func server_hello(steam_id_of_server: int) -> void:
	# 绑定到此服务器 Steam ID 的票证无法在其他服务器上重放。
	var ticket: Dictionary = steam.getAuthSessionTicket(steam_id_of_server)
	var bytes: PackedByteArray = ticket["buffer"].slice(0, ticket["size"])
	# Steam 需要一点时间来注册票证：等 Steam 确认后再发送。
	while true:
		var response: Array = await steam.get_auth_session_ticket_response
		if response[0] == ticket["id"]:
			if response[1] != 1:  # Steam 结果 OK
				_fail("Steam 无法签发票证（结果 %d）" % response[1])
				return
			break
	_status("已连接，正在向服务器 %d 发送 Steam 票证（%d 字节）" % [bytes.size(), steam_id_of_server])
	submit_ticket.rpc_id(1, bytes, steam.getSteamID())


@rpc("authority", "reliable")
func welcome(player_count: int) -> void:
	_status("已通过 Steam 认证，服务器上有 %d 名玩家" % player_count)
	if "--quit-after-auth" in OS.get_cmdline_user_args():
		await get_tree().create_timer(2.0).timeout
		get_tree().quit()


# ---------------------------------------------------------------- 辅助函数

func _status(text: String) -> void:
	print("CLIENT " + text)
	var label := get_tree().current_scene as Label
	if label:
		label.text = text


func _fail(text: String) -> void:
	push_error(text)
	print("ERROR " + text)
	if is_server_launch():
		get_tree().quit(1)
	else:
		_status(text)


static func _env(key: String, default: String) -> String:
	var value := OS.get_environment(key)
	return default if value.is_empty() else value


static func _arg(key: String, default: String) -> String:
	for a in OS.get_cmdline_user_args():
		if a.begins_with("--%s=" % key):
			return a.get_slice("=", 1)
	return default


static func _ip_to_string(ip: int) -> String:
	return "%d.%d.%d.%d" % [(ip >> 24) & 255, (ip >> 16) & 255, (ip >> 8) & 255, ip & 255]
```

{% endcode %}

☑️ 将其注册为名为 `Session`的自动加载项，并启用 `flush_stdout_on_print` ，这样服务器的 `print()` 输出就会立即显示在容器日志中。在 `project.godot`:

{% code title="project.godot" expandable="true" %}

```ini
[application]

run/flush_stdout_on_print=true

[autoload]

Session="*res://net/session.gd"
```

{% endcode %}

☑️ 准备就绪后，将占位符替换为你自己的值： `STEAM_APP_ID`, `setModDir()`, `setGameDescription()` 和 `SERVER_VERSION`.

☑️ 在编辑器中测试：将 `--server` 作为用户参数运行项目以启动服务器（Project Settings / Editor / Run / Main Run Args： `-- --server`），然后使用 `-- --connect=127.0.0.1:7777` 启动第二个实例作为客户端。服务器验证完票据后，客户端会显示 `AUTHENTICATED by Steam` 。

✅ 现在可以继续下一步了。

## 🐧 3. 导出无头 Linux 服务器

Edgegap 运行 Linux 容器，因此服务器需在 Godot 中导出为 **Linux** 平台，并启用 **Dedicated Server** 模式：以无头方式启动（无窗口、无 GPU），并在导出时移除纹理和音频。

☑️ 添加名为 `Edgegap Linux Server` 的导出预设（Project / Export / Add / Linux），并设置：

* **导出模式** （Resources 选项卡）：导出为专用服务器。
* **要排除的文件/文件夹过滤器**: `addons/godotsteam/*`，这样服务器导出包中就只包含 GodotSteam Server。
* **导出路径**: `build/edgegap-linux-server.x86_64`.
* **嵌入 PCK**：关闭。

或者将以下内容粘贴到 `export_presets.cfg` （如果已有预设，请重新编号 `[preset.0]` ）：

{% code title="export\_presets.cfg" expandable="true" %}

```ini
[preset.0]

name="Edgegap Linux Server"
platform="Linux"
runnable=false
dedicated_server=true
custom_features=""
export_filter="customized"
customized_files={
"res://": "strip"
}
include_filter=""
exclude_filter="addons/godotsteam/*"
export_path="build/edgegap-linux-server.x86_64"
encryption_include_filters=""
encryption_exclude_filters=""
encrypt_pck=false
encrypt_directory=false
script_export_mode=2

[preset.0.options]

custom_template/debug=""
custom_template/release=""
debug/export_console_wrapper=0
binary_format/embed_pck=false
texture_format/s3tc_bptc=true
texture_format/etc2_astc=false
binary_format/architecture="x86_64"
```

{% endcode %}

☑️ 对于客户端预设（Windows、macOS、Linux 桌面版），请改为排除服务器插件： `addons/godotsteam_server/*`.

☑️ 从“项目 / 导出”或通过命令行导出服务器：

```bash
mkdir -p build
godot --headless --path . --export-release "Edgegap Linux Server" build/edgegap-linux-server.x86_64
```

{% hint style="info" %}
Godot 不会创建导出文件夹：请确保 `build/` 在导出前已存在。
{% endhint %}

☑️ 检查 `build` 文件夹。Godot 会将 GDExtension 和 Steamworks API 库复制到二进制文件旁边，服务器需要以下全部四个文件：

```
build/
├─ edgegap-linux-server.x86_64
├─ edgegap-linux-server.pck
├─ libgodotsteam_server.linux.template_release.x86_64.so
└─ libsteam_api.so
```

{% hint style="info" %}
预设名称和路径与 [Edgegap Godot 插件](https://github.com/edgegap/buildtool-godot-plugin)相同，因此它的 **导出服务器** 按钮会重复使用此预设（绝不会更改现有预设）。它的 **容器化** 步骤需要用到下一步中的 Dockerfile：该插件的默认 Dockerfile 只会复制二进制文件和 `.pck`，不会复制 GodotSteam Server 所需的 `.so` 文件。
{% endhint %}

✅ 现在可以继续下一步了。

## 🐋 4. 将服务器容器化

Steam 游戏服务器还需要一个未包含在导出内容中的文件： **`steamclient.so`**，这是 Steam 客户端库，Steamworks API 会加载它以连接 Steam。Valve 随 [SteamCMD](https://developer.valvesoftware.com/wiki/SteamCMD)一起分发该库，而 Steamworks API 会在 `~/.steam/sdk64/`中查找它。下面的 Dockerfile 会在第一个阶段下载 SteamCMD，只将 `steamclient.so` 复制到最终镜像中，并在 `tini`下以非 root 用户运行服务器，因此停止部署后服务器会立即结束。

☑️ 将以下内容保存为项目根目录下的 `Dockerfile` ：

{% code title="Dockerfile" lineNumbers="true" expandable="true" %}

```docker
# 阶段 1：SteamCMD 下载 steamclient.so。游戏服务器需要它来登录
# Steam，而它不属于 GodotSteam 随附的 Steamworks 可再分发文件。
FROM ubuntu:24.04 AS steamcmd
RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates curl lib32gcc-s1 \
 && rm -rf /var/lib/apt/lists/*
WORKDIR /steamcmd
RUN curl -fsSL https://steamcdn-a.akamaihd.net/client/installer/steamcmd_linux.tar.gz | tar -xz \
 && ./steamcmd.sh +quit \
 && test -f linux64/steamclient.so

# 阶段 2：Godot 专用服务器。
FROM ubuntu:24.04
# 与 Edgegap Godot 插件的约定相同：相对于项目的路径，不带扩展名。
ARG SERVER_BUILD_PATH=build/edgegap-linux-server

RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates tini \
 && rm -rf /var/lib/apt/lists/* \
 && useradd --create-home --uid 1001 game

# steam_api 会在 ~/.steam/sdk64/ 中查找 64 位 Steam 客户端库。
COPY --from=steamcmd --chown=game:game /steamcmd/linux64/steamclient.so /home/game/.steam/sdk64/steamclient.so

WORKDIR /home/game/server
COPY --chown=game:game ${SERVER_BUILD_PATH}.x86_64 ./server.x86_64
COPY --chown=game:game ${SERVER_BUILD_PATH}.pck ./server.pck
# 与二进制文件一同导出的 GDExtension 和 Steamworks API 库。
COPY --chown=game:game build/libgodotsteam_server.linux.template_*.x86_64.so build/libsteam_api.so ./
RUN chmod +x server.x86_64

# 你的 Steam App ID（480 = Spacewar，Valve 的测试应用）。效果与 steam_appid.txt 相同。
ENV SteamAppId=480

USER game
# tini 会转发 SIGTERM，因此停止部署后，服务器会立即结束。
ENTRYPOINT ["/usr/bin/tini", "--", "./server.x86_64"]
```

{% endcode %}

☑️ 在旁边添加 `.dockerignore` 文件，避免 Docker 将 Godot 的缓存发送到构建上下文中：

{% code title=".dockerignore" %}

```
.godot/
.git/
```

{% endcode %}

{% hint style="info" %}
这个 `SteamAppId` 环境变量会告知 Steamworks API 此服务器所属的游戏。你可以在 Edgegap 上按应用版本覆盖此值，而无需重新构建镜像。
{% endhint %}

☑️ 构建镜像。使用时间戳作为标签，切勿使用 `latest`:

```bash
docker build --platform linux/amd64 -t my-game-server:20261109-1924 .
```

☑️ 上传前先在本地测试：

```bash
docker run --name my-game-server -p 7777:7777/udp -p 27015:27015/udp my-game-server:20261109-1924
```

日志中应显示服务器已登录 Steam：

```
[S_API] SteamAPI_Init(): Loaded '/home/game/.steam/sdk64/steamclient.so' OK.  (First tried local 'steamclient.so')
Setting breakpad minidump AppID = 480
STEAM init ok game_port=7777 query_port=27015
SERVER listening udp=7777 request_id=-
STEAM logged on steam_id=90297081554892826 public_ip=203.0.113.10 secure=false
```

{% hint style="info" %}
在 `dlopen failed trying to load: steamclient.so` 之前出现的 `Loaded '/home/game/.steam/sdk64/steamclient.so' OK` 这些日志行是正常的：Steamworks API 会先尝试从工作目录加载。
{% endhint %}

☑️ 在你的机器上运行 Steam，然后从项目启动客户端并连接到容器：

```bash
godot --path . -- --connect=127.0.0.1:7777
```

客户端会显示 `AUTHENTICATED by Steam, 1 player(s) on the server`，服务器日志则会显示 `AUTH ok peer=... steam_id=...`。关闭客户端后，服务器日志会显示 `SERVER stopping reason=everyone left` ，随后退出（本地没有部署可供删除）。

✅ 现在可以继续下一步了。

## ☁️ 5. 上传到 Edgegap

☑️ 将镜像推送到 [Edgegap 的容器注册表](https://docs.edgegap.com/zh/learn/advanced-features/edgegap-container-registry.md)。在控制面板的 [容器注册表页面](https://app.edgegap.com/registry-management/repositories/list) 找到你的项目名称、用户名和令牌：

```bash
echo "<registry-token>" | docker login registry.edgegap.com -u "<registry-username>" --password-stdin
docker tag my-game-server:20261109-1924 registry.edgegap.com/<project>/my-game-server:20261109-1924
docker push registry.edgegap.com/<project>/my-game-server:20261109-1924
```

☑️ [创建一个应用](https://app.edgegap.com/application-management/applications/list)，然后为其创建一个 [新版本](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md) ，使用你的镜像和标签，并配置以下端口：

| 端口名称        | 端口    | 协议  | 用途                                                                                     |
| ----------- | ----- | --- | -------------------------------------------------------------------------------------- |
| `gameport`  | 7777  | UDP | ENet 游戏流量。玩家在此连接。                                                                      |
| `queryport` | 27015 | UDP | Steam 服务器查询（A2S）。可选，参见 [#steam-server-browser](#steam-server-browser "mention")。关闭其验证。 |

☑️ 可选：添加版本环境变量：

* `SteamAppId` 用于覆盖镜像中预设的 App ID。
* `STEAM_GSLT` 用于设置游戏服务器登录令牌。该名称表明它是一个密钥。

{% hint style="info" %}
对于此脚本，0.5 个 vCPU 和 1 GB 内存绰绰有余。请根据部署的容器指标，为你自己的游戏配置合适的资源。
{% endhint %}

✅ 现在可以继续下一步了。

## 🚀 6. 部署并连接客户端

☑️ 从 [控制面板](https://app.edgegap.com/deployment-management/deployments/list)启动新版本的部署，并选择靠近你的位置。部署状态变为 **就绪**后，容器日志会显示服务器已连接到 Steam：

```
STEAM init ok game_port=32137 query_port=27015
SERVER listening udp=7777 request_id=101ce07c06f7
STEAM logged on steam_id=90297081535503378 public_ip=192.46.222.253 secure=false
```

`game_port` 是 **外部** 端口，Edgegap 将其映射到 7777。脚本会从注入的 `ARBITRIUM_PORT_GAMEPORT_EXTERNAL` 变量中读取该端口并传给 Steam，因此 Steam 公布的地址是玩家实际能够访问的地址。

☑️ 将客户端连接到部署的主机，以及 `gameport`:

```bash
godot --path . -- --connect=101ce07c06f7.pr.edgegap.net:32137
```

客户端日志：

```
CLIENT Connecting to 101ce07c06f7.pr.edgegap.net:32137...
CLIENT Connected, sending Steam ticket (234 bytes) to server 90297081535503378
CLIENT AUTHENTICATED by Steam, 1 player(s) on the server
```

服务器日志：

```
PEER connected peer=1943168941, waiting for Steam ticket
AUTH begin peer=1943168941 steam_id=76561198040851267 result=0
AUTH ok peer=1943168941 steam_id=76561198040851267 owner=76561198040851267 players=1
```

☑️ 关闭客户端。服务器会退出 Steam 并通过 `ARBITRIUM_DELETE_URL`删除自己的部署，因此部署会自动结束。如果客户端未正常断开就消失（例如崩溃或连接中断），ENet 会在超时后将其移除（最长约 30 秒）。

{% hint style="warning" %}
**对于在线游戏，手动启动部署并粘贴地址是行不通的。** 让 [Edgegap Matchmaker](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md) 启动服务器并将地址发送给每位匹配成功的客户端，同时在服务器端检查 Steam 身份验证票据。
{% endhint %}

🙌 恭喜！你的 GodotSteam 专用服务器已在 Edgegap 上运行！

## 👉 后续步骤

### Steam 服务器浏览器

Steam 的服务器浏览器（`requestInternetServerList()` （在 GodotSteam 中调用），或 Steam 客户端中的服务器列表） **并不适合 Edgegap 部署**。我们进行了测试：Steam 列出的服务器连接地址正确（公网 IP 和外部游戏端口），但记录的查询端口却是内部 `27015`端口。Edgegap 会将该端口映射到一个随机外部端口，因此 Steam 对服务器的 ping 请求会超时，服务器也会显示为无响应。向部署的外部 `queryport` 发送 A2S 查询则会收到响应。

你可以通过以下方式之一让玩家进入服务器：

* [Edgegap Matchmaker](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md)：玩家点击“查找比赛”，Edgegap 会在玩家附近启动服务器，并将其地址发送给每位客户端。
* Steam 大厅：服务器就绪后，由队伍队长通过 `Steam.setLobbyGameServer()` 或大厅数据存储服务器地址，成员读取该地址后即可加入。
* [Edgegap Server Browser](https://docs.edgegap.com/zh/learn/fu-wu-qi-liu-lan-qi.md) ：适用于持久运行的服务器，玩家可以从列表中选择。

### Steam 账户和游戏服务器登录令牌

`logOnAnonymous()` 会在服务器每次启动时为其分配一个新的 Steam ID。这通常适用于只运行一场比赛的比赛服务器，也是身份验证票据检查所需的全部内容。

持久服务器身份（例如，方便玩家将服务器加入收藏）需要 [游戏服务器登录令牌（GSLT）](https://steamcommunity.com/dev/managegameservers) 以及 `logOn(token)`。每个令牌同一时间只能由一台运行中的服务器使用，因此适合少数长期运行的服务器，而不适合每场比赛都部署一个服务器。请将其存储为 `STEAM_GSLT` 版本变量，切勿将其放入镜像或代码仓库。我们的测试仅使用了匿名登录。

### 身份验证模式

`serverInitEx()` 接受服务器模式参数：

* `SERVER_MODE_NO_AUTHENTICATION` （1）：不进行 Steam 检查。
* `SERVER_MODE_AUTHENTICATION` （2）：Steam 会验证身份验证票据。本指南使用此模式。
* `SERVER_MODE_AUTHENTICATION_AND_SECURE` （3）：对于启用了 VAC 的应用，还会启用 VAC。 `isServerSecure()` 在 Steam 将服务器标记为安全后会返回 `true` 。

### 故障排除

<details>

<summary><code>Failed to retrieve non-existent singleton 'SteamServer'</code> 或 <code>GDExtension dynamic library not found</code></summary>

服务器导出文件缺失 `libgodotsteam_server.linux.template_*.x86_64.so`。检查导出是否将其写入 `build/`，并确认 Dockerfile 将它复制到了二进制文件旁边。Edgegap Godot 插件的默认 Dockerfile 不会这样做：请使用本指南中的 Dockerfile。

</details>

<details>

<summary><code>serverInitEx failed</code> 在服务器上</summary>

* `steamclient.so` 缺失于 `~/.steam/sdk64/` 中（该目录属于运行服务器的用户）。保留 SteamCMD 阶段和 `COPY --from=steamcmd` 这一行，以及 `USER game` 所指向的主目录。
* 未设置 App ID：设置 `SteamAppId` （或在二进制文件旁添加一个 `steam_appid.txt` 文件，其中写入该 ID）。

</details>

<details>

<summary><code>Steam init failed, is Steam running and logged in?</code> 在客户端上</summary>

玩家的计算机上必须运行 Steam 客户端并登录，而且该账户必须拥有此 App ID（所有账户都可以使用 480）。通过 Steam 启动时，App ID 由 Steam 本身提供。

</details>

<details>

<summary>客户端被踢出，并显示 <code>Steam auth failed</code> 或 <code>ticket rejected</code></summary>

* `beginAuthSession` 结果 `1`：票据无效。仅发送票据缓冲区的前 `size` 个字节（`buffer.slice(0, size)`），不要发送整个缓冲区。
* `beginAuthSession` 结果 `2`：该 Steam ID 的票据已在使用中，例如有两个客户端登录了同一个 Steam 账户。
* `validate_auth_ticket_response` 响应 `2`：用户不拥有此 App ID。请确认客户端和服务器使用的是同一个 App ID。

</details>

<details>

<summary>客户端被踢出，并显示 <code>no Steam ticket</code></summary>

客户端未能在 `AUTH_TIMEOUT_SEC`内发送票据。检查客户端输出中是否有 Steam 错误，并确认客户端在发送票据前等待 `get_auth_session_ticket_response` 。

</details>

<details>

<summary>部署日志为空</summary>

在项目设置中启用 `application/run/flush_stdout_on_print` 。如果未启用， `print()` 无头服务器的输出会一直缓冲。

</details>

<details>

<summary>服务器已在 Steam 上列出，但玩家无法在服务器浏览器中找到它</summary>

在 Edgegap 上这是预期行为，请参阅 [#steam-server-browser](#steam-server-browser "mention").

</details>

{% hint style="info" %}
如果您需要帮助， [请通过 Discord 联系我们](https://discord.gg/MmJf8fWjnt)。有关在线游戏支持，请参阅我们的 [工单系统](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}
