# Alice Miner v2.0 教程（极简版）

更新时间：2026-03-09  
适用版本：`alice-miner-v2.0.0`

---

## 0. 这版和老版本有什么不同？

v2.0 是 **强制升级** 版本，核心变化：

1. 注册改为一步完成（`/register` 直接返回 token）
2. 不再需要本地钱包、私钥、签名 challenge
3. 启动只需要 `--address`
4. 支持模型缓存 + 增量更新（delta）

> 老矿工如果仍走 `/register/verify`，会直接失败。

---

## 1. 下载与安装

### 1.1 下载矿工包

```bash
curl -O https://dl.aliceprotocol.org/miner/alice-miner-latest.tar.gz
curl -O https://dl.aliceprotocol.org/miner/alice-miner-latest.tar.gz.sha256
```

### 1.2 校验完整性（推荐）

```bash
sha256sum -c alice-miner-latest.tar.gz.sha256
```

输出 `OK` 再继续。

### 1.3 解压并安装依赖

```bash
tar -xzf alice-miner-latest.tar.gz
cd alice-miner
pip install -r requirements.txt
```

---

## 2. 启动方式

> 你只需要准备一个 Alice 收款地址（`a...` 开头）。

### 2.1 单卡 / 单设备

```bash
python3 alice_miner.py \
  --ps-url https://ps.aliceprotocol.org \
  --address a1YourAddress... \
  --allow-insecure
```

说明：
- 如果 PS 是 `http://`，需要 `--allow-insecure`
- 如果你用 `https://`，可去掉 `--allow-insecure`

### 2.2 多卡（一机多进程）

```bash
./start_mining.sh \
  --address a1YourAddress... \
  --gpus 0,1,2,3 \
  --ps-url https://ps.aliceprotocol.org
```

或自动使用全部 NVIDIA GPU：

```bash
./start_mining.sh --address a1YourAddress... --gpus all --ps-url https://ps.aliceprotocol.org
```

---

## 3. 常用参数

- `--address`：**必填**，收款地址/身份地址（`a...`）
- `--instance-id`：可选，实例标识（多卡时可手动指定）
- `--model-dir`：模型缓存目录，默认 `~/.alice/models`
- `--reward-address`：可选，单独奖励地址
- `--ps-url`：PS 地址

示例（手动指定 instance_id）：

```bash
CUDA_VISIBLE_DEVICES=0 python3 alice_miner.py \
  --ps-url https://ps.aliceprotocol.org \
  --address a1YourAddress... \
  --instance-id gpu0 \
  --allow-insecure
```

---

## 4. 模型缓存与增量更新（v2.0 重点）

默认缓存目录：

```text
~/.alice/models/
  alice-7b-v{version}.pt
  alice-7b-v{version}.pt.sha256
  current_version
  .download.lock
```

行为说明：

1. 若本地版本 == PS 版本 + hash 正确 → 直接复用，不下载
2. 若本地版本落后且版本差 <= 10 → 尝试 delta 更新
3. delta 不可用或差距太大 → 回退完整下载
4. 自动保留最近 2 个版本，清理更老版本

这意味着：
- 多卡可共享同一份模型缓存
- 重启不会每次重下大模型

---

## 5. 运维命令

### 查看状态

```bash
./mining_status.sh
```

### 停止挖矿

```bash
./stop_mining.sh
```

仅停止某个地址对应进程：

```bash
./stop_mining.sh --address a1YourAddress...
```

### 看日志

```bash
tail -f logs/*.log
```

---

## 6. 常见问题

### Q1: 报 `/register/verify` 相关错误
你在用旧矿工。请升级到 v2.0。

### Q2: `Missing token` / `Invalid token`
一般是实例重连或 token 过期导致。重启矿工会自动重新注册拿 token。

### Q3: `502 Bad Gateway`
PS 暂时不可用，矿工会重试。可稍后重启一次矿工。

### Q4: 多卡同时下载冲突
v2.0 已有 `.download.lock` 文件锁，理论上不会写坏文件。

### Q5: 校验失败（hash mismatch）
会自动删除损坏模型并重新下载。

---

## 7. 推荐上线顺序（生产）

1. 先 1 台 canary 升级
2. 观察 10-20 分钟无异常
3. 再放量到多台/多卡

---

## 8. 一句话总结

v2.0 的目标是：

**“一条命令开挖，缓存复用，增量更新，少踩坑。”**