# 灵枢智能任务平台

## 部署方式选择

| 方式 | 适合场景 | 启动命令 |
|------|----------|----------|
| **本地模式**（推荐） | 个人电脑，OpenClaw 运行在本机 | `./start_local.sh` |
| **全 Docker 模式** | 服务器部署，OpenClaw 监听 `0.0.0.0` | `sudo ./start.sh` |

> **推荐使用本地模式**：MySQL 用 Docker 跑，Flask 直接在宿主机跑，OpenClaw 连接最稳定，无网络隔离问题。

---

## 本地模式部署（推荐）

### 前置要求

| 软件 | 安装命令 |
|------|----------|
| Docker | `sudo apt install docker.io docker-compose-plugin` |
| Python 3.8+ | `sudo apt install python3 python3-pip` |
| OpenClaw | 已安装并在本机运行 |

### 第一步：确认 OpenClaw 已运行

```bash
# 确认进程存在
ps aux | grep openclaw-gateway

# 确认端口正常响应
curl http://127.0.0.1:18789
# 有响应即可（不报 Connection refused）
```

### 第二步：确认 identity 文件存在

灵枢使用 **device 签名认证**（Ed25519 私钥），不需要手动配置任何 token。

```bash
# 确认以下两个文件存在
ls ~/.openclaw/identity/device.json
ls ~/.openclaw/identity/device-auth.json
```

如果文件不存在，说明 OpenClaw 尚未完成初始化，先正常启动运行一次 OpenClaw。

### 第三步：启动

```bash
chmod +x start_local.sh
./start_local.sh
```

脚本会自动完成：
1. 检测 OpenClaw identity 目录并写入 `.env`
2. 启动 MySQL Docker 容器
3. 安装 Python 依赖
4. 启动 Flask 后端

首次启动会下载 MySQL 镜像（约 600MB），需要几分钟。

启动成功后访问：**http://localhost:5000**

默认账号：`wangpai` / `admin123`

### 停止服务

```bash
# 停止 Flask：Ctrl+C

# 停止 MySQL 容器
docker compose -f docker-compose.db-only.yml down
```

### 重置数据库

```bash
docker compose -f docker-compose.db-only.yml down -v
./start_local.sh
```

---

## 全 Docker 模式

> 此模式要求 OpenClaw 监听 `0.0.0.0:18789`（默认只监听 `127.0.0.1`，需要修改 OpenClaw 配置）。

### 前置要求

| 软件 | 版本要求 |
|------|----------|
| Docker | 20.10+（`sudo apt install docker.io docker-compose-plugin`） |
| OpenClaw | 已配置监听 `0.0.0.0:18789` |

### 修改 OpenClaw 监听地址

在 `~/.openclaw/openclaw.json` 中将 gateway 监听地址改为 `0.0.0.0`，然后重启 OpenClaw。

验证：
```bash
ss -tlnp | grep 18789
# 应看到 0.0.0.0:18789，而不是 127.0.0.1:18789
```

### 启动

```bash
chmod +x start.sh
sudo ./start.sh
```

### 停止 / 重置

```bash
docker compose down          # 停止
docker compose down -v       # 停止并清空数据库
```

---

## 常见问题

**Q: `./start_local.sh` 报 `python3: command not found`？**
```bash
sudo apt install python3 python3-pip
```

**Q: pip 安装依赖失败？**
```bash
pip3 install -r backend/requirements.txt
# 网络慢时加国内镜像：
pip3 install -r backend/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

**Q: 触发任务报"Connection refused"？**
- 确认 OpenClaw 正在运行：`ps aux | grep openclaw`
- 确认端口正常：`curl http://127.0.0.1:18789`

**Q: 触发任务报"AUTH_DEVICE_TOKEN_MISMATCH"？**

identity 文件与当前 OpenClaw 实例不匹配。重新生成 identity：
```bash
rm -rf ~/.openclaw/identity/
# 重启 OpenClaw，让其重新生成 identity 文件
pkill openclaw-gateway
openclaw  # 重新启动，等待 identity 目录出现
ls ~/.openclaw/identity/  # 确认 device.json 和 device-auth.json 已生成
# 再重启灵枢
./start_local.sh
```

**Q: 端口 5000 被占用？**
```bash
# 在 start_local.sh 最后一行修改 --port=5000 为其他端口
```

**Q: 端口 3307 被占用？**

编辑 `docker-compose.db-only.yml`，把 `"3307:3306"` 改为其他端口，同时在 `.env` 中更新 `DB_PORT`。

---

## 目录结构

```
lingshu/
├── backend/                    # Flask 后端代码
├── docker-compose.yml          # 全 Docker 模式
├── docker-compose.db-only.yml  # 本地模式（仅 MySQL）
├── Dockerfile
├── .env.example                # 环境变量模板
├── start.sh                    # 全 Docker 模式启动脚本
├── start_local.sh              # 本地模式启动脚本（推荐）
├── 灵枢数据库设计.sql
└── init_demo_data.sql
```