跳到主要内容
工程

本页尚未翻译,当前显示英文版本。

使用 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 固定了版本,以它为准。
authplayer(默认):使用客户端 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_ 开头的名称为保留名称。
secretsFunction 需要的 secret 名称;值通过 playserv secrets set 设置。
scalingpolicy、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-timeout1200 sCLI 等待上传和构建的时长。CLI 停止等待后,构建仍会在平台上继续。
--dry-run—校验所有能在本地检查的内容,并输出将要上传的内容。不会上传任何东西。
--detach—上传被接受后立即返回,并输出部署 ID。不能与 --dry-run 同时使用。

部署包包含 --src 下的全部内容,但不包括 bin/、obj/、.git/、.vs/、.idea/、node_modules/,以及所有名称以 .env 开头的文件。从 --src 之外引用的共享项目会被自动打包进来。

结果退出码含义
deployed0已上线。CLI 输出 Function 的地址。
detached0--detach:上传已被接受。之后用 functions deploys get <id> 查看。
upload refused2平台拒绝了部署包。
build failed3消息中说明了原因;其余信息在 functions logs 中。
timeout4CLI 停止等待;构建可能仍会完成。
session expired5等待期间会话过期;会输出部署 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 poolplayserv 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 之外的所有选项都必须提供:

选项范围含义
--capacity1–1000每个 Room 的 Player 数。
--reservation-ttl1–60 s匹配预留为席位保留的时长。
--lifetime≥ 0 sRoom 的最长存在时间;0 表示不限,此时必须设置 --idle-timeout。
--idle-timeout≥ 1 sRoom 在没有 Player 的状态下持续这么久后关闭。省略即取消该设置。
--max-rooms1–10000这个 game server 可同时运行的 Room 数。

rooms config get 显示当前设置,rooms config delete 删除设置;只要还有 Room 处于注册状态,删除就会被拒绝。


下一步

  • 命令行工具 —— 登录、全部命令、退出码和错误
  • Functions —— 在 Backoffice 中查看已部署的 Function、日志和设置
  • Servers —— fleet、machine pool 和 Room 设置

更新于 2026年10月14日