# Node 后端知识图谱

日期：`2026-04-08`

## 1. 当前定位

当前运行时后端以 `server-node/` 为唯一有效服务端实现。

当前职责：

- 承接运行时鉴权
- 承接运行时持久化
- 承接运行时 AI 接口
- 为 Vite 前端提供开发期代理目标

当前不再使用：

- Vite 本地 API 插件 `scripts/dev-server/`

## 2. 技术栈

- HTTP 框架：`Express`
- 语言与构建：`TypeScript` + `tsx` + `esbuild`
- 数据库：`better-sqlite3`
- JWT：`jose`
- 密码哈希：`@node-rs/argon2`
- 日志：`pino` + `pino-http` + `pino-roll`

## 3. 运行入口

推荐命令：

```bash
npm run dev:node
```

相关脚本：

- 根目录联调：`npm run dev:node`
- 单独启动后端开发模式：`npm run server-node:dev`
- 构建后端：`npm run server-node:build`
- 运行后端测试：`npm run server-node:test`

默认监听：

- 前端：`3000`
- Node 后端：`8081`

## 4. 目录与主入口

服务端主入口：

- `server-node/src/server.ts`
- `server-node/src/app.ts`

路由入口：

- `server-node/src/routes/authRoutes.ts`
- `server-node/src/routes/runtimeRoutes.ts`

基础设施：

- `server-node/src/config.ts`
- `server-node/src/logging.ts`
- `server-node/src/db.ts`
- `server-node/src/context.ts`

数据访问：

- `server-node/src/repositories/userRepository.ts`
- `server-node/src/repositories/runtimeRepository.ts`

鉴权相关：

- `server-node/src/auth/authService.ts`
- `server-node/src/auth/token.ts`
- `server-node/src/auth/password.ts`
- `server-node/src/middleware/auth.ts`

## 5. 鉴权模型

当前采用：

- 前端本地保存 `JWT + 自动生成的用户名密码`
- 请求头使用 `Authorization: Bearer <token>`
- 后端 middleware 统一解析出 `UserID`
- handler 不直接解析 token

当前账号策略：

- 默认自动匿名账号启动
- 本地无 JWT 时，前端会自动生成随机用户名密码并调用 `POST /api/auth/entry`
- 本地 JWT 失效但仍保留随机凭据时，前端自动重新调用 `auth/entry` 恢复同一账号

JWT 现状：

- 当前为永久签发
- claim 仍保留：`sub`、`iat`、`iss`、`ver`
- `logout` 通过递增 `token_version` 立即失效旧 token

## 6. 数据存储

当前数据库：

- 默认 SQLite 文件：`server-node/data/genarrative.sqlite`
- 可通过 `SQLITE_PATH` 覆盖

当前核心表：

- `users`
- `save_snapshots`
- `runtime_settings`
- `custom_world_profiles`

当前隔离原则：

- 所有运行时数据按用户隔离

## 7. 已承接接口

鉴权：

- `POST /api/auth/entry`
- `GET /api/auth/me`
- `POST /api/auth/logout`

运行时持久化：

- `GET /api/runtime/save/snapshot`
- `PUT /api/runtime/save/snapshot`
- `DELETE /api/runtime/save/snapshot`
- `GET /api/runtime/settings`
- `PUT /api/runtime/settings`
- `GET /api/runtime/custom-world-library`
- `PUT /api/runtime/custom-world-library/:profileId`
- `DELETE /api/runtime/custom-world-library/:profileId`

运行时 AI：

- `POST /api/llm/chat/completions`
- `POST /api/custom-world/scene-image`
- `POST /api/runtime/story/initial`
- `POST /api/runtime/story/continue`
- `POST /api/runtime/custom-world/sessions`
- `GET /api/runtime/custom-world/sessions/:sessionId`
- `POST /api/runtime/custom-world/sessions/:sessionId/answers`
- `GET /api/runtime/custom-world/sessions/:sessionId/generate/stream`
- `POST /api/runtime/chat/character/suggestions`
- `POST /api/runtime/chat/character/summary`
- `POST /api/runtime/chat/character/reply/stream`
- `POST /api/runtime/chat/npc/dialogue/stream`
- `POST /api/runtime/chat/npc/recruit/stream`
- `POST /api/runtime/items/runtime-intent`
- `POST /api/runtime/quests/generate`

## 8. Story 与 Custom World 现状

Story：

- Node 后端直接复用前端成熟 prompt 与归一化逻辑
- 服务端走 `src/services/ai.ts` 中的严格版 story 生成链

Custom World：

- Node 后端直接复用前端现有多阶段生成编排
- 当前保留 `session + answers + SSE progress/result/error` 协议
- 前端已支持接收真实阶段进度对象

## 9. 前端接入点

鉴权与请求：

- `src/services/apiClient.ts`
- `src/services/authService.ts`
- `src/components/auth/AuthGate.tsx`

运行时服务层：

- `src/services/storageService.ts`
- `src/services/aiService.ts`

## 10. 当前 Vite 角色

Vite 当前只负责代理，不再提供本地 API 插件。

当前代理目标：

- `/api/auth`
- `/api/runtime`
- `/api/llm`
- `/api/custom-world/scene-image`
- `/api/ws`

全部转发到 Node 后端。