first commit
This commit is contained in:
279
README.md
Normal file
279
README.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# 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 文件
|
||||
Reference in New Issue
Block a user