edge-node/README.md

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：

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

# 启动并认证
tailscale up

# 查看 Tailscale IP
tailscale ip -4

3. 配置环境变量

cd edge-node
cp .env.example .env

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

# 边缘节点的 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. 启动服务

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 中的协议设置：

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

自定义健康检查

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

# TCP 检查  
CHECK_TYPE=tcp
CHECK_INTERVAL=10s

多服务部署

复制 docker-compose.yml 中的服务定义，修改：

• 服务名称
• 端口配置
• 环境变量

🔍 调试与监控

查看日志

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

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

Consul 状态检查

# 检查 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 服务：

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 或外部配置管理：

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

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

监控集成

添加 Prometheus 指标收集：

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

📚 相关文档

• Tailscale 文档
• Consul 文档
• Traefik 文档
• Docker Compose 文档

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE 文件