本页尚未翻译,当前显示英文版本。
使用 CLI 部署
你发布的是源码,而不是容器。 CLI 把代码连同 platform.json 打包上传,由平台负责构建和运行,所以除了运行在 machine pool 上的 game server 之外,你的机器上不需要 Docker。这里的所有操作都在已登录的会话中执行,见命令行工具。
快速开始
从零到部署好一个 Function:
playserv init --solution Acme --function hello-fn --kind cloud_function
cd Acme
playserv publish --dry-run
playserv publish --yes
playserv functions logs hello-fn --tail 50
init 不需要登录,也不会在平台上创建任何内容;Function 在首次部署时才会出现。publish 会找到 solution 中的每个 platform.json,并以 functions deploy 部署单个 Function 的方式逐一部署。
语言
Function 可以用 C#、JavaScript、Python 或 Go 编写;game server 可以用 C# 或 JavaScript 编写。
| 类型 | C#(csharp) | JavaScript(node) | Python(python) | Go(go) |
|---|---|---|---|---|
cloud_function | ✓ | ✓ | ✓ | ✓ |
game_server | ✓ | ✓ | — | — |
省略 --language 时,CLI 会自动检测:有 .csproj 是 C#,有 package.json 是 JavaScript,有 go.mod 是 Go,有 requirements.txt 或 main.py 是 Python;单个文件按扩展名判断。找不到任何标志时默认为 C#。init 只生成 C# 项目,其他语言的项目需要手动编写。
C# Function 实现 PlayServ SDK 中的 IPlatformFunction。其他语言的 Function 是一个普通的 HTTP 服务器,监听 $PORT 并以 JSON 应答。下面都是完整、可直接部署的 Function:
using PlayServ.Sdk;
namespace HelloFunc;
public class Hello : IPlatformFunction
{
public Task<FunctionResponse> HandleAsync(FunctionRequest req, CancellationToken ct = default)
=> Task.FromResult(FunctionResponse.Json(new { message = "hello from playserv" }));
}const http = require('http');
const port = process.env.PORT || 8080;
http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ message: 'hello world' }));
}).listen(port);也支持 TypeScript:把 --src 指向一个包含 package.json、tsconfig.json 和 src/index.ts 的目录。平台在构建时只转译、不做类型检查,所以请在你自己的 CI 中运行 tsc。
import json, os
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
class Handler(BaseHTTPRequestHandler):
def _respond(self):
data = json.dumps({"message": "hello world"}).encode()
self.send_response(200)
self.send_header("Content-Type", "application/json")
self.end_headers()
self.wfile.write(data)
do_GET = do_POST = _respond
ThreadingHTTPServer(("", int(os.environ.get("PORT", "8080"))), Handler).serve_forever()package main
import (
"encoding/json"
"net/http"
"os"
)
func main() {
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]string{"message": "hello world"})
})
http.ListenAndServe(":"+port, nil)
}manifest:platform.json
每个 Function 目录都带有一个 platform.json: 它描述 Function 的身份和 bindings,随代码提交到 git。publish 也靠它来发现 Function。
{
"name": "hello-fn",
"kind": "cloud_function",
"language": "csharp",
"auth": "player",
"execute": { "client": true, "server": true, "backend": false },
"env": { "GREETING": "hi" },
"secrets": ["STRIPE_API_KEY"],
"triggers": [ { "type": "scheduled", "cron": "0 5 * * *" } ]
}
| 字段 | 含义 |
|---|---|
name | 必填。即 slug:小写字母、数字和连字符,3–50 个字符,以字母开头,不能以连字符结尾,也不能有连续的连字符。 |
kind | 必填。cloud_function 或 game_server。 |
language | 必填。csharp、node、python 或 go。 |
entry | 处理器类型,例如 MyNamespace.Server。C# game server 必填,生成的项目中已写好。 |
description | 可选的自由文本。 |
sdk_version | 项目文件没有固定版本时,构建所用的 SDK 版本。如果 .csproj 固定了版本,以它为准。 |
auth | player(默认):使用客户端 key 调用的游戏必须有已登录的 Player,否则返回 401 player_auth_required。none:不需要 Player。使用服务端 key 的调用不受影响。每次调用都需要 API key。 |
execute | 谁可以调用这个 Function:client、server、backend,每项为 true 或 false。被拒绝的调用方会收到 403 function_execute_forbidden。未列出的调用方默认允许。 |
env | 普通环境变量。以 PLAYSERV_ 或 PLATFORM_ 开头的名称为保留名称。 |
secrets | Function 需要的 secret 名称;值通过 playserv secrets set 设置。 |
scaling | policy、min_replicas、max_replicas、desired_replicas:与 functions scale 设置的配置相同。 |
triggers | 额外的触发器,例如 cron 定时任务。 |
文件中可以使用 // 注释和尾随逗号。校验很严格,并且在所有地方都一致:格式错误的文件以 invalid_bundle 失败,违反规则以 invalid_manifest 失败,--dry-run 会在不上传的情况下执行本地检查。
部署单个 Function
playserv functions deploy --slug <slug> --kind cloud_function|game_server [--src <dir>] [--language <lang>] \
[--tag <tag>] [--poll-timeout <s>] [--dry-run | --detach]
| 选项 | 默认值 | 含义 |
|---|---|---|
--slug | 必填 | Function 在平台上的名称。 |
--kind | 必填 | cloud_function 或 game_server。 |
--src | . | 一个目录,或单个源文件。 |
--language | 自动检测 | 见语言。 |
--tag | — | 以具名版本部署,见版本标签。 |
--poll-timeout | 1200 s | CLI 等待上传和构建的时长。CLI 停止等待后,构建仍会在平台上继续。 |
--dry-run | — | 校验所有能在本地检查的内容,并输出将要上传的内容。不会上传任何东西。 |
--detach | — | 上传被接受后立即返回,并输出部署 ID。不能与 --dry-run 同时使用。 |
部署包包含 --src 下的全部内容,但不包括 bin/、obj/、.git/、.vs/、.idea/、node_modules/,以及所有名称以 .env 开头的文件。从 --src 之外引用的共享项目会被自动打包进来。
| 结果 | 退出码 | 含义 |
|---|---|---|
| deployed | 0 | 已上线。CLI 输出 Function 的地址。 |
| detached | 0 | --detach:上传已被接受。之后用 functions deploys get <id> 查看。 |
| upload refused | 2 | 平台拒绝了部署包。 |
| build failed | 3 | 消息中说明了原因;其余信息在 functions logs 中。 |
| timeout | 4 | CLI 停止等待;构建可能仍会完成。 |
| session expired | 5 | 等待期间会话过期;会输出部署 ID。 |
发布整个 solution
playserv publish [--src <path>] [--solution-path <file>] [--only <slug>]... [--tag <tag>] \
[--parallel N] [--poll-timeout <s>] [--dry-run] [--yes]
publish 会找到 solution 下每个带 platform.json 的目录,与 Environment 中已部署的内容进行比较,输出计划并请求确认。随后逐一部署每个 Function,最多同时部署 --parallel 个(默认 1)。在 CI 中请传入 --yes。只要有任何 Function 失败,命令就以 1 退出;可以用 --only <slug> 只重试失败的那个。
版本标签
在 functions deploy 或 publish 上使用 --tag <tag>,会在不带标签的最新版本旁边再部署一个版本。普通流量仍发往最新版本;调用方通过 X-Playserv-Function-Version: <tag> 请求头选择带标签的版本。未知标签返回 404 function_version_not_found,不会回退到最新版本。重新部署同一个标签会让它指向新版本。
标签由 3–22 个小写字母、数字和连字符组成,以字母开头,以字母或数字结尾。典型用法是:用 --tag ver2-canary 发布,让测试客户端指向它,确认稳定后再以不带标签的方式部署同 样的代码。
调用 Function
在 Unity 游戏中,用 PlayServCode.CallAsync 调用 Function,见 Cloud Functions & RPC。下面的调用方式适用于你自己的工具和服务器。
已部署的 Function 在平台的 /fn/<slug> 上应答,调用时使用运行时凭据,而不是 CLI 会话。从服务器调用时,使用服务端 key:
curl -X POST <platform-url>/fn/<slug> \
-H "Authorization: Bearer sk_..." \
-H "Content-Type: application/json" \
-d '{"n":5}'
代表 Player 调用时,使用客户端 key 加上 Player 的会话 token:
curl -X POST <platform-url>/fn/<slug> \
-H "X-PlayServ-Client: pk_..." \
-H "Authorization: Bearer <player-jwt>" \
-H "Content-Type: application/json" \
-d '{"n":5}'
Function 接受哪种形式,取决于它的 auth 和 execute 设置。
Game server
game server 的发布方式有三种,与它的运行方式一一对应(见 Servers)。
| 运行位置 | 发布方式 |
|---|---|
| 由 PlayServ 在 Cloud Run 上运行 | 和其他 Function 一样,使用 playserv functions deploy --kind game_server 或 publish。C# 或 JavaScript。 |
| PlayServ 的 machine pool | playserv image push --slug <slug> --tag <version> --roll 构建 linux/amd64 镜像,推送到项目的镜像仓库,并让 pool 切换到该镜像。需要带 buildx 的 Docker。C# game server 不需要 Dockerfile:CLI 会自动生成。 |
| 你自己的机器 | playserv functions declare <slug> --kind game_server 只注册、不构建,这样它的 Room 可以立即注册。--hosting-mode multi-room(默认)或 process-per-room。 |
先创建 pool,并且不要让运行在 pool 上的 server 参与 publish
image push --roll 不会创建 machine pool:如果该 game server 在当前 Environment 中还没有 pool,镜像会被推送,但命令以 pool_not_found 失败。请在 Servers 中该 game server 的 Hosting 标签页上创建 pool。另外,用 --only 把运行在 pool 上的 game server 排除在 publish 之外:一次 Cloud Run 构建会把它从 pool 上撤下来。
Room 设置也可以在终端中配置,与 Servers → Room settings 中的设置相同。rooms config set 会替换整个配置,所以除了 --idle-timeout 之外的所有选项都必须提供:
| 选项 | 范围 | 含义 |
|---|---|---|
--capacity | 1–1000 | 每个 Room 的 Player 数。 |
--reservation-ttl | 1–60 s | 匹配预留为席位保留的时长。 |
--lifetime | ≥ 0 s | Room 的最长存在时间;0 表示不限,此时必须设置 --idle-timeout。 |
--idle-timeout | ≥ 1 s | Room 在没有 Player 的状态下持续这么久后关闭。省略即取消该设置。 |
--max-rooms | 1–10000 | 这个 game server 可同时运行的 Room 数。 |
rooms config get 显示当前设置,rooms config delete 删除设置;只要还有 Room 处于注册状态,删除就会被拒绝。
下一步
- 命令行工具 —— 登录、全部命令、退出码和错误
- Functions —— 在 Backoffice 中查看已部署的 Function、日志和设置
- Servers —— fleet、machine pool 和 Room 设置
更新于 2026年10月14日