# Pipe Network CDN Node - Docker 部署

这是一个用于部署 Pipe Network CDN 节点的 Docker 项目。通过 Docker 和 Docker Compose，你可以快速搭建并运行自己的 PipeCDN 节点，参与网络并提供 CDN 服务以获得 $PIPE 代币奖励。

## 📋 目录

- [功能特性](#功能特性)
- [系统要求](#系统要求)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [使用方法](#使用方法)
- [监控与维护](#监控与维护)
- [故障排除](#故障排除)
- [性能优化](#性能优化)
- [参考文档](#参考文档)

## ✨ 功能特性

- 🐳 **Docker 化部署**：一键部署，无需手动配置
- 🔄 **自动重启**：容器异常退出时自动重启
- 💾 **数据持久化**：缓存数据自动保存，重启不丢失
- 🏥 **健康检查**：自动监控节点健康状态
- 📊 **Prometheus 指标**：支持监控和指标收集
- ⚙️ **灵活配置**：通过 `.env` 文件轻松管理配置

## 🔧 系统要求

### 操作系统
- Linux（推荐 Ubuntu 24.04+ 或 Debian 11+）
- macOS（用于开发）
- Windows（使用 WSL2）

### 软件依赖
- Docker 20.10+
- Docker Compose 2.0+

### 硬件要求
- **存储空间**：至少 20 GB 可用空间
- **内存**：建议 2 GB 以上（可根据缓存配置调整）
- **网络**：需要开放 TCP 端口 `80` 和 `443`
- **存储类型**：SSD/NVMe 推荐用于缓存（提升性能）

## 🚀 快速开始

### 1. 克隆或下载项目

```bash
git clone <repository-url>
cd pipe
```

### 2. 创建配置文件

复制示例配置文件并编辑：

```bash
cp .env.example .env
```

编辑 `.env` 文件，**必须修改**以下配置：

```bash
# 必需：你的 Solana 钱包地址（44 字符）
NODE_SOLANA_PUBLIC_KEY=your_solana_wallet_address

# 节点名称
NODE_NAME=my-pop-node

# 你的邮箱
NODE_EMAIL="operator@example.com"

# 节点位置
NODE_LOCATION="San Francisco, USA"
```

### 3. 获取 Solana 钱包地址

如果你还没有 Solana 钱包，可以通过以下方式创建：

**方式一：使用 Phantom Wallet**
1. 安装 [Phantom Wallet](https://phantom.app/) 浏览器扩展
2. 创建新钱包或导入现有钱包
3. 复制公钥地址

**方式二：使用 Solana CLI**
```bash
# 安装 Solana CLI（如果未安装）
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# 生成新密钥对
solana-keygen new

# 查看公钥地址
solana address
```

⚠️ **安全提示**：永远不要分享你的私钥或助记词！

### 4. 构建并启动

```bash
# 构建 Docker 镜像
docker compose build

# 启动服务（后台运行）
docker compose up -d

# 查看日志
docker compose logs -f
```

### 5. 验证运行状态

```bash
# 检查容器状态
docker compose ps

# 健康检查
curl http://localhost:8081/health

# 预期输出：{"status":"healthy"}
```

## ⚙️ 配置说明

### 环境变量配置

所有配置都在 `.env` 文件中，主要配置项说明：

| 配置项 | 说明 | 默认值 | 必需 |
|--------|------|--------|------|
| `NODE_SOLANA_PUBLIC_KEY` | Solana 钱包公钥地址 | - | ✅ 是 |
| `NODE_NAME` | 节点名称 | `my-pop-node` | 否 |
| `NODE_EMAIL` | 运营者邮箱 | - | 否 |
| `NODE_LOCATION` | 节点地理位置 | - | 否 |
| `MEMORY_CACHE_SIZE_MB` | 内存缓存大小（MB） | `512` | 否 |
| `DISK_CACHE_SIZE_GB` | 磁盘缓存大小（GB） | `100` | 否 |
| `DISK_CACHE_PATH` | 缓存路径 | `./cache` | 否 |
| `HTTP_PORT` | HTTP 端口 | `80` | 否 |
| `HTTPS_PORT` | HTTPS 端口 | `443` | 否 |
| `UPNP_ENABLED` | 启用 UPnP 自动端口转发 | `false` | 否 |

### 端口说明

| 端口 | 用途 | 说明 |
|------|------|------|
| 80 | HTTP | CDN 服务端口 |
| 443 | HTTPS | CDN 服务端口（SSL/TLS） |
| 8081 | 健康检查 | 节点健康状态检查 |
| 9090 | Prometheus | 监控指标端口 |

### UPnP 配置

- **VPS/云服务器**：建议设置 `UPNP_ENABLED=false`
- **家庭网络**：可以设置 `UPNP_ENABLED=true`（需要路由器支持 UPnP）

## 📖 使用方法

### 基本命令

```bash
# 启动服务
docker compose up -d

# 停止服务
docker compose stop

# 停止并删除容器
docker compose down

# 停止并删除容器和数据卷（清理缓存）
docker compose down -v

# 查看日志
docker compose logs -f

# 查看最近 100 行日志
docker compose logs --tail=100

# 重启服务
docker compose restart

# 重新构建镜像
docker compose build --no-cache
```

### 更新配置

修改 `.env` 文件后，需要重新构建镜像：

```bash
# 停止服务
docker compose down

# 重新构建（不使用缓存）
docker compose build --no-cache

# 启动服务
docker compose up -d
```

### 查看节点状态

```bash
# 进入容器
docker compose exec pipe-node bash

# 查看节点状态
./pop status

# 查看收益
./pop earnings

# 退出容器
exit
```

## 📊 监控与维护

### 健康检查

```bash
# 使用 curl 检查
curl http://localhost:8081/health

# 使用 Docker 检查
docker inspect --format='{{.State.Health.Status}}' pipe-node
```

### Prometheus 指标

```bash
# 查看指标
curl http://localhost:9090/metrics
```

### 日志查看

```bash
# 实时日志
docker compose logs -f pipe-node

# 查看特定时间段的日志
docker compose logs --since 1h pipe-node

# 查看最后 50 行日志
docker compose logs --tail=50 pipe-node
```

### 缓存管理

```bash
# 查看缓存使用情况
docker exec pipe-node du -sh /opt/pipe/cache

# 清理缓存（需要停止服务）
docker compose down
docker volume rm pipe_pipe-cache
docker compose up -d
```

## 🔍 故障排除

### 常见问题

#### 1. 端口被占用

**错误信息**：`Bind for 0.0.0.0:80 failed: port is already allocated`

**解决方法**：
```bash
# 查找占用端口的进程
sudo lsof -i :80
sudo lsof -i :443

# 停止占用端口的服务或修改 docker compose.yml 中的端口映射
```

#### 2. 容器启动失败

**检查步骤**：
```bash
# 查看容器日志
docker compose logs pipe-node

# 检查容器状态
docker compose ps

# 检查配置文件
cat .env
```

#### 3. 健康检查失败

**可能原因**：
- 节点还在启动中（等待 40 秒后重试）
- 配置文件错误
- 网络问题

**解决方法**：
```bash
# 查看详细日志
docker compose logs -f pipe-node

# 手动检查健康端点
docker compose exec pipe-node curl http://localhost:8081/health
```

#### 4. 磁盘空间不足

**解决方法**：
```bash
# 减少缓存大小（修改 .env 文件）
DISK_CACHE_SIZE_GB=50  # 从 100 改为 50

# 清理未使用的 Docker 资源
docker system prune -a
```

#### 5. 内存使用过高

**解决方法**：
```bash
# 减少内存缓存（修改 .env 文件）
MEMORY_CACHE_SIZE_MB=256  # 从 512 改为 256
```

#### 6. UPnP 失败（家庭网络）

**解决方法**：
- 在路由器中启用 UPnP
- 或设置 `UPNP_ENABLED=false` 并手动配置端口转发

## ⚡ 性能优化

### 高流量配置

对于高流量场景，可以调整以下配置：

```bash
# .env 文件
MEMORY_CACHE_SIZE_MB=8192        # 8 GB 内存缓存
DISK_CACHE_SIZE_GB=500           # 500 GB 磁盘缓存
DISK_CACHE_PATH=/mnt/nvme/cache  # 使用 NVMe SSD
```

### 系统优化

```bash
# 增加文件描述符限制（在 docker compose.yml 中已注释）
# 取消注释 ulimits 部分

# 使用 SSD/NVMe 存储
# 将缓存挂载到高性能存储设备
volumes:
  - /mnt/nvme/cache:/opt/pipe/cache
```

### 网络优化

- 确保服务器有足够的带宽
- 使用 CDN 或负载均衡器（如果运行多个节点）
- 监控网络流量和延迟

## 📚 参考文档

- [Pipe Network 官方文档](https://docs.pipe.network/)
- [Mainnet 安装指南](https://docs.pipe.network/docs/nodes/mainnet.md)
- [Docker 官方文档](https://docs.docker.com/)
- [Docker Compose 文档](https://docs.docker.com/compose/)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📝 许可证

本项目遵循相应的开源许可证。

## ⚠️ 免责声明

- 运行节点需要稳定的网络和足够的资源
- 收益取决于网络使用情况和节点性能
- 请妥善保管你的 Solana 钱包私钥
- 本工具仅用于学习和合法用途

---

**祝你的 Pipe Network 节点运行顺利！** 🚀