docs/TECH_STACK.md

项目技术栈文档

本文件详细说明 InterConnect-Server 的技术组成、模块职责与关键依赖版本。

1. 运行环境

• Node.js: 建议 v18+（Docker 镜像使用 node:18-alpine）
• 包管理: npm
• 平台: Windows / Linux / macOS

2. 核心依赖与用途

2.1 后端服务

• express@4.18.x

  • REST API 服务框架
  • 路由结构：src/routes/*.js
  • 入口：src/server.js

• ws@8.14.x

  • WebSocket 服务端实现
  • 协议：/ws?api_key=...
  • 连接管理：src/websocket.js

• sql.js@1.10.x

  • SQLite 在内存中运行并导出文件
  • 本地持久化文件：minecraft_ws.db
  • 初始化与表结构：src/database.js

• bcryptjs@2.4.x

  • Key 哈希存储
  • 认证校验：db.verifyApiKey()
  • 恢复 Token 哈希：admin_recovery 表

• uuid@9.0.x

  • 生成密钥 ID 与原始 Key

• dotenv@16.3.x

  • 读取环境变量
  • 用于命令过滤与数据库路径等配置

2.2 CLI 工具

• commander@11.1.x

  • CLI 命令定义
  • 命令入口：cli/cli.js
  • 支持管理 Key / health / reset-admin

• http / https (Node 内置)

  • CLI 直接调用 API

2.3 前端 Dashboard

纯静态页面，无前端框架。

• dashboard/public/index.html
• dashboard/public/app.js
• dashboard/public/style.css

3. 关键模块职责

3.1 src/server.js

• 服务入口
• REST API 路由挂载
• WebSocket 升级与连接管理
• 初始化数据库与 Admin Key / Recovery Token

3.2 src/database.js

• SQLite 初始化与持久化
• Key 创建 / 激活 / 停用 / 删除
• Admin Recovery Token 管理
• 事件日志写入

3.3 src/auth.js

• Bearer Token 认证中间件
• Admin / Regular 权限判断

3.4 src/routes/keys.js

• Key CRUD
• /manage/keys/server-keys 列表与激活/停用逻辑

3.5 src/routes/server.js

• 服务器信息与命令入口
• Admin 命令过滤（可配置 allowlist / blocklist）

3.6 src/websocket.js

• WebSocket 连接管理
• 广播消息

4. 数据结构

4.1 api_keys

字段	类型	说明
id	TEXT	主键
name	TEXT	Key 名称
description	TEXT	描述
key_hash	TEXT	bcrypt 哈希
key_prefix	TEXT	mc_admin_ / mc_key_ / mc_server_
key_type	TEXT	admin / regular / server
server_id	TEXT	关联服务器
regular_key_id	TEXT	关联 Regular Key
created_at	TEXT	创建时间
last_used	TEXT	最近使用
is_active	INTEGER	是否启用

4.2 event_logs

事件上报记录。

4.3 admin_recovery

字段	类型	说明
id	INTEGER	固定为 1
token_hash	TEXT	恢复 Token 哈希
created_at	TEXT	创建时间
last_used	TEXT	最近使用

5. 权限与安全策略

• Admin Key：完整管理权限
• Regular Key：只允许操作自身 Server Key
• Server Key：仅用于插件/Mod，不允许登录 Dashboard
• Admin 命令过滤：
  • ADMIN_ALLOWED_COMMANDS 非空时为 allowlist
  • 否则使用 ADMIN_BLOCKED_COMMANDS 作为默认拦截表

6. 部署与运行

6.1 直接运行

npm install
npm start

6.2 Docker

docker-compose up -d

6.3 数据持久化

必须保留 minecraft_ws.db，否则 Admin Key 将重新生成。

7. 关键配置项

SERVER_HOST=0.0.0.0
SERVER_PORT=8000
DATABASE_PATH=minecraft_ws.db
ADMIN_ALLOWED_COMMANDS=list,tps,version
ADMIN_BLOCKED_COMMANDS=stop,deop,op,ban

8. 兼容与约束

• WebSocket 与 REST 使用同一端口
• Dashboard 只通过 /dashboard 提供
• Admin Key 恢复必须使用 recovery token，禁止删除数据库