suanli-juzhen/03_节点部署/SKILL.md

---
name: 节点部署
description: 分布式算力矩阵 - 算力节点远程植入与一键部署（含PCDN/矿机/GPU/存储全类型）
triggers: 部署、植入、节点部署、远程部署、分布式部署、矩阵部署、一键部署、chroot部署
owner: 卡若
version: "2.0"
updated: "2026-02-15"
---

# 03_节点部署

> 核心任务：远程植入算力客户端到目标节点，实现一键批量部署
> 已吸收：金仓·分布式算力管控 + 金盾·远程环境一键部署 + 老旧NAS chroot部署经验

---

## 一、模块概述

节点部署模块负责将算力计算客户端远程部署到目标主机，支持多平台（Linux/Windows/macOS），实现从「发现IP」到「节点上线」的最后一步。

**已验证的部署类型**：

| 类型 | 程序/平台 | 收益来源 | 推荐优先级 |
|:---|:---|:---|:---|
| PCDN节点 | 网心云(wxedge) | 带宽共享 | ⭐⭐⭐ 首选 |
| PCDN节点 | 甜糖(ttnode) | 带宽共享 | ⭐⭐ |
| 加密矿机(CPU) | XMRig | 门罗币(XMR) | ⭐ |
| GPU算力出租 | Vast.ai / Golem | 算力租赁 | ⭐⭐⭐（有GPU时） |
| 存储节点 | Storj / Filecoin | 存储出租 | ⭐ |
| 远程环境 | Clash+Cursor+Docker | 开发环境 | 按需 |

---

## 二、部署架构

```
┌──────────────┐     SSH/WinRM      ┌──────────────────────┐
│  部署控制台   │ ──────────────────▶ │  目标节点             │
│  (本机)      │                     │  ├── 环境检测         │
│              │   ① 连接验证        │  ├── 依赖安装         │
│  deploy.py   │   ② 环境检测        │  ├── 客户端部署       │
│              │   ③ 推送文件        │  ├── 配置写入         │
│              │   ④ 执行部署        │  ├── 服务注册         │
│              │   ⑤ 验证上线        │  └── 心跳上报 ✓      │
└──────────────┘                     └──────────────────────┘
```

### 设备类型决策树（10秒判断部署路线）

```
SSH到目标设备 → uname -a → 判断走哪条路
                │
                ├─ 有Docker → 路线A：Docker部署（3分钟搞定）
                ├─ 无Docker + 内核≥4.x → 路线A（先装Docker）
                ├─ 无Docker + 内核<4.x → 路线B：chroot方案（10分钟）
                └─ Windows/Mac远程 → 路线C：远程环境一键部署
```

---

## 三、部署流程

### 3.1 完整部署流水线

```
连接验证 → 环境检测 → 依赖安装 → 推送客户端 → 配置注入 → 启动服务 → 上线验证
   │           │          │           │           │          │          │
   └─ 凭证库   └─ OS/架构  └─ Python   └─ SCP/SFTP └─ 节点ID  └─ systemd └─ 心跳
              RAM/CPU     Docker等    rsync      调度地址   supervisor  API注册
```

### 3.2 各步骤详细

#### Step 1: 连接验证
```bash
# 从凭证库获取登录信息，验证SSH连通性
python scripts/deploy.py check --host 192.168.1.100
```

#### Step 2: 环境检测
```bash
# 检测目标主机的OS、架构、CPU、内存、磁盘、网络
# 输出适配报告：是否满足最低部署要求
```

**最低要求**：
| 资源 | 最低要求 | 推荐配置 |
|:---|:---|:---|
| CPU | 1核 | 4核+ |
| 内存 | 512MB | 2GB+ |
| 磁盘 | 1GB可用 | 10GB+ |
| 网络 | 可达调度中心 | 带宽 10Mbps+ |
| OS | Linux/Win/macOS | Ubuntu 20.04+ |

#### Step 3: 依赖安装
```bash
# 根据OS自动安装依赖
# Linux: Python3, Docker(可选), 基础工具
# Windows: Python3, 远程管理服务
```

#### Step 4: 推送客户端
```bash
# 将算力客户端包推送到目标节点
scp -i ~/.ssh/matrix_key ./packages/agent-linux-amd64.tar.gz root@192.168.1.100:/opt/matrix/

# 或使用部署脚本
python scripts/deploy.py push --host 192.168.1.100
```

#### Step 5: 配置注入
```yaml
# 节点配置 (自动生成)
node:
  id: "node-abc123"
  name: "matrix-192.168.1.100"
  group: "default"
  
scheduler:
  url: "https://scheduler.example.com"
  token: "auto-generated-token"
  heartbeat_interval: 30
  
resources:
  cpu_limit: 80%      # CPU使用上限
  memory_limit: 70%   # 内存使用上限
  disk_limit: 50GB    # 磁盘使用上限
```

#### Step 6: 启动服务
```bash
# Linux - systemd 方式
systemctl enable matrix-agent
systemctl start matrix-agent

# 或 supervisor 方式
supervisorctl start matrix-agent

# Windows - 注册为服务
sc create MatrixAgent binPath= "C:\matrix\agent.exe"
sc start MatrixAgent
```

#### Step 7: 上线验证
```bash
# 验证节点是否成功上线
python scripts/deploy.py verify --host 192.168.1.100
# 检查项：进程存活、心跳正常、调度中心已注册
```

---

## 四、批量部署

### 4.1 并行批量部署

```bash
# 从凭证库批量部署所有ready节点
python scripts/deploy.py batch --group all --parallel 20

# 按分组部署
python scripts/deploy.py batch --group "linux-nodes" --parallel 10

# 指定IP列表部署
python scripts/deploy.py batch --hosts hosts.txt --parallel 20
```

### 4.2 部署策略

| 策略 | 说明 | 适用场景 |
|:---|:---|:---|
| 全量部署 | 所有节点同时部署 | 首次部署 |
| 滚动部署 | 分批部署，每批N台 | 更新升级 |
| 金丝雀部署 | 先部署1-2台验证 | 新版本测试 |
| 失败重试 | 失败节点自动重试3次 | 网络不稳定 |

### 4.3 一键部署脚本

```bash
#!/bin/bash
# one_click_deploy.sh - 一键部署全流程
# 使用：./one_click_deploy.sh <target_ip> [ssh_user] [ssh_port]

TARGET_IP=${1:?"用法: $0 <IP> [user] [port]"}
SSH_USER=${2:-root}
SSH_PORT=${3:-22}

echo "[1/6] 连接验证..."
ssh -p $SSH_PORT -o ConnectTimeout=5 $SSH_USER@$TARGET_IP "echo OK" || exit 1

echo "[2/6] 环境检测..."
ssh -p $SSH_PORT $SSH_USER@$TARGET_IP "uname -a && free -h && df -h"

echo "[3/6] 安装依赖..."
ssh -p $SSH_PORT $SSH_USER@$TARGET_IP "apt-get update && apt-get install -y python3 curl wget"

echo "[4/6] 推送客户端..."
scp -P $SSH_PORT ./packages/agent-latest.tar.gz $SSH_USER@$TARGET_IP:/opt/matrix/

echo "[5/6] 部署启动..."
ssh -p $SSH_PORT $SSH_USER@$TARGET_IP "cd /opt/matrix && tar xf agent-latest.tar.gz && ./install.sh"

echo "[6/6] 验证上线..."
ssh -p $SSH_PORT $SSH_USER@$TARGET_IP "systemctl status matrix-agent"
echo "✓ 部署完成: $TARGET_IP"
```

---

## 五、多平台支持

| 平台 | 连接方式 | 部署方式 | 服务管理 |
|:---|:---|:---|:---|
| Linux (Ubuntu/CentOS) | SSH | tar + install.sh | systemd |
| Linux (Alpine/其他) | SSH | tar + install.sh | supervisor |
| Windows Server | WinRM / SSH | zip + PowerShell | Windows Service |
| macOS | SSH | tar + install.sh | launchd |
| Docker | SSH + Docker | docker pull + run | docker compose |
| 老旧NAS(无Docker) | SSH | chroot + 二进制补丁 | rc.d自启动 |
| 群晖NAS(有Docker) | SSH | 特殊Docker路径 | systemd/Docker |

### 群晖NAS特殊处理

| 项目 | 标准Linux | 群晖NAS |
|:---|:---|:---|
| Docker路径 | `/usr/bin/docker` | `/var/packages/ContainerManager/target/usr/bin/docker` |
| 需要sudo | 不需要（root） | **需要 `sudo`** |
| 存储目录 | `/data/wxedge` | `/volume1/docker/wxedge` |

---

## 六、脚本清单

| 脚本 | 功能 | 说明 |
|:---|:---|:---|
| `deploy.py` | 部署主控程序 | 单台/批量部署、检查、验证 |
| `env_detect.py` | 环境检测 | OS/CPU/RAM/磁盘/网络检测 |
| `one_click_deploy.sh` | 一键部署 | Shell版快速部署 |
| `agent_builder.py` | 客户端打包 | 多平台客户端构建 |
| `config_generator.py` | 配置生成器 | 为每个节点生成配置 |
| `rollback.py` | 回滚脚本 | 部署失败时回滚 |
| `upgrade.py` | 升级脚本 | 客户端版本升级 |
| `pcdn_auto_deploy.py` | PCDN自动部署 | 扫描+登录+安装（来自金仓） |
| `fleet_monitor.py` | 机群监控 | 所有节点状态+收益（来自金仓） |

---

## 七、配置文件

`config/deploy_config.yaml` 示例：

```yaml
deploy:
  parallel: 20           # 并行部署数
  timeout: 300           # 单台超时（秒）
  retry: 3               # 失败重试次数
  strategy: rolling      # full / rolling / canary
  
agent:
  version: "1.0.0"
  package_dir: ./packages/
  install_dir: /opt/matrix/
  config_dir: /etc/matrix/
  log_dir: /var/log/matrix/
  
scheduler:
  url: "https://scheduler.example.com"
  register_api: "/api/v1/nodes/register"
  heartbeat_api: "/api/v1/nodes/heartbeat"
  
requirements:
  min_cpu: 1
  min_memory_mb: 512
  min_disk_gb: 1
  required_ports: [22]
```

---

## 八、部署状态

| 状态 | 说明 |
|:---|:---|
| `pending` | 待部署 |
| `deploying` | 部署中 |
| `deployed` | 已部署，等待验证 |
| `online` | 在线运行中 |
| `failed` | 部署失败 |
| `offline` | 离线 |
| `upgrading` | 升级中 |

---

## 九、已吸收的参考材料（references/）

> 以下材料来自卡若AI体系，已完整复制到本目录 `references/` 下，供本 SKILL 查阅和执行。

| 文件 | 来源 | 核心内容 |
|:---|:---|:---|
| `分布式算力管控_金仓_完整指南.md` | 卡若AI/金仓 | PCDN/矿机/存储全类型部署、自动扫描、批量部署、28条排错经验、外网扫描流程 |
| `远程环境一键部署_金盾.md` | 卡若AI/金盾 | Windows/Mac远程一键部署Clash+Cursor+Docker+Ubuntu容器 |
| `老旧NAS_chroot部署完整经验.md` | 卡若AI/经验库 | DS213j(armv7l/内核3.2)无Docker设备的chroot部署全流程，含二进制补丁、fake_runc、硬件伪装 |
| `已部署节点清单.md` | 卡若AI/金仓 | 所有已部署节点状态、外网访问、绑定检查 |

### 关键经验速查

**三种部署路线**：

| 场景 | 推荐方式 | 复杂度 | 详见 |
|:---|:---|:---|:---|
| 有Docker的Linux/NAS | Docker `docker run` | 低 | `分布式算力管控_金仓_完整指南.md` §0.2 |
| 无Docker但内核≥4.x | 先装Docker再部署 | 中 | `分布式算力管控_金仓_完整指南.md` §0.2 |
| 无Docker且内核<4.x | chroot + 二进制补丁 | 高 | `老旧NAS_chroot部署完整经验.md` |
| Windows/Mac远程环境 | 一键部署脚本 | 低 | `远程环境一键部署_金盾.md` |

**PCDN快速部署（最常用）**：
```bash
# Docker一行部署网心云
docker run -d --name wxedge --restart=always --net=host --privileged \
  -v /data/wxedge:/storage onething1/wxedge:latest

# 全自动扫描+部署
python3 pcdn_auto_deploy.py --auto 192.168.1.0/24
```

**收益参考**：
| 配置 | 日收益 | 月收益 |
|:---|:---|:---|
| 100M上行 PCDN | ~¥10 | ~¥300 |
| 50M上行 PCDN | ~¥5 | ~¥150 |
| RTX 4090 GPU出租 | ~$10 | ~$300 |

---

## 十、法律声明

本模块的扫描/部署工具仅用于管理自有设备和已授权的安全测试。未经授权攻击他人系统违反《刑法》第285条。