mgmt/docs/waypoint/waypoint_setup_guide.md

# Waypoint 部署和配置指南

本文档提供了在现有基础设施上部署和配置HashiCorp Waypoint的详细步骤。

## 1. 前置准备

### 1.1 创建数据目录

在Waypoint服务器节点上创建数据目录：

```bash
sudo mkdir -p /opt/waypoint/data
sudo chown -R nomad:nomad /opt/waypoint
```

### 1.2 安装Waypoint CLI

在开发机器和CI/CD服务器上安装Waypoint CLI：

```bash
curl -fsSL https://releases.hashicorp.com/waypoint/0.11.0/waypoint_0.11.0_linux_amd64.zip -o waypoint.zip
unzip waypoint.zip
sudo mv waypoint /usr/local/bin/
```

## 2. 部署Waypoint服务器

### 2.1 使用Nomad部署

将`waypoint-server.nomad`文件提交到Nomad：

```bash
nomad job run waypoint-server.nomad
```

### 2.2 验证部署状态

```bash
# 检查Nomad任务状态
nomad job status waypoint-server

# 检查Waypoint UI是否可访问
curl -I http://warden:9701
```

## 3. 初始化Waypoint

### 3.1 连接到Waypoint服务器

```bash
# 连接CLI到服务器
waypoint context create \
  -server-addr=warden:9703 \
  -server-tls-skip-verify \
  -set-default my-waypoint-server
```

### 3.2 验证连接

```bash
waypoint context verify
waypoint server info
```

## 4. 配置Waypoint

### 4.1 配置Nomad作为运行时平台

```bash
# 确认Nomad连接
waypoint config source-set -type=nomad nomad-platform \
  addr=http://localhost:4646
```

### 4.2 配置与Vault的集成

```bash
# 配置Vault集成
waypoint config source-set -type=vault vault-secrets \
  addr=http://localhost:8200 \
  token=<vault-token>
```

## 5. 创建第一个Waypoint项目

### 5.1 创建项目配置文件

在应用代码目录中创建`waypoint.hcl`文件：

```hcl
project = "example-app"

app "web" {
  build {
    use "docker" {
      dockerfile = "Dockerfile"
    }
  }

  deploy {
    use "nomad" {
      datacenter = "dc1"
      namespace  = "default"
      
      service_provider = "consul" {
        service_name = "web"
      }
    }
  }
}
```

### 5.2 初始化和部署项目

```bash
# 初始化项目
cd /path/to/app
waypoint init

# 部署应用
waypoint up
```

## 6. 与现有工具集成

### 6.1 与Gitea Actions集成

创建一个Gitea Actions工作流文件`.gitea/workflows/waypoint.yml`：

```yaml
name: Waypoint Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install Waypoint
        run: |
          curl -fsSL https://releases.hashicorp.com/waypoint/0.11.0/waypoint_0.11.0_linux_amd64.zip -o waypoint.zip
          unzip waypoint.zip
          sudo mv waypoint /usr/local/bin/          
      
      - name: Configure Waypoint
        run: |
          waypoint context create \
            -server-addr=${{ secrets.WAYPOINT_SERVER_ADDR }} \
            -server-auth-token=${{ secrets.WAYPOINT_AUTH_TOKEN }} \
            -set-default ci-context          
      
      - name: Deploy Application
        run: waypoint up -app=web
```

### 6.2 与Vault集成

在`waypoint.hcl`中使用Vault获取敏感配置：

```hcl
app "web" {
  deploy {
    use "nomad" {
      # 其他配置...
      
      env {
        DB_PASSWORD = dynamic("vault", {
          path = "kv/data/app/db"
          key  = "password"
        })
      }
    }
  }
}
```

## 7. 高级配置

### 7.1 配置蓝绿部署

```hcl
app "web" {
  deploy {
    use "nomad" {
      # 基本配置...
    }
  }
  
  release {
    use "nomad-bluegreen" {
      service      = "web"
      datacenter   = "dc1"
      namespace    = "default"
      traffic_step = 25
      confirm_step = true
    }
  }
}
```

### 7.2 配置金丝雀发布

```hcl
app "web" {
  deploy {
    use "nomad" {
      # 基本配置...
    }
  }
  
  release {
    use "nomad-canary" {
      service    = "web"
      datacenter = "dc1"
      namespace  = "default"
      
      canary {
        percentage = 10
        duration   = "5m"
      }
    }
  }
}
```

### 7.3 配置自动回滚

```hcl
app "web" {
  deploy {
    use "nomad" {
      # 基本配置...
      
      health_check {
        timeout = "5m"
        check {
          name   = "http-check"
          route  = "/health"
          method = "GET"
          code   = 200
        }
      }
    }
  }
}
```

## 8. 监控和日志

### 8.1 查看部署状态

```bash
# 查看所有应用
waypoint list projects

# 查看特定应用的部署
waypoint list deployments -app=web

# 查看部署详情
waypoint deployment inspect <deployment-id>
```

### 8.2 查看应用日志

```bash
# 查看应用日志
waypoint logs -app=web
```

## 9. 备份和恢复

### 9.1 备份Waypoint数据

```bash
# 备份数据目录
tar -czf waypoint-backup.tar.gz /opt/waypoint/data
```

### 9.2 恢复Waypoint数据

```bash
# 停止Waypoint服务
nomad job stop waypoint-server

# 恢复数据
rm -rf /opt/waypoint/data/*
tar -xzf waypoint-backup.tar.gz -C /

# 重启服务
nomad job run waypoint-server.nomad
```

## 10. 故障排除

### 10.1 常见问题

1. **连接问题**:
   - 检查Waypoint服务器是否正常运行
   - 验证网络连接和防火墙规则

2. **部署失败**:
   - 检查Nomad集群状态
   - 查看详细的部署日志: `waypoint logs -app=<app> -deploy=<deployment-id>`

3. **权限问题**:
   - 确保Waypoint有足够的权限访问Nomad和Vault

### 10.2 调试命令

```bash
# 检查Waypoint服务器状态
waypoint server info

# 验证Nomad连接
waypoint config source-get nomad-platform

# 启用调试日志
WAYPOINT_LOG=debug waypoint up
```

## 11. 最佳实践

1. **模块化配置**: 将通用配置抽取到可重用的Waypoint插件中
2. **环境变量**: 使用环境变量区分不同环境的配置
3. **版本控制**: 将`waypoint.hcl`文件纳入版本控制
4. **自动化测试**: 在部署前添加自动化测试步骤
5. **监控集成**: 将部署状态与监控系统集成