# 蝶雅采购智能体平台 — 生产环境部署指南

> **适用场景**：将开发/测试环境上的蝶雅智能体平台完整迁移到新的生产服务器
> 
> **核心原则**：开发环境与生产环境隔离互不影响，后续通过升级包方式更新生产环境

---

## 目录

1. [环境要求](#1-环境要求)
2. [准备工作](#2-准备工作)
3. [第一步：新电脑基础环境配置](#3-第一步新电脑基础环境配置)
4. [第二步：传输项目文件](#4-第二步传输项目文件)
5. [第三步：使用一键迁移脚本](#5-第三步使用一键迁移脚本)
6. [第四步：手动迁移（如有需要）](#6-第四步手动迁移如有需要)
7. [第五步：验证部署](#7-第五步验证部署)
8. [第六步：配置小龙虾（OpenClaw）](#8-第六步配置小龙虾openclaw)
9. [常见问题排查](#9-常见问题排查)
10. [日常升级流程](#10-日常升级流程)

---

## 1. 环境要求

### 开发环境（旧电脑）
- **操作系统**：Ubuntu 24.04（或其他 Linux 发行版）
- **已安装**：MySQL 8.0+、Python 3.12+、pip、OpenClaw（小龙虾）
- **项目路径**：`~/.openclaw/workspace/dy-dashboard/`
- **数据平台**：Flask/Gunicorn 运行中，端口 18888

### 生产环境（新电脑）
- **操作系统**：Ubuntu 24.04（推荐与开发环境一致）
- **网络**：需要固定的内网 IP，请提前配置好
- **SSH**：需要开启 SSH Server 以便远程操作
- **用户**：请记录新电脑的登录用户名（本例中为 `dieya`）

---

## 2. 准备工作

### 2.1 确认开发环境（旧电脑）状态

在旧电脑上运行以下命令，确认当前服务正常：

```bash
# 检查 MySQL 是否运行
sudo systemctl status mysql

# 检查 Gunicorn 是否运行
ps aux | grep gunicorn

# 检查数据平台能否访问
curl -s http://127.0.0.1:18888/ | head -c 100

# 检查 OpenClaw 状态
openclaw status
```

确认所有服务正常运行后再开始迁移。

### 2.2 记录关键信息

| 信息项 | 示例值 | 说明 |
|--------|--------|------|
| 新电脑 IP | `192.168.11.79` | 内网固定 IP |
| 新电脑用户名 | `dieya` | 登录新电脑的账号 |
| 新电脑 SSH 端口 | `22` | 默认，如有修改请记录 |
| 数据库用户名 | `dy_app` | 无特殊需要不必修改 |
| 数据库密码 | `dy_data_2026` | 无特殊需要不必修改 |
| 数据库名 | `dy_data` | 无特殊需要不必修改 |
| 平台端口 | `18888` | 无特殊需要不必修改 |

### 2.3 配置旧电脑到新电脑的免密 SSH 登录（推荐）

在旧电脑上执行：

```bash
ssh-copy-id dieya@192.168.11.79
```

按提示输入新电脑的登录密码。完成后测试：

```bash
ssh dieya@192.168.11.79 "echo 连接成功"
```

> **如果不配置免密登录**，迁移过程中每次 SSH 操作都需要手动输入密码，效率较低。

---

## 3. 第一步：新电脑基础环境配置

> 以下操作在新电脑上执行，可通过 SSH 登录后操作。

### 3.1 登录新电脑

```bash
ssh dieya@192.168.11.79
```

### 3.2 更新系统包

```bash
sudo apt update
sudo apt upgrade -y
```

### 3.3 安装 SSH Server（如果尚未安装）

```bash
sudo apt install openssh-server -y
sudo systemctl enable ssh
sudo systemctl start ssh
```

### 3.4 配置免密码 sudo（可选）

> 如果后续要一键执行部署脚本，需要配置免密码 sudo，否则每个 `sudo` 命令都需要手动输入密码。

```bash
echo 'dieya ALL=(ALL) NOPASSWD:***' | sudo tee /etc/sudoers.d/dieya
sudo chmod 440 /etc/sudoers.d/dieya
```

> 请将 `dieya` 替换为实际的用户名。

### 3.5 确保项目目录存在

```bash
mkdir -p /home/dieya/.openclaw/workspace/dy-dashboard
```

---

## 4. 第二步：传输项目文件

### 4.1 方法一：SCP 传输（推荐小项目）

在 **旧电脑** 上执行：

```bash
# 传输整个项目目录（排除不必要的文件）
cd ~/.openclaw/workspace
rsync -avz --exclude='venv/' --exclude='.git/' --exclude='__pycache__/' --exclude='logs/' --exclude='backups/*.tar.gz' --exclude='*.sql' dy-dashboard/ dieya@192.168.11.79:/home/dieya/.openclaw/workspace/dy-dashboard/
```

### 4.2 方法二：打包后传输（推荐大项目）

在 **旧电脑** 上执行：

```bash
cd ~/.openclaw/workspace
tar czf dy-dashboard.tar.gz dy-dashboard/ --exclude=venv --exclude=.git --exclude='__pycache__' --exclude='logs' --exclude='backups/*.tar.gz' --exclude='*.sql'
scp dy-dashboard.tar.gz dieya@192.168.11.79:/home/dieya/
```

在 **新电脑** 上执行：

```bash
cd /home/dieya
mkdir -p .openclaw/workspace
tar xzf dy-dashboard.tar.gz -C .openclaw/workspace/
rm -f dy-dashboard.tar.gz
```

### 4.3 验证文件传输成功

在 **新电脑** 上执行：

```bash
ls -la /home/dieya/.openclaw/workspace/dy-dashboard/
```

应看到 `app.py`、`config.py`、`routes/`、`services/`、`static/` 等文件和目录。

---

## 5. 第三步：使用一键迁移脚本

> 旧电脑上已经编写了 `migrate_to_prod.sh` 脚本，可以自动完成剩余的迁移步骤。
> 
> **前提条件**：上一节的文件传输已完成，且新电脑已配置免密码 sudo。

### 5.1 运行迁移脚本

在 **旧电脑** 上执行：

```bash
cd ~/.openclaw/workspace/dy-dashboard
bash migrate_to_prod.sh
```

### 5.2 回答交互问题

脚本会依次询问：

```
请输入新电脑 IP 地址: 192.168.11.79
请输入新电脑 SSH 用户名（默认 gxd）: dieya
请输入新电脑项目路径（默认 /home/gxd/.openclaw/workspace/dy-dashboard）: 直接回车（会自动识别为 /home/dieya/.openclaw/workspace/dy-dashboard）
```

### 5.3 脚本执行流程

脚本会自动完成以下 9 个步骤：

| 步骤 | 操作 | 耗时 |
|------|------|------|
| 1 | 测试 SSH 连接 | 约 3 秒 |
| 2 | 配置新电脑免密码 sudo（需输一次密码） | 约 5 秒 |
| 3 | 检查旧电脑 MySQL | 约 2 秒 |
| 4 | 导出旧电脑数据库（dy_data） | 约 1-5 分钟（视数据量） |
| 5 | 传输 SQL 文件到新电脑 | 约 1-3 分钟 |
| 6 | 新电脑安装 MySQL + 建库 + 导入数据 | 约 3-10 分钟 |
| 7 | 新电脑安装 Python 依赖 + 启动 Gunicorn | 约 3-5 分钟 |
| 8 | 新电脑配置定时任务（自动更新 + 每日备份） | 约 5 秒 |
| 9 | 新电脑重启小龙虾（OpenClaw） | 约 3 秒 |

### 5.4 脚本可能遇到的错误及处理

| 错误现象 | 原因 | 解决方法 |
|----------|------|----------|
| SSH 连接失败 | 未配置免密登录或 IP 错误 | 检查 IP / 执行 `ssh-copy-id` |
| sudo 密码输入超时 | `ssh -tt` 交互超时 | 重新运行脚本，快速输入密码 |
| 项目目录不存在 | 文件尚未传输或路径错误 | 先完成 [第二步：传输项目文件] |
| MySQL 安装失败 | apt 源问题或网络问题 | 手动 `sudo apt install mysql-server` 后重新运行 |
| Gunicorn 启动失败 | 需进一步排查（见常见问题） | 查看日志：`tail -50 logs/error.log` |
| OpenClaw 无法重启 | 数据库损坏 | 参考 [第六步：配置小龙虾] |

---

## 6. 第四步：手动迁移（如有需要）

> 如果一键迁移脚本执行失败，可按以下步骤手动完成。

### 6.1 新电脑安装 MySQL

```bash
sudo apt install mysql-server -y
sudo systemctl enable mysql
sudo systemctl start mysql
```

### 6.2 创建数据库和用户

```bash
sudo mysql -e "
  CREATE DATABASE IF NOT EXISTS dy_data CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  CREATE USER IF NOT EXISTS 'dy_app'@'localhost' IDENTIFIED BY 'dy_data_2026';
  GRANT ALL PRIVILEGES ON dy_data.* TO 'dy_app'@'localhost';
  ALTER USER 'dy_app'@'localhost' IDENTIFIED BY 'dy_data_2026';
  FLUSH PRIVILEGES;
"
```

### 6.3 导出旧电脑数据库

在 **旧电脑** 上执行：

```bash
mysqldump -h 127.0.0.1 -u dy_app -p'dy_data_2026' --single-transaction --no-tablespaces --routines --triggers --default-character-set=utf8mb4 dy_data > /tmp/dy_data_full.sql
```

### 6.4 传输并导入数据库

```bash
# 旧电脑：传输 SQL 到新电脑
scp /tmp/dy_data_full.sql dieya@192.168.11.79:/tmp/

# 新电脑：导入数据
mysql -u dy_app -p'dy_data_2026' dy_data < /tmp/dy_data_full.sql

# 验证
mysql -u dy_app -p'dy_data_2026' -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='dy_data';"
```

### 6.5 新电脑部署数据平台

```bash
# 安装 Python 依赖工具
sudo apt install python3-venv python3-pip -y

# 进入项目目录
cd /home/dieya/.openclaw/workspace/dy-dashboard

# 创建虚拟环境并安装依赖
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install flask==3.1.3 pymysql==1.2.0 gunicorn==26.0.0 gevent==26.5.0 openpyxl==3.1.5 DBUtils==3.1.2 flask-cors==6.0.2 Flask-Login==0.6.3 Flask-Compress==1.24 python-dateutil
deactivate

# 创建日志目录
mkdir -p logs

# 清理 Python 缓存（避免新旧电脑字节码冲突）
find . -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null
find . -name '*.pyc' -delete 2>/dev/null

# 启动 Gunicorn
nohup venv/bin/gunicorn -w 4 -b 0.0.0.0:18888 --timeout 120 --access-logfile logs/access.log --error-logfile logs/error.log app:app > /dev/null 2>&1 &

# 验证启动
sleep 3
curl -s http://127.0.0.1:18888/ | head -c 100
```

### 6.6 配置定时任务

```bash
# 添加自动更新（每天 7:00 / 12:00 / 18:00）
(crontab -l 2>/dev/null; echo "0 7,12,18 * * * cd /home/dieya/.openclaw/workspace/dy-dashboard && python3 auto_update.py >> /home/dieya/.openclaw/workspace/dy-dashboard/logs/auto_update.log 2>&1") | crontab -

# 添加每日备份（每天 8:30）
(crontab -l 2>/dev/null; echo "30 8 * * * cd /home/dieya/.openclaw/workspace/dy-dashboard && bash backup.sh >> /home/dieya/.openclaw/workspace/dy-dashboard/logs/backup.log 2>&1") | crontab -

# 查看定时任务
crontab -l
```

---

## 7. 第五步：验证部署

### 7.1 验证 MySQL

```bash
# 新电脑
mysql -u dy_app -p'dy_data_2026' -e "SELECT COUNT(*) AS 表数量 FROM information_schema.tables WHERE table_schema='dy_data';"
```

### 7.2 验证数据平台

- **本地验证**（在新电脑上）：
  ```bash
  curl -s http://127.0.0.1:18888/ | head -c 100
  # 应返回 <!doctype html><html lang=en>...
  ```

- **远程访问**（在任何同网段电脑的浏览器）：
  ```
  http://192.168.11.79:18888
  ```
  应该看到登录页面。

### 7.3 验证定时任务

```bash
crontab -l
# 应包含 auto_update.py 和 backup.sh 两条任务
```

### 7.4 验证错误日志为空

```bash
tail -20 /home/dieya/.openclaw/workspace/dy-dashboard/logs/error.log
# 不应有新的 ERROR 日志
```

---

## 8. 第六步：配置小龙虾（OpenClaw）

> 如果新电脑需要运行 OpenClaw（小龙虾）与用户对话，请按以下步骤配置。

### 8.1 基础配置

```bash
# 初始化
openclaw setup

# 启动网关
openclaw gateway run --force
```

### 8.2 添加智能体

```bash
openclaw agents add "dingtalk-assistant" --workspace /home/dieya/.openclaw/workspace/dingtalk-assistant
```

### 8.3 访问方式

- **终端对话**（在新电脑 SSH 中）：
  ```bash
  openclaw chat
  ```

- **WebChat 浏览器访问**（需要修改绑定地址）：
  ```bash
  openclaw config set gateway.bind "0.0.0.0"
  openclaw gateway run --force
  ```
  然后从浏览器访问：
  ```
  http://192.168.11.79:18789/
  ```

### 8.4 常见问题：数据库损坏

**现象**：`openclaw` 命令报错 `database disk image is malformed`

**解决**：
```bash
# 完全重置状态（不影响 workspace 文件）
rm -rf /home/dieya/.openclaw/state
rm -rf /home/dieya/.openclaw/agents
rm -rf /home/dieya/.openclaw/openclaw.json
rm -rf /home/dieya/.openclaw/openclaw.json.*
rm -rf /home/dieya/.openclaw/cron
rm -rf /home/dieya/.openclaw/tasks
rm -rf /home/dieya/.openclaw/flows
rm -rf /home/dieya/.openclaw/completions
rm -rf /home/dieya/.openclaw/session-delivery-queue
rm -rf /home/dieya/.openclaw/delivery-queue

# 重新初始化
openclaw setup
openclaw gateway run --force
```

---

## 9. 常见问题排查

### 9.1 Gunicorn 启动失败

**查看错误日志**：
```bash
tail -50 /home/dieya/.openclaw/workspace/dy-dashboard/logs/error.log
```

**常见错误及解决**：

| 错误 | 原因 | 解决 |
|------|------|------|
| `No module named 'dateutil'` | 缺少依赖 | `pip install python-dateutil` |
| `bad marshal data` | Python 缓存冲突 | 删除 `__pycache__` 和 `.pyc` |
| `No module named 'flask'` | 虚拟环境未激活 | 检查 `venv/bin/` 下是否有 gunicorn |
| `bind: Address already in use` | 端口被占用 | `kill $(lsof -t -i:18888)` |

### 9.2 MySQL 连接失败

```bash
# 检查 MySQL 是否运行
sudo systemctl status mysql

# 测试连接
mysql -u dy_app -p'dy_data_2026' -e "SELECT 1"

# 如果连接被拒绝，检查配置
sudo mysql -e "SELECT user, host FROM mysql.user WHERE user='dy_app';"
```

### 9.3 网页访问超时或无法连接

```bash
# 服务端检查端口监听
ss -tlnp | grep 18888

# 检查防火墙
sudo ufw status

# 如果 ufw 开启，放行 18888 端口
sudo ufw allow 18888
```

### 9.4 页面打开但报"网络错误"

**查看后端错误日志**：
```bash
tail -50 /home/dieya/.openclaw/workspace/dy-dashboard/logs/error.log
```

**常见代码错误**：
- 变量未初始化（如 `bom_json = None` 问题）
- 数据库查询 SQL 兼容性问题
- Python 版本差异导致的语法问题

### 9.5 定时任务未执行

```bash
# 检查 crontab 配置
crontab -l

# 检查日志
tail -50 /home/dieya/.openclaw/workspace/dy-dashboard/logs/auto_update.log
tail -50 /home/dieya/.openclaw/workspace/dy-dashboard/logs/backup.log
```

---

## 10. 日常升级流程

> 此流程用于开发环境改完代码后，更新生产环境。

### 10.1 创建一键升级脚本

将以下内容保存为 `~/upgrade_prod.sh`（在旧电脑上）：

```bash
#!/usr/bin/env bash
# 蝶雅智能体平台 — 生产环境升级脚本
# 用法：bash upgrade_prod.sh
set -euo pipefail

REMOTE_IP="192.168.11.79"
REMOTE_USER="dieya"
REMOTE_DIR="/home/dieya/.openclaw/workspace/dy-dashboard"
LOCAL_DIR="/home/gxd/.openclaw/workspace/dy-dashboard"

echo "=========================================="
echo "  蝶雅智能体平台 — 生产环境升级"
echo "=========================================="
echo ""

# 1. 同步代码（仅变更的文件）
echo "[1/3] 同步代码到生产服务器..."
rsync -avz --delete \
  --exclude='venv/' \
  --exclude='.git/' \
  --exclude='__pycache__/' \
  --exclude='*.pyc' \
  --exclude='logs/' \
  --exclude='backups/' \
  --exclude='*.tar.gz' \
  --exclude='*.sql' \
  "${LOCAL_DIR}/" "${REMOTE_USER}@${REMOTE_IP}:${REMOTE_DIR}/"

# 2. 清理缓存
echo "[2/3] 清理缓存..."
ssh "${REMOTE_USER}@${REMOTE_IP}" "find ${REMOTE_DIR} -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null; find ${REMOTE_DIR} -name '*.pyc' -delete 2>/dev/null; echo '  缓存清理完成'"

# 3. 重启服务
echo "[3/3] 重启 Gunicorn..."
ssh "${REMOTE_USER}@${REMOTE_IP}" "
  kill \$(lsof -t -i:18888) 2>/dev/null || true
  sleep 2
  cd ${REMOTE_DIR}
  nohup venv/bin/gunicorn -w 4 -b 0.0.0.0:18888 --timeout 120 --access-logfile logs/access.log --error-logfile logs/error.log app:app > /dev/null 2>&1 &
  sleep 3
  if curl -s http://127.0.0.1:18888/ > /dev/null 2>&1; then
    echo '  ✅ 服务重启成功'
  else
    echo '  ⚠️ 服务可能未启动，请检查日志'
  fi
"

echo ""
echo "✅ 升级完成"
echo "  访问：http://${REMOTE_IP}:18888"
```

### 10.2 使用方式

每次在开发环境改完代码、测试通过后，在旧电脑执行：

```bash
bash upgrade_prod.sh
```

只需输入一次 SSH 密码（或免密则无需输入），即可完成：
1. 增量同步代码（只传改动过的文件，秒级）
2. 清理缓存
3. 重启 Gunicorn

### 10.3 升级注意事项

- **避免在高峰期升级**（建议午休或下班后操作）
- **升级前最好先备份生产数据库**：`ssh dieya@IP "bash backup.sh"`
- **如果有数据库结构变更**，需要单独导出导入 SQL
- **升级后最好做一次功能冒烟测试**（登录、查询、下单）

---

> **文档版本**：v1.0 | **最后更新**：2026-06-26 | **编写人**：OpenClaw

## 11. 知识库迁移

> 平台知识库读取的是 Obsidian Vault 路径下的 Markdown 文件，独立于项目代码和数据库，需要单独迁移。

### 11.1 前置说明

`routes/knowledge.py` 中的 `VAULT_PATH` 硬编码了旧电脑的用户路径（`/home/gxd/蝶雅供应链`），存在两个问题：

1. 迁移脚本未覆盖知识库文件
2. 路径未配置化，新电脑需修改

### 11.2 解决方案

#### 1. 改造路径配置

在 `config.py` 中添加：

```python
VAULT_PATH = "/home/gxd/蝶雅供应链"  # 按实际用户名修改
```

修改 `routes/knowledge.py`，将硬编码改为从 `config` 导入：

```python
from config import VAULT_PATH
```

#### 2. 传输知识库文件

```bash
# 旧电脑执行
rsync -avz --delete "/home/gxd/蝶雅供应链/" dieya@新电脑IP:"/home/dieya/蝶雅供应链/"
```

#### 3. 修改新电脑配置

```bash
# 新电脑执行
sed -i 's|/home/gxd/蝶雅供应链|/home/dieya/蝶雅供应链|' /home/dieya/.openclaw/workspace/dy-dashboard/config.py
systemctl --user restart dy-dashboard.service
```

### 11.3 验证

登录数据平台 → 📖 知识库 → 检查各卡片目录内容是否正常显示。

---

## 12. 常见遗漏检查清单

迁移完成后应逐项确认：

| # | 检查项 | 命令/方法 | 已迁移 |
|---|--------|-----------|:------:|
| 1 | 项目代码 | `ls /远程路径/dy-dashboard/app.py` | ✅ |
| 2 | MySQL 数据库 | `mysql -u dy_app -p -e "USE dy_data; SELECT 1"` | ✅ |
| 3 | Gunicorn 服务 | `systemctl --user status dy-dashboard.service` | ✅ |
| 4 | 定时任务 | `crontab -l`（auto_update + backup） | ✅ |
| 5 | 知识库文件 | `ls /远程路径/蝶雅供应链/知识库/ ` | ✅ |
| 6 | dws CLI 授权 | `dws auth status`（authenticated=true） | ✅ |
| 7 | 知识库路径配置 | `grep VAULT_PATH config.py` | ✅ |
| 8 | 网页可访问 | 浏览器打开 `http://新IP:18888` | ✅ |
| 9 | 开机能自启 | 重启新电脑后验证服务自动运行 | ✅ |

---

> **文档版本**：v1.1 | **最后更新**：2026-06-26 16:04 | **编写人**：OpenClaw