跳到正文

服务器与安全:零依赖、两种登录、长轮询

联机放置游戏第 07 节 / 共 11 节 ·2026-11-16·~7 min

游戏服务器在 server/src/,11 个文件、三千多行。Node 24 直接执行 TypeScript,存储是 SQLite,零第三方依赖(devDependencies 只有 @types/node 和 typescript)。

1. 运行时

文件管什么
main.ts入口;每 60 秒一次 tick:退过期挂单(每次最多 200 张)、清过期会话、回收限流桶、重读网页版 CURRENT
env.ts环境变量读取与校验,配错了直接拒绝启动
app.ts路由总表、静态文件、CDN 改写
http.ts路由器、JSON / 表单读取(64 KB / 8 KB 上限)、限流、安全头、cookie
auth.ts、identity.tsOIDC 登录、会话、设备码;独立身份服务的客户端
db.ts迁移与事务
game.ts存档、各种操作、市场
gm.tsGM 指令执行
events.ts长轮询推送
pages.ts登录结果页、设备确认页
  • SQLite 用 node:sqlite 的同步 API,WAL 模式。数据表:用户、会话、存档(整份 JSON + 版本号)、挂单、成交、GM 审计、键值、装备寄售、外部身份绑定。
  • 事务规则:所有改状态的操作包在 db.tx(() => …) 里(BEGIN IMMEDIATE,可嵌套)。函数返回 Promise 就抛错:单进程同步 SQLite 不需要锁的前提,就是事务中间不让出事件循环。
  • 游戏操作的固定顺序:读存档 → settle(now) → touch(now) → 修改 → 写回。
  • 收到 SIGTERM 先放掉所有挂起的长轮询,最多等 10 秒再退出。

2. 接口

前缀 /idle/api。

组接口
公开healthz、config(ETag = 配表版本)、client-version、bundle-sizes、version(服务器提交、配表、网页、原生包)
登录auth/login、auth/callback、auth/logout、auth/me;设备码 auth/device/start、auth/device/poll、auth/device(确认页)
生产state、job(派人 / 撤人)、action/stop
战斗combat/class、combat/start、combat/stop、combat/potion
工坊workshop/craft、equip、unequip、enhance、refine、transfer、salvage
家园home/upgrade
外观cosmetic/buy、equip、buy-set、equip-set、unequip;profile/gender
市场market/summary、market/book/:item、market/order、market/cancel;装备 market/gear、gear/list、gear/buy、gear/cancel
推送events?since=N
管理gm(gm 及以上);admin/audit、stats、gm-commands、players、dashboard、tables 与配表的校验 / 应用 / 恢复(只给超级管理员)

另有 /idle/download/<版本>/<文件>(原生安装包,要登录)、/idle/admin/* 与 /idle/dashboard/*(页面壳谁都能拿,数据接口才验权限)、/idle/*(网页版)。

写新接口:要身份的用 need(ctx),写操作用 need(ctx, true)(额外校验 Origin),管理员接口再加 await auth.requireFreshRole(a, now, 'gm' | 'super')。

3. 登录

游戏不存密码、没有注册页,身份来自外部的 OIDC 提供方。两种凭据进同一张会话表:

  • 网页:授权码 + PKCE(S256)+ state + nonce [1]。state 绑在一个 10 分钟的 cookie 上,回调后只许跳回游戏自己的几个页面。会话 cookie __Host-idlehd(HttpOnly、Secure、SameSite=Lax),7 天。
  • 原生端:设备码,形状照 RFC 8628 [2]。客户端拿到 8 位码(XXXX-XXXX,31 个不易混淆的字符,10 分钟有效),打开浏览器去确认页登录,自己每 3 秒轮询;轮得太勤回 slow_down。确认页带 HMAC 表单令牌和 Origin 校验,还有一个「不是我」按钮——RFC 8628 §5.4 说的远程钓鱼:别人把自己的码发给你,骗你替他登录。原生端拿 Bearer 令牌,30 天。

两种身份提供方

由 IDLE_AUTH_PROVIDER 选:

gitea(默认)identity(2026-11-12 加的「独立账号登录」)
身份来源站点的 Gitea一套独立于 Gitea 的身份服务
谁能玩指定 Gitea 组织的成员带 idlehd:player 应用角色的账号
管理员组 idlehd:owners → 超级管理员,idlehd:gm → gm角色 idlehd:super / idlehd:gm
id_token只核对 nonce,身份以 userinfo 为准RS256,经 JWKS 验签,核对 iss / aud / nonce / 时间 / at_hash / azp
角色多久刷新10 分钟用 refresh token 刷一次;管理员操作时超过 60 秒就强制回去确认每个受保护请求都做一次令牌内省(同一会话的并发请求合并成一次)

identity 模式更严:所有端点必须和 issuer 同源、不跟随重定向;access token 不超过一小时,refresh 家族不超过 30 天,轮换时成对原子落库。账号键是 issuer + sub 的哈希,从不按名字认领旧 Gitea 账号,两种模式的会话互不相认。

令牌在库里只存 sha256;需要保留的 refresh / access token 用 AES-256-GCM 加密。开发登录 IDLE_DEV_AUTH=1 只在所有 origin 都是 localhost 时允许,否则服务器拒绝启动。

4. 安全要点

  • 鉴权只在服务器。 客户端「显示不显示控制台」只是便利,每条 GM 指令服务器都重新确认身份并写审计。
  • 不信任任何身份头(X-Auth-Request-* 之类)。站点前面有一层自己的登录代理,游戏服务器不认它塞的头;线上冒烟专门验这一条。
  • CSRF 两道防线:cookie 会话的写操作校验 Origin 必须在白名单里;JSON 接口强制 Content-Type: application/json(简单表单发不出来)[3]。
  • 限流(内存令牌桶):每用户每秒 10 次、突发 40;每 IP 每秒 5 次、突发 30,登录和申请设备码更贵。待登录流程和设备码各最多一万条,满了回 503。
  • 安全头:nosniff、Referrer-Policy: same-origin、X-Frame-Options: SAMEORIGIN、COOP same-origin;游戏页单独一份 CSP(允许 wasm 和 blob Worker,开了 CDN 时只多放行 CDN 那一个源)。
  • 请求体有上限,超时有上限(请求 60 秒、头 20 秒)。

5. 推送:长轮询

GET events?since=N:没有新事件就挂起最多 25 秒。

  • 为什么不用 WebSocket / SSE:Cocos 原生端没有 EventSource,WebSocket 要额外处理反代和心跳;长轮询在所有平台上都只是普通 HTTP 请求。
  • 事件只在内存里:每人最近 100 条,加 100 条全服事件;每人最多同时挂 8 个请求。
  • 游标从服务器启动时刻起算,重启后旧游标照样有效。
  • 事件类型:日志、成交、挂单关闭、状态变了、全服广播、配表变了。客户端收到成交 / 状态类的就同步一次,收到配表变了就重拉配表。

6. GM 指令

17 条(定义在 packages/core/src/gm.ts):help who stats inspect give gold xp setlevel free house skip reset-class reset cancel-order cancel-listing broadcast config-reload。

  • gm 角色只能用其中 7 条(help、inspect、xp、setlevel、house、skip、reset-class),而且只能对自己(me)——用来测试自己的角色。
  • 超级管理员全部能用,对象可以是任何人。
  • 每条执行都写进审计表(指令截 500 字,输出截 2000 字)。

free 让一个角色跳过等级、原料、材料检查,测试新内容用。

7. 管理后台与全服看板

管理后台 /idle/admin/:概览(运行时长、请求数、在线人数、挂单数、内存、配表版本,每 30 秒刷新);玩家搜索与快捷操作(给物品、给金币、加经验、设等级、快进、重置存档);带补全的 GM 控制台;网页配表编辑器(配表 );经验曲线图;最近 200 条审计。

全服看板 /idle/dashboard/:所有角色 × 每个技能的等级,加上「正在做什么」和「最近在线」,可排序、可筛选。只读,不替玩家结算。站点上 /idleDashboard/ 转到这里。

参考

  1. RFC 7636, Proof Key for Code Exchange:https://www.rfc-editor.org/rfc/rfc7636 ;OpenID Connect Core 1.0 §3.1.3.7:https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation
  2. RFC 8628, OAuth 2.0 Device Authorization Grant:https://www.rfc-editor.org/rfc/rfc8628
  3. OWASP, Cross-Site Request Forgery Prevention Cheat Sheet:https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html