技能名称: structs-guild-stack
详细描述:

Structs 公会栈

公会栈是一个 Docker Compose 应用程序，它运行一个完整的公会节点，包含 PostgreSQL 索引、GRASS 实时事件、一个 Web 应用、MCP 服务器和交易签名代理。它能够为游戏状态提供亚秒级数据库查询，而通过 CLI 查询则需要 1-60 秒。

这是一个高级/可选升级。 CLI 命令适用于基础游戏玩法。公会栈适用于需要实时战斗自动化、自动威胁检测或全星系情报的代理。

仓库: https://github.com/playstructs/docker-structs-guild

何时使用公会栈

规则: 使用 PG 进行读取，使用 CLI 进行写入。

前提条件

• - 已安装 Docker 和 docker compose
• 约 10 GB 磁盘空间
• 首次链同步需要数小时（一次性成本；后续启动只需几分钟即可追上）

设置步骤

1. 克隆仓库

bash
git clone https://github.com/playstructs/docker-structs-guild
cd docker-structs-guild

2. 配置环境

复制或创建 .env 文件，至少包含以下内容：

MONIKER=MyAgentNode
NETWORK_VERSION=111b
NETWORKCHAINID=structstestnet-111

3. 启动栈

bash
docker compose up -d

4. 等待链同步

区块链节点必须从创世块或快照同步。首次运行需要数小时。监控进度：

bash
docker compose logs -f structsd --tail 20

当健康检查通过时，节点即同步完成。使用以下命令检查：

bash
docker compose ps

所有服务应显示 healthy 或 running。structsd 服务有 48 小时的健康检查启动期，以适应初始同步。

5. 验证 PG 访问

运行一个测试查询（参见下面的“连接到 PostgreSQL”）：

bash
docker exec docker-structs-guild-structs-grass-1 \
psql postgres://structs_indexer@structs-pg:5432/structs?sslmode=require \
-t -A -c SELECT count(*) FROM structs.player;

如果返回一个数字，则栈正在工作。

连接到 PostgreSQL

使用 GRASS 容器 进行 psql 访问——它可以通过 Docker DNS 访问 PG 服务，并且 structs_indexer 角色具有广泛的读取权限。

bash
PG_CONTAINER=docker-structs-guild-structs-grass-1
PGCONN=postgres://structsindexer@structs-pg:5432/structs?sslmode=require

docker exec $PGCONTAINER psql $PGCONN -t -A -c SELECT ...

对于 JSON 输出：

bash
docker exec $PGCONTAINER psql $PGCONN -t -A -c \
SELECT COALESCE(jsonagg(rowto_json(t)), []) FROM (...) t;

容器名称可能因安装而异。使用 docker compose ps 查找并寻找 structs-grass 服务。

Grid 表陷阱

structs.grid 表是一个键值存储，而不是列式表。每一行是一个对象的一个属性。

sql
-- 错误：没有 ore 列
SELECT ore FROM structs.grid WHERE object_id = 1-142;

-- 正确：按 attribute_type 过滤
SELECT val FROM structs.grid WHERE objectid = 1-142 AND attributetype = ore;

对于同一对象的多个属性，使用多个 JOIN：

sql
SELECT p.id,
COALESCE(g_ore.val, 0) as ore,
COALESCE(gload.val, 0) as structsload
FROM structs.player p
LEFT JOIN structs.grid gore ON gore.objectid = p.id AND gore.attribute_type = ore
LEFT JOIN structs.grid gload ON gload.objectid = p.id AND gload.attribute_type = structsLoad
WHERE p.id = 1-142;

常见查询

玩家资源

sql
SELECT p.id, p.guildid, p.planetid, p.fleet_id,
COALESCE(g_ore.val, 0) as ore,
COALESCE(gload.val, 0) as structsload
FROM structs.player p
LEFT JOIN structs.grid gore ON gore.objectid = p.id AND gore.attribute_type = ore
LEFT JOIN structs.grid gload ON gload.objectid = p.id AND gload.attributetype = structsload
WHERE p.id = 1-142;

舰队组成及武器数据

sql
SELECT s.id, st.classabbreviation, s.operatingambit,
st.primaryweaponcontrol, st.primaryweapondamage,
st.primaryweaponambitsarray, st.unitdefenses,
st.counterattacksame_ambit
FROM structs.struct s
JOIN structs.struct_type st ON st.id = s.type
WHERE s.owner = 1-142 AND s.location_type = fleet
AND s.is_destroyed = false
ORDER BY s.operating_ambit, s.slot;

突袭目标侦察

sql
SELECT pl.id as planet, pl.owner, g_ore.val as ore,
COALESCE(pa_shield.val, 0) as shield,
COALESCE(gload.val, 0) as structsload
FROM structs.planet pl
JOIN structs.grid gore ON gore.objectid = pl.owner AND gore.attribute_type = ore
LEFT JOIN structs.planetattribute pashield ON pashield.objectid = pl.id
AND pashield.attributetype = planetaryShield
LEFT JOIN structs.grid gload ON gload.object_id = pl.owner
AND gload.attributetype = structsLoad
WHERE g_ore.val > 0
ORDER BY g_ore.val DESC, shield ASC;

星球上的敌方建筑

sql
SELECT s.id, st.classabbreviation, s.operatingambit,
st.primaryweaponcontrol, st.primaryweapondamage,
st.unit_defenses
FROM structs.struct s
JOIN structs.struct_type st ON st.id = s.type
JOIN structs.fleet f ON f.id = s.location_id
WHERE f.locationid = 2-105 AND s.isdestroyed = false
AND s.location_type = fleet
ORDER BY s.operating_ambit;

实时威胁检测（轮询模式）

sql
-- 启动时设置高水位线
SELECT COALESCE(MAX(seq), 0) FROM structs.planet_activity
WHERE planet_id IN (2-105);

-- 每约6秒轮询一次（一个区块间隔）
SELECT seq, planet_id, category, detail::text
FROM structs.planet_activity
WHERE planet_id IN (2-105, 2-127)
AND seq > $LAST_SEQ
ORDER BY seq ASC;

关注 fleetarrive、raidstatus 和 struct_attack 类别。

建筑生命值和防御分配

sql
SELECT sa.objectid as structid, sa.attribute_type, sa.val
FROM structs.struct_attribute sa
WHERE sa.object_id = 5-1165;

SELECT defendingstructid, protectedstructid
FROM structs.struct_defender
WHERE protectedstructid = 5-100;

栈管理

bash

启动所有服务

检查服务状态

查看区块链同步进度

停止（保留所有数据）

销毁所有数据（重新开始）

端口汇总