# storage_usage_tools

**Repository Path**: microbug/storage_usage_tools

## Basic Information

- **Project Name**: storage_usage_tools
- **Description**: 这是一个基于Flask的存储目录空间管理工具，用于监控和管理存储目录的空间使用情况。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-22
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 存储目录空间管理工具

## 项目简介
这是一个基于Flask的存储目录空间管理工具，用于监控和管理存储目录的空间使用情况。

## 基本功能
1. 连接MySQL数据库，读取存储相关数据表
2. 通过网页界面展示存储目录结构和空间使用情况
3. 计算指定目录结构下的总空间使用量
4. 生成存储使用趋势图
5. 支持目录前缀匹配和单位自动转换

## 技术栈
- Flask 2.3.3
- MySQL Connector Python 8.2.0
- Gunicorn 23.0.0（生产环境WSGI服务器）
- PyYAML 6.0.1

## 安装依赖

### 方式一：使用虚拟环境（推荐）

创建Python虚拟环境并安装依赖：

```bash
# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 退出虚拟环境（使用完毕后）
deactivate
```

### 方式二：直接安装（不推荐）

```bash
pip install -r requirements.txt
```

## 运行方式

### 1. 使用启动脚本（推荐）

项目提供了适用于不同操作系统的启动脚本，支持交互式选择运行模式：

#### Windows
```cmd
start_windows.cmd
```

#### Linux
```bash
chmod +x start_linux.sh
./start_linux.sh
```

#### macOS
```bash
chmod +x start_macos.sh
./start_macos.sh
```

启动脚本会自动检测并创建虚拟环境（如果不存在），然后根据用户选择启动应用。
- **开发模式**：默认模式，支持热重载，适合开发和调试
- **生产模式（前台运行）**：使用gunicorn运行，4个工作进程，适合测试生产环境
- **生产模式（后台运行）**：使用gunicorn后台运行，日志输出到gunicorn.log
- **停止生产模式**：停止后台运行的gunicorn进程

### 2. 手动运行（不推荐）

#### 开发模式（不推荐用于生产环境）
```bash
python3 app.py
```

- 开发服务器默认运行在 http://0.0.0.0:80
- 支持热重载，代码修改后自动重启
- 包含调试信息，便于开发和调试

#### 生产模式（推荐）
```bash
# 使用gunicorn运行，4个工作进程
python3 -m gunicorn -w 4 -b 0.0.0.0:80 app:app

# 可选：后台运行
nohup python3 -m gunicorn -w 4 -b 0.0.0.0:80 app:app > gunicorn.log 2>&1 &
```

- 生产级WSGI服务器，性能更好，更安全
- 支持多进程，提高并发处理能力
- 适合生产环境部署

### 3. Docker容器化运行（推荐用于生产环境）

项目提供了Dockerfile，可以方便地将应用打包为Docker容器：

#### 构建Docker镜像
```bash
docker build -t storage_usage_tools -f docker/Dockerfile .
```

#### 运行Docker容器
```bash
  docker run -d --name storage_usage_tools -p 80:80 -v /path/to/your/config.yaml:/app/config.yaml storage_usage_tools
```

- 容器默认使用端口80
- 容器没有内置`config.yaml`文件，需要通过挂载配置文件来配置应用
- 配置文件路径：`/app/config.yaml`

#### 查看容器日志
```bash
docker logs storage_usage_tools
```

#### 停止容器
```bash
docker stop storage_usage_tools
```

#### 移除容器
```bash
docker rm storage_usage_tools
```

## 停止方式

### 开发模式
- 在终端中按 `Ctrl + C` 停止

### 生产模式
```bash
# 查找gunicorn进程ID
ps aux | grep gunicorn

# 终止进程
kill -9 <进程ID>

# 或者使用pkill
pkill -f gunicorn
```

## 配置说明

### 配置文件
- 配置文件：`config.yaml`
- 包含数据库连接信息和其他配置项
- 示例配置：
  ```yaml
  database:
    host: x.x.x.x
    user: xxxx
    password: xxxx
    database: xxxx
  app:
    debug: true
    host: 0.0.0.0
    port: 80
  management_app:
    debug: true
    host: 0.0.0.0
    port: 8080
  storage:
    default_growth_rate: 1073741824  # 默认1GB/天
    decimal_places: 2  # 显示小数位数
  ```

### 配置文件位置
- 应用会自动读取当前目录下的`config.yaml`文件
- 不需要通过命令行参数或环境变量指定配置文件路径
- Docker部署时，应用会读取容器内`/app/config.yaml`文件

### 环境变量
- 可以通过环境变量覆盖配置文件中的设置

## 访问方式
- 网页访问：http://<服务器IP>:80（Docker部署）或 http://<服务器IP>:80（传统部署）
- API访问：支持RESTful API接口

## 主要功能模块

### 1. 存储系统信息展示
- 显示所有存储目录的最新空间使用情况
- 按使用率排序，方便查看占用率高的目录
- 展示预期写满时间和日增长率

### 2. 目录空间查询
- 支持手动输入目录结构
- 支持目录前缀匹配
- 实时计算并显示指定目录的总空间使用量

### 3. 存储使用趋势图
- 生成指定目录的空间使用趋势图
- 支持查看历史数据
- 可视化展示空间增长趋势

## 注意事项
1. 确保MySQL数据库连接信息正确
2. 生产环境建议使用gunicorn等生产级WSGI服务器
3. 定期备份数据库和配置文件
4. 根据实际需求调整gunicorn工作进程数量
5. 监控服务器资源使用情况，避免资源耗尽

## 故障排查
1. 查看日志文件：`gunicorn.log`（生产模式）
2. 检查数据库连接是否正常
3. 检查端口是否被占用：`lsof -i :80`
4. 检查配置文件格式是否正确

## 版本信息
- 当前版本：1.0.0
- 最后更新：2025-12-22

---

# 存储管理工具

这是一个基于Flask的Web应用程序，用于管理数据库中的存储标识和存储目录信息。

## 功能特性

1. **存储标识管理 (t_storage_identifier)**
   - 查看所有存储标识记录
   - 搜索存储标识和描述
   - 新增存储标识
   - 编辑存储标识信息
   - 删除存储标识

2. **存储目录管理 (t_storage_management)**
   - 查看所有存储目录记录
   - 搜索存储标识、目录、任务标识和描述
   - 新增存储目录
   - 编辑存储目录信息
   - 删除存储目录

3. **分页功能**
   - 每页显示10条记录
   - 支持上一页/下一页导航

## 文件结构

```
storage_usage_tools/
├── db_manager.py           # 数据库操作模块
├── management_app.py       # Flask Web应用主程序
├── templates/
│   └── management.html     # 管理界面HTML模板
├── config.yaml             # 配置文件
└── requirements.txt       # Python依赖包
```

## 配置说明

确保 `config.yaml` 文件中配置了正确的数据库连接信息和应用配置：

```yaml
database:
  host: "your_database_host"
  port: 3306
  user: "your_username"
  password: "your_password"
  database: "your_database"

management_app:
  debug: true
  host: 0.0.0.0
  port: 8080
```

配置说明：
- `database`: 数据库连接配置
- `management_app`: 存储管理工具的应用配置
  - `debug`: 调试模式（生产环境建议设为false）
  - `host`: 监听地址（0.0.0.0表示监听所有网络接口）
  - `port`: 监听端口

## 启动应用

```bash
./start_management.sh
```

或直接运行：

```bash
python3 management_app.py
```

应用将根据 `config.yaml` 中的配置启动，访问地址为 `http://<host>:<port>`。

## 使用说明

### 访问界面

在浏览器中打开 `http://<host>:<port>`（根据config.yaml中management_app配置的host和port）

### 存储标识管理

1. **查看记录**：页面加载后自动显示所有存储标识记录
2. **搜索**：在搜索框中输入关键词，点击"搜索"按钮
3. **新增**：点击"新增存储标识"按钮，填写表单并保存
4. **编辑**：点击记录的"编辑"按钮，修改信息后保存
5. **删除**：点击记录的"删除"按钮，确认后删除

### 存储目录管理

1. **切换标签**：点击"存储目录管理"标签
2. **查看记录**：显示所有存储目录记录
3. **搜索**：在搜索框中输入关键词，点击"搜索"按钮
4. **新增**：点击"新增存储目录"按钮，填写表单并保存
5. **编辑**：点击记录的"编辑"按钮，修改信息后保存
6. **删除**：点击记录的"删除"按钮，确认后删除

## API接口

### 存储标识接口

- `GET /api/storage_identifiers` - 获取存储标识列表
  - 参数：`search` (搜索关键词), `page` (页码), `per_page` (每页条数)
- `GET /api/storage_identifiers/<id>` - 获取单条存储标识
- `POST /api/storage_identifiers` - 创建存储标识
- `PUT /api/storage_identifiers/<id>` - 更新存储标识
- `DELETE /api/storage_identifiers/<id>` - 删除存储标识

### 存储目录接口

- `GET /api/storage_management` - 获取存储目录列表
  - 参数：`search` (搜索关键词), `page` (页码), `per_page` (每页条数)
- `GET /api/storage_management/<id>` - 获取单条存储目录
- `POST /api/storage_management` - 创建存储目录
- `PUT /api/storage_management/<id>` - 更新存储目录
- `DELETE /api/storage_management/<id>` - 删除存储目录

## 数据库表结构

### t_storage_identifier

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int(11) | 主键ID |
| storage_identifier | varchar(255) | 存储标识 |
| total_storage_capacity | bigint(20) | 总存储容量(字节) |
| description | varchar(255) | 描述 |

### t_storage_management

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int(11) | 主键ID |
| storage_identifier | varchar(255) | 存储标识 |
| directory | varchar(255) | 目录 |
| task_identifier | varchar(255) | 任务标识 |
| storage_occupy | bigint(20) | 存储占用(字节) |
| method | varchar(10) | 方法(du/df) |
| server_type | varchar(50) | 服务器类型 |
| description | text | 描述 |

## 注意事项

1. 确保MySQL数据库服务正在运行
2. 确保配置文件中的数据库连接信息正确
3. 删除操作不可恢复，请谨慎操作
4. 存储容量和存储占用字段以字节为单位
5. 应用会自动读取 `config.yaml` 文件中的 `management_app` 配置项