Genarrative/docs/technical/NODE_SERVER_KNOWLEDGE_GRAPH_2026-04-08.md

Node 后端知识图谱

日期：2026-04-08

1. 当前定位

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

当前职责：

• 承接运行时鉴权
• 承接运行时持久化
• 承接运行时 AI 接口
• 承接编辑器写盘与资产生成工具接口
• 为 Vite 前端提供开发期代理目标

当前不再使用：

• 已删除的旧 Vite 本地 API 插件链路 scripts/dev-server/*.ts

2. 技术栈

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

3. 运行入口

推荐命令：

npm run dev

相关脚本：

• 根目录联调：npm run dev / npm run dev:node
• 仅前端开发：npm run dev:web
• 单独启动后端开发模式：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/modules/editor/editorRoutes.ts
• server-node/src/modules/assets/characterAssetRoutes.ts
• server-node/src/modules/assets/qwenSpriteRoutes.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. 数据存储

当前数据库：

• 当前运行时持久化已切换到 PostgreSQL
• 连接信息由后端 DATABASE_URL 环境变量注入
• 不再以本地 SQLite 文件作为正式运行时数据库
• 后端测试默认使用 pg-mem 作为内存级 PostgreSQL 兼容实现
• 基础表初始化通过 schema_migrations 基线管理
• 可通过 npm run server-node:db:migrate 主动校验并补齐数据库基线

当前核心表：

• 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/agent/sessions
• GET /api/runtime/custom-world/agent/sessions/:sessionId
• POST /api/runtime/custom-world/agent/sessions/:sessionId/messages
• POST /api/runtime/custom-world/agent/sessions/:sessionId/actions
• GET /api/runtime/custom-world/works
• 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

补充说明（2026-04-19）：

• POST /api/custom-world/scene-image 现在支持前端仅提交 profile + landmark + userPrompt 上下文，由后端统一补齐场景图 prompt 与默认 negative prompt。
• runtime story option 的 interaction 元数据现在由后端随 option 一并返回，前端不再本地按 functionId 重建 NPC / treasure 交互语义。

编辑器工具：

• GET /api/editor/catalog/items
• GET /api/editor/json/:resourceId
• POST /api/editor/json/:resourceId

资产工具：

• POST /api/assets/character-visual/generate
• POST /api/assets/character-visual/publish
• GET /api/assets/character-visual/jobs/:taskId
• POST /api/assets/character-animation/generate
• POST /api/assets/character-animation/publish
• GET /api/assets/character-animation/jobs/:taskId
• POST /api/assets/character-animation/import-video
• GET /api/assets/character-animation/templates

编辑器与资产接口门禁：

• EDITOR_API_ENABLED 控制 /api/editor/*
• ASSETS_API_ENABLED 控制 /api/assets/*
• 非生产环境默认开启，生产环境默认关闭

8. Story 与 Custom World 现状

Story：

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

Custom World：

• Node 后端当前已自持 server-node/src/modules/custom-world/** 运行时模块
• 已承接 creator intent 归一化、anchorPack / lockState 推导、framework normalize、runtime profile compile
• customWorldOrchestrator 与 customWorldAgentFoundationDraftService 已不再运行时 import 前端 src/services/customWorld*.ts 与 src/types.js
• server-node/src/prompts/customWorldPrompts.ts 已承接 foundation draft 与 scene image 使用的 custom world prompt source
• 上述 prompt 迁移只改变源码归属位置，没有改动提示词正文
• 当前保留 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

编辑器与资产工具层：

• src/editor/shared/editorApiClient.ts
• src/components/preset-editor/characterAssetStudioPersistence.ts

10. 当前 Vite 角色

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

当前代理目标：

• /api/auth
• /api/runtime
• /api/editor
• /api/assets
• /api/llm
• /api/custom-world/scene-image
• /api/ws

全部转发到 Node 后端。

scripts/dev-server/ 目录现仅保留 README 作为迁移说明，旧本地 API 实现代码已于 2026-04-19 删除。