GC Team Control 队伍协议工具
约 1831 字
GC Team Control 是 Client 内置的 SSL Game Controller Team Protocol 调试客户端。它代表一支参赛队连接 GC,用于验证队伍注册、门将声明、优势选择、换人申请、签名认证及控制器回复。它适合本机联调和比赛前协议验收,不是用来发送 HALT、STOP 等裁判指令的裁判盒。

GC Team Control
连接、注册、队伍消息、控制器回复和通信日志

GC Team Control 控件标注
连接成功并注册黄队后的示例
这个工具解决什么问题
- 确认 GC 的 Team Server 是否在预期地址监听。
- 独立于策略程序验证 Team Protocol 的 Protobuf 编解码和消息分帧。
- 检查队名、颜色、签名令牌是否能完成注册。
- 手动复现“换门将被拒绝”“优势选择未生效”等协议问题。
- 通过 Controller Reply 和 Traffic Log 区分“消息没发出去”与“GC 收到但拒绝”。
与 Referee UDP 的区别
GC 会通过 publish-address 向网络广播裁判状态,Client 的 Referee 页面被动接收这一路 UDP 数据;Team Control 则主动建立到 GC Team Server 的 TCP/TLS 连接并双向交换请求和回复。两条链路用途、端口和数据格式都不同。
通信链路
GC Team Control
│ TCP 或 TLS,默认 127.0.0.1:10008
│ 长度头 + Protobuf
▼
SSL Game Controller Team Server
│
├─ TeamRegistration:第一条客户端消息
├─ TeamToController:门将 / 优势 / 换人 / Ping
└─ ControllerToTeam:每次请求的 ControllerReply本项目 ssl-game-controller.yaml 中对应配置为 server.team.address: :10008,可信公钥目录为 config/trusted_keys/team。连接远程 GC 时将 127.0.0.1 改为 GC 所在电脑的 IP,并确认防火墙允许该 TCP 端口。
传输与分帧
协议消息使用 Protobuf,但 TCP 本身没有消息边界,因此每个 payload 前还要加长度:
| Framing 选项 | 线上格式 |
|---|---|
| Length prefix (4-byte) | 4 字节无符号长度,大端序,之后紧跟 Protobuf payload |
| Varint length | Protobuf 风格的 varint32 长度,之后紧跟 payload;本工具默认值 |
客户端和 GC 必须使用相同分帧方式。分帧不一致时,TCP 可能已经 Connected,但日志会出现解析失败、非法长度或始终收不到有效回复。
协议消息
1. TeamRegistration
Team Protocol 规定注册必须是队伍发送给 GC 的第一条消息:
| 字段 | 必需性 | 含义 |
|---|---|---|
team_name | 必需 | 必须与 GC 发布的队名完全一致 |
team | 可选 | Yellow/Blue;主要用于同一队伍与自己比赛时区分两侧 |
signature | 可选 | 安全通信使用的 Token 与 PKCS#1 v1.5 签名字节 |
页面的 Team name 下拉框取自当前裁判数据中的蓝黄队名。普通比赛也建议明确选择颜色,便于日志和人工核对。
2. TeamToController
每条消息的 oneof msg 只携带一种操作:
| 页面操作 | Protobuf 字段 | 协议含义 |
|---|---|---|
| Desired keeper id | desired_keeper | 请求设置新的门将编号;GC 可按比赛状态拒绝 |
| Advantage STOP | advantage_choice = STOP | 犯规后停止比赛 |
| Advantage CONTINUE | advantage_choice = CONTINUE | 选择有利原则,保持比赛继续 |
| Request substitution | substitute_bot = true/false | 申请在下一允许时机换人,或撤销申请 |
| Ping | ping = true | 验证连接仍开放;值本身会被忽略 |
优势选择会持续有效,直到再次发送另一选择;连接断开后 GC 将它恢复为默认 STOP。因此它不是一次性的按钮状态。
3. ControllerToTeam
GC 对每个注册或请求返回 ControllerReply:
| 字段 | 页面显示 | 含义 |
|---|---|---|
status_code | Status | OK、REJECTED 或未知状态 |
reason | Reason | 接受或拒绝的具体原因 |
verification | Verification | 安全签名是否 VERIFIED |
next_token | Next token | 下一次安全请求必须使用的新令牌 |
“Send”只表示本地已把消息写入 socket;只有收到 OK 才表示 GC 接受。收到 REJECTED 时应先读 Reason,例如比赛运行中可能不允许修改门将。
控件说明
| 编号 | 控件 | 作用 |
|---|---|---|
| 1–2 | Status / Enable Team Channel | 显示连接状态;开关负责建立或关闭通道 |
| 3–4 | Host / Port | GC 地址与 Team Server 端口,默认 127.0.0.1:10008 |
| 5–6 | Use SSL / Ignore SSL Errors | 启用 TLS;仅测试环境才可忽略证书错误 |
| 7 | Framing | 选择 4-byte 或 Varint 长度头 |
| 8 | Auto register | 连接建立后立即自动发送注册 |
| 9–10 | Reconnect / Disconnect | 重新建立或主动断开连接 |
| 11–12 | Team name / Team | 填写精确队名并选择 Yellow/Blue |
| 13–17 | Signature / Token | 安全通信、令牌轮换和手动注册 |
| 18–23 | Team Commands | 门将、优势、换人和 Ping |
| 24–27 | Controller Reply | GC 的状态、原因、验证结果和下一令牌 |
| 28 | Traffic Log | 最近 200 条连接、发送和回复记录,最新在上 |
无签名的本机联调
- 在 SSL Game Controller Launcher 启动本机 GC。
- 保持 Host 为
127.0.0.1、Port 为10008,按 GC 配置选择 Framing;本项目默认使用 Varint。 - 关闭 Use SSL 和 Use Signature,从裁判数据中选择准确队名与颜色。
- 保持 Auto register 开启,再打开 Enable Team Channel。
- Traffic Log 应依次出现连接建立、Registration sent 和 Controller reply;以
OK为成功依据。 - 先发送 Ping,再在测试比赛状态下验证门将、优势或换人请求。
安全通信与令牌轮换
协议用 Signature { token, pkcs1v15 } 防止伪造和重放。GC 在安全通信的首次回复中提供 Token;之后每次请求都应携带上次回复的 Token,并使用受信任私钥生成该消息的 PKCS#1 v1.5 签名。GC 再返回新的 next_token。
本页面不会替你生成密码学签名
Signature (hex) 输入框接收的是外部生成的签名字节十六进制;当前实现只去掉空格/换行和可选的 0x 前缀,再把字节与 Token 放进消息。若已开启签名但 Token 或十六进制无效,工具会记录警告并清除 Signature,随后仍以无签名方式发送。
安全联调时建议关闭 Auto register,先连接并等待 GC 的初始 Token,点击 Use Next Token 填入 Token,在外部按协议生成当前待发消息的签名后再手动 Send Registration。后续每次请求都必须针对新消息重新签名,并使用最新 Token;Use Next Token 只复制令牌,不会重新计算签名。
常见问题
| 现象 | 优先检查 |
|---|---|
| 一直 Disconnected | GC 是否启动、server.team.address、Host/Port、防火墙 |
| Connected 但没有有效回复 | Framing 是否一致、第一条消息是否为 TeamRegistration |
| Registration 被拒绝 | team_name 是否与 GC 完全一致、颜色、Reason |
| Verification 为 UNVERIFIED | Token 是否最新、签名是否对应当前完整消息、可信公钥目录 |
| Use SSL 后卡在握手 | GC 端是否启用 TLS、证书链和主机名 |
| 请求被 REJECTED | 查看 Reason;当前比赛阶段可能不允许该操作 |
比赛环境中的使用边界
这个工具能向真实 GC 提交队伍意图。正式比赛中只应由获授权人员操作,并避免与策略程序的 Team Protocol 客户端同时代表同一队注册,以免产生相互覆盖或难以解释的请求。
贡献者
更新日志
4424a-settingpanel 教程于