---
description: jiang13-bbs 认证 Cookie 方案与公共 WebSocket 实时总线约定
alwaysApply: true
---

# 认证与实时总线

## Cookie 认证（禁止 localStorage token）

- `j13_token` HttpOnly 15m；`j13_refresh` HttpOnly 7d Path=/；`j13_csrf` 非 HttpOnly
- 客户端 `/api/*` + `credentials:'include'`；写请求带 `X-CSRF-Token`
- `fetchWithRefresh`：401 自动 refresh 重试；`TokenVersion` 封禁/改密/改角色后使 JWT 失效
- SSR：middleware 过期可续 refresh；layout 直出 Header 登录态，避免 F5 闪游客

## WebSocket（全站一条连接）

- `GET /api/ws`；dev 直连 `ws://hostname:3001/api/ws`（Next rewrite 不透传 Upgrade）
- Origin **必须存在**；dev 允许 localhost/127.0.0.1 任意端口；生产要求 Origin host == 请求 Host（页面与 `/api/ws` 须同一 Host）
- 事件：`hello` / `pong` / `settings:changed` / `presence:update` / `chat:*` / `notification:new` / `feed:changed` / `moderation:changed`
- 消息铁律：**先落库再 WS 广播**；WS 不可靠投递；未读靠 HTTP 对账
- 角标优先推送：通知落库统一 `OnNotifyNew`；待审变化推 staff `moderation:changed`；**禁止**再恢复 30s 轮询未读/待审
- ThemeSync：推送优先 + visibility/focus 校准，**无定时轮询**
- 主题 DOM：禁止对 SSR `#j13-accent-vars` 做 `remove()`；热换肤只用 `#j13-accent-runtime`

## Git

- remote：`https://git.iioio.com/freefire/jiang13-bbs.git`，分支 `main`
- 自建 Gitea 偶发不稳：`git push` 失败则**原样重试一次**；勿改 remote / 勿反复重试
- 勿提交 `node_modules`、`.next`、`backend/data`、`backend/cmd/jiang13/data`（错误 cwd 遗留）、真实 `app.ini`