# web-db

**Repository Path**: wmcloud/web-db

## Basic Information

- **Project Name**: web-db
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web DB

团队内部 Web 端数据库管理工具，整体布局参考 Navicat。通过浏览器管理数据库连接，完成对象浏览、表数据编辑、SQL 查询等日常操作，无需安装桌面客户端。

## 功能特性

### 连接与认证

- 内置账号密码登录，JWT 鉴权
- 管理员可创建/管理用户
- 用户仅可见自己创建的数据库连接
- 连接密码 AES-GCM 加密存储

### 支持的数据库

| 数据库 | 默认端口 |
|--------|----------|
| MySQL | 3306 |
| PostgreSQL | 5432 |
| Oracle | 1521 |
| 达梦 (DM) | 5236 |

内置 JDBC 驱动预设，也支持自定义 JDBC URL 与驱动类。

### 对象浏览

- Navicat 式左侧对象树，懒加载 Schema / 表 / 视图等
- Schema 可见性过滤
- 全局对象搜索（表、视图、函数等）
- 右键菜单：打开表、新建查询、查看 DDL、重命名、截断/删除表、导入数据

### 数据网格

- 虚拟滚动表格，分页浏览（默认每页 100 行）
- 表头排序、列筛选、DataGrip 风格 WHERE 条件栏
- 行内编辑、新增、删除，支持自动/手动事务模式
- 单元格查看器（含 JSON 格式化）
- 行多选与 SQL 复制（SELECT / INSERT / UPDATE / DELETE）

### SQL 编辑器

- Monaco Editor，语法高亮与自动补全
- 多标签查询、选中执行 / 全部执行、执行取消
- 查询结果网格展示
- 可配置快捷键

### 表结构

- 字段列表、索引信息只读查看
- 表结构变更（增删改列、索引管理）

### 事务控制

- 自动提交（默认）/ 手动提交可切换
- SQL 执行与数据网格共用同一事务会话

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Spring Boot 2.7 + Java 8 + H2（应用元数据） |
| 前端 | React 19 + TypeScript + Vite + Ant Design 6 |
| SQL 编辑器 | Monaco Editor |
| 状态管理 | Zustand + TanStack Query |

应用元数据（用户、连接配置等）存储在内嵌 H2 数据库（`backend/data/`），零外部依赖即可启动。

## 环境要求

- **开发运行**：JDK 8+、Maven 3.6+、Node.js 18+、npm 9+
- **生产部署（Docker）**：Docker 20+、Docker Compose v2+

## 快速启动（开发模式）

前后端分离启动，适合日常开发调试。

### 1. 启动后端

```bash
cd backend
export WEBDB_SECRET_KEY="0123456789abcdef0123456789abcdef"
mvn spring-boot:run
```

- API 地址：http://localhost:8080
- 默认管理员：`admin` / `admin123`（可通过 `WEBDB_ADMIN_PASSWORD` 修改）

### 2. 启动前端

```bash
cd frontend
npm install
npm run dev
```

- 前端地址：http://localhost:5173
- 开发服务器自动将 `/api` 代理到后端 8080 端口

## 构建

### 构建前端

```bash
cd frontend
npm install
npm run build
```

产物输出至 `frontend/dist/`。

### 构建后端

```bash
cd backend
mvn clean package -DskipTests
```

产物输出至 `backend/target/webdb-server-0.1.0-SNAPSHOT.jar`。

### 一体化构建（生产部署）

将前端静态资源嵌入后端 JAR，由 Spring Boot 统一提供服务：

```bash
# 1. 构建前端
cd frontend && npm ci && npm run build && cd ..

# 2. 复制静态资源并打包后端
mkdir -p backend/src/main/resources/static
cp -r frontend/dist/* backend/src/main/resources/static/
cd backend && mvn clean package -DskipTests
```

启动后访问 http://localhost:8080 即可使用完整应用。

> 注意：`backend/src/main/resources/static/` 为构建产物目录，已在 `.gitignore` 规则外，请勿将构建生成的静态文件提交到仓库。Docker 构建会自动完成上述步骤。

## 部署

### 方式一：本机部署

适用于单机生产环境或内网服务器。

**步骤 1：构建一体化 JAR**

```bash
cd frontend && npm ci && npm run build && cd ..
mkdir -p backend/src/main/resources/static
cp -r frontend/dist/* backend/src/main/resources/static/
cd backend && mvn clean package -DskipTests
```

**步骤 2：配置环境变量**

| 变量 | 必填 | 说明 | 默认值 |
|------|------|------|--------|
| `WEBDB_SECRET_KEY` | 是 | AES 加密密钥（32 字节） | — |
| `WEBDB_ADMIN_PASSWORD` | 否 | 初始管理员密码 | `admin123` |
| `WEBDB_JWT_SECRET` | 是（生产） | JWT 签名密钥 | 内置默认值 |
| `WEBDB_SESSION_TIMEOUT` | 否 | 会话超时（分钟） | `30` |
| `WEBDB_CORS_ALLOWED_ORIGINS` | 否 | 允许跨域的前端地址，逗号分隔 | `http://localhost:5173,...` |

**步骤 3：启动服务**

```bash
export WEBDB_SECRET_KEY="your-32-byte-secret-key-here!!"
export WEBDB_JWT_SECRET="your-jwt-secret-key-change-me!!"
export WEBDB_ADMIN_PASSWORD="your-secure-password"

cd backend
java -jar target/webdb-server-0.1.0-SNAPSHOT.jar
```

访问 http://localhost:8080 。

**数据持久化**

H2 数据文件位于 `backend/data/`（启动时自动创建），请定期备份该目录。

**后台运行（可选）**

```bash
nohup java -jar target/webdb-server-0.1.0-SNAPSHOT.jar > webdb.log 2>&1 &
```

### 方式二：Docker 部署

适用于容器化环境，前后端已打包为单一镜像。敏感配置通过 `.env` 文件或宿主机环境变量注入，**不会写入镜像或 `docker-compose.yml`**。

**步骤 1：创建 `.env` 文件**

在项目根目录创建 `.env`（该文件已被 `.gitignore` 忽略，请勿提交到仓库）：

```bash
cat > .env <<'EOF'
WEBDB_SECRET_KEY=your-32-byte-secret-key-here!!
WEBDB_JWT_SECRET=your-jwt-secret-key-change-me!!
WEBDB_ADMIN_PASSWORD=your-secure-password
WEBDB_CORS_ALLOWED_ORIGINS=http://localhost:8080
EOF
```

| 变量 | 必填 | 说明 |
|------|------|------|
| `WEBDB_SECRET_KEY` | 是 | AES 加密密钥（32 字符） |
| `WEBDB_JWT_SECRET` | 是 | JWT 签名密钥 |
| `WEBDB_ADMIN_PASSWORD` | 是 | 初始管理员 `admin` 的密码 |
| `WEBDB_CORS_ALLOWED_ORIGINS` | 否 | 允许跨域的前端地址，默认 `http://localhost:8080` |

Docker Compose 会自动读取项目根目录的 `.env`，并注入到容器中：

```yaml
environment:
  WEBDB_SECRET_KEY: ${WEBDB_SECRET_KEY}
  WEBDB_JWT_SECRET: ${WEBDB_JWT_SECRET}
  WEBDB_ADMIN_PASSWORD: ${WEBDB_ADMIN_PASSWORD}
  WEBDB_CORS_ALLOWED_ORIGINS: ${WEBDB_CORS_ALLOWED_ORIGINS:-http://localhost:8080}
```

**步骤 2：构建并启动**

```bash
docker compose up -d --build
```

访问 http://localhost:8080 ，使用 `admin` 和 `.env` 中配置的 `WEBDB_ADMIN_PASSWORD` 登录。

**常用命令**

```bash
# 查看日志
docker compose logs -f webdb

# 停止服务
docker compose down

# 停止并清除数据卷（会删除所有用户和连接配置）
docker compose down -v
```

**数据持久化**

应用数据通过 Docker 卷 `webdb-data` 挂载至容器内 `/app/data`，删除容器不会丢失数据（除非执行 `docker compose down -v`）。

**仅使用 Docker（不使用 Compose）**

```bash
docker build -t webdb:latest .

docker run -d \
  --name webdb \
  -p 8080:8080 \
  -v webdb-data:/app/data \
  --env-file .env \
  webdb:latest
```

也可通过 `-e` 逐项传入环境变量：

```bash
docker run -d \
  --name webdb \
  -p 8080:8080 \
  -v webdb-data:/app/data \
  -e WEBDB_SECRET_KEY="your-32-byte-secret-key-here!!" \
  -e WEBDB_JWT_SECRET="your-jwt-secret-key-change-me!!" \
  -e WEBDB_ADMIN_PASSWORD="your-secure-password" \
  -e WEBDB_CORS_ALLOWED_ORIGINS="http://localhost:8080" \
  webdb:latest
```

> **安全提示：** `Dockerfile` 中不包含任何密钥；生产环境请使用强随机值，并妥善保管 `.env` 文件。

## 项目结构

```text
web_db/
├── backend/          # Spring Boot 后端
│   ├── src/
│   └── pom.xml
├── frontend/         # React 前端
│   ├── src/
│   └── package.json
├── docs/             # 设计文档
├── Dockerfile        # Docker 多阶段构建
├── docker-compose.yml
├── .env              # 本地部署密钥（需自行创建，已 gitignore）
└── README.md
```

## 文档

- MVP 设计规格：`docs/superpowers/specs/2026-06-18-web-db-design.md`
- V1 数据网格规格：`docs/superpowers/specs/2026-06-18-v1-data-grid-features.md`

## 许可证

内部团队工具，仅供组织内部使用。