跳到主要内容
工程

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

命令行工具

playserv 是在终端或 CI 中运维游戏 backend 的命令行工具。 它可以生成并部署 Function 和 game server、读取日志、扩缩,以及管理 API key 和 secret。每条命令都在一个已登录的 Project Environment 中执行,并且都能输出供脚本使用的机器可读结果。

本页介绍安装、登录和全部命令。代码的构建和发布见使用 CLI 部署。


安装

在 Backoffice 中点击 Download CLI 下载适合你操作系统的 playserv 可执行文件,然后把它放到 PATH 中。这个按钮位于尚无 Function 的项目的 Functions 页面上,也出现在新项目的设置横幅中。

它同时也是 PlayServ NuGet 源上的 .NET 全局工具,无需任何凭据。先注册一次 NuGet 源,再安装:

dotnet nuget add source https://nuget.playserv.com/v3/index.json -n playserv
dotnet tool install --global PlayServ.Platform.Cli
playserv --version

用 dotnet tool update --global PlayServ.Platform.Cli 更新。无论用哪种方式安装,生成 C# 项目都需要 .NET 10 SDK。


登录

CLI 在用服务端 API key 打开的会话中工作。 会话属于该 key 所在的 Project 和 Environment,之后的每条命令都以它们为目标。

playserv status
playserv login <sk_your_key>
playserv logout
命令作用
playserv login <key>打开会话。只接受服务端 key(sk_…),客户端 key(pk_…)会被拒绝。
playserv status输出会话的平台地址、组织、Project 和 Environment。未登录时以 1 退出,脚本可以把它当作前置检查。
playserv logout结束会话。

在 Backoffice 中创建 key(API Key Management),或使用 playserv keys create。会话从不保存原始 key。

--env 只做检查,不会切换 Environment

大多数命令都接受 --env <env>,但如果传入的 Environment 与会话不同,命令会被拒绝。在脚本中用它来断言命令运行的位置。要在另一个 Environment 中工作,请用该 Environment 的 key 登录:准备一个 dev key 和一个 prod key,在执行任何破坏性操作之前先运行 playserv status。

CLI 默认连接其构建时对应的平台。设置了 PLAYSERV_API_URL 时,所有命令都改为连接这个平台地址。


命令参考

functions 可以简写为 fn。会移除或替换内容的命令会请求确认:publish、functions delete、rollback、disable、keys revoke、keys undo-revoke、keys rotate 和 rooms config delete。-y / --yes 跳过确认;其他命令不接受这个参数。

构建与发布。 详细说明和选项见使用 CLI 部署。

命令作用
playserv init <slug>生成带 platform.json 的项目:默认是 game server,加 --kind cloud_function 则是云函数。--solution <Name> 改为生成一个包含共享项目的 solution。
playserv publish先展示计划,然后部署 solution 中每个带 platform.json 的 Function。
playserv functions deploy --slug <slug> --kind <kind>从源码部署单个 Function。
playserv functions declare <slug>只注册 Function 而不部署代码,例如你自己运行的 game server。
playserv image push --slug <slug>为 machine pool 构建并推送 game server 镜像;加 --roll 会让 pool 切换到这个镜像。
playserv rooms config get|set|delete <slug>读取或替换 game server 的 Room 设置。

查看。

命令作用
playserv functions listEnvironment 中的所有 Function:slug、类型、语言、状态、地址。
playserv functions logs <slug>最近的日志行。--tail N、--since <ISO 8601>、--level error|warn|info。
playserv functions deploys listEnvironment 的部署历史,带 ID。
playserv functions deploys get <id>单次部署的阶段、消息和耗时,使用 functions deploy 输出的 ID。
playserv functions replicas <slug>运行中的副本,包括 ID、区域、状态和启动时间。

运维。

命令作用
playserv functions redeploy <slug>在当前构建上重启 Function,不重新构建。
playserv functions rollback <slug> --to <deploy-id>把流量切回之前的某次部署,使用 deploys list 中的 ID。
playserv functions enable <slug> · disable <slug>恢复或停止处理流量。Function 及其数据保留。
playserv functions scale <slug> --policy manual|auto --desired N --min N --max N替换扩缩配置。四个参数都必须提供。
playserv functions delete --slug <slug>从 Environment 中移除 Function。

key 与 secret。

命令作用
playserv keys listEnvironment 中的所有 key,包括类型、前缀、状态和最近使用时间。secret 值不会再次显示。
playserv keys create --name <name> [--kind sk|pk]创建服务端 key(默认)或客户端 key,并只输出一次其 secret。
playserv keys rotate <id>替换 secret。旧值立即失效。
playserv keys revoke <id> · keys undo-revoke <id>吊销 key 并关闭它的活动连接,或在撤销窗口内取消吊销。
playserv secrets set <NAME>设置或轮换 secret。值从 stdin 或隐藏输入提示中读取,绝不从命令参数读取。
playserv secrets list · secrets delete <NAME>列出 secret 名称及使用它们的 Function,或删除其中一个。

仅限所有者。

命令作用
playserv org:regenerate-slug --confirmation <slug>重新生成组织的公开 slug。
playserv project:regenerate-slug --confirmation <slug>重新生成 Project 的公开 slug。

旧 slug 在 --redirect-window-days(0–180,默认 60)天内仍然有效。每个资源每 30 天只能重新生成一次,总共最多五次。


Secret

secret 是按 Project 和 Environment 保存的具名值,从不进入 git,也从不进入部署包。Function 在 platform.json 中列出它需要的名称,并以环境变量的形式读取;对已有名称再次设置即为轮换,使用它的 Function 会读取到新值。

printf %s "$STRIPE_KEY" | playserv secrets set STRIPE_API_KEY

只要还有 Function 声明了某个 secret,它就无法删除(secret_in_use):先从 manifest 中移除,重新部署,然后再删除。在全新的 Environment 中,请在首次部署之前设置好 secret;声明的 secret 没有值的 Function 会一直处于 failing,直到设置了值。


脚本与 CI

--json 让每条命令都输出机器可读的结果。 成功时在 stdout 输出一个 JSON 对象或数组;失败时在 stderr 输出 {"error": {…}},其中包含 summary、detail、hint 和 code。部署失败或超时时,结果输出在 stdout,publish 会在结果中报告每个 Function 的错误。在 --json 下不会等待交互确认:确认直接失败,并指出应传入的参数。

退出码含义
0成功,包括上传已被接受的 --detach。
1一般性失败:参数错误、确认被拒绝、API 错误,或 publish 中至少有一个 Function 失败。
2平台拒绝了上传或无法连接,或者 login 失败。
3构建失败。
4CLI 停止等待,或在上传、构建期间失去连接。构建可能仍会完成。
5等待期间会话过期。

典型的 CI 任务会把目标 Environment 的 sk_ key 存为 secret,然后运行:

playserv login "$PLAYSERV_KEY" --json
playserv status --json
playserv publish --dry-run --json
playserv publish --yes --parallel 4 --json

未知参数会报错(invalid_arguments),因此拼写错误永远不会悄悄地执行别的操作。


错误

错误码处理方法
not_logged_in运行 playserv login。
env_not_resolved--env 指定的 Environment 与会话不同。用该 Environment 的 key 登录,或去掉 --env。
env_not_linked该 Environment 没有关联部署。运营人员需要在 Project settings → Environments 中点击 Re-link deploys 重新关联;正在进行的构建会继续运行。
invalid_arguments参数未知或格式错误。查看 playserv <command> --help。
invalid_bundle部署包或 platform.json 格式错误。消息中会指出具体文件。
invalid_manifest违反了某条 manifest 规则:值错误、扩缩超出范围、cron 错误、使用了保留名称。消息中会指出具体规则。
duplicate_function_slugsolution 中有两个 manifest 使用了相同的 slug。
unknown_function_filterpublish --only 指定的 Function 不在 solution 中。
upload_timeout上传未能按时完成。没有部署任何内容,请重试。
function_not_found · deployment_not_found这里没有该 slug 或该部署。查看 functions list 或 functions deploys list。
secret_in_use · secret_not_found见 Secret。
token_slug_stale会话创建于 slug 变更之前。请重新登录。
prompt_unavailable在 --json 下或管道中需要确认。传入消息中指出的参数。
platform_unreachable · platform_timeout检查网络以及 playserv status 输出的地址,然后重试。
unreadable_responseCLI 与平台版本不一致。请更新 CLI。

如果部署失败而原因不明,先运行 playserv functions deploys get <id> 查看阶段和消息,再运行 playserv functions logs <slug> --level error。如果 Function 在部署后立即返回 404,用 playserv status 检查 Environment:部署到 dev 的 Function 在 prod 中并不存在。


下一步

  • 使用 CLI 部署 —— 生成、部署和发布 Function 与 game server
  • Functions —— 在 Backoffice 中查看已部署的 Function
  • Servers —— 在 machine pool 上运行 game server

更新于 2026年10月14日