# Edge Node - Tailscale + Consul + Traefik 边缘节点方案

本项目提供了一个完整的边缘节点解决方案，通过 Tailscale 网络将内网服务安全地暴露到云端，使用 Consul 进行服务发现，Traefik 进行流量代理和 SSL 终端。

## 🏗️ 架构概览

```
┌────────────────────────────────────────────────────────────────────┐
│                           云端 (阿里云)                              │
├─────────────────┬─────────────────┬─────────────────────────────────┤
│   Traefik       │   Consul Server │   其他服务                      │
│   (代理入口)     │   (服务发现)     │                                │
└─────────────────┴─────────────────┴─────────────────────────────────┘
                               │
                    Tailscale 网络 (100.64.x.x)
                               │
┌────────────────────────────────────────────────────────────────────┐
│                         边缘节点 (内网)                              │
├─────────────────┬─────────────────┬─────────────────────────────────┤
│   Consul Agent  │   你的服务       │   Registrar (注册器)            │
│   (客户端)       │   (API/应用)     │   (自动注册到云端)               │
└─────────────────┴─────────────────┴─────────────────────────────────┘
```

## 📁 项目结构

```
edge-node/
├── docker-compose.yml    # 服务编排配置
├── registrar.sh         # 服务注册脚本
├── .env.example         # 环境变量模板
└── README.md           # 本文档
```

## 🚀 快速开始

### 1. 环境准备

确保已安装：
- Docker & Docker Compose
- Tailscale 客户端
- 有效的域名（用于 HTTPS）

### 2. 配置 Tailscale

在所有节点（云端和边缘节点）上安装并配置 Tailscale：

```bash
# 安装 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# 启动并认证
tailscale up

# 查看 Tailscale IP
tailscale ip -4
```

### 3. 配置环境变量

```bash
cd edge-node
cp .env.example .env
```

编辑 `.env` 文件，修改以下关键配置：

```bash
# 边缘节点的 Tailscale IP
LOCAL_TS_IP=100.64.0.42

# 云端 Consul Server 的 Tailscale IP  
CONSUL_SERVER_IP=100.64.0.1

# 要暴露的服务配置
SERVICE_NAME=mypy
SERVICE_PORT=8229
ROUTE_HOST=api.jmsu.top
```

### 4. 启动服务

```bash
docker compose up -d
```

### 5. 验证部署

- 检查服务状态：`docker compose ps`
- 查看 Consul 注册：`curl http://$CONSUL_SERVER_IP:8500/v1/agent/services`
- 访问 HTTPS：`https://api.jmsu.top`

## ⚙️ 配置详解

### 环境变量说明

| 变量名 | 说明 | 示例 |
|-------|------|------|
| `LOCAL_TS_IP` | 边缘节点的 Tailscale IP | `100.64.0.42` |
| `CONSUL_SERVER_IP` | 云端 Consul Server IP | `100.64.0.1` |
| `CONSUL_DC` | 数据中心名称 | `dc1` |
| `SERVICE_NAME` | 服务名称（用于路由） | `mypy` |
| `SERVICE_PORT` | 服务端口 | `8229` |
| `ROUTE_HOST` | 暴露的域名 | `api.jmsu.top` |
| `CHECK_TYPE` | 健康检查类型 | `http` 或 `tcp` |
| `CHECK_PATH` | HTTP 检查路径 | `/` |
| `TRAEFIK_CERT_RESOLVER` | 证书解析器 | `cf` 或 `alidns` |

### 服务组件

#### 1. Consul Agent（客户端）
- 连接到云端 Consul Server
- 提供本地服务发现
- 使用 host 网络模式避免端口冲突

#### 2. API 服务
- 示例 Python HTTP 服务
- 仅绑定到 Tailscale IP（安全）
- 可替换为任何容器化服务

#### 3. Registrar（注册器）
- 自动将服务注册到云端 Consul
- 生成 Traefik 路由配置
- 支持 HTTP/TCP 协议
- 包含健康检查机制

## 🔧 高级配置

### TCP 服务配置

修改 `.env` 中的协议设置：

```bash
SERVICE_PROTOCOL=tcp
ROUTE_HOST=tcp.jmsu.top
CHECK_TYPE=tcp
```

### 自定义健康检查

```bash
# HTTP 检查
CHECK_TYPE=http
CHECK_PATH=/health
CHECK_INTERVAL=30s
CHECK_TIMEOUT=5s

# TCP 检查  
CHECK_TYPE=tcp
CHECK_INTERVAL=10s
```

### 多服务部署

复制 `docker-compose.yml` 中的服务定义，修改：
- 服务名称
- 端口配置
- 环境变量

## 🔍 调试与监控

### 查看日志

```bash
# 查看所有服务日志
docker compose logs -f

# 查看特定服务
docker compose logs -f registrar
```

### Consul 状态检查

```bash
# 检查 Consul Agent 状态
curl http://localhost:8500/v1/agent/self

# 检查服务注册
consul catalog services

# 检查健康状态  
consul health check service mypy
```

### 常见问题排查

1. **Consul 连接失败**
   - 检查 Tailscale 网络连通性
   - 验证云端 Consul Server 状态
   - 确认防火墙端口开放

2. **服务注册失败**
   - 检查环境变量配置
   - 验证服务端口监听状态
   - 查看 registrar 容器日志

3. **HTTPS 证书问题**
   - 确认域名解析正确
   - 检查 Traefik 证书解析器配置
   - 验证 Cloudflare/API 密钥

## 🔒 安全建议

1. **网络隔离**
   - 服务仅绑定 Tailscale IP
   - 避免暴露到公网
   - 使用 Tailscale ACL 控制访问

2. **访问控制**
   - 配置 Consul ACL
   - 使用 Traefik 中间件
   - 启用 Tailscale 设备认证

3. **证书管理**
   - 使用自动证书续期
   - 定期轮换 API 密钥
   - 监控证书有效期

## 🚀 扩展功能

### 自定义服务镜像

替换 `docker-compose.yml` 中的 `api` 服务：

```yaml
api:
  image: your-registry/your-app:latest
  container_name: your-app
  ports:
    - "${LOCAL_TS_IP}:${SERVICE_PORT}:${SERVICE_PORT}"
  environment:
    - APP_ENV=production
  depends_on:
    consul-agent:
      condition: service_healthy
```

### 环境变量管理

使用 Docker secrets 或外部配置管理：

```bash
# 使用外部 env 文件
docker compose --env-file .env.production up -d

# 使用环境变量
export LOCAL_TS_IP=100.64.0.42
docker compose up -d
```

### 监控集成

添加 Prometheus 指标收集：

```yaml
# 在 docker-compose.yml 中添加
prometheus:
  image: prom/prometheus
  container_name: prometheus
  ports:
    - "${LOCAL_TS_IP}:9090:9090"
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
```

## 📚 相关文档

- [Tailscale 文档](https://tailscale.com/kb/)
- [Consul 文档](https://www.consul.io/docs)
- [Traefik 文档](https://doc.traefik.io/traefik/)
- [Docker Compose 文档](https://docs.docker.com/compose/)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License - 详见 LICENSE 文件