# 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-01-03

## 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

## 安装依赖
```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

  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