gcomneno/ubuntu-system-tools
GitHub: gcomneno/ubuntu-system-tools
一套以「默认只读、安全优先」为理念的 Ubuntu/Linux Bash 命令行工具集，提供开发产物清理审核、依赖引用查找、系统日志安全巡检和 CUPS 打印机诊断等实用功能。
Stars: 0 | Forks: 0
# ubuntu-system-tools
为 Ubuntu 和 Linux 提供的一小部分**极度谨慎、安全第一的系统实用工具**。
该项目专注于**检查、诊断和面向开发者的维护**，遵循保守的理念：
- **默认只读**
- **仅在明确同意时才执行更改状态的操作**
- **最小依赖**
- **可预测的 CLI 行为**
其目标是提供解决日常 Linux 问题的工具，而不会成为一个完整的系统管理框架。
## 理念
该代码仓库有意倾向于使用**小型、可组合的实用工具**，而不是大型自动化套件。
核心原则：
- 安全第一
- 尽可能保持只读
- 在执行破坏性操作前需明确确认
- 确定性行为
- 不进行隐藏的权限提升
- 由用户控制范围
如果某个命令会更改系统状态，则必须仅在用户明确要求时才执行。
## 安装
```
git clone https://github.com/gcomneno/ubuntu-system-tools
cd ubuntu-system-tools
make install PREFIX=$HOME/.local
```
卸载：
```
make uninstall PREFIX=$HOME/.local
```
## 快速示例
检查最近的安全相关事件：
```
security-health --since "24 hours ago"
```
查找某个依赖项或标识符的使用位置：
```
who-uses scan requests
```
预览可重新生成的开发者产物：
```
hdd_cleanup
```
在不删除任何内容的情况下审核可移除的开发产物：
```
garbage-collector ~/Progetti --max-depth 4
```
诊断 CUPS 打印机队列：
```
printer-doctor doctor
```
列出已配置的 CUPS 打印机：
```
printer-doctor list
```
恢复被禁用的 CUPS 队列：
```
printer-doctor repair
```
## 配置
创建本地配置：
```
make init-config
nano ~/.config/ubuntu-system-tools/config.env
```
加载它：
```
set -a
source ~/.config/ubuntu-system-tools/config.env
set +a
```
## 包含的工具
### `hdd_cleanup`
安全地识别可重新生成的开发者产物，例如 `node_modules/`、`.venv/`、`target/` 和常见缓存。
- 默认 dry-run
- 需要 `--apply` 才能执行删除
- 专为开发者工作区设计
### `garbage-collector`
用于扫描可移除开发产物（如 `.venv/`、`node_modules/`、`target/`、Python 缓存和构建输出）的只读扫描器。
- 仅审核
- 无删除模式
- 报告每个产物的大小
- 输出潜在的总体可回收空间
### `who-uses`
查找包、依赖项、二进制文件或标识符的引用位置。
功能：
- 项目扫描
- 依赖项检查
- 可选的系统检查
- JSON 输出
- 只读操作
### `security-health`
从本地系统日志检查最近的安全相关事件。
功能：
- sudo 活动
- 登录/登出事件
- 内核警告
- 可选的输出脱敏
### `printer-doctor`
与供应商无关的 CUPS 打印机队列诊断和恢复工具。
功能：
- 检查 CUPS 调度程序
- 列出已配置的打印机
- 检查已配置的打印机
- 检查队列
- 检测被禁用的队列
- 列出待处理的任务
- 明确恢复队列
- 确认后可选择取消卡住的任务
非目标：
- 清洁墨盒
- 喷嘴检查
- 特定于供应商的维护
- 专有驱动程序管理
## 环境要求
- Bash
- ripgrep (`rg`)
- python3
- systemd（可选）
- CUPS（仅用于 `printer-doctor`）
## 设计目标
每个实用工具都应该：
- 小巧
- 易于理解
- 可脚本化
- 确定性
- 默认安全
只要实际可行，工具都会通过 `--help-md` 提供独立的文档。
## 本代码仓库不会做的事情
- 没有自动安装
- 默认不执行破坏性操作
- 不进行服务管理
- 不进行隐藏的权限提升
- 不进行不安全的系统修改
如果您正在寻找一个自动化框架，这 intentionally 并非如此。
## 状态
稳定，规模 intentionally 小巧，且在缓慢演进。
## JSON 输出 (who-uses)
`who-uses scan --json` 会输出确定性的 JSON，其特点是：
- 无绝对路径
- 无匹配的文本
- 仅扫描项目
- 稳定的排序
退出代码：
- `0` = 未找到匹配项
- `1` = 找到匹配项
- `2` = 操作错误
## 安全提示
这些工具仅执行本地操作。
某些命令可能会显示敏感的本地信息（用户名、主机名、IP 地址、服务名称）。在公开分享之前，请先检查输出内容。
## 政策
参见 `POLICY.md`。
标签：Bash, 应用安全, 系统工具, 系统诊断, 运维脚本