mgmt/README-traefik-swarm.md

# Traefik + Docker Swarm 集成

## 📋 概述

本项目实现了 Traefik 与 Docker Swarm 的完整集成，提供统一的入口点管理所有 Swarm 服务。

## 🏗️ 架构设计

```
Internet
    ↓
Traefik (Load Balancer)
    ↓
Docker Swarm Services
    ├── Web App (app.local)
    ├── API Service (api.local)
    ├── Monitor Service (monitor.local)
    └── Other Services...
```

## 📁 文件结构

```
/root/mgmt/
├── traefik-swarm-stack.yml      # Traefik 主服务配置
├── demo-services-stack.yml      # 示例服务配置
├── monitoring-stack.yml         # 监控服务配置
├── swarm-traefik-manager.sh     # 管理脚本
└── README-traefik-swarm.md      # 说明文档
```

## 🚀 快速开始

### 1. 初始化环境

```bash
# 确保 Docker Swarm 已激活
docker swarm init

# 初始化 Traefik 环境
./swarm-traefik-manager.sh init
```

### 2. 部署所有服务

```bash
# 一键部署所有服务
./swarm-traefik-manager.sh deploy-all

# 或分步部署
./swarm-traefik-manager.sh deploy           # 仅部署 Traefik
./swarm-traefik-manager.sh deploy-demo      # 部署示例服务
./swarm-traefik-manager.sh deploy-monitoring # 部署监控服务
```

### 3. 更新 hosts 文件

```bash
# 自动更新 hosts 文件
./swarm-traefik-manager.sh update-hosts

# 或手动添加到 /etc/hosts
echo "127.0.0.1 traefik.local app.local api.local monitor.local prometheus.local grafana.local" >> /etc/hosts
```

## 🌐 访问地址

| 服务 | 地址 | 说明 |
|------|------|------|
| Traefik Dashboard | http://traefik.local:8080 | 管理界面 |
| Web App | http://app.local | 示例 Web 应用 |
| API Service | http://api.local | 示例 API 服务 |
| Monitor Service | http://monitor.local | 监控服务 |
| Prometheus | http://prometheus.local | 指标收集 |
| Grafana | http://grafana.local | 可视化面板 |

## 🛠️ 管理命令

### 查看服务状态
```bash
./swarm-traefik-manager.sh status
```

### 查看服务日志
```bash
./swarm-traefik-manager.sh logs traefik_traefik
./swarm-traefik-manager.sh logs demo_webapp
```

### 扩缩容服务
```bash
# 扩容 webapp 到 3 个副本
./swarm-traefik-manager.sh scale demo webapp 3

# 扩容 API 服务到 2 个副本
./swarm-traefik-manager.sh scale demo api 2
```

### 清理环境
```bash
./swarm-traefik-manager.sh cleanup
```

## 📊 监控配置

### Prometheus 指标
- Traefik 指标: http://traefik:8080/metrics
- Node Exporter: 系统指标
- cAdvisor: 容器指标

### Grafana 配置
- 默认用户: admin
- 默认密码: admin123
- 数据源: Prometheus (http://prometheus:9090)

## 🔧 服务配置

### 为新服务添加 Traefik 路由

在 Docker Compose 文件中添加以下标签：

```yaml
services:
  your-service:
    image: your-image
    networks:
      - traefik-public
    deploy:
      labels:
        - traefik.enable=true
        - traefik.http.routers.your-service.rule=Host(`your-domain.local`)
        - traefik.http.routers.your-service.entrypoints=web
        - traefik.http.services.your-service.loadbalancer.server.port=80
```

### 高级路由配置

```yaml
# 路径前缀路由
- traefik.http.routers.api-path.rule=Host(`app.local`) && PathPrefix(`/api`)

# HTTPS 重定向
- traefik.http.routers.your-service.entrypoints=websecure
- traefik.http.routers.your-service.tls.certresolver=letsencrypt

# 中间件配置
- traefik.http.routers.your-service.middlewares=auth
- traefik.http.middlewares.auth.basicauth.users=user:password
```

## 🔒 安全配置

### 基本认证
```yaml
labels:
  - traefik.http.middlewares.auth.basicauth.users=admin:$$2y$$10$$...
  - traefik.http.routers.service.middlewares=auth
```

### HTTPS 配置
```yaml
labels:
  - traefik.http.routers.service.tls.certresolver=letsencrypt
  - traefik.http.routers.service.entrypoints=websecure
```

## 🐛 故障排除

### 常见问题

1. **服务无法访问**
   ```bash
   # 检查服务状态
   docker stack services traefik
   
   # 检查网络连接
   docker network ls | grep traefik-public
   ```

2. **路由不生效**
   ```bash
   # 查看 Traefik 日志
   ./swarm-traefik-manager.sh logs traefik_traefik
   
   # 检查服务标签
   docker service inspect demo_webapp
   ```

3. **DNS 解析问题**
   ```bash
   # 检查 hosts 文件
   cat /etc/hosts | grep local
   
   # 更新 hosts 文件
   ./swarm-traefik-manager.sh update-hosts
   ```

### 调试命令

```bash
# 查看所有 Swarm 服务
docker service ls

# 查看特定服务详情
docker service inspect traefik_traefik

# 查看服务任务
docker service ps traefik_traefik

# 进入容器调试
docker exec -it $(docker ps -q -f name=traefik) sh
```

## 📈 性能优化

### 负载均衡配置
```yaml
labels:
  - traefik.http.services.service.loadbalancer.sticky.cookie=true
  - traefik.http.services.service.loadbalancer.healthcheck.path=/health
```

### 缓存配置
```yaml
labels:
  - traefik.http.middlewares.cache.headers.customrequestheaders.Cache-Control=max-age=3600
```

## 🔄 备份与恢复

### 备份配置
```bash
# 备份 Docker 配置
docker config ls
docker config inspect config_name

# 备份 Swarm 状态
docker node ls
docker service ls
```

### 恢复服务
```bash
# 重新部署服务
./swarm-traefik-manager.sh deploy-all
```

## 📚 参考资料

- [Traefik 官方文档](https://doc.traefik.io/traefik/)
- [Docker Swarm 文档](https://docs.docker.com/engine/swarm/)
- [Prometheus 配置](https://prometheus.io/docs/prometheus/latest/configuration/configuration/)
- [Grafana 文档](https://grafana.com/docs/)