TeamViewRelay Squaremap Source Client

这个项目读取 Squaremap 的在线玩家数据，并把玩家位置发送到 TeamViewRelay。协议 0.8.0 还可以读取服务器 官方居民目录，在不改变实时在线人数的前提下发布离线玩家归属和城镇/国家敌友关系。

示例在线玩家地址是：

https://map.example.com/tiles/players.json

这个地址可能出现 EdgeOne 真人验证，所以项目提供两种启动方式：

1. 浏览器模式：自动启动无界面的 Chromium 完成验证，适合云服务器，推荐使用。
2. 直连模式：直接请求源站，不启动 Chromium；只有源站允许普通 HTTP 请求时才能使用。

准备目录

协议固定在仓库的 Git submodule 中。首次克隆时使用：

git clone --recurse-submodules https://github.com/MC-TeamViewer/TeamViewRelay-Squaremap-Source-Client.git

已经克隆过仓库时执行 git submodule update --init --recursive。之后普通的 cargo build、 docker build . 和 docker compose build 都会使用仓库锁定的协议提交，不需要额外构建上下文。

服务器只需安装 Docker 和 Docker Compose，不需要安装 Python，也不需要在宿主机安装 Chromium。

推荐：浏览器模式

这是读取带有浏览器验证的 Squaremap 数据源时的推荐方式。

1. 创建配置

cp config.pass-cdn.example.toml config.toml

打开 config.toml，至少修改下面两项：

# TeamViewRelay 的玩家客户端地址，必须以 /mc-client 结尾。
# 这个地址必须能从 Docker 容器内访问，不能继续使用示例中的 127.0.0.1。
relay_url = "wss://你的-TeamViewRelay-地址/mc-client"

# 玩家数据要发送到的 TeamViewRelay 房间。
room_code = "你的房间代码"

source_url 不要改，它已经指向负责读取源站的容器：

source_url = "http://pass-cdn:8080/tiles/players.json"

其他配置可以先保持默认。

完整目录配置示例如下；realm_id 必须与 room_code 一致：

relationships_url = "https://directory.example.com/nodes/towns.json"
relationships_format = "nodes_towns_v1"
relationships_poll_interval_secs = 300
relationships_stale_after_secs = 604800
# realm_id 默认使用 room_code，当前 backend 要求两者一致。
relationship_dataset_id = "example-towns"

完整目录与 Squaremap 在线列表独立轮询。目录不可用时，已经持久化到 backend 的记录仍可查询并会标记为 stale；位置上报继续工作。

2. 构建并启动

docker compose --profile browser up -d --build

第一次构建会下载 Rust 和 Chromium，所需时间取决于网络速度。

这条命令会启动两个容器：pass-cdn 负责从配置的地图源取数，squaremap-source 负责把取到的玩家数据发送给 TeamViewRelay。

3. 确认是否成功

docker compose --profile browser ps

pass-cdn 显示 healthy 后，再查看日志：

docker compose --profile browser logs -f pass-cdn squaremap-source

成功时应看到：

• pass-cdn 周期性输出 players.json updated
• squaremap-source 成功连接 TeamViewRelay
• TeamViewRelay 对应房间中出现 Squaremap 玩家

按 Ctrl+C 只会退出日志查看，不会停止容器。

4. 停止

docker compose --profile browser down

直连模式

如果 players.json 可以直接返回 JSON，没有 EdgeOne 验证，可以不用 Chromium。

1. 创建配置

cp config.example.toml config.toml

打开 config.toml，修改：

relay_url = "wss://你的-TeamViewRelay-地址/mc-client"
room_code = "你的房间代码"
source_url = "https://map.example.com/tiles/players.json"

2. 构建并启动

docker compose up -d --build

3. 查看日志

docker compose logs -f squaremap-source

如果日志提示 captcha_required，说明源站要求真人验证，请停止直连模式并改用上面的浏览器模式：

docker compose down
cp config.pass-cdn.example.toml config.toml

然后重新填写 relay_url 和 room_code，再执行：

docker compose --profile browser up -d --build

构建镜像失败

如果服务器无法从 Docker Hub 下载基础镜像，可以使用镜像站重新构建：

RUST_IMAGE=docker.1ms.run/library/rust:1.94.1-bookworm \
DEBIAN_IMAGE=docker.1ms.run/library/debian:bookworm-slim \
  docker compose --profile browser up -d --build

常用命令

浏览器模式：

docker compose --profile browser ps
docker compose --profile browser logs -f
docker compose --profile browser restart
docker compose --profile browser down

直连模式：

docker compose ps
docker compose logs -f
docker compose restart
docker compose down

玩家离线历史保存在 Docker volume squaremap-history 中。普通的 docker compose down 不会删除它；不要使用 docker compose down -v，除非确定要删除历史数据。