242 lines
6.2 KiB
Markdown
242 lines
6.2 KiB
Markdown
# Node 后端知识图谱
|
||
|
||
日期：`2026-04-08`
|
||
|
||
## 1. 当前定位
|
||
|
||
当前运行时后端以 `server-node/` 为唯一有效服务端实现。
|
||
|
||
当前职责：
|
||
|
||
- 承接运行时鉴权
|
||
- 承接运行时持久化
|
||
- 承接运行时 AI 接口
|
||
- 承接编辑器写盘与资产生成工具接口
|
||
- 为 Vite 前端提供开发期代理目标
|
||
|
||
当前不再使用：
|
||
|
||
- Vite 本地 API 插件 `scripts/dev-server/` 作为当前接口入口
|
||
|
||
## 2. 技术栈
|
||
|
||
- HTTP 框架：`Express`
|
||
- 语言与构建：`TypeScript` + `tsx` + `esbuild`
|
||
- 数据库：`PostgreSQL`
|
||
- JWT：`jose`
|
||
- 密码哈希：`@node-rs/argon2`
|
||
- 日志：`pino` + `pino-http` + `pino-roll`
|
||
|
||
## 3. 运行入口
|
||
|
||
推荐命令：
|
||
|
||
```bash
|
||
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/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`
|
||
|
||
编辑器工具：
|
||
|
||
- `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`
|
||
- `POST /api/assets/qwen-sprite/master`
|
||
- `POST /api/assets/qwen-sprite/sheet`
|
||
- `POST /api/assets/qwen-sprite/frame-repair`
|
||
- `POST /api/assets/qwen-sprite/save`
|
||
|
||
编辑器与资产接口门禁：
|
||
|
||
- `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 后端直接复用前端现有多阶段生成编排
|
||
- 当前保留 `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/editor/shared/useJsonSave.ts`
|
||
- `src/components/preset-editor/characterAssetStudioPersistence.ts`
|
||
- `src/tools/qwenSpriteSheetToolPersistence.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/**` 文件仅保留为迁移参考，不再由 `vite.config.ts` 注入。
|