# devflow-go

**Repository Path**: ourbrander/devflow_go

## Basic Information

- **Project Name**: devflow-go
- **Description**: 用来帮助快速开发的工具，主要功能包括： + 实时监控文件夹或文件的变化，并将指定的文件复制到指定的build文件夹，方便调试或部署； + 部署到指定服务器 为什么要自己造轮子： 用ide自带的，不方便用ide的时候就抓瞎了； 用第三方的，也不靠谱，多了很多没必要的功能，比较臃肿，另外还断更了，例如gulp最后更新在2019年。 还是自己动手吧。
- **Primary Language**: Go
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-13
- **Last Updated**: 2025-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DevFlow Go（构建与部署工具）

一个功能强大的 Go 项目与前端项目的构建/打包/部署工具，支持本地开发监听、跨平台构建、服务器特定覆盖、SSH 部署与零停机切换。

## 功能特点

- 🏗️ **多平台构建** - 支持本地和部署平台的交叉编译（macOS/Linux）
- 📁 **文件同步** - 自动同步配置文件和静态资源
- 👀 **文件监视** - 实时监听文件变化并自动同步
- 🚀 **SSH远程部署** - 一键部署到远程服务器，支持跳过构建选项
- 🔄 **版本管理** - 支持多版本部署和快速回滚
- 💾 **零停机部署** - 使用软链接实现无缝切换
- 🧩 **Go二进制混淆（garble）** - 可按全局、目标、服务器维度启用
- 🔐 **安全认证** - 支持SSH密钥和密码两种认证方式
- 🛡️ **自动密码处理** - 部署时自动处理 sudo 密码认证
- 📦 **压缩上传** - 支持tar.gz压缩上传，大幅提升前端项目部署速度

## 安装

```bash
# 克隆仓库
git clone https://gitee.com/your-username/devflow_go.git

# 进入目录
cd devflow_go

# 编译工具
./build.sh

# 添加到PATH
export PATH=$PATH:/path/to/devflow_go/bin
```

## 配置文件

### 主配置文件 (`devflow.yaml`)

#### Go项目配置示例

```yaml
# 项目基本配置
project: example_admin              # 项目名称
go_build_args: ["-ldflags", "-s -w"]  # Go构建参数
garble:                                 # 全局garble混淆配置（可选）
  enabled: false                        # 是否开启混淆（默认：false）
  args: ["-tiny"]                      # 额外garble参数（例如 -literals, -tiny）
build_dir: build                      # 开发构建目录（默认：build）
deploy_dir: deploy                    # 部署构建目录（默认：deploy）

# 多平台构建配置
build:
  targets:
    local:                            # 本地开发环境
      goos: darwin                    # 目标操作系统
      goarch: arm64                   # 目标架构
      suffix: _macos_arm64            # 文件名后缀
      garble:                         # 目标级覆盖（优先于全局）
        enabled: false
        args: []
    deploy:                           # 部署环境
      goos: linux                     # 目标操作系统
      goarch: amd64                   # 目标架构
      suffix: _linux_amd64            # 文件名后缀
      garble:                         # 目标级覆盖（优先于全局）
        enabled: true
        args: ["-literals", "-tiny"]

# 文件同步配置（仅用于本地开发）
sync:
  - config                            # 同步config目录
  - static                            # 同步static目录
  - templates                         # 同步templates目录

# 部署配置
host_config: devflow.host.yaml        # 主机配置文件路径（默认：devflow.host.yaml）
deploy:
  keep_releases: 3                    # 保留版本数量（默认：3）
  backup: true                        # 是否启用备份（默认：true；设为 false 时启用“简单覆盖模式”，直接上传到服务器目录）
  use_compression: true               # 是否使用压缩上传（推荐用于前端项目）
  compression_level: 6                # 压缩级别 (1-9，默认6)

# 服务器特定文件覆盖配置
server_override:
  enabled: true                       # 是否启用服务器覆盖（默认：false）
  prefix: "server"                    # 服务器特定目录前缀（默认：server）
  fallback: "common"                  # 通用覆盖目录（默认：default）
```

#### Vue/React/Node.js项目配置示例

```yaml
# 项目基本配置
project: example_admin_web          # 项目名称
build_command: "cnpm run build"       # 自定义构建命令（默认：npm run build）
build_output_dir: "dist"              # 构建输出目录（默认：dist）
build_dir: build                      # 开发构建目录（默认：build）
deploy_dir: deploy                    # 部署构建目录（默认：deploy）

# 文件同步配置（用于额外需要部署的文件）
sync:
  - public                            # 同步public目录（如果需要）
  - config                            # 同步配置文件

# 部署配置
host_config: devflow.host.yaml        # 主机配置文件路径
deploy:
  keep_releases: 3                    # 保留版本数量
  backup: true                        # 是否启用备份（设为 false 时启用“简单覆盖模式”，不创建版本目录）
  use_compression: true               # 是否使用压缩上传（推荐用于前端项目）
  compression_level: 6                # 压缩级别 (1-9，默认6)

# 服务器特定文件覆盖配置
server_override:
  enabled: true                       # 是否启用服务器覆盖
  prefix: "server"                    # 服务器特定目录前缀
  fallback: "common"                  # 通用覆盖目录
```

### 主机配置文件 (`devflow.host.yaml`) 

⚠️ **重要：此文件包含敏感信息，不应提交到Git仓库**

```yaml
servers:
  - name: dev                        # 服务器名称
    host: 111.229.194.39            # 服务器地址
    port: 22                         # SSH端口（默认：22）
    user: liuyi                      # SSH用户名
    password: your_password          # 密码认证（与key_path二选一）
    # key_path: ~/.ssh/id_rsa        # SSH密钥认证（与password二选一）
    path: /data/www/example/admin  # 服务器部署路径
    restart_cmd: "sudo supervisorctl restart example_admin"  # 重启命令
    health_check: "curl -f http://localhost:8102/health"  # 健康检查命令（可选）
    health_timeout: 30               # 健康检查超时时间（默认：30秒）
    garble:                          # 服务器级覆盖（优先于目标/全局）
      enabled: false
      
  - name: production                 # 生产环境配置
    host: prod.example.com
    port: 22
    user: deploy
    key_path: ~/.ssh/id_rsa          # SSH密钥认证
    path: /opt/example/admin
    restart_cmd: "sudo supervisorctl restart example_admin"
    health_check: "curl -f http://localhost:8102/health"
    health_timeout: 30
    garble:
      enabled: true
      args: ["-tiny"]
## Garble 混淆

### 功能简介

集成 [garble](https://github.com/burrowers/garble) 对Go二进制进行混淆，可降低逆向难度。支持三层级配置：全局、目标(target)、服务器(server)。

### 启用方式

1. 安装garble：
```bash
go install mvdan.cc/garble@latest
```

2. 在配置中启用：
```yaml
garble:
  enabled: true
  args: ["-literals", "-tiny"]
```

3. 可按构建目标或服务器覆盖：
```yaml
build:
  targets:
    deploy:
      garble:
        enabled: true
        args: ["-tiny"]

# devflow.host.yaml
servers:
  - name: production
    garble:
      enabled: true
      args: ["-tiny"]
```

### 参数透传

`args` 会原样传给 `garble`，devflow 执行形如：

```bash
garble [args...] build -o <output> [go_build_args...]
```

常见参数：
- `-literals`: 混淆字符串/常量
- `-tiny`: 进一步减小体积
- 其它参阅 garble 官方文档

### 配置优先级

优先级从高到低：
1. 服务器级 `servers[].garble`
2. 目标级 `build.targets.<name>.garble`
3. 全局级 `garble`

任一层级 `enabled: false` 明确禁用将生效；未配置则回退到更低优先级。

### 运行时检查

启用混淆时，devflow 会检查 `garble` 是否已安装，未找到则报错并提示安装命令。

## 故障排除（Garble）

- 错误：
```
cannot get modified linker: compiler compile error: exit status 1

go: overlay contains a replacement for .../toolchain@.../src/cmd/link/internal/ld/pcln.go. Files beneath GOMODCACHE must not be replaced.
```
- 原因：Go 1.21+ 引入模块化 toolchain，落在 GOMODCACHE 下时会与 garble 的 overlay 冲突。
- 解决：devflow 在启用 garble 时会自动设置 `GOTOOLCHAIN=local`。如需手动执行，可：
```bash
export GOTOOLCHAIN=local
```
- 备注：仍建议升级 garble 到最新版本：
```bash
go install mvdan.cc/garble@latest
```
    
  - name: testing                    # 测试环境配置
    host: test.example.com
    port: 2222                       # 自定义SSH端口
    user: tester
    password: test_password          # 密码认证
    path: /var/www/project_test
    restart_cmd: "sudo supervisorctl restart example_admin_test"
    # 注意：如果不需要健康检查，可以省略health_check和health_timeout
```

### 配置字段说明

#### 主配置文件字段

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `project` | string | - | 项目名称，Go项目将作为二进制文件名（不包含平台后缀） |
| `build_command` | string | 自动检测 | 自定义构建命令，Vue项目默认 `npm run build`，Go项目默认 `go build` |
| `build_output_dir` | string | 自动检测 | 构建输出目录，Vue项目默认 `dist`，Go项目由构建目标决定 |
| `go_build_args` | []string | `[]` | Go构建参数，如 `["-ldflags", "-s -w"]`（仅Go项目有效） |
| `build_dir` | string | `build` | 开发构建目录 |
| `deploy_dir` | string | `deploy` | 部署构建目录 |
| `build.targets.local.goos` | string | `darwin` | 本地构建目标操作系统 |
| `build.targets.local.goarch` | string | `arm64` | 本地构建目标架构 |
| `build.targets.local.suffix` | string | `_macos_arm64` | 本地构建文件名后缀 |
| `build.targets.deploy.goos` | string | `linux` | 部署构建目标操作系统 |
| `build.targets.deploy.goarch` | string | `amd64` | 部署构建目标架构 |
| `build.targets.deploy.suffix` | string | `_linux_amd64` | 部署构建文件名后缀 |
| `sync` | []string | `[]` | 本地开发时需要同步的目录列表 |
| `host_config` | string | `devflow.host.yaml` | 主机配置文件路径 |
| `deploy.keep_releases` | int | `3` | 服务器上保留的版本数量 |
| `deploy.backup` | bool | `true` | 是否启用备份功能；为 `false` 时使用简单覆盖模式，直接上传至 `servers[].path`，不创建 `releases/current`，回滚与版本列表不可用 |
| `deploy.use_compression` | bool | `false` | 是否使用压缩上传（推荐用于前端项目） |
| `deploy.compression_level` | int | `6` | 压缩级别 (1-9，数字越大压缩率越高) |
| `server_override.enabled` | bool | `false` | 是否启用服务器特定文件覆盖 |
| `server_override.prefix` | string | `server` | 服务器特定目录前缀 |
| `server_override.fallback` | string | `default` | 通用覆盖目录名 |

#### 主机配置文件字段

| 字段 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| `name` | string | - | ✅ | 服务器名称，用于命令行指定 |
| `host` | string | - | ✅ | 服务器地址或域名 |
| `port` | int | `22` | ❌ | SSH端口 |
| `user` | string | - | ✅ | SSH用户名 |
| `password` | string | - | 🔄 | SSH密码（与key_path二选一） |
| `key_path` | string | - | 🔄 | SSH私钥文件路径（与password二选一） |
| `path` | string | - | ✅ | 服务器部署根目录 |
| `restart_cmd` | string | - | ❌ | 部署后执行的重启命令 |
| `health_check` | string | - | ❌ | 健康检查命令 |
| `health_timeout` | int | `30` | ❌ | 健康检查超时时间（秒） |

> **认证说明**：
> - 如果提供 `key_path`，优先使用SSH密钥认证
> - 如果提供 `password`，使用密码认证
> - 两者必须至少提供一个

## 使用方法

### 基本命令

#### Go项目命令

```bash
# 本地开发构建（构建到build目录，生成 project_macos_arm64）
devflow

# 监视文件变化（开发模式）
devflow -watch

# 服务器特定构建（构建到deploy/{server}/目录，生成 project_linux_amd64）
devflow -release -server dev
devflow -release -server prod
```

#### Vue/React/Node.js项目命令

```bash
# 本地开发构建（执行 npm run build，将dist目录复制到build/）
devflow

# 监视文件变化（开发模式，监视配置文件变化）
devflow -watch

# 服务器特定构建（执行构建命令，将dist目录复制到deploy/{server}/）
devflow -release -server dev
devflow -release -server prod
```

### 部署命令

```bash
# 部署到服务器（自动构建 + 部署）
devflow -deploy dev

# 部署到服务器（跳过构建，仅部署现有文件）
devflow -deploy dev -no-build

# 回滚到上一版本
devflow -rollback dev

# 查看部署状态
devflow -status dev

# 查看版本列表
devflow -releases dev
```

### 命令选项说明

| 选项 | 说明 |
|------|------|
| `-deploy string` | 部署到指定服务器 |
| `-no-build` | 部署时跳过构建步骤（仅在 -deploy 时有效） |
| `-release` | 构建发布版本 |
| `-server string` | 指定目标服务器（仅在 -release 时有效） |
| `-releases string` | 查看指定服务器版本列表 |
| `-rollback string` | 回滚指定服务器 |
| `-status string` | 查看指定服务器状态 |
| `-watch` | 监视文件变化 |

## 压缩上传功能

### 📦 功能介绍

为了解决前端项目（如Vue、React等）中散文件过多导致上传时间较长的问题，DevFlow提供了压缩上传功能。

### 🚀 工作原理

1. **本地压缩**: 将整个部署目录压缩为tar.gz文件
2. **上传压缩包**: 仅上传一个压缩文件，大幅减少网络传输时间
3. **远程解压**: 在服务器端自动解压压缩包
4. **清理临时文件**: 自动清理本地和远程的临时压缩文件

### ⚙️ 配置方式

在 `devflow.yaml` 文件中添加以下配置：

```yaml
deploy:
  use_compression: true         # 启用压缩上传
  compression_level: 6          # 压缩级别 (1-9)
```

#### 压缩级别说明

- **1-3**: 低压缩率，速度快
- **4-6**: 中等压缩率，平衡速度和压缩率（推荐）
- **7-9**: 高压缩率，速度较慢

### 📊 适用场景

#### ✅ 推荐使用压缩上传的场景：

- **前端项目**: Vue、React、Angular等，通常包含大量小文件
- **静态资源**: CSS、JS、图片等文件较多的项目
- **慢速网络**: 网络带宽有限的部署环境

#### ❌ 不推荐使用压缩上传的场景：

- **单文件项目**: Go二进制文件等单个大文件
- **已压缩文件**: 主要包含图片、视频等已压缩文件的项目
- **高速网络**: 内网部署等高速网络环境

### 📈 性能对比

以典型的Vue项目为例：

| 方式 | 文件数量 | 传输大小 | 上传时间 |
|------|----------|----------|----------|
| 散文件上传 | 1000+ | 50MB | 5-10分钟 |
| 压缩上传 | 1个 | 15MB | 1-2分钟 |

### 💡 使用示例

```bash
# 启用压缩上传后，正常部署即可
devflow -deploy production

# 输出示例：
# 使用压缩上传: /path/to/deploy/production
# 创建压缩文件: /tmp/deploy_20240101120000.tar.gz
# 上传压缩文件: deploy_20240101120000.tar.gz
# 远程解压文件: deploy_20240101120000.tar.gz
# 压缩上传完成
```

### ⚠️ 注意事项

1. **服务器要求**: 服务器需要支持tar命令（大部分Linux系统默认支持）
2. **临时空间**: 确保本地临时目录和服务器有足够空间存储压缩文件
3. **回滚兼容**: 压缩上传的版本可以正常回滚
4. **错误处理**: 如果解压失败，会自动清理临时文件并报错

## 工作流程

### 开发流程

#### Go项目开发流程

1. **本地开发**：
   ```bash
   devflow -watch
   ```
   - 自动构建Go项目到`build/`目录（生成 `project_macos_arm64`）
   - 监听源文件变化并实时同步到`build/`
   - 同步配置文件、静态资源等

2. **服务器特定构建**：
   ```bash
   devflow -release -server dev    # 开发环境构建
   devflow -release -server prod   # 生产环境构建
   ```
   - 交叉编译Linux版本到`deploy/{server}/`目录（生成 `project_linux_amd64`）
   - 同步所需的配置文件和资源
   - 自动应用服务器特定文件覆盖

#### Vue/React/Node.js项目开发流程

1. **本地开发**：
   ```bash
   devflow -watch
   ```
   - 执行构建命令（如 `cnpm run build`）
   - 将构建输出（如 `dist/`）复制到`build/`目录
   - 监听配置文件变化并实时同步

2. **服务器特定构建**：
   ```bash
   devflow -release -server dev    # 开发环境构建
   devflow -release -server prod   # 生产环境构建
   ```
   - 执行构建命令生成生产版本
   - 将构建输出复制到`deploy/{server}/`目录
   - 同步额外文件（如public目录、配置文件等）
   - 自动应用服务器特定文件覆盖

### 部署流程

1. **完整部署**（推荐）：
   ```bash
   devflow -deploy dev
   ```

2. **快速重部署**（跳过构建）：
   ```bash
   devflow -deploy dev -no-build
   ```

3. **部署步骤**：
   - ✅ 自动执行服务器特定构建（可选，使用 `-no-build` 跳过）
   - ✅ 建立SSH连接（自动处理密码认证）
   - ✅ 创建带时间戳的版本目录（如：`20250109115054`）
   - ✅ 从`deploy/{server}/`上传文件到临时目录
   - ✅ 移动文件到版本目录
   - ✅ 更新软链接指向新版本
   - ✅ 执行重启命令（自动处理sudo密码）
   - ✅ 健康检查（可选）
   - ✅ 清理旧版本

### 项目目录结构

#### 🏠 本地项目结构

##### Go项目结构

```
project/
├── main.go                               # 主程序
├── devflow.yaml                          # devflow配置
├── devflow.host.yaml                     # 主机配置（不提交到Git）
├── config/                               # 基础配置文件
│   ├── app_config.yaml                   # 应用配置
│   └── jwt_cert/                         # JWT证书
├── server.dev/                           # 开发环境覆盖文件 ✨
│   ├── config/app_config.yaml            # 开发环境配置
│   └── deploy/README_DEV.md              # 开发环境说明
├── server.prod/                          # 生产环境覆盖文件 ✨
│   └── config/app_config.yaml            # 生产环境配置
├── server.common/                        # 通用服务器覆盖文件 ✨
│   └── config/app_config.yaml            # 通用服务器配置
├── build/                                # 本地构建输出
│   └── project_macos_arm64               # 本地二进制文件
└── deploy/                               # 服务器构建输出 ✨
    ├── dev/                              # 开发环境构建
    │   ├── project_linux_amd64           # Linux二进制文件
    │   ├── config/app_config.yaml        # 已应用dev覆盖
    │   └── deploy/README_DEV.md          # 开发环境说明
    └── prod/                             # 生产环境构建
        ├── project_linux_amd64           # Linux二进制文件
        └── config/app_config.yaml        # 已应用prod/common覆盖
```

##### Vue/React/Node.js项目结构

```
project/
├── package.json                          # Node.js项目配置
├── devflow.yaml                          # devflow配置
├── devflow.host.yaml                     # 主机配置（不提交到Git）
├── src/                                  # 源代码目录
├── public/                               # 静态资源目录
├── dist/                                 # 构建输出目录（cnpm run build生成）
├── config/                               # 配置文件
│   └── app_config.json                   # 应用配置
├── server.dev/                           # 开发环境覆盖文件 ✨
│   ├── config/app_config.json            # 开发环境配置
│   └── public/env.js                     # 开发环境变量
├── server.prod/                          # 生产环境覆盖文件 ✨
│   ├── config/app_config.json            # 生产环境配置
│   └── public/env.js                     # 生产环境变量
├── build/                                # 本地构建输出
│   ├── index.html                        # 前端页面
│   ├── assets/                           # 静态资源
│   ├── config/                           # 配置文件
│   └── public/                           # 同步的public目录
└── deploy/                               # 服务器构建输出 ✨
    ├── dev/                              # 开发环境构建
    │   ├── index.html                    # 前端页面
    │   ├── assets/                       # 静态资源
    │   ├── config/app_config.json        # 已应用dev覆盖
    │   └── public/env.js                 # 开发环境变量
    └── prod/                             # 生产环境构建
        ├── index.html                    # 前端页面
        ├── assets/                       # 静态资源
        ├── config/app_config.json        # 已应用prod覆盖
        └── public/env.js                 # 生产环境变量
```

#### 🖥️ 服务器目录结构

```
/data/www/example/admin/
├── current -> releases/20250109115054/    # 软链接指向当前版本
├── releases/                              # 版本目录
│   ├── 20250109115054/                   # 当前版本
│   │   ├── example_admin_linux_amd64   # 二进制文件（带平台后缀）
│   │   ├── config/                       # 配置文件（已应用覆盖）
│   │   │   ├── app_config.yaml           # 服务器特定配置
│   │   │   └── jwt_cert/
│   │   ├── deploy/                       # 部署相关文件
│   │   │   ├── example_admin.conf      # Supervisor配置
│   │   │   └── README_DEV.md             # 环境说明（如有）
│   │   └── README_DEPLOYMENT.md          # 部署说明
│   ├── 20250109112826/                   # 历史版本1
│   └── 20250109110040/                   # 历史版本2
├── shared/                               # 共享目录（保留）
│   ├── config/
│   └── logs/
└── tmp/                                  # 临时目录
    └── uploading/                        # 上传临时目录
```

## 多平台构建

devflow支持为不同平台交叉编译二进制文件：

### 🎯 构建目标配置

```yaml
build:
  targets:
    local:                            # 本地开发环境
      goos: darwin                    # macOS
      goarch: arm64                   # Apple Silicon
      suffix: _macos_arm64            # 文件后缀
    deploy:                           # 部署环境
      goos: linux                     # Linux
      goarch: amd64                   # x86-64
      suffix: _linux_amd64            # 文件后缀
```

### 📁 构建输出

| 命令 | 目标环境 | 输出文件 | 说明 |
|------|----------|----------|------|
| `devflow` | local | `build/project_macos_arm64` | 本地开发使用 |
| `devflow -release -server dev` | deploy | `deploy/dev/project_linux_amd64` | 开发环境部署使用 |
| `devflow -release -server prod` | deploy | `deploy/prod/project_linux_amd64` | 生产环境部署使用 |
| `devflow -deploy dev` | deploy | `deploy/dev/project_linux_amd64` | 自动构建并部署 |

### 🔧 自定义平台

可以根据需要添加更多构建目标：

```yaml
build:
  targets:
    local:
      goos: darwin
      goarch: arm64
      suffix: _macos_arm64
    deploy:
      goos: linux
      goarch: amd64
      suffix: _linux_amd64
    windows:                          # Windows构建
      goos: windows
      goarch: amd64
      suffix: _windows_amd64.exe
    arm:                              # ARM Linux构建
      goos: linux
      goarch: arm64
      suffix: _linux_arm64
```

### 💡 使用建议

- **开发阶段**：使用 `devflow` 构建本地版本进行测试
- **发布构建**：使用 `devflow -release -server {name}` 构建服务器特定版本
- **部署阶段**：使用 `devflow -deploy {server}` 自动构建并部署
- **快速部署**：使用 `devflow -deploy {server} -no-build` 跳过构建直接部署现有文件

## 服务器文件覆盖

devflow支持为不同服务器环境提供特定的配置文件覆盖，在构建时自动应用环境相关的配置差异。

### 🔧 配置覆盖机制

#### **覆盖目录结构**

```
project/
├── config/                               # 基础配置文件
│   └── app_config.yaml                   # 默认配置
├── server.dev/                           # 开发环境覆盖 ✨
│   ├── config/app_config.yaml            # 开发环境特定配置
│   └── deploy/README_DEV.md              # 开发环境文档
├── server.prod/                          # 生产环境覆盖 ✨
│   └── config/app_config.yaml            # 生产环境特定配置
└── server.common/                        # 通用服务器覆盖 ✨
    └── config/app_config.yaml            # 通用服务器配置
```

#### **覆盖优先级**

1. **服务器特定覆盖**：`server.{server_name}/` 
2. **通用服务器覆盖**：`server.{fallback}/`（默认：`server.common/`）
3. **跳过覆盖**：如果以上目录都不存在

### ⚙️ 配置覆盖功能

```yaml
# devflow.yaml
server_override:
  enabled: true                           # 启用覆盖功能
  prefix: "server"                        # 目录前缀（可自定义）
  fallback: "common"                      # 兜底目录名
```

### 🚀 使用示例

#### **1. 配置环境差异**

**基础配置** (`config/app_config.yaml`)：
```yaml
server:
  port: 8080
  mode: development
db:
  host: localhost
  name: myapp
```

**开发环境覆盖** (`server.dev/config/app_config.yaml`)：
```yaml
server:
  port: 8102
  mode: debug
db:
  host: 111.229.194.39
  name: myapp_dev
  user: dev_user
  password: dev_password
```

**生产环境覆盖** (`server.prod/config/app_config.yaml`)：
```yaml
server:
  port: 8080
  mode: release
db:
  host: prod-db.example.com
  name: myapp_prod
  user: prod_user
  password: secure_password
```

#### **2. 构建服务器特定版本**

```bash
# 构建开发环境版本
devflow -release -server dev
# ✅ 使用 server.dev/ 覆盖文件
# ✅ 输出到 deploy/dev/

# 构建生产环境版本  
devflow -release -server prod
# ✅ 使用 server.prod/ 覆盖文件
# ✅ 输出到 deploy/prod/

# 构建测试环境版本（无专用覆盖）
devflow -release -server test
# ✅ 使用 server.common/ 兜底覆盖
# ✅ 输出到 deploy/test/
```

#### **3. 覆盖日志输出**

```bash
$ devflow -release -server dev
构建 (deploy): /project/deploy/dev/myapp_linux_amd64 用于服务器 dev
同步目录: /project/config -> /project/deploy/dev/config
🔧 应用服务器覆盖: server.dev/
   - config/app_config.yaml
   - deploy/README_DEV.md
✅ 覆盖了 2 个文件
构建成功 (deploy): /project/deploy/dev/myapp_linux_amd64
发布构建完成: dev
```

### 📋 覆盖功能特性

#### **✅ 支持的覆盖类型**

- **配置文件覆盖**：数据库连接、Redis配置、日志级别等
- **环境文档覆盖**：不同环境的部署说明、操作手册
- **脚本文件覆盖**：启动脚本、监控脚本等
- **静态资源覆盖**：环境特定的资源文件

#### **🔄 构建时自动应用**

- **清空目标**：每次构建前清空 `deploy/{server}/`
- **基础文件**：先同步 `sync` 配置的基础目录
- **覆盖文件**：再应用服务器特定的覆盖文件
- **部署就绪**：生成完全独立的部署包

#### **🎯 实际应用场景**

1. **数据库配置**：开发/测试/生产环境使用不同的数据库
2. **缓存配置**：Redis密码、主从配置等
3. **日志级别**：开发用debug，生产用error
4. **功能开关**：不同环境启用不同的功能特性
5. **监控配置**：Supervisor、健康检查等环境相关配置

### ❓ 常见问题

**Q: 如何验证覆盖是否生效？**
```bash
# 构建后检查文件内容
devflow -release -server dev
cat deploy/dev/config/app_config.yaml
```

**Q: 可以自定义覆盖目录前缀吗？**
```yaml
server_override:
  enabled: true
  prefix: "env"           # 使用 env.dev/, env.prod/
  fallback: "default"     # 使用 env.default/
```

**Q: 如果没有覆盖文件会怎样？**
```bash
# 如果 server.test/ 和 server.common/ 都不存在
devflow -release -server test
# ✅ 跳过覆盖，使用基础配置文件
```

## 版本管理

- **版本号格式**：`YYYYMMDDHHMMSS`（东八区时间）
- **版本保留**：默认保留最近3个版本，自动清理旧版本
- **快速回滚**：通过软链接切换实现秒级回滚
- **零停机**：部署过程中服务不中断

## 安全建议

1. **配置文件管理**：
   ```bash
   # 将敏感配置文件加入.gitignore
   echo "devflow.host.yaml" >> .gitignore
   ```

2. **SSH密钥认证**：
   ```bash
   # 生成SSH密钥
   ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
   
   # 复制公钥到服务器
   ssh-copy-id user@server
   ```

3. **环境变量**：
   ```bash
   # 使用环境变量覆盖敏感信息
   export DEPLOY_PASSWORD=your_password
   devflow -deploy production
   ```

## 故障排除

### 常见问题

1. **SSH连接失败**：
   - 检查服务器地址和端口
   - 确认用户名和密码/密钥
   - 测试SSH连接：`ssh user@host`

2. **构建失败**：
   - 检查Go环境和依赖
   - 确认项目路径正确
   - 查看详细错误信息

3. **健康检查失败**：
   - 健康检查失败不会阻止部署
   - 检查服务启动状态
   - 手动验证服务可用性

4. **权限问题**：
   - 确保用户有部署目录的写权限
   - 检查文件权限设置

## 服务器端进程管理

### Supervisor - Go服务进程管理工具

推荐使用Supervisor来管理服务器上的Go服务进程，它提供了类似PM2的功能和体验。

#### 🔧 安装Supervisor

##### Ubuntu/Debian系统
```bash
# 更新包列表
sudo apt update

# 安装Supervisor
sudo apt install supervisor

# 启动并设置开机自启
sudo systemctl enable supervisor
sudo systemctl start supervisor

# 验证安装
sudo supervisorctl version
```

##### CentOS/RHEL系统
```bash
# 安装EPEL仓库
sudo yum install epel-release

# 安装Supervisor
sudo yum install supervisor

# 启动并设置开机自启
sudo systemctl enable supervisord
sudo systemctl start supervisord
```

#### ⚙️ 配置Go服务

devflow部署时会自动同步Supervisor配置文件到服务器，配置文件示例：

```ini
# /etc/supervisor/conf.d/example_admin.conf
[program:example_admin]
command=/data/www/example/admin/current/example_admin_linux_amd64
directory=/data/www/example/admin/current
user=liuyi
autostart=true
autorestart=true
startsecs=10
startretries=3
redirect_stderr=true
stdout_logfile=/var/log/supervisor/example_admin.log
stdout_logfile_maxbytes=100MB
stdout_logfile_backups=5
environment=GIN_MODE=release,PORT=8102
priority=999
killasgroup=true
stopasgroup=true

# Superlance 监控配置
[eventlistener:example_admin_memmon]
command=/home/liuyi/.local/bin/memmon -a 500MB -p example_admin
events=PROCESS_STATE_RUNNING
buffer_size=10
stdout_logfile=/var/log/supervisor/example_admin.log
stderr_logfile=/var/log/supervisor/example_admin.log

[eventlistener:example_admin_httpok]
command=/home/liuyi/.local/bin/httpok -p example_admin -u http://localhost:8102/health -t 30 -r 3
events=TICK_60
buffer_size=10
stdout_logfile=/var/log/supervisor/example_admin.log
stderr_logfile=/var/log/supervisor/example_admin.log

[eventlistener:example_admin_crashmail]
command=/home/liuyi/.local/bin/crashmail -a -p example_admin -s "example Admin Process Crashed"
events=PROCESS_STATE_EXITED
buffer_size=10
stdout_logfile=/var/log/supervisor/example_admin.log
stderr_logfile=/var/log/supervisor/example_admin.log
```

#### 📋 Supervisor管理命令

##### 基本进程管理
```bash
# 查看所有进程状态（类似 pm2 list）
sudo supervisorctl status

# 启动进程（类似 pm2 start）
sudo supervisorctl start example_admin

# 重启进程（类似 pm2 restart）
sudo supervisorctl restart example_admin

# 停止进程（类似 pm2 stop）
sudo supervisorctl stop example_admin

# 重启所有进程
sudo supervisorctl restart all

# 停止所有进程
sudo supervisorctl stop all
```

##### 配置管理
```bash
# 重新读取配置文件
sudo supervisorctl reread

# 更新配置（添加新的程序）
sudo supervisorctl update

# 重新加载supervisor配置
sudo supervisorctl reload
```

##### 日志查看
```bash
# 查看进程日志（类似 pm2 logs）
sudo supervisorctl tail example_admin

# 实时查看日志（类似 pm2 logs -f）
sudo supervisorctl tail -f example_admin

# 查看错误日志
sudo supervisorctl tail example_admin stderr

# 清空日志
sudo supervisorctl clear example_admin
```

##### 交互式管理
```bash
# 进入supervisor交互模式
sudo supervisorctl

# 在交互模式下可以直接输入命令（不需要sudo）
supervisor> status
supervisor> restart example_admin
supervisor> tail -f example_admin
supervisor> quit
```

#### 🌐 Web管理界面（可选）

启用Supervisor的Web管理界面，可以通过浏览器管理进程：

##### 1. 配置Web界面
编辑supervisor配置文件：
```bash
sudo nano /etc/supervisor/supervisord.conf
```

添加或修改以下配置：
```ini
[inet_http_server]
port=127.0.0.1:9001
username=admin
password=your_password
```

##### 2. 重启supervisor
```bash
sudo systemctl restart supervisor
```

##### 3. 访问Web界面
```bash
# 方法1：SSH隧道访问（推荐）
ssh -L 9001:127.0.0.1:9001 user@server
# 然后在本地浏览器访问：http://localhost:9001

# 方法2：如果允许外部访问，将127.0.0.1改为0.0.0.0
# 浏览器访问：http://服务器IP:9001
```

#### 📊 进程监控信息

Supervisor提供的监控信息包括：
- **进程状态**：RUNNING（运行中）、STOPPED（已停止）、FATAL（致命错误）
- **运行时间**：进程已运行的时间
- **重启次数**：进程重启的次数
- **PID**：进程ID
- **CPU使用率**：通过Web界面查看
- **内存使用**：通过Web界面查看

#### 🔧 部署时的自动化

devflow在部署时会自动：
1. **交叉编译**：根据配置自动生成Linux版本二进制文件
2. **SSH认证**：使用配置文件中的密码或密钥进行SSH连接
3. **文件上传**：通过Go原生SSH客户端上传文件（无需外部工具）
4. **Supervisor配置**：上传包含平台后缀的配置文件到服务器
5. **自动重启**：自动处理sudo密码并执行重启命令
6. **进程验证**：验证Supervisor进程启动状态

#### 🛡️ 自动密码处理

devflow的一个重要特性是**自动sudo密码处理**：

```yaml
# 配置文件中只需要写一次密码
servers:
  - name: dev
    password: your_password
    restart_cmd: "sudo supervisorctl restart example_admin"
```

**工作原理**：
- devflow会自动检测restart_cmd中的sudo命令
- 自动将命令转换为：`echo 'your_password' | sudo -S supervisorctl restart example_admin`
- 无需在restart_cmd中重复写密码
- 实现完全无交互的自动化部署

#### 🚀 Superlance - 高级监控插件

Superlance是Supervisor的官方监控插件，提供内存监控、HTTP健康检查、崩溃通知等高级功能。

##### 🔧 安装Superlance
```bash
# 安装Superlance
pip3 install superlance

# 验证安装
memmon --help
httpok --help
```

##### ⚙️ 配置监控
devflow部署时会同步Superlance配置文件，主要功能包括：

**1. 内存监控** - 自动重启内存超限的进程
```ini
[eventlistener:memmon]
command=memmon -a 500MB -p example_admin
events=PROCESS_STATE_RUNNING
```

**2. HTTP健康检查** - 定期检查服务响应
```ini
[eventlistener:httpok]
command=httpok -p example_admin -u http://localhost:8080/health -t 30 -r 3
events=TICK_60
```

**3. 崩溃监控** - 记录进程意外退出
```ini
[eventlistener:crashmail]
command=crashmail -a -p example_admin -s "example Admin Process Crashed"
events=PROCESS_STATE_EXITED
```

##### 📊 监控功能对比

| 功能 | Supervisor原生 | Supervisor + Superlance |
|------|---------------|-------------------------|
| 进程管理 | ✅ 启动/停止/重启 | ✅ 启动/停止/重启 |
| 状态监控 | ✅ 基础状态 | ✅ 基础状态 |
| 内存监控 | ❌ 无 | ✅ 超限自动重启 |
| HTTP健康检查 | ❌ 无 | ✅ 响应失败重启 |
| 崩溃通知 | ❌ 无 | ✅ 详细崩溃记录 |

##### 🛠️ 部署Superlance配置
```bash
# 1. 运行安装脚本（devflow会自动同步）
chmod +x superlance-setup.sh
./superlance-setup.sh

# 2. 复制配置文件
sudo cp superlance.conf /etc/supervisor/conf.d/

# 3. 重新加载配置
sudo supervisorctl reread
sudo supervisorctl update

# 4. 查看监控状态
sudo supervisorctl status
```

##### 📋 Superlance状态查看
```bash
# 查看所有进程状态（包括监控进程）
sudo supervisorctl status

# 示例输出：
# example_admin                  RUNNING   pid 1234, uptime 0:01:00
# superlance:crashmail             RUNNING   pid 1235, uptime 0:01:00  
# superlance:httpok                RUNNING   pid 1236, uptime 0:01:00
# superlance:memmon                RUNNING   pid 1237, uptime 0:01:00

# 查看监控日志
tail -f /var/log/supervisor/memmon.log
tail -f /var/log/supervisor/httpok.log
tail -f /var/log/supervisor/crashmail.log
```

#### ❓ 常见问题

##### Q: 如何查看进程是否正常运行？
```bash
sudo supervisorctl status example_admin
```

##### Q: 进程启动失败怎么办？
```bash
# 查看错误日志
sudo supervisorctl tail example_admin stderr

# 或查看supervisor日志
sudo tail -f /var/log/supervisor/supervisord.log
```

##### Q: 如何手动启动进程？
```bash
# 先停止supervisor管理
sudo supervisorctl stop example_admin

# 手动测试运行
cd /data/www/example/admin/current
./example_admin

# 确认无误后重新交给supervisor管理
sudo supervisorctl start example_admin
```

##### Q: 配置文件修改后如何生效？
```bash
# 重新读取配置
sudo supervisorctl reread

# 更新变更
sudo supervisorctl update

# 重启进程
sudo supervisorctl restart example_admin
```

#### 📝 最佳实践

1. **日志管理**：定期清理日志文件，避免占用过多磁盘空间
2. **权限管理**：使用专门的用户运行应用，不要使用root
3. **监控告警**：结合系统监控工具，当进程异常时及时告警
4. **备份配置**：定期备份supervisor配置文件

## 许可证

MIT License