# shell-ready

**Repository Path**: ricsy/shell-ready

## Basic Information

- **Project Name**: shell-ready
- **Description**: No description available
- **Primary Language**: Shell
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-07
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# shell-ready - 自动化环境部署工具

<p style="text-align:center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue.svg" alt="Version">
  <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS-green.svg" alt="Platform">
  <img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License">
</p>

> 一键部署标准化开发环境，告别重复配置，开箱即用。支持全量部署和按需安装，完全配置驱动，无需修改脚本代码。

## ✨ 核心特性

- 🎯 **多系统兼容**：同时支持 Linux (Ubuntu/CentOS/RHEL) 和 macOS 系统
- 🧩 **模块化设计**：核心引擎和业务模块完全分离，易扩展易维护
- ⚙️ **配置驱动**：所有配置集中在 `config.yaml`，自定义部署内容无需改代码
- 🔒 **生产级可靠**：脚本具备幂等性，多次运行不会出错，完善的错误处理机制
- 📝 **完整日志**：彩色分级日志，所有操作自动存档，便于审计和问题排查
- 🚀 **CI/CD 友好**：内置代码质量检查、格式化、Docker 镜像构建等完整工具链
- 🎨 **灵活部署**：支持全量部署、按需部署指定模块、干跑预览等多种运行模式
- 🛠️ **开箱即用**：内置常用开发工具栈，覆盖终端、包管理、AI 服务等常见场景

## 📁 目录结构

```
shell-ready/
├── install.sh              # 主入口脚本
├── config.yaml             # 统一配置文件（所有自定义修改都在这里）
├── package.json            # NPM 命令配置
├── Dockerfile              # 容器化部署镜像
├── core/                   # 核心引擎层（无需修改）
│   ├── constants.sh        # 全局常量、路径、退出码定义
│   └── engine.sh           # 核心能力：日志系统、配置解析、任务调度、工具函数
├── modules/                # 业务模块层（可按需扩展）
│   ├── base.sh             # 基础依赖：自动安装 jq/yq/curl 等公共依赖
│   ├── git.sh              # Git 版本控制工具模块
│   ├── ohmyzsh.sh          # Oh My Zsh 终端增强模块
│   ├── npm.sh              # NPM/Node.js 环境模块
│   ├── brew.sh             # Homebrew macOS 包管理器模块
│   ├── ollama.sh           # Ollama 本地大模型服务模块
│   └── openclaw.sh         # OpenClaw AI 网关服务模块
├── scripts/                # 辅助工具脚本
│   ├── shfmt.sh            # Shell 脚本格式检查/自动修复
│   ├── shellcheck.sh       # Shell 脚本静态代码检查
│   ├── lint.sh             # 统一代码质量检查入口
│   ├── format.sh           # 统一代码格式化入口
│   └── build-docker.sh     # Docker 镜像构建脚本
└── logs/                   # 运行日志自动存档目录（自动生成）
```

## 🚀 快速开始

### 环境要求

- Linux/macOS 系统
- Bash 4.0+
- Root 或 sudo 权限（安装系统包时需要）

### 安装使用

#### 1. 克隆项目

```bash
git clone https://github.com/ricsy/shell-ready.git
cd shell-ready
```

#### 2. 自定义配置（可选）

编辑 `config.yaml` 文件：

- 在 `run` 数组中调整要部署的模块顺序
- 在 `module_tasks` 中自定义每个模块要执行的任务
- 在 `knowledge` 下修改各个模块的具体配置（镜像源、版本、参数等）

#### 3. 执行部署

```bash
# 方式1：使用 NPM 命令（推荐）
npm run install:all           # 全量部署所有配置的模块
npm run install:module git ohmyzsh  # 只部署指定模块（支持多个）

# 方式2：直接运行脚本
chmod +x install.sh
sudo ./install.sh -a            # 全量部署
sudo ./install.sh -m git -m ohmyzsh  # 按需部署
```

#### 4. 预览部署（干跑模式）

不实际执行操作，只预览要执行的步骤：

```bash
npm run dry-run:all             # 预览全量部署
npm run dry-run:module git      # 预览指定模块部署
```

### 常用命令

| 命令                   | 功能说明                                   |
| ---------------------- | ------------------------------------------ |
| `npm run help`         | 查看完整帮助信息                           |
| `npm run lint`         | 执行全量代码质量检查（提交代码前推荐执行） |
| `npm run format`       | 自动修复所有可格式化的代码问题             |
| `npm run build:docker` | 构建 Docker 部署镜像                       |
| `npm run shellcheck`   | 执行 Shell 脚本静态代码检查                |

## ⚙️ 配置说明

### 核心配置项

```yaml
# 执行模块顺序列表（按数组顺序依次执行，可根据需求增删）
run: [ohmyzsh, git, npm, brew, ollama, openclaw]

# 各模块支持的任务类型列表
module_tasks:
  ohmyzsh: [install, installPlugins, update, uninstall, check]
  git: [install, updateConfig, update, uninstall, check]
  # ... 其他模块配置
```

### 任务类型说明

| 任务类型              | 说明                                                        |
| --------------------- | ----------------------------------------------------------- |
| `check`               | 检查软件是否已安装/功能是否正常，所有安装类任务自动前置执行 |
| `install`             | 软件安装（自动执行 check 检查，安装失败自动回滚）           |
| `uninstall`           | 软件卸载，清理配置文件和残留数据                            |
| `update`              | 更新软件到最新版本，保留原有配置                            |
| `setEnv`              | 设置系统环境变量，自动写入 shell 配置文件                   |
| `setSystemd`          | 配置 Systemd 后台服务，设置开机自启和重启策略               |
| `updateConfig`        | 更新软件的自定义配置文件                                    |
| `installDependencies` | 安装软件运行所需的系统依赖包                                |
| `installPlugins`      | 安装软件的扩展/插件                                         |

## 🐳 Docker 使用

### 构建镜像

```bash
npm run build:docker v1.0.0
# 或手动执行
docker build -t shell-ready:v1.0.0 .
```

### 运行容器

```bash
# 全量部署
docker run --privileged -v $(pwd)/config.yaml:/opt/shell-ready/config.yaml shell-ready:v1.0.0 -a

# 按需部署指定模块
docker run --privileged -v $(pwd)/config.yaml:/opt/shell-ready/config.yaml shell-ready:v1.0.0 -m git -m npm

# 查看帮助
docker run --rm shell-ready:v1.0.0 -h
```

### 进入容器

```
docker exec -it -u root shell-ready-runner /bin/bash -l
```

### Docker Compose 使用

#### 生产环境配置

```bash
# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

#### OpenClaw 一键部署（推荐）

使用 `docker-compose.openclaw.yaml` 可以一键部署 OpenClaw AI 网关服务，容器启动时会自动执行 `install.sh` 安装所有模块。

```bash
# 1. 复制环境变量配置
cp .env.example .env

# 2. 编辑 .env 配置必要的环境变量
#    至少需要配置：
#    - OPENCLAW_GATEWAY_TOKEN（网关 Token）
#    - MINIMAX_API_KEY 或 VOLCENGINE_API_KEY（至少一个模型 API Key）

# 3. 启动 OpenClaw 服务
docker-compose -f docker-compose.openclaw.yaml up -d

# 4. 查看启动日志
docker-compose -f docker-compose.openclaw.yaml logs -f

# 5. 进入容器
docker exec -it openclaw-gateway /bin/bash
```

#### 暴露的端口

| 端口 | 说明 |
|------|------|
| 18789 | OpenClaw Gateway HTTP 端口 |
| 18790 | OpenClaw Bridge 端口 |

## 🤝 开发贡献

### 代码规范

项目使用严格的 Shell 代码规范，提交代码前必须执行检查：

```bash
npm run lint   # 执行所有代码质量检查
npm run format # 自动修复格式问题
```

### 新增模块

只需在 `modules/` 目录下新增 `<module_name>.sh` 文件，实现约定的函数接口即可：

```bash
#!/bin/bash
# 新增模块示例
moduleName_install() {
  # 安装逻辑
}
moduleName_updateConfig() {
  # 配置更新逻辑
}
moduleName_check() {
  # 状态检查逻辑
}
```

## ❓ 常见问题

### Q：执行脚本提示权限不足？

A：安装系统级软件需要 root 权限，请使用 sudo 执行命令，或切换到 root 用户。

### Q：可以只安装部分模块吗？

A：完全支持，使用 `npm run install:module <模块名1> <模块名2>` 即可按需安装。

### Q：脚本执行失败会导致系统异常吗？

A：不会，所有脚本都具备幂等性和错误处理机制，任何步骤失败都会立即退出，不会留下半截状态。

### Q：支持 CentOS 7/8 吗？

A：支持，已适配 Ubuntu/Debian 系列和 CentOS/RHEL/Fedora 系列主流 Linux 发行版。

---

⭐ 如果这个项目对你有帮助，欢迎 Star 支持！