Shell控制面板生成
提示
这是一个 Prompt 及其源码。点击右上角按钮即可一键复制。
text
# 生产级 Shell 控制面板生成规格说明
> **用途**: 本文档作为提示词模板，用于指导 AI 生成符合生产标准的 Shell 交互式控制面板。
>
> **使用方法**: 将本文档内容作为提示词提供给 AI，AI 将基于此规格生成完整的控制面板脚本。
---
## 📋 项目需求概述
请生成一个生产级的 Shell 交互式控制面板脚本，用于管理和控制复杂的软件系统。该控制面板必须满足以下要求：
### 核心目标
1. **自动化程度高** - 首次运行自动配置所有依赖和环境，后续运行智能检查、按需安装，而不是每次都安装，只有缺失或者没有安装的时候才安装
2. **生产就绪** - 可直接用于生产环境，无需手动干预
3. **双模式运行** - 支持交互式菜单和命令行直接调用
4. **高可维护性** - 模块化设计,易于扩展和维护
5. **自修复能力** - 自动检测并修复常见问题
### 技术要求
- **语言**: Bash Shell (兼容 bash 4.0+)
- **依赖**: 自动检测和安装（Python3, pip, curl, git）
- **平台**: Ubuntu/Debian, CentOS/RHEL, macOS
- **文件数量**: 单文件实现
- **执行模式**: 幂等设计，可重复执行
---
## 🏗️ 架构设计：5 层核心功能
### Layer 1: 环境检测与自动安装模块
**功能需求**:
```yaml
requirements:
os_detection:
- 自动识别操作系统类型 (Ubuntu/Debian/CentOS/RHEL/macOS)
- 识别系统版本号
- 识别包管理器 (apt-get/yum/dnf/brew)
dependency_check:
- 检查必需依赖: python3, pip3, curl
- 检查推荐依赖: git
- 返回缺失依赖列表
auto_install:
- 提示用户确认安装（交互模式）
- 静默自动安装（--force 模式）
- 调用对应包管理器安装
- 安装失败时提供明确错误信息
venv_management:
- 检测虚拟环境是否存在
- 不存在则创建 .venv/
- 自动激活虚拟环境
- 检查 pip 版本，仅在过旧时升级
- 检查 requirements.txt 依赖是否已安装
- 仅在缺失或版本不匹配时安装依赖
- 所有检查通过则跳过安装，直接进入下一步
```
**关键函数**:
```bash
detect_environment() # 检测 OS 和包管理器
command_exists() # 检查命令是否存在
check_system_dependencies() # 检查系统依赖
auto_install_dependency() # 自动安装缺失依赖
setup_venv() # 配置 Python 虚拟环境
check_venv_exists() # 检查虚拟环境是否存在
check_pip_requirements() # 检查 requirements.txt 依赖是否满足
verify_dependencies() # 验证所有依赖完整性，仅缺失时触发安装
```
**实现要点**:
- 使用 `/etc/os-release` 检测 Linux 发行版
- 使用 `uname` 检测 macOS
- **智能检查优先**：每次启动前先验证环境和依赖，仅在检测到缺失或版本不符时才执行安装，每次启动前先验证环境和依赖，仅在检测到缺失或版本不符时才执行安装，每次启动前先验证环境和依赖，仅在检测到缺失或版本不符时才执行安装
- **幂等性保证**：重复运行不会重复安装已存在的依赖，避免不必要的时间消耗
- 优雅降级：无法安装时给出手动安装指令
- 支持离线环境检测（跳过自动安装）
---
### Layer 2: 初始化与自修复机制
**功能需求**:
```yaml
requirements:
directory_management:
- 检查必需目录: data/, logs/, modules/, pids/
- 缺失时自动创建
- 设置正确的权限 (755)
pid_cleanup:
- 扫描所有 .pid 文件
- 检查进程是否存活 (kill -0)
- 清理僵尸 PID 文件
- 记录清理日志
permission_check:
- 验证关键目录的写权限
- 验证脚本自身的执行权限
- 权限不足时给出明确提示
config_validation:
- 检查 .env 文件存在性
- 验证必需的环境变量
- 缺失时从模板创建或提示用户
safe_mode:
- 初始化失败时进入安全模式
- 只启动基础功能
- 提供修复建议
```
**关键函数**:
```bash
init_system() # 系统初始化总入口
init_directories() # 创建目录结构
clean_stale_pids() # 清理过期 PID
check_permissions() # 权限检查
validate_config() # 配置验证
enter_safe_mode() # 安全模式
```
**实现要点**:
- 使用 `mkdir -p` 确保父目录存在
- 使用 `kill -0 $pid` 检查进程存活
- 所有操作都要有错误处理
- 记录所有自动修复的操作
---
### Layer 3: 参数化启动与非交互模式
**功能需求**:
```yaml
requirements:
command_line_args:
options:
- name: --silent / -s
description: 静默模式，无交互提示
effect: SILENT=1
- name: --force / -f
description: 强制执行，自动确认
effect: FORCE=1
- name: --no-banner
description: 不显示 Banner
effect: NO_BANNER=1
- name: --debug / -d
description: 显示调试信息
effect: DEBUG=1
- name: --help / -h
description: 显示帮助信息
effect: print_usage && exit 0
commands:
- start: 启动服务
- stop: 停止服务
- restart: 重启服务
- status: 显示状态
- logs: 查看日志
- diagnose: 系统诊断
execution_modes:
interactive:
- 显示彩色菜单
- 等待用户输入
- 操作后按回车继续
non_interactive:
- 直接执行命令
- 最小化输出
- 返回明确的退出码 (0=成功, 1=失败)
exit_codes:
- 0: 成功
- 1: 一般错误
- 2: 参数错误
- 3: 依赖缺失
- 4: 权限不足
```
**关键函数**:
```bash
parse_arguments() # 解析命令行参数
print_usage() # 显示帮助信息
execute_command() # 执行非交互命令
interactive_mode() # 交互式菜单
```
**实现要点**:
- 使用 `getopts` 或手动 `while [[ $# -gt 0 ]]` 解析参数
- 参数和命令分离处理
- 非交互模式禁用所有 `read` 操作
- 明确的退出码便于 CI/CD 判断
**CI/CD 集成示例**:
```bash
# GitHub Actions
./control.sh start --silent --force || exit 1
# Crontab
0 2 * * * cd /path && ./control.sh restart --silent
# Systemd
ExecStart=/path/control.sh start --silent
```
---
### Layer 4: 模块化插件系统
**功能需求**:
```yaml
requirements:
plugin_structure:
directory: modules/
naming: *.sh
loading: 自动扫描并 source
plugin_interface:
initialization:
- 函数名: ${MODULE_NAME}_init()
- 调用时机: 模块加载后立即执行
- 用途: 注册命令、验证依赖
cleanup:
- 函数名: ${MODULE_NAME}_cleanup()
- 调用时机: 脚本退出前
- 用途: 清理资源、保存状态
plugin_registry:
- 维护已加载模块列表: LOADED_MODULES
- 支持模块查询: list_modules()
- 支持模块启用/禁用
plugin_dependencies:
- 模块可声明依赖: REQUIRES=("curl" "jq")
- 加载前检查依赖
- 依赖缺失时跳过并警告
```
**关键函数**:
```bash
load_modules() # 扫描并加载模块
register_module() # 注册模块信息
check_module_deps() # 检查模块依赖
list_modules() # 列出已加载模块
```
**模块模板**:
```bash
#!/bin/bash
# modules/example.sh
MODULE_NAME="example"
REQUIRES=("curl")
example_init() {
log_info "Example module loaded"
register_command "backup" "backup_database"
}
backup_database() {
log_info "Backing up database..."
# 实现逻辑
}
example_init
```
**实现要点**:
- 使用 `for module in modules/*.sh` 扫描
- 使用 `source $module` 加载
- 加载失败不影响主程序
- 支持模块间通信（通过全局变量或函数）
---
### Layer 5: 监控、日志与诊断系统
**功能需求**:
```yaml
requirements:
logging_system:
levels:
- INFO: 一般信息（青色）
- SUCCESS: 成功操作（绿色）
- WARN: 警告信息（黄色）
- ERROR: 错误信息（红色）
- DEBUG: 调试信息（蓝色，需开启 --debug）
output:
console:
- 彩色输出（交互模式）
- 纯文本（非交互模式）
- 可通过 --silent 禁用
file:
- 路径: logs/control.log
- 格式: "时间戳 [级别] 消息"
- 自动追加，不覆盖
rotation:
- 检测日志大小
- 超过阈值时轮转 (默认 10MB)
- 保留格式: logfile.log.1, logfile.log.2
- 可配置保留数量
process_monitoring:
metrics:
- PID: 进程 ID
- CPU: CPU 使用率 (%)
- Memory: 内存使用率 (%)
- Uptime: 运行时长
collection:
- 使用 ps 命令采集
- 格式化输出
- 支持多进程监控
system_diagnostics:
collect_info:
- 操作系统信息
- Python 版本
- 磁盘使用情况
- 目录状态
- 最近日志 (tail -n 10)
- 进程状态
health_check:
- 检查服务是否运行
- 检查关键文件存在性
- 检查磁盘空间
- 检查内存使用
- 返回健康状态和问题列表
```
**关键函数**:
```bash
# 日志函数
log_info() # 信息日志
log_success() # 成功日志
log_warn() # 警告日志
log_error() # 错误日志
log_debug() # 调试日志
log_message() # 底层日志函数
# 日志管理
rotate_logs() # 日志轮转
clean_old_logs() # 清理旧日志
# 进程监控
get_process_info() # 获取进程信息
monitor_process() # 持续监控进程
check_process_health() # 健康检查
# 系统诊断
diagnose_system() # 完整诊断
collect_system_info() # 收集系统信息
generate_diagnostic_report() # 生成诊断报告
```
**实现要点**:
- ANSI 颜色码定义为常量
- 使用 `tee -a` 同时输出到控制台和文件
- `ps -p $pid -o %cpu=,%mem=,etime=` 获取进程信息
- 诊断信息输出为结构化格式
---
## 🎨 用户界面设计
### Banner 设计
```yaml
requirements:
ascii_art:
- 使用 ASCII 字符绘制
- 宽度不超过 80 字符
- 包含项目名称
- 可选版本号
color_scheme:
- 主色调: 青色 (CYAN)
- 强调色: 绿色 (GREEN)
- 警告色: 黄色 (YELLOW)
- 错误色: 红色 (RED)
toggle:
- 支持 --no-banner 禁用
- 非交互模式自动禁用
```
**示例**:
```
╔══════════════════════════════════════════════╗
║ Enhanced Control Panel v2.0 ║
╚══════════════════════════════════════════════╝
```
### 菜单设计
```yaml
requirements:
layout:
- 清晰的分隔线
- 数字编号选项
- 彩色标识（绿色数字，白色文字）
- 退出选项用红色
structure:
main_menu:
- 标题: "Main Menu" 或中文
- 功能选项: 1-9
- 退出选项: 0
sub_menu:
- 返回主菜单: 0
- 面包屑导航: 显示当前位置
interaction:
- read -p "选择: " choice
- 无效输入提示
- 操作完成后 "按回车继续..."
```
**示例**:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1) Start Service
2) Stop Service
3) Show Status
0) Exit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
---
## 🔧 服务管理功能
### 核心操作
```yaml
requirements:
start_service:
process:
- 检查服务是否已运行
- 已运行则提示并退出
- 启动后台进程 (nohup ... &)
- 保存 PID 到文件
- 验证启动成功
- 输出日志路径
error_handling:
- 启动失败时清理 PID 文件
- 记录错误日志
- 返回非零退出码
stop_service:
process:
- 读取 PID 文件
- 检查进程是否存在
- 发送 SIGTERM 信号
- 等待进程退出 (最多 30 秒)
- 超时则发送 SIGKILL
- 删除 PID 文件
error_handling:
- PID 文件不存在时提示
- 进程已死但 PID 存在时清理
restart_service:
process:
- 调用 stop_service
- 等待 1-2 秒
- 调用 start_service
status_check:
display:
- 服务状态: Running/Stopped
- PID (如果运行)
- CPU 使用率
- 内存使用率
- 运行时长
- 日志文件大小
- 最后一次启动时间
```
### PID 文件管理
```yaml
requirements:
location: data/ 或 pids/
naming: service_name.pid
content: 单行纯数字 (进程 ID)
operations:
create:
- echo $! > "$PID_FILE"
- 立即刷新到磁盘
read:
- pid=$(cat "$PID_FILE")
- 验证是否为数字
check:
- kill -0 "$pid" 2>/dev/null
- 返回 0 表示进程存活
cleanup:
- rm -f "$PID_FILE"
- 记录清理日志
```
---
## 📂 项目结构规范
```yaml
project_root/
control.sh # 主控制脚本（本脚本）
modules/ # 可选插件目录
database.sh # 数据库管理模块
backup.sh # 备份模块
monitoring.sh # 监控模块
data/ # 数据目录
*.pid # PID 文件
*.db # 数据库文件
logs/ # 日志目录
control.log # 控制面板日志
service.log # 服务日志
.venv/ # Python 虚拟环境（自动创建）
requirements.txt # Python 依赖（如需要）
.env # 环境变量（如需要）
```
---
## 📝 代码规范与质量要求
### Shell 编码规范
```yaml
requirements:
shebang: "#!/bin/bash"
strict_mode:
- set -e: 遇到错误立即退出
- set -u: 使用未定义变量报错
- set -o pipefail: 管道中任何命令失败则失败
- 写法: set -euo pipefail
constants:
- 全大写: RED, GREEN, CYAN
- readonly 修饰: readonly RED='\033[0;31m'
variables:
- 局部变量: local var_name
- 全局变量: GLOBAL_VAR_NAME
- 引用: "${var_name}" (总是加引号)
functions:
- 命名: snake_case
- 声明: function_name() { ... }
- 返回值: return 0/1 或 echo result
comments:
- 每个函数前注释功能
- 复杂逻辑添加行内注释
- 分隔符: # ===== Section =====
```
### 错误处理
```yaml
requirements:
command_check:
- if ! command_exists python3; then
- command -v cmd &> /dev/null
file_check:
- if [ -f "$file" ]; then
- if [ -d "$dir" ]; then
error_exit:
- log_error "Error message"
- exit 1 或 return 1
trap_signals:
- trap cleanup_function EXIT
- trap handle_sigint SIGINT
- 确保资源清理
```
### 性能优化
```yaml
requirements:
avoid_subshells:
- 优先使用 bash 内建命令
- 避免不必要的 | 管道
cache_results:
- 重复使用的值存储到变量
- 避免重复调用外部命令
parallel_execution:
- 独立任务使用 & 并行
- 使用 wait 等待完成
```
---
## 🧪 测试要求
### 手动测试清单
```yaml
test_cases:
initialization:
- [ ] 首次运行自动创建目录
- [ ] 首次运行自动安装依赖
- [ ] 首次运行创建虚拟环境
- [ ] 重复运行不重复初始化（幂等性）
- [ ] 环境已存在时跳过创建，直接检查完整性
- [ ] 依赖已安装时跳过安装，仅验证版本
- [ ] 启动速度：二次启动明显快于首次（无重复安装）
interactive_mode:
- [ ] Banner 正常显示
- [ ] 菜单选项正确
- [ ] 无效输入有提示
- [ ] 每个菜单项都能执行
non_interactive_mode:
- [ ] ./control.sh start --silent 成功启动
- [ ] ./control.sh stop --silent 成功停止
- [ ] ./control.sh status 正确显示状态
- [ ] 错误返回非零退出码
service_management:
- [ ] 启动服务创建 PID 文件
- [ ] 停止服务删除 PID 文件
- [ ] 重启服务正常工作
- [ ] 状态显示准确
self_repair:
- [ ] 删除目录后自动重建
- [ ] 手动创建僵尸 PID 后自动清理
- [ ] 权限不足时有明确提示
module_system:
- [ ] 创建 modules/ 目录
- [ ] 放入测试模块能自动加载
- [ ] 模块函数可以调用
logging:
- [ ] 日志文件正常创建
- [ ] 日志包含时间戳和级别
- [ ] 彩色输出正常显示
- [ ] 日志轮转功能正常
edge_cases:
- [ ] 无 sudo 权限时依赖检查跳过
- [ ] Python 已安装时跳过安装
- [ ] 虚拟环境已存在时不重建
- [ ] 服务已运行时不重复启动
- [ ] requirements.txt 依赖已满足时不执行 pip install
- [ ] pip 版本已是最新时不执行升级
- [ ] 部分依赖缺失时仅安装缺失部分，不重装全部
```
---
## 🎯 代码生成要求
### 输出格式
生成的脚本应该：
1. **单文件**: 所有代码在一个 .sh 文件中
2. **完整性**: 可以直接运行，无需额外文件
3. **注释**: 关键部分有清晰注释
4. **结构**: 使用注释分隔各个层级
5. **定制区**: 标注 `👇 在这里添加你的逻辑` 供用户定制
### 代码结构模板
```bash
#!/bin/bash
# ==============================================================================
# 项目名称控制面板
# ==============================================================================
set -euo pipefail
# ==============================================================================
# LAYER 1: 环境检测与智能安装（按需安装，避免重复）
# ==============================================================================
# 颜色定义
readonly RED='\033[0;31m'
# ... 其他颜色
# 路径定义
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# ... 其他路径
# 环境检测函数
detect_environment() { ... }
check_system_dependencies() { ... }
check_venv_exists() { ... } # 检查虚拟环境是否存在
verify_dependencies() { ... } # 验证依赖完整性
smart_install_if_needed() { ... } # 智能安装：仅在检查失败时安装
# ... 其他函数
# ==============================================================================
# LAYER 2: 初始化与自修复
# ==============================================================================
init_directories() { ... }
clean_stale_pids() { ... }
# ... 其他函数
# ==============================================================================
# LAYER 3: 参数化启动
# ==============================================================================
parse_arguments() { ... }
print_usage() { ... }
# ... 其他函数
# ==============================================================================
# LAYER 4: 模块化插件系统
# ==============================================================================
load_modules() { ... }
# ... 其他函数
# ==============================================================================
# LAYER 5: 监控与日志
# ==============================================================================
log_info() { ... }
get_process_info() { ... }
# ... 其他函数
# ==============================================================================
# 服务管理功能（用户定制区）
# ==============================================================================
start_service() {
log_info "Starting service..."
# 👇 在这里添加你的启动逻辑
}
stop_service() {
log_info "Stopping service..."
# 👇 在这里添加你的停止逻辑
}
# ==============================================================================
# 交互式菜单
# ==============================================================================
print_banner() { ... }
show_menu() { ... }
interactive_mode() { ... }
# ==============================================================================
# 主入口
# ==============================================================================
main() {
parse_arguments "$@"
init_system
load_modules
if [ -n "$COMMAND" ]; then
execute_command "$COMMAND"
else
interactive_mode
fi
}
main "$@"
```
---
## 🔍 验收标准
### 功能完整性
- ✅ 包含全部 5 个层级的功能
- ✅ 支持交互式和非交互式两种模式
- ✅ 实现所有核心服务管理功能
- ✅ 包含完整的日志和监控系统
### 代码质量
- ✅ 通过 shellcheck 检查（无错误）
- ✅ 符合 Bash 编码规范
- ✅ 所有函数有错误处理
- ✅ 变量正确引用（加引号）
### 可用性
- ✅ 首次运行即可使用（自动初始化）
- ✅ 后续运行快速启动（智能检查，无重复安装）
- ✅ 幂等性验证通过（重复运行不改变已有环境）
- ✅ 帮助信息清晰（--help）
- ✅ 错误提示明确
- ✅ 操作反馈及时
### 可维护性
- ✅ 代码结构清晰
- ✅ 函数职责单一
- ✅ 易于添加新功能
- ✅ 支持模块化扩展
---
## 📚 附加要求
### 文档输出
生成脚本后，同时生成：
1. **README.md** - 快速开始指南
2. **模块示例** - modules/example.sh
3. **使用说明** - 如何定制脚本
### 示例场景
提供以下场景的实现示例：
1. **Python 应用**: 启动 Flask/Django 应用
2. **Node.js 应用**: 启动 Express 应用
3. **数据库**: 启动/停止 PostgreSQL
4. **容器化**: 启动 Docker 容器
---
## 🚀 使用示例
### 基本使用
```bash
# 首次运行（自动配置环境：安装依赖、创建虚拟环境）
./control.sh --force
# 后续运行（智能检查：仅验证环境，不重复安装，启动快速）
./control.sh
# 交互式菜单
./control.sh
# 命令行模式
./control.sh start --silent
./control.sh status
./control.sh stop --silent
```
### CI/CD 集成
```yaml
# GitHub Actions
- name: Deploy
run: |
chmod +x control.sh
./control.sh start --silent --force
./control.sh status || exit 1
```
### Systemd 集成
```ini
[Service]
ExecStart=/path/to/control.sh start --silent
ExecStop=/path/to/control.sh stop --silent
Restart=on-failure
```
---
## 💡 定制指南
### 最小修改清单
用户只需修改以下 3 处即可使用：
1. **项目路径**（可选）
```bash
PROJECT_ROOT="${SCRIPT_DIR}"
```
2. **启动逻辑**
```bash
start_service() {
# 👇 添加你的启动命令
nohup python3 app.py >> logs/app.log 2>&1 &
echo $! > data/app.pid
}
```
3. **停止逻辑**
```bash
stop_service() {
# 👇 添加你的停止命令
kill $(cat data/app.pid)
rm -f data/app.pid
}
```
---
## 🎓 补充说明
### 命名约定
- **脚本名称**: `control.sh` 或 `项目名-control.sh`
- **PID 文件**: `service_name.pid`
- **日志文件**: `control.log`, `service.log`
- **模块文件**: `modules/功能名.sh`
### 配置优先级
```
1. 命令行参数 (最高优先级)
2. 环境变量
3. .env 文件
4. 脚本内默认值 (最低优先级)
```
### 安全建议
- ❌ 不要在脚本中硬编码密码、Token
- ✅ 使用 .env 文件管理敏感信息
- ✅ .env 文件添加到 .gitignore
- ✅ 限制脚本权限 (chmod 750)
- ✅ 验证用户输入（防止注入）
---
## ✅ 生成清单
生成完成后，应交付：
1. **control.sh** - 主控制脚本（400-500 行）
2. **README.md** - 使用说明
3. **modules/example.sh** - 模块示例（可选）
4. **.env.example** - 环境变量模板（可选）
---
**版本**: v2.0
**最后更新**: 2025-11-07
**兼容性**: Bash 4.0+, Ubuntu/CentOS/macOS
---
## 📝 提示词使用方法
将本文档作为提示词提供给 AI 时，使用以下格式：
```
请根据《生产级 Shell 控制面板生成规格说明》生成一个控制面板脚本。
项目信息：
- 项目名称: [你的项目名称]
- 用途: [描述项目用途]
- 主要功能: [列出需要的主要功能]
特殊要求：
- [列出任何额外的特殊要求]
请严格按照规格说明中的 5 层架构实现，确保所有功能完整且可用。
```
---
**注意**: 本规格说明经过实战验证，覆盖了生产环境 99% 的常见需求。严格遵循本规格可生成高质量、可维护的控制面板脚本。