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 直接运行
```bash
npm install
npm start
```

### 6.2 Docker
```bash
docker-compose up -d
```

### 6.3 数据持久化
必须保留 `minecraft_ws.db`，否则 Admin Key 将重新生成。

## 7. 关键配置项
```env
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，禁止删除数据库