998 lines
24 KiB
Markdown
998 lines
24 KiB
Markdown
# 生产级 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% 的常见需求。严格遵循本规格可生成高质量、可维护的控制面板脚本。
|