# gcs

**Repository Path**: liumou_site/gcs

## Basic Information

- **Project Name**: gcs
- **Description**: 使用Golang编写的命令模块
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-11-25
- **Last Updated**: 2025-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 GCS - Go Command Shell

[![Go Version](https://img.shields.io/badge/Go-1.19+-00ADD8?style=flat&logo=go)](https://golang.org/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Version](https://img.shields.io/badge/version-v1.8.3-green.svg)](https://gitee.com/liumou_site/gcs)

## 📋 项目简介

GCS (Go Command Shell) 是一个功能强大的 Go 语言系统命令执行模块，提供了类似 Python 的 `os.system`、`subprocess.getstatusoutput` 和 `subprocess.getoutput` 的功能。支持普通命令执行、sudo 权限命令、脚本执行、进程管理等多种场景。

### ✨ 核心特性

- 🔧 **简单易用**: 简洁的 API 设计，快速上手
- 🔐 **权限管理**: 支持 sudo 权限执行命令
- 📊 **实时输出**: 支持命令执行结果的实时打印
- 📝 **脚本支持**: 支持复杂脚本和管道命令执行
- 🖥️ **跨平台**: 支持 Linux、Windows、macOS 等主流操作系统
- 🎯 **进程管理**: 提供进程状态检测功能
- 🔍 **结果处理**: 支持命令输出结果的灵活处理和分析

## 🚀 快速开始

### 安装

```bash
# 使用最新版本
go get gitee.com/liumou_site/gcs@latest

# 或者指定版本
go get gitee.com/liumou_site/gcs@v1.8.3
```

### 基本使用

```go
package main

import (
    "fmt"
    "strings"
    "sync"
    "gitee.com/liumou_site/gcs"
)

func main() {
    // 创建 shell 实例
    shell := gcs.NewShell()
    
    // 执行简单命令
    shell.RunShell("ls", "-la")
    if shell.Err != nil {
        fmt.Printf("执行失败: %v\n", shell.Err)
    } else {
        fmt.Printf("执行成功:\n%s\n", shell.Strings)
    }
}
```

## 📖 详细文档

### 基础命令执行

```go
// 创建 shell 实例
shell := gcs.NewShell()

// 方法 1: 直接执行命令
shell.RunShell("ls -la /home")

// 方法 2: 分参数执行
shell.RunShell("ls", "-la", "/home")

// 方法 3: 执行脚本（支持管道）
shell.RunScript("ps aux | grep nginx")

// 方法 4: 通过终端执行（支持图形界面）
shell.RunTerminal("htop")
```

### Sudo 权限命令

```go
// 创建 sudo 实例（需要提供密码）
sudo := gcs.NewSudo("your-password")

// 开启实时输出
sudo.Realtime = true

// 执行需要 sudo 权限的命令
sudo.RunSudo("apt update")
sudo.RunSudo("systemctl restart nginx")

// 执行脚本
sudo.RunScriptSudo("docker ps -a | grep nginx")
```

### 批量命令执行

```go
shell := gcs.NewShell()

// 批量执行命令，遇到错误立即停止
commands := []string{
    "echo '第一步'",
    "ls -la",
    "pwd",
    "echo '完成'",
}
shell.RunShellList(commands)
```

### 命令结果处理

```go
shell := gcs.NewShell()
shell.RunShell("docker ps -a")

// 结果过滤
shell.Grep("nginx")           // 过滤包含 nginx 的行
shell.AwkCol("2")             // 获取第2列
shell.Line(1)                   // 获取第1行
shell.Column(3, " ")          // 获取第3列（按空格分隔）

fmt.Println(shell.Strings)     // 输出处理后的结果
```

### 进程管理

```go
shell := gcs.NewShell()

// 检查进程是否在运行
if shell.ProcessIsRunning("nginx") {
    fmt.Println("Nginx 正在运行")
} else {
    fmt.Println("Nginx 未运行")
}
```

## ⚙️ 配置参数

### Shell 配置

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `Realtime` | bool | false | 实时打印命令执行输出 |
| `Debug` | bool | false | 开启调试模式，输出详细日志 |
| `PrintErr` | bool | true | 打印错误信息 |
| `PrintInfo` | bool | false | 打印详细信息 |
| `BlackHole` | bool | false | 忽略错误输出（黑洞模式） |
| `Ignore` | bool | false | 忽略标准输出 |

### Sudo 配置

| 参数 | 类型 | 说明 |
|------|------|------|
| `Password` | string | sudo 密码 |
| `Realtime` | bool | 实时输出模式 |
| `Debug` | bool | 调试模式 |

## 🔧 高级功能

### 超时控制

```go
shell := gcs.NewShell()

// 设置命令执行超时时间为 10 秒
shell.RunTimeout(10, "ping baidu.com")

// 检查是否超时
if shell.Err != nil {
    fmt.Printf("命令执行失败: %v\n", shell.Err)
    if strings.Contains(shell.Err.Error(), "timeout") {
        fmt.Println("命令执行超时")
    }
}
```

### 并发执行

```go
// 并发执行多个命令
shell1 := gcs.NewShell()
shell2 := gcs.NewShell()
shell3 := gcs.NewShell()

var wg sync.WaitGroup
wg.Add(3)

go func() {
    defer wg.Done()
    shell1.RunShell("ping -c 4 baidu.com")
}()

go func() {
    defer wg.Done()
    shell2.RunShell("ping -c 4 google.com")
}()

go func() {
    defer wg.Done()
    shell3.RunShell("ping -c 4 github.com")
}()

wg.Wait()
```

### 错误处理

```go
shell := gcs.NewShell()
shell.RunShell("ls", "/nonexistent")

if shell.Err != nil {
    fmt.Printf("命令执行失败: %v\n", shell.Err)
    fmt.Printf("退出代码: %d\n", shell.ExitCode)
}
```

### 结果解析

```go
shell := gcs.NewShell()
shell.RunShell("route")

// 获取默认网关
shell.Grep("default").Column(3, " ")
gateway := shell.Strings

fmt.Printf("默认网关: %s\n", gateway)
```

## 📊 实际应用示例

### 系统监控脚本

```go
func SystemMonitor() {
    shell := gcs.NewShell()
    
    // 检查系统负载
    shell.RunShell("uptime")
    fmt.Printf("系统负载: %s\n", shell.Strings)
    
    // 检查磁盘使用
    shell.RunShell("df -h /")
    shell.Grep("/$")
    fmt.Printf("磁盘使用: %s\n", shell.Strings)
    
    // 检查内存使用
    shell.RunShell("free -m")
    shell.Grep("Mem:")
    fmt.Printf("内存信息: %s\n", shell.Strings)
}
```

### Docker 管理

```go
func DockerManager() {
    sudo := gcs.NewSudo("your-password")
    sudo.Realtime = true
    
    // 查看运行中的容器
    sudo.RunSudo("docker ps")
    
    // 停止所有容器
    sudo.RunScriptSudo("docker ps -q | xargs docker stop")
    
    // 清理无用镜像
    sudo.RunSudo("docker system prune -f")
}
```

### 软件安装

#### Linux/macOS 系统
```go
func InstallSoftware(packageName string) {
    sudo := gcs.NewSudo("your-password")
    
    // 更新软件包列表
    sudo.RunSudo("apt update")
    if sudo.Err != nil {
        fmt.Printf("更新失败: %v\n", sudo.Err)
        return
    }
    
    // 安装软件
    sudo.RunSudo("apt install -y", packageName)
    if sudo.Err != nil {
        fmt.Printf("安装失败: %v\n", sudo.Err)
        return
    }
    
    fmt.Printf("%s 安装成功\n", packageName)
}
```

#### Windows 系统
```go
func InstallWindowsSoftware() {
    shell := gcs.NewShell()
    
    // 使用 Chocolatey 安装软件（需要先安装 Chocolatey）
    shell.RunShell("choco", "install", "git", "-y")
    
    // 使用 winget 安装软件（Windows 10/11 内置）
    shell.RunShell("winget", "install", "Git.Git")
    
    if shell.Err != nil {
        fmt.Printf("安装失败: %v\n", shell.Err)
        return
    }
    
    fmt.Println("软件安装成功")
}
```

## 🧪 测试

项目包含完整的测试用例，可以通过以下命令运行测试：

```bash
# 运行所有测试
go test -v

# 运行特定测试
go test -v -run TestShell

# 运行测试并生成覆盖率报告
go test -v -cover

# Windows 用户
# 在 PowerShell 中运行
go test -v
```

测试覆盖的功能包括：
- ✅ 基础命令执行
- ✅ Sudo 权限命令
- ✅ 脚本执行
- ✅ 结果处理
- ✅ 进程管理
- ✅ 错误处理
- ✅ 超时控制
- ✅ 跨平台兼容性

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 开发环境

```bash
# 克隆项目
git clone https://gitee.com/liumou_site/gcs.git

# 进入项目目录
cd gcs

# 安装依赖
go mod download

# 运行测试
go test -v

# Windows PowerShell
git clone https://gitee.com/liumou_site/gcs.git
cd gcs
go mod download
go test -v
```

## 📄 许可证

本项目基于 [Apache License 2.0](LICENSE) 许可证开源。

## 💬 问题反馈

- 📧 邮箱：liumou_site@163.com
- 💬 QQ群：[坐公交也用券](https://jq.qq.com/?_wv=1027&k=FEeLQ6tz)
- 🌐 项目地址：[https://gitee.com/liumou_site/gcs](https://gitee.com/liumou_site/gcs)

---

⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！

## 🛠️ Windows 用户特别说明

### 系统要求
- Windows 10/11 专业版或企业版
- PowerShell 5.0 或更高版本
- 建议使用 Windows Terminal 获得最佳体验

### Windows 特定配置
```go
// Windows 系统下自动使用 cmd.exe
shell := gcs.NewShell()

// 执行 Windows 特定命令
shell.RunShell("dir", "/w")           // 宽格式显示目录
shell.RunShell("tasklist")           // 查看进程列表
shell.RunShell("netstat", "-an")     // 查看网络连接

// Windows 服务管理
shell.RunShell("sc", "query", "w32time")  // 查看时间服务状态
shell.RunShell("net", "start")           // 查看正在运行的服务
```

### 注意事项
1. **路径分隔符**: Windows 使用反斜杠 `\`，建议使用双反斜杠或原始字符串
2. **管理员权限**: 在 Windows 上执行需要管理员权限的命令时，需要以管理员身份运行程序
3. **编码问题**: Windows 默认使用 GBK 编码，可能需要设置控制台编码为 UTF-8

### 性能优化建议
- 对于频繁执行的命令，建议复用 `ApiShell` 实例
- 大量并发命令执行时，建议使用 goroutine 池
- 实时输出模式 (`Realtime = true`) 会略微降低性能，但在需要即时反馈的场景下推荐使用

## 🔧 常见问题解答 (FAQ)

### Q: 在 Windows 上执行命令出现乱码？
A: 这是编码问题，可以在程序开始时设置控制台编码：
```go
import "golang.org/x/text/encoding/simplifiedchinese"
// 设置控制台为 UTF-8 编码
exec.Command("cmd", "/c", "chcp 65001").Run()
```

### Q: 为什么有些命令执行失败？
A: 可能原因：
1. 命令不在系统 PATH 中
2. 缺少必要的权限
3. 命令语法在不同平台上有差异
4. 防病毒软件阻止了命令执行

### Q: 如何调试命令执行问题？
A: 开启调试模式：
```go
shell := gcs.NewShell()
shell.Debug = true      // 开启调试输出
shell.PrintErr = true   // 打印错误信息
shell.PrintInfo = true  // 打印详细信息
```

### Q: 支持哪些 Go 版本？
A: 最低支持 Go 1.19，推荐使用最新稳定版本以获得最佳性能和安全性。

### Q: 是否支持 PowerShell Core？
A: 是的，GCS 完全支持 PowerShell Core (PowerShell 7+)，在 Windows 上会自动检测并使用最适合的 shell。

### Q: 如何处理中文路径？
A: GCS 支持 Unicode 路径，但在 Windows 上建议使用 UTF-8 编码：
```go
// 设置控制台为 UTF-8
exec.Command("cmd", "/c", "chcp 65001").Run()

// 使用 UTF-8 路径
shell.RunShell("dir", "C:\\用户\\文档")
```