# QuickEnvDeployGoEdition

**Repository Path**: wavef/quick-env-deploy-go-edition

## Basic Information

- **Project Name**: QuickEnvDeployGoEdition
- **Description**: 离线快速部署运维工具 Go 版本
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-09-23
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickEnv Go Edition

离线快速部署运维工具 —— 基于 Go 的单文件绿色运维面板，通过浏览器远程管理服务器上的中间件环境。

## 技术栈

| 层面 | 技术 |
|---|---|
| 后端 | Go 1.20 |
| 前端 | 原生 HTML / CSS / JavaScript（SPA 嵌入模式） |
| 系统托盘 | [getlantern/systray](https://github.com/getlantern/systray)（Windows / Linux 桌面） |
| 无桌面运行 | PID 文件 + `/health` 健康检查端点 + 信号监听（Linux 服务器 / 麒麟 no-CGO 兜底） |
| 数据存储 | JSON 文件（`installed.json` / `settings.json` / `process.json`） |
| 前端嵌入 | Go 1.16+ `embed` 包，编译后单文件分发 |
| 跨平台 | Go build tags 拆分平台代码（`_windows` / `_linux` / `_cgo` / `_nocgo`） |

## 依赖

- **Go 1.20+**（编译时依赖）
- `github.com/getlantern/systray v1.2.2`（运行时依赖，`go mod tidy` 自动下载）

无需数据库、无需 Web 容器，无其他运行时依赖。

### 平台与构建模式

| 目标平台 | CGO | 托盘实现 | 运行状态检查方式 |
|---|---|---|---|
| Windows | 关闭 | Win32 API systray（系统托盘图标） | 托盘菜单 + 日志 |
| Linux 桌面（Ubuntu/Kylin 有 GUI） | 开启 | GTK/AppIndicator systray | 托盘菜单 + 日志 |
| Linux 服务器 / 麒麟无桌面 | **关闭** | no-op + PID 文件 + `/health` 端点 + SIGINT/SIGTERM | `curl /health`、`cat quickenv.pid`、`ss -ltnp` |

> Windows 上交叉编译 Linux 产物时必须 `CGO_ENABLED=0`（否则 systray 会链接 GTK，Windows 上无对应库）。Linux 桌面 CGO 版需在对应架构的 Linux 机器上打包（详见下文「构建说明」）。

## 快速启动

```bash
# 1. 克隆项目
git clone <repo-url>
cd QuickEnvDeployGoEdition

# 2. 安装依赖
go mod tidy

# 3. 开发模式运行（前端从 web/ 目录读取，可热更新）
go run main.go

# 4. 生产构建（前端嵌入二进制，单文件输出到 dist/）
# Windows（在项目根目录执行）
build\build-win.bat

# Linux 全平台批量构建（在项目根目录执行）
bash build/build-all.sh
```

启动后自动打开浏览器访问 `http://localhost:50080`。端口 50080 被占时会自动递增查找可用端口。

> **Linux 服务器版（无桌面）启动方式**：直接运行二进制即可，无需 `nohup` 之外的特殊处理。
> ```bash
> chmod +x QuickEnvDeploy-kylin-arm64
> ./QuickEnvDeploy-kylin-arm64
> # 后台运行
> nohup ./QuickEnvDeploy-kylin-arm64 > /dev/null 2>&1 &
> ```
> 运行时会在二进制同级目录写入 `quickenv.pid` / `quickenv.port`，退出时自动清理。

## 构建说明

### 构建产物目录

所有脚本统一将产物输出到项目根的 `dist/` 目录（脚本内部会自动 `cd` 到项目根，可在任意位置调用）。

### Windows 上交叉编译（推荐，覆盖 99% 场景）

在 Windows 上即可打包全部平台产物，无需额外环境：

| 脚本 | 产物 | 说明 |
|---|---|---|
| `build\build-win.bat` | `dist/QuickEnvDeploy-win-x64.exe` | Windows x64 |
| `bash build/build-all.sh` | 4 个产物全出 | 全平台批量（Win + Kylin x64/arm64 + Ubuntu x64） |
| `bash build/build-kylin-arm64.sh` | `dist/QuickEnvDeploy-kylin-arm64` | 仅 Kylin ARM64 |
| `bash build/build-kylin-x64.sh` | `dist/QuickEnvDeploy-kylin-x64` | 仅 Kylin x64 |
| `bash build/build-ubuntu-x64.sh` | `dist/QuickEnvDeploy-ubuntu-x64` | 仅 Ubuntu x64 |

> Windows 上交叉编译 Linux 产物时，脚本已内置 `CGO_ENABLED=0`，选中 `tray_nocgo.go`（PID 文件 + `/health` 端点兜底），纯 Go 编译无需 GTK。

### Linux 桌面 CGO 版（仅需要 systray 图标时）

如需在 Linux 桌面显示托盘图标（非服务器版），必须在**对应架构的 Linux 机器**上用 CGO 打包：

```bash
# 1. 安装依赖（Debian/Ubuntu 系）
sudo apt install -y gcc libgtk-3-dev libayatana-appindicator3-dev

# 2. CGO 构建（amd64 示例，arm64 需在 arm64 机器上执行）
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o dist/QuickEnvDeploy-linux-amd64-cgo .
```

> 麒麟服务器版 / 无桌面环境**不需要**此模式，直接用上表的 no-CGO 产物即可。

## 目录结构

### 项目源码

```
├── main.go                 # 入口：初始化存储 / 加载配置 / 启动服务 / 系统托盘
├── go.mod / go.sum
├── features.json           # 功能开关配置（启用/禁用哪些中间件）
├── models/                 # 数据模型定义
├── store/                  # 持久化层（JSON 读写 + 目录管理）
├── server/                 # HTTP 服务 + REST API + SSE 进度推送
│   ├── server.go           #   服务主体 + /health 健康检查端点
│   ├── handlers.go         #   通用 API handler
│   ├── handlers_memory_windows.go  # 内存信息（Windows）
│   ├── handlers_memory_linux.go    # 内存信息（Linux）
│   ├── middleware.go       #   CORS / 日志 / 恢复中间件
│   ├── feature_loader.go   #   功能开关加载
│   └── sse.go              #   SSE 进度推送
├── detector/               # 环境检测引擎（硬件 / 系统信息采集）
│   ├── detector.go         #   主体逻辑
│   ├── port_generic.go     #   端口检测（通用）
│   └── port_linux.go       #   端口检测（Linux 专用）
├── software/               # 各中间件的安装 / 启动 / 停止逻辑
│   ├── software.go         #   统一接口定义
│   ├── java.go / mysql.go / redis.go / nginx.go / jar.go
│   ├── mysql_windows.go    #   MySQL Windows 专属（sc 服务、DLL 拷贝）
│   └── mysql_linux.go      #   MySQL Linux 专属（ss/kill、.so 依赖、权限）
├── env/                    # 环境变量与隐藏命令
│   ├── env.go              #   通用
│   ├── env_windows.go / env_linux.go
│   └── hidden_cmd_windows.go / hidden_cmd_other.go
├── extract/                # 离线包解压工具
├── features/               # 功能开关管理
├── process/                # 进程管理（启动 / 监控 / 停止）
│   ├── process.go          #   通用
│   ├── process_windows.go  #   Windows（tasklist/wmic/taskkill）
│   └── process_linux.go    #   Linux（ps/pgrep/kill）
├── tray/                   # 系统托盘 / 运行状态管理（按 build tag 拆分）
│   ├── tray.go             #   共享代码（Config、OpenBrowser、Quit、loadIcon）
│   ├── tray_windows.go     #   Windows systray（Win32 API，无需 CGO）
│   ├── tray_cgo.go         #   Linux 桌面 systray（GTK/AppIndicator，需 CGO）
│   └── tray_nocgo.go       #   Linux 服务器兜底（PID 文件 + /health + 信号）
├── web/                    # 前端 SPA（嵌入到二进制）
│   ├── index.html
│   ├── css/main.css
│   ├── js/app.js
│   ├── js/api-client.js
│   └── js/state.js
├── build/                  # 各平台构建脚本（产物输出到项目根 dist/）
│   ├── build-win.bat       # Windows x64
│   ├── build-ubuntu-x64.sh # Ubuntu x64
│   ├── build-kylin-x64.sh  # Kylin x64
│   ├── build-kylin-arm64.sh# Kylin ARM64
│   └── build-all.sh        # 全平台批量构建
├── icon/                   # 应用图标
├── dist/                   # 构建产物输出目录（脚本自动创建）
└── temp/                   # 临时 / 测试文件
```

### 运行数据目录（固定路径）

```
/opt/quickenv/                   # Linux
D:\opt\quickenv\                 # Windows (有 D 盘)
C:\ProgramData\quickenv\         # Windows (无 D 盘 fallback)
  ├── apps/                      # 已安装的软件
  ├── packages/                  # 离线安装包
  ├── data/                      # installed.json / settings.json / process.json
  ├── logs/                      # 运行日志
  ├── cache/                     # 缓存文件
  └── temp/                      # 临时文件
```

> 安装目录和包目录可通过 `data/settings.json` 手动覆盖（编辑文件后重启即可生效）。

## 功能说明

| 功能 | 说明 |
|---|---|
| **环境检测** | 采集服务器的 CPU、内存、主机名、操作系统、架构等系统信息 |
| **多级软件探测** | L1 环境变量（JAVA_HOME / MYSQL_HOME / REDIS_HOME / NGINX_HOME）→ L2 PATH 扫描 → L3 常规安装目录，自动发现外部已安装版本并去重 |
| **服务发现** | Windows 平台通过 `sc` 命令发现 MySQL 等已注册为服务的实例，并反查 binPath |
| **软件安装** | 支持 Java、MySQL、Redis、Nginx 的离线包（`.zip` / `.tar.gz`）安装 |
| **目录导入** | 直接指定已存在的安装目录，复制内容后注册为本工具管理的版本（version 传 `imported` 时自动从目录名推导版本号） |
| **纳管已有安装** | 通过 `adopt` 接口将外部已安装的软件路径直接注册到 `installed.json`，**不复制文件**；自动从二进制检测版本号、端口、密码、Windows 服务名、初始化状态 |
| **Jar 应用管理** | 上传 jar 包及可选 `config.zip` 配置压缩包，独立管理每个 jar 应用实例（端口、配置路径） |
| **版本管理** | 同一软件可安装多版本，支持切换默认版本与卸载 |
| **启停控制** | 一键启动 / 停止 / 重启已安装的中间件服务 |
| **启动前检测** | 启动前检查运行环境（端口占用、依赖、配置等），按 `error` / `warning` / `info` 分级返回 |
| **进程监控** | 运行时状态展示（PID、端口、运行状态），通过端口反查绑定进程 |
| **MySQL 管理** | 数据目录初始化、连接测试、修改密码、创建数据库、导入 SQL 文件 |
| **Nginx 重载** | 在不停止服务的情况下重载 Nginx 配置（`nginx -s reload`） |
| **Redis 密码** | 在线设置 / 修改 Redis `requirepass` 密码 |
| **离线包上传** | 通过浏览器上传 `.zip` / `.tar.gz` 离线包到服务器（最大 500MB） |
| **平台包过滤** | 根据当前 OS 自动过滤包类型（Windows 仅 `.zip`，Linux 仅 `.tar.gz` / `.tar` / `.gz`），并优先扫描平台子目录（`win-x64` / `linux-x64` / `kylin-arm64`） |
| **进度推送** | 基于 SSE（Server-Sent Events）实时推送安装 / 导入进度到浏览器 |
| **日志查看** | 读取软件启动日志末尾内容，以及 QuickEnv 自身运行日志（`server.log`） |
| **远程管理** | 浏览器访问，无需登录服务器桌面 |
| **端口自适配** | 默认端口 50080，被占用时自动在 50080-50179 范围内递增查找可用端口 |
| **系统托盘** | Windows / Linux 桌面托盘图标，右键菜单退出；Linux 服务器无桌面时走 no-CGO 兜底（PID 文件 + `/health` 端点 + 信号退出） |
| **功能开关** | `features.json` 控制启用的中间件列表与平台支持（`windows` / `linux`） |

## API 概览

> 路径中的 `{name}` 为软件标识（`java` / `mysql` / `redis` / `nginx` / `jar`），`{taskId}` 为 SSE 进度 ID。
> 所有软件操作接口的 `version` 通过 Query 参数传递：`?version=xxx`。
> 统一响应格式：`{"success": bool, "data": ...}` 或 `{"success": false, "error": "..."}`。

### 软件管理

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/software` | 软件列表（含检测结果与已安装 jar 应用） |
| GET | `/api/software/{name}` | 单个软件详情（含外部探测版本） |
| POST | `/api/software/{name}/install` | 安装软件（JSON：`packagePath` + `version`；当 `packagePath` 为目录时走导入流程） |
| POST | `/api/software/jar/install` | Jar 应用上传安装（multipart：`jar` + 可选 `config.zip` + `version` + `port`） |
| POST | `/api/software/{name}/uninstall` | 卸载指定版本（Query: `version`） |
| POST | `/api/software/{name}/adopt` | 纳管外部已有安装（JSON：`path` + 可选 `version`，不复制文件） |
| POST | `/api/software/{name}/start` | 启动指定版本 |
| POST | `/api/software/{name}/stop` | 停止指定版本 |
| POST | `/api/software/{name}/restart` | 重启指定版本（先 stop 再 start） |
| GET | `/api/software/{name}/check-prerequisites` | 启动前环境检测（Query: `version`） |
| GET | `/api/software/{name}/env` | 获取软件运行所需环境变量 |
| GET | `/api/software/{name}/read-log` | 读取软件启动日志末尾 100 行 |
| POST | `/api/software/{name}/switch-default` | 切换默认版本（Query: `version`） |

### MySQL 专属

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/software/mysql/init` | 数据目录初始化（Query: `version`） |
| POST | `/api/software/mysql/test-conn` | 连接测试（JSON：`user` + `password`） |
| POST | `/api/software/mysql/change-pwd` | 修改密码（JSON：`user` + `oldPassword` + `newPassword`） |
| POST | `/api/software/mysql/create-db` | 创建数据库（JSON：`dbName` + `charset` + `collate` 等） |
| POST | `/api/software/mysql/import-sql` | 导入 SQL 文件（multipart：`file` + `dbName` + `user` + `password`） |

### Nginx / Redis 专属

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/software/nginx/reload` | 重载 Nginx 配置（Query: `version`） |
| POST | `/api/software/redis/set-password` | 设置 Redis 密码（JSON：`password`，Query: `version`） |

### 系统 / 通用

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/detect` | 触发环境检测，返回软件摘要列表 |
| GET | `/api/packages` | 离线包列表（含 `packagesDir`、`platform`） |
| POST | `/api/packages/upload` | 上传离线包（multipart，最大 500MB） |
| GET | `/api/features` | 功能开关列表 |
| GET / POST | `/api/settings` | 读取 / 修改全局配置（`packagesDir` / `storeDir` / `baseDir`） |
| GET | `/api/system-info` | 系统信息（主机名 / OS / 架构 / CPU / 内存） |
| GET | `/api/installed-summary` | 已安装摘要（纯内存读取，不执行系统命令） |
| GET | `/api/progress/{taskId}` | SSE 进度订阅（`text/event-stream`） |
| GET | `/api/port` | 服务端口信息 |
| POST | `/api/upload` | 通用文件上传（与 `/api/packages/upload` 等价） |
| GET | `/api/server-log` | QuickEnv 自身运行日志末尾 200 行 |
| GET | `/health` | 健康检查（无需登录，返回 `status`/`pid`/`port`/`os`/`arch`/`uptime_seconds`/`start_time`） |

## 构建产物

| 平台 | 文件名 | CGO |
|---|---|---|
| Windows x64 | `QuickEnvDeploy-win-x64.exe` | 否 |
| Ubuntu x64 | `QuickEnvDeploy-ubuntu-x64` | 否（no-CGO 兜底） |
| Kylin x64 | `QuickEnvDeploy-kylin-x64` | 否（no-CGO 兜底） |
| Kylin ARM64 | `QuickEnvDeploy-kylin-arm64` | 否（no-CGO 兜底） |

构建产物位于项目根的 `dist/` 目录，均为单文件，可直接拷贝到服务器运行，无外部依赖。

### 运行状态检查（Linux 服务器版）

no-CGO 产物启动后会在二进制同级目录写入运行状态文件，并提供 HTTP 健康检查端点：

```bash
# 1. HTTP 健康检查（推荐）
curl -s http://127.0.0.1:50080/health

# 2. 读取 PID 并验证进程存活
cat quickenv.pid | xargs ps -p

# 3. 读取端口并检查监听
cat quickenv.port | xargs ss -ltnp 'sport = :'

# 4. 优雅退出
kill $(cat quickenv.pid)
```