# multi_db_query_api

**Repository Path**: giantlungfish_admin2/multi_db_query_api

## Basic Information

- **Project Name**: multi_db_query_api
- **Description**: 数据库查询api
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多数据库查询 API

提供统一 API，支持注册多种数据库（SQL Server、Oracle、MySQL、PostgreSQL、SQLite、Caché/IRIS），并按表/视图、字段、条件执行只读查询。数据源与授权信息存储于本地 SQLite。

## 功能特性

- **多数据库支持**：SQL Server、Oracle、MySQL、PostgreSQL、SQLite、Caché/IRIS
- **数据源 CRUD**：注册、更新、删除、列出数据源
- **只读查询**：按表/视图、字段、条件执行查询，参数化防注入
- **鉴权与授权**：管理端 API Key；数据访问 appKey+appSecret，支持表级 allowedTables 控制

## 快速开始

```bash
# 安装依赖
npm install

# 复制环境配置
cp .env.example .env
# 编辑 .env，按需配置 PORT、API_KEY、SQLITE_DB_PATH

# 构建
npm run build

# 启动（生产）
npm start

# 或开发模式（热重载）
npm run dev
```

健康检查：`GET http://localhost:3000/health`

## 部署说明

`npm run build` 仅编译 TypeScript，**不会**将 `node_modules` 打包进 `dist/`。部署时需在服务器上安装依赖：

```bash
# 方式一：本地打包后上传
npm run deploy:pack   # 生成 deploy-pkg 目录
# 上传 deploy-pkg 到服务器后：
cd /path/to/project
npm ci --omit=dev    # 在服务器安装依赖（含原生模块）
cp .env.example .env # 配置环境变量
npm start

# 方式二：直接上传项目
# 上传 package.json、package-lock.json、dist/、.env 到服务器
cd /path/to/project
npm ci --omit=dev
npm start
```

**重要**：`better-sqlite3`、`oracledb` 等含原生 C++ 绑定，必须在目标服务器执行 `npm install`/`npm ci` 才能正确编译，无法随 JS 一并打包。部署包详见 `scripts/deploy-pack.js`。

## 环境变量

| 变量 | 说明 | 默认 |
|------|------|------|
| `PORT` | 服务端口 | 3000 |
| `API_KEY` | 管理端 API Key（可选），设置后 `/api/databases` 需带 `X-API-Key` | - |
| `SQLITE_DB_PATH` | 注册数据源与授权信息的 SQLite 路径 | `./data/sources.db` |

## API 接口

### 鉴权说明

- **`/api/databases`**：若配置 `API_KEY`，请求头需带 `X-API-Key: <API_KEY>`；未配置则免鉴权
- **`/api/query`**：请求头需带 `X-App-Key`、`X-App-Secret`，且该授权已绑定目标 `databaseId`；表/视图需在 `allowedTables` 允许范围内
- 注册数据源时自动创建默认 appKey/appSecret，响应中返回 `defaultAuth`

### 数据源管理

#### GET /api/databases

列出所有已注册数据源（不返回密码）。

**响应示例：**
```json
{
  "list": [
    {
      "id": "uuid",
      "name": "生产库",
      "dbType": "mysql",
      "host": "192.168.1.10",
      "port": 3306,
      "database": "mydb",
      "username": "readonly",
      "createdAt": "2025-02-11T...",
      "updatedAt": "2025-02-11T..."
    }
  ]
}
```

#### POST /api/databases

注册新数据源。SQLite 仅需 `name`、`dbType`、`database`（.db 文件路径）；其余类型需 `host`、`port`、`username`、`password`。

**请求体（非 SQLite）：**
```json
{
  "name": "生产库",
  "dbType": "mysql",
  "host": "192.168.1.10",
  "port": 3306,
  "database": "mydb",
  "username": "readonly",
  "password": "xxx"
}
```

**请求体（SQLite）：**
```json
{
  "name": "本地 SQLite",
  "dbType": "sqlite",
  "database": "./data/my.db"
}
```

**dbType 取值**：`sqlserver` | `oracle` | `mysql` | `postgresql` | `sqlite` | `cache`

**响应**：返回数据源元信息及 `defaultAuth: { name, appKey, appSecret }`

#### PUT /api/databases/:id

更新数据源（部分字段可选）。

#### DELETE /api/databases/:id

删除数据源。

---

### 只读查询

#### POST /api/query

按表/视图、字段、条件执行只读查询。需请求头 `X-App-Key`、`X-App-Secret`。

**请求体：**
```json
{
  "databaseId": "数据源ID",
  "tableOrView": "表名或视图名",
  "fields": "*",
  "conditions": { "status": "active", "amount": { "$gte": 100 } }
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| databaseId | string | 是 | 数据源 ID |
| tableOrView | string | 是 | 表名或视图名（需在 allowedTables 允许内） |
| fields | `"*"` \| string[] | 是 | 字段列表，`"*"` 表示全部 |
| conditions | object | 否 | 查询条件，支持 `$and`/`$or` 及操作符 |

**条件操作符**：`$eq`、`$ne`、`$lt`、`$gt`、`$lte`、`$gte`、`$like`、`$in`

**示例：**

```json
{
  "conditions": {
    "$and": [
      { "status": "active" },
      { "amount": { "$gte": 100, "$lt": 1000 } },
      { "name": { "$like": "%test%" } },
      { "id": { "$in": [1, 2, 3] } }
    ]
  }
}
```

```json
{
  "conditions": {
    "$or": [
      { "status": "draft" },
      { "status": "pending" }
    ]
  }
}
```

**响应：**
```json
{
  "data": [
    { "id": 1, "name": "xxx", "amount": 200 },
    ...
  ]
}
```

## 授权与 allowedTables

- 数据源注册时自动创建一条默认授权（`appKey: default`）
- 授权信息存储在 `database_authorizations` 表，可手工编辑 SQLite 添加更多 appKey/appSecret
- `allowedTables`：`*` 表示允许所有表；否则为逗号分隔的表名/视图名，仅可访问列表内对象

**为已有数据源补全授权**：
```bash
npm run backfill-auth
```

## 技术栈

- Node.js 18+、TypeScript、Express
- 驱动：mssql、oracledb（Thick 模式）、mysql2、pg、better-sqlite3、odbc（Caché/IRIS）