# ToolHub

**Repository Path**: cqg/tool-hub

## Basic Information

- **Project Name**: ToolHub
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ToolHub 企业应用商店

一个面向企业内部的应用分发平台：员工可浏览、搜索、下载工具软件，管理员可上传应用、管理分类与存储后端。前端 Vue3 + Vite，后端 Node.js（MySQL + 可选 MinIO/S3 对象存储）。

## 技术栈

| 层 | 技术 |
|----|------|
| 前端 | Vue 3.5 + Vite 6 + Vue Router 4 + Ant Design Vue 4 + Tailwind CSS 4 |
| 后端 | Node.js（原生 `http` + `busboy` 流式上传），运行入口 `server/server.mjs` |
| 数据库 | MySQL（通过 `mysql2` 连接池）|
| 对象存储 | 本地磁盘 或 兼容 S3 的 MinIO / AWS S3（预签名 URL 直链下载）|

## 目录结构

```
.
├── src/                 # 前端源码（Vue3 + Vite）
│   ├── views/           # 9 个页面：首页/详情/上传/管理/登录/设置...
│   ├── components/      # 公共组件 AppIcon/Layout/Sidebar/Topbar
│   ├── api/index.ts     # 后端接口封装 + 流式下载
│   ├── router/index.ts  # 前端路由
│   └── stores/auth.ts   # 登录态
├── server/              # 后端
│   ├── server.mjs       # ★ 实际运行的入口（MySQL 版）
│   ├── db.mjs           # MySQL 连接池 + 零依赖 .env 加载
│   ├── config.mjs       # 运行时配置（settings 表）
│   ├── s3.mjs           # MinIO/S3 签名上传下载
│   ├── storage.mjs      # 存储后端抽象（local / s3）
│   ├── init-db.mjs      # 建库建表脚本
│   ├── .env.example     # 配置模板（复制为 .env 使用）
│   └── src/             # 模块化重构（Express + SQLite，WIP，尚未启用）
├── index.html
├── vite.config.ts       # 前端开发服务器（:3000，代理 /api、/uploads → :3001）
└── package.json         # 前端依赖与脚本
```

## 环境要求

- **Node.js ≥ 18**（推荐 20+，开发环境使用 22）
- **MySQL ≥ 5.7**（数据库需提前可访问）
- 可选：**MinIO / 任意 S3 兼容服务**（使用对象存储时）
- 包管理器：`npm`

## 快速开始

### 1. 克隆仓库

```bash
git clone https://gitee.com/cqg/tool-hub.git
cd tool-hub
```

### 2. 配置后端环境变量

后端**不会**提交真实密钥，需要自行创建 `server/.env`：

```bash
cp server/.env.example server/.env
```

然后编辑 `server/.env`，至少填好数据库与存储两项（见下方「配置说明」）。

### 3. 初始化数据库

确保 `server/.env` 里的 `DB_*` 指向可达的 MySQL，然后执行建库建表：

```bash
cd server
npm install          # 安装后端依赖（mysql2 / busboy / jsonwebtoken 等）
node init-db.mjs     # 创建 toolhub 数据库及所有表
```

> `init-db.mjs` 会读取 `.env` 中的 `DB_HOST/DB_USER/DB_PASSWORD`，若缺失则回落到内置默认值。

### 4. 启动后端

```bash
cd server
node server.mjs
```

正常启动后监听 `http://localhost:3001`，可访问 `GET /api/health` 验证。

### 5. 启动前端

另开一个终端：

```bash
npm install          # 安装前端依赖
npm run dev          # 启动 Vite 开发服务器
```

前端默认运行在 `http://localhost:3000`，开发服务器已配置代理：
- `/api` → `http://localhost:3001`
- `/uploads` → `http://localhost:3001`

浏览器打开 `http://localhost:3000` 即可使用。

## 配置说明（`server/.env`）

| 变量 | 说明 | 示例 |
|------|------|------|
| `PORT` | 后端端口 | `3001` |
| `JWT_SECRET` | JWT 签名密钥（生产务必更换）| 任意随机串 |
| `DB_HOST` / `DB_PORT` | MySQL 地址与端口 | `127.0.0.1` / `3306` |
| `DB_USER` / `DB_PASSWORD` | MySQL 账号密码 | `root` / `******` |
| `DB_NAME` | 数据库名 | `toolhub` |
| `STORAGE_TYPE` | 存储类型：`local` 或 `s3` | `s3` |
| `STORAGE_ENDPOINT` | MinIO/S3 端点 | `http://10.67.67.244:9000` |
| `STORAGE_REGION` | 区域 | `us-east-1` |
| `STORAGE_ACCESS_KEY` / `STORAGE_SECRET_KEY` | 对象存储 AK/SK | `admin` / `******` |
| `STORAGE_BUCKET` | 存储桶 | `toolhub` |
| `STORAGE_PRESIGNED` | 是否用预签名 URL 直链下载（`true` 减轻后端带宽）| `true` |

> 存储后端也可在「系统设置」管理页面（需管理员）里可视化修改，无需改文件重启。

## 存储后端

- **local（本地磁盘）**：文件保存在 `server/uploads/`，适合单机部署。
- **s3（MinIO / AWS S3）**：上传/下载走对象存储，`STORAGE_PRESIGNED=true` 时下载返回预签名 URL 由浏览器直连，后端不转发文件流。跨域下载需 MinIO 配置允许前端域名的 CORS。

## 账号与权限

- 登录页可自助注册账号（`allow_register` 默认开启，可在系统设置关闭）。
- 管理员权限由 `users.role = 'admin'` 控制；如需将某账号设为管理员，直接在数据库执行：
  ```sql
  UPDATE users SET role = 'admin' WHERE email = '你的邮箱';
  ```

## 常见问题

- **后端起不来 / 报数据库连接错误**：确认 `server/.env` 的 `DB_*` 正确，且 MySQL 已启动、账号有建库权限；先跑一遍 `node init-db.mjs`。
- **前端调接口 404**：确认后端已在 `:3001` 运行，且 Vite 代理未被改掉（见 `vite.config.ts`）。
- **上传大文件失败（507 XMinioStorageFull）**：MinIO 磁盘空间不足，到 MinIO 主机释放/扩容后重启后端即可。

## 备注：模块化重构

`server/src/`（Express + better-sqlite3 + TypeScript）是一套更工整的模块化后端重构，**目前尚未启用**，线上服务仍由 `server/server.mjs` 提供。如需试用重构版：`cd server && npm run dev`（基于 `tsx watch`）。两套实现请勿混用数据库。